Principle:Guardrails ai Guardrails Telemetry

Overview

The Telemetry principle covers the observability instrumentation architecture in Guardrails. The framework uses OpenTelemetry-based tracing to capture execution spans across the entire validation pipeline, including runner steps, LLM calls, and individual validation operations. These spans form a hierarchical trace that represents the full lifecycle of a Guard execution, from initial invocation through LLM interaction to final validation outcome.

Telemetry is implemented through tracing decorators that wrap key functions in the pipeline. When telemetry is enabled, these decorators automatically create OpenTelemetry spans, record timing information, attach relevant attributes (such as token counts, model names, and validator identifiers), and propagate trace context across function boundaries. This decorator-based approach keeps instrumentation concerns separate from business logic, allowing telemetry to be enabled or disabled without modifying the core validation code.

The telemetry data enables several operational capabilities: performance profiling of the validation pipeline to identify bottlenecks, error tracking to diagnose failures in LLM calls or validators, cost monitoring through token count aggregation, and audit logging for compliance purposes. By building on the OpenTelemetry standard, Guardrails telemetry integrates with any OpenTelemetry-compatible backend, including Jaeger, Zipkin, Datadog, and Grafana Tempo.

Theoretical Basis

The Telemetry architecture is based on the Decorator (or Wrapper) pattern, where tracing decorators augment the behavior of existing functions without altering their signatures or core logic. This is a classic application of the Aspect-Oriented Programming (AOP) concept, where cross-cutting concerns like logging and tracing are modularized into reusable aspects rather than being scattered throughout the codebase.

The span hierarchy follows the Distributed Tracing model standardized by OpenTelemetry. Each span represents a unit of work with a start time, end time, status, and set of attributes. Spans are organized in a parent-child tree that mirrors the call graph of the validation pipeline. The root span corresponds to the Guard invocation, child spans correspond to runner steps and LLM calls, and leaf spans correspond to individual validator executions. This hierarchical model enables both coarse-grained latency analysis (total Guard execution time) and fine-grained debugging (time spent in a specific validator).

Related Pages

Implementations

• Implementation:Guardrails_ai_Guardrails_Runner_Tracing
• Implementation:Guardrails_ai_Guardrails_Runner_Tracing

Workflows

(To be connected)