The Prometheus metrics OGuardAI exposes, the Grafana dashboard and alerting rules it ships, how to wire them up, and the current state of distributed tracing.

OGuardAI exposes operational metrics in Prometheus exposition format and ships a ready-to-import Grafana dashboard plus a starter set of alerting rules. This page is the metric reference and the wiring guide.

The /metrics endpoint

Each server instance exposes GET /metrics in Prometheus text format. The endpoint requires the admin scope, so Prometheus must scrape it with admin credentials, unlike the unauthenticated /livez and /readyz probes. In API-key auth mode that means an admin X-API-Key; in JWT or OIDC mode it means a token that carries the admin scope. In a multi-instance deployment every instance exposes its own /metrics, and Prometheus scrapes each independently. See Deployment for the scrape config and PromQL aggregation across instances.

Metric catalog

Operation counters

Metric	Type	Meaning
`guardai_transforms_total`	counter	Transform operations processed
`guardai_rehydrates_total`	counter	Rehydrate operations processed
`guardai_detections_total`	counter	Detect operations processed
`guardai_errors_total`	counter	Errors returned
`guardai_prompt_security_triggers_total`	counter	Prompt-security engine triggers
`guardai_output_guard_triggers_total`	counter	Output-guard triggers (new PII in a model response)
`guardai_sessions_created_total`	counter	Sealed sessions created
`guardai_rate_limit_rejections_total`	counter	Requests rejected by the rate limiter
`guardai_rag_operations_total`	counter	RAG pipeline operations
`guardai_ner_degraded_total`	counter	Requests where configured NER (`both`/`advanced`) did not run and detection degraded to regex-only (sidecar outage)

Entity counters (labeled)

Metric	Type	Labels	Meaning
`guardai_entities_detected_total`	counter	`type`	Entities detected, by entity type
`guardai_entities_blocked_total`	counter	`type`	Entities blocked, by entity type

The type label is cardinality-capped at 64 distinct values per counter. Operator-defined custom entity types (policy custom_patterns) beyond that cap are counted under type="other", so a policy cannot grow the Prometheus series set without bound. Label values are escaped for the exposition format.

Latency histograms

Metric	Type	Meaning
`guardai_transform_duration_seconds`	histogram	Transform latency in seconds
`guardai_rehydrate_duration_seconds`	histogram	Rehydrate latency in seconds

Each histogram exposes _bucket{le="..."}, _sum, and _count. Buckets run from 1 ms to 10 s. Compute quantiles with histogram_quantile, for example:

histogram_quantile(0.95, sum(rate(guardai_transform_duration_seconds_bucket[5m])) by (le))

Grafana dashboard

A ready-to-import dashboard ships at deploy/grafana/oguardai-dashboard.json. In Grafana, open Dashboards, New, Import, then upload the JSON file and select your Prometheus data source. It visualizes request and error rates, transform and rehydrate p95 latency, entity detection and blocking by type, session creation, RAG operations, and the prompt-security and output-guard triggers. Every panel is built on the metrics in the catalog above.

Alerting rules

A starter alert set ships at deploy/prometheus/alerting-rules.yml. Load it with Prometheus --rule-files. It covers:

high error rate (guardai_errors_total)
transform p95 latency above 1 second
prompt-security trigger spikes (critical, possible token-extraction attempts)
output-guard trigger spikes (the model may be emitting PII that was not in the input)
rate-limit saturation
no transform traffic for 5 minutes (possible outage upstream)
entity-detection spikes (possible scanning)

Treat the thresholds as starting points. Tune them to your own traffic and SLOs (see SLO).

Distributed tracing

OGuardAI ships the Prometheus metrics, the Grafana dashboard, and the alerting rules described above, plus optional OpenTelemetry trace export. Trace export is off by default. Set GUARDAI_OTEL_TRACES_ENDPOINT to your collector's OTLP over HTTP traces endpoint (for example http://collector:4318/v1/traces) to turn it on, and GUARDAI_OTEL_SERVICE_NAME to override the service name (default oguardai-server). The exporter posts OTLP over HTTP and adds no gRPC dependency; when the endpoint is unset the server runs exactly as before, with metrics and structured logs only. Verify the pipeline against your own collector. Spans carry request identifiers (such as tenant and policy names) and safe metadata (entity types and counts), never the raw detected values that tokenization protects. Because those identifiers are caller-controlled, treat exported spans at the same trust level as your logs, and export only to a collector you control.

Monitoring