Tracing Configuration for the NVIDIA NeMo Guardrails Library | NVIDIA NeMo Guardrails Library Developer Guide

This section describes how to configure tracing and monitoring in the config.yml file.

Overview

The NeMo Guardrails library includes tracing capabilities to monitor and debug guardrails interactions. Tracing helps you understand rail activation, LLM call patterns, flow execution, and error conditions.

The `tracing` Key

Configure tracing in config.yml:

tracing:
    enabled: true
    adapters:
        - name: FileSystem
          filepath: "./logs/traces.jsonl"

Configuration Options

Option	Description	Default
`enabled`	Enable or disable tracing	`false`
`adapters`	List of tracing adapters	`[]`
`span_format`	Span structure for LLMRails tracing path: `opentelemetry` (recommended) or `legacy` (deprecated)	`opentelemetry`
`enable_content_capture`	Capture prompt and response content on spans. May include PII. See Content Capture	`false`

Content Capture

By default, traces record metadata about each request but not the prompt or response content. Set enable_content_capture: true to additionally record message content on spans:

tracing:
    enabled: true
    enable_content_capture: true # caution: may capture PII; see privacy considerations

Content capture records user inputs and model outputs, which can include sensitive information (PII). The behavior, environment variable overrides, and output format differ between the IORails and LLMRails engines. See Content Capture for the full contract.

Tracing Adapters

FileSystem Adapter

Log traces to local JSON files (recommended for development):

tracing:
    enabled: true
    adapters:
        - name: FileSystem
          filepath: "./logs/traces.jsonl"

Option	Description
`filepath`	Path to the trace output file

OpenTelemetry Adapter

Integrate with observability platforms (recommended for production):

tracing:
    enabled: true
    adapters:
        - name: OpenTelemetry

To use OpenTelemetry tracing, install the tracing dependencies: pip install nemoguardrails[tracing]

OpenTelemetry integration requires configuring the OpenTelemetry SDK in your application code. The NeMo Guardrails library follows OpenTelemetry best practices where libraries use only the API and applications configure the SDK.

Adapter Comparison

Adapter	Use Case	Configuration
FileSystem	Development, debugging, simple logging	`filepath: "./logs/traces.jsonl"`
OpenTelemetry	Production, monitoring platforms, distributed systems	Requires application-level SDK configuration

Multiple Adapters

Configure multiple adapters simultaneously:

tracing:
    enabled: true
    adapters:
        - name: FileSystem
          filepath: "./logs/traces.jsonl"
        - name: OpenTelemetry

Trace Information

Traces capture the following information:

Data	Description
Rail Activation	Which rails get triggered during the conversation
LLM Calls	LLM invocations, parameters, token usage, and prompts and responses when content capture is enabled
Flow Execution	Colang flow execution paths and timing
Actions	Custom action invocations and results
Errors	Error conditions and debugging information
Timing	Duration of each operation

Example Configurations

Development Configuration

tracing:
    enabled: true
    adapters:
        - name: FileSystem
          filepath: "./logs/traces.jsonl"

Production Configuration

tracing:
    enabled: true
    adapters:
        - name: OpenTelemetry

Comprehensive Configuration

tracing:
    enabled: true
    adapters:
        # Local logs for debugging
        - name: FileSystem
          filepath: "./logs/traces.jsonl"
        # Export to observability platform
        - name: OpenTelemetry

OpenTelemetry Setup

To use OpenTelemetry in production, configure the SDK in your application:

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
# Configure the tracer provider
provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Now NeMo Guardrails will export traces to your configured backend

Viewing Traces

FileSystem Traces

View JSON traces from the filesystem:

cat ./logs/traces.jsonl | jq .

OpenTelemetry Traces

View traces in your configured observability platform:

Jaeger
Zipkin
Grafana Tempo
Datadog
New Relic

Tracing Guide - Detailed tracing setup and examples
Detailed Logging - Additional logging options