Metric Reference

This page lists the metrics emitted by the IORails engine and the instrumented canonical outbound HTTP client.

Metrics fall into three families:

• Request-level metrics (guardrails.*) describe IORails request flow: volume, errors, blocks, latency, and saturation of the streaming and non-streaming admission paths. They cover generate_async(), stream_async(), and the rails-only check_async(), which shares the non-streaming admission path.
• LLM client-side metrics (gen_ai.client.*) describe downstream LLM calls IORails issues. These follow the OpenTelemetry GenAI semantic conventions and use the bucket boundaries recommended by that spec.
• HTTP client-side metrics (http.client.*) describe outbound requests sent through an explicitly instrumented canonical HTTP client.

IORails request and LLM metrics require metrics.enabled: true and a configured MeterProvider. HTTP client metrics require a configured MeterProvider and instrument_http_client(..., metrics_enabled=True).

Request-Level Metrics

Bucket Boundaries: guardrails.request.duration

The duration histogram buckets use seconds:

[0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]

Saturation Metrics

These metrics expose the internal admission paths so you can detect overload before users encounter errors.

Non-Streaming Path (Admission Queue)

queued and active are read live at collection time, so dashboards always show the current state. After IORails.stop() is called, both gauges return no observations rather than stale values.

Streaming Path (Concurrency Semaphore)

Cross-Checking Saturation Metrics

At any collection instant, the sum of the per-path saturation gauges should approximately equal guardrails.requests.active:

guardrails.requests.active ≈ guardrails.nonstream.queued
                           + guardrails.nonstream.active
                           + guardrails.stream.active

A persistent drift between the two is a useful integrity check during dashboard development.

Dual-Counted Rejections

A QueueFull rejection on the non-streaming path increments both:

• guardrails.nonstream.rejections (saturation signal)
• guardrails.requests.errors{error.type=QueueFull} (error signal)

This is intentional: dashboards built around either signal alone still reflect the rejection.

HTTP Client Metrics

The canonical outbound HTTP instrumentation records one observation for each logical request, including all retry attempts performed by a wrapped retrying client.

The instrumentation normalizes the method to uppercase. The server port is the explicit URL port or the default port for http and https. A response contributes http.response.status_code. Status codes of 400 or greater also contribute error.type as the status string. A raised exception contributes its class name as error.type and has no response-status label.

The metric does not include URL paths, query parameters, headers, bodies, credentials, or exception messages. URLs without a host or a recognized port do not produce an observation.

Bucket Boundaries: http.client.request.duration

The histogram uses the OpenTelemetry HTTP client recommendation in seconds:

[0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]

Use instrument_http_client with metrics_enabled=True to enable this metric. create_http_client does not enable it automatically.

LLM Client-Side Metrics

These metrics are recorded once per downstream LLM call, not once per IORails request, and follow the OpenTelemetry GenAI semantic conventions.

Bucket Boundaries

Per the OpenTelemetry GenAI spec, durations use powers-of-two boundaries up to ~82 s:

[0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92]

Token counts use powers-of-four boundaries up to ~67M tokens:

[1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864]

Both match the spec exactly so backends auto-render the distributions correctly.

Streaming vs. Non-Streaming Emission

For streaming responses, token.usage is emitted only when the upstream provider returns a usage field. This is common when stream_options.include_usage=true is forwarded. When usage is absent, no observation is recorded; “no observation” is deliberately distinct from “0 tokens”.

Common Label Reference

Public API Stability

The metric names listed on this page are part of the library’s public API, so dashboards and alerts can reference them. The library tests assert on the raw strings for this reason. Bucket boundaries follow the relevant OpenTelemetry HTTP or GenAI specification and can change if those specifications change.

Related Resources

• Enable Guardrails Metrics — Minimal SDK setup with console output.
• OpenTelemetry Metrics Integration — Production exporters: OTLP, Prometheus.
• Outbound HTTP in Actions: Canonical client ownership, retries, instrumentation, and testing.
• OpenTelemetry HTTP metrics specification: Upstream HTTP client metric conventions.
• OpenTelemetry GenAI metrics specification — Upstream semantic conventions.