Guardrails and OpenAPPA Metrics

Track Guardrails hooks and OpenAPPA engine operations through Archestra's standard Prometheus /metrics endpoint.

Collection Setup

Scrape every Archestra web and worker pod using the standard metrics endpoints and authentication. Hook and engine metrics are included in the same response. No additional exporter, receiver, or data source is required.

If your collector filters metric names, retain openappa_hook_*, appa_*, and agent_runtime_crossing_refusals_total, including histogram _bucket, _sum, and _count series. Preserve the metric labels and pod identity labels.

Exercise a Guardrails-enabled request, then query sum by (hook, decision) (openappa_hook_dispatches_total) and sum by (outcome) (appa_policy_decisions_total) in Prometheus. Select that Prometheus source as Metrics on the Guardrails & OpenAPPA dashboard. Metrics appear when their corresponding operations run; an absent event-driven series is not a successful zero.

Embedded Hook Metrics

Archestra exposes two metric families on its standard Prometheus scrape endpoint (:9050/metrics on web pods and :9000/metrics on worker pods; see Scraping).

Dispatch Semantics

Each observation records one logical hook dispatch across the embedded host boundary after any policy-move retries settle. One user request or agent turn can trigger multiple hook dispatches (such as session_start, tool_result, prompt, tool_call, and turn_end), and a single tool_call dispatch can evaluate policy rules, consult helpers or annotators, and retry when an organization's policy revision moves. These metrics do not count individual engine rule checks or unique user requests.

Metric collection cannot alter enforcement. If metric recording is disabled or fails, Archestra preserves the original hook decision or error unchanged.

Labels

Both families use closed label sets to keep cardinality bounded and never emit organization, session, user, agent, or call IDs, tool names, arguments, policy text, or error messages.

Related boundary counters on other pages track downstream effects: llm_blocked_tools_total counts tool calls blocked at the LLM Proxy, and agent_runtime_crossing_refusals_total counts runtime boundary refusals.

Shared policy preloading for a tool-call batch and principal lookup happen before this boundary and are excluded.

Query dispatch rates, failures, and tail latency with PromQL:

# Embedded hook dispatch rate by hook and decision
sum by (hook, decision) (
  rate(openappa_hook_dispatches_total[5m])
)

# Failed dispatches or structured runtime refusals
sum by (hook, decision) (
  rate(openappa_hook_dispatches_total{decision=~"error|refuse"}[5m])
)

# 95th-percentile hook dispatch wall time by hook
histogram_quantile(
  0.95,
  sum by (le, hook) (rate(openappa_hook_dispatch_duration_seconds_bucket[5m]))
)

Engine Metrics

These metrics describe policy checks, external calls, remedies, and runtime failures inside Archestra. They use the same endpoint as hook metrics. Durations are in seconds. Counters and histograms are cumulative for each process; scrapes do not reset them.

A host hook acknowledgment is distinct from a tool-proposal policy decision. One hook dispatch can include multiple engine operations. Compare these counters by their documented operation rather than treating them as interchangeable request counts.

Only operational labels are exported. Organization, user, session, tool, policy, and request content are excluded. If engine collection fails, Archestra continues serving its other process metrics.