Implementation:Guardrails ai Guardrails Validator Tracing

Knowledge Sources	Guardrails
Domains	Telemetry, Validation
Last Updated	2026-02-14 00:00 GMT

Overview

Provides OpenTelemetry-based tracing decorators for synchronous and asynchronous validator execution in the Guardrails framework.

Description

The Validator Tracing module implements instrumentation for validator operations using OpenTelemetry spans. It contains three primary components:

• add_validator_attributes -- A helper function that populates an OpenTelemetry span with detailed validator metadata, including the validator name, instance ID, on-fail descriptor, initialization kwargs, input values, and validation output. It also integrates with OpenInference semantic conventions when available, setting both legacy and new-style span attributes.

• trace_validator -- A decorator factory for synchronous validator functions. When tracing is enabled (via settings.disable_tracing), it creates a child span named {validator_name}.validate, invokes the wrapped function, records all attributes on success or sets an error status on failure, and re-raises any exceptions. When tracing is disabled, it simply calls the underlying function directly.

• trace_async_validator -- An identical decorator factory for asynchronous validator functions, using async/await semantics while maintaining the same tracing behavior.

The module optionally integrates with the OpenInference semantic conventions library to tag spans with OPENINFERENCE_SPAN_KIND = "GUARDRAIL".

Usage

Use this module when you need to instrument validator execution with distributed tracing. The trace_validator and trace_async_validator decorators are applied to validator validate methods at runtime (typically from ValidatorServiceBase.execute_validator) to capture telemetry data about each validation invocation, including inputs, outputs, timing, and error states.

Code Reference

Source Location

• Repository: Guardrails
• File: guardrails/telemetry/validator_tracing.py

Signature

def add_validator_attributes(
    *args,
    validator_span: Span,
    validator_name: str,
    obj_id: int,
    on_fail_descriptor: Optional[str] = None,
    result: Optional[ValidationResult] = None,
    init_kwargs: Dict[str, Any] = {},
    validation_session_id: str,
    **kwargs,
) -> None: ...

def trace_validator(
    validator_name: str,
    obj_id: int,
    on_fail_descriptor: Optional[str] = None,
    tracer: Optional[Tracer] = None,
    *,
    validation_session_id: str,
    **init_kwargs,
) -> Callable: ...

def trace_async_validator(
    validator_name: str,
    obj_id: int,
    on_fail_descriptor: Optional[str] = None,
    tracer: Optional[Tracer] = None,
    *,
    validation_session_id: str,
    **init_kwargs,
) -> Callable: ...

Import

from guardrails.telemetry.validator_tracing import (
    add_validator_attributes,
    trace_validator,
    trace_async_validator,
)

I/O Contract

add_validator_attributes

Parameter	Type	Description
*args	Any	Positional arguments; first is the input value, second is metadata dict
validator_span	Span	The OpenTelemetry span to annotate
validator_name	str	Name of the validator being traced
obj_id	int	Instance ID of the validator object (from id())
on_fail_descriptor	Optional[str]	The on-fail action descriptor (e.g. "fix", "reask", "noop")
result	Optional[ValidationResult]	The validation result, if available
init_kwargs	Dict[str, Any]	Keyword arguments passed to the validator constructor
validation_session_id	str	Unique identifier for the current validation session
**kwargs	Any	Additional keyword arguments recorded as span attributes

Returns: None (mutates the span in-place)

trace_validator / trace_async_validator

Parameter	Type	Description
validator_name	str	Name of the validator
obj_id	int	Instance ID of the validator object
on_fail_descriptor	Optional[str]	The on-fail action descriptor
tracer	Optional[Tracer]	Optional OpenTelemetry tracer (a default tracer is created internally)
validation_session_id	str	Unique identifier for the current validation session
**init_kwargs	Any	Validator constructor keyword arguments for attribute recording

Returns: A decorator that wraps the validator function. The wrapped function returns Optional[ValidationResult].

Span Attributes Set

Attribute	Description
type	Always "guardrails/guard/step/validator"
validation_session_id	Session identifier
validator.name	Validator name
validator.on_fail	On-fail action descriptor
validator.instance_id	Validator instance ID
validator.init.{key}	Each init kwarg
validator.validate.input.value	Serialized input value
validator.validate.input.metadata	Serialized input metadata
validator.validate.output.{key}	Each output field from the result dict

Usage Examples

from guardrails.telemetry.validator_tracing import trace_validator

# Decorate a synchronous validator function
@trace_validator(
    validator_name="my_validator",
    obj_id=12345,
    on_fail_descriptor="reask",
    validation_session_id="session-abc-123",
    threshold=0.8,
)
def my_validate_func(value, metadata):
    # Perform validation logic
    return ValidationResult(outcome="pass", metadata={})

result = my_validate_func("some input", {"key": "value"})

from guardrails.telemetry.validator_tracing import trace_async_validator

# Decorate an asynchronous validator function
@trace_async_validator(
    validator_name="my_async_validator",
    obj_id=67890,
    on_fail_descriptor="fix",
    validation_session_id="session-def-456",
)
async def my_async_validate_func(value, metadata):
    # Perform async validation logic
    return ValidationResult(outcome="pass", metadata={})

result = await my_async_validate_func("some input", {"key": "value"})

Related Pages

• Guardrails_ai_Guardrails_ValidatorServiceBase -- Uses trace_validator in execute_validator
• Guardrails_ai_Guardrails_Telemetry_Common -- Provides add_user_attributes and serialize helpers
• Guardrails_ai_Guardrails_OpenInference -- Provides trace_operation for OpenInference integration