Configure GuardrailsConfiguring YAML File

Tracing Configuration for the NVIDIA NeMo Guardrails Library

View as Markdown

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:

1tracing:
2    enabled: true
3    adapters:
4        - name: FileSystem
5          filepath: "./logs/traces.jsonl"

Configuration Options

OptionDescriptionDefault
enabledEnable or disable tracingfalse
adaptersList of tracing adapters[]
span_formatSpan structure for LLMRails tracing path: opentelemetry (recommended) or legacy (deprecated)opentelemetry
enable_content_captureCapture prompt and response content on spans. May include PII. See Content Capturefalse

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:

1tracing:
2    enabled: true
3    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):

1tracing:
2    enabled: true
3    adapters:
4        - name: FileSystem
5          filepath: "./logs/traces.jsonl"
OptionDescription
filepathPath to the trace output file

OpenTelemetry Adapter

Integrate with observability platforms (recommended for production):

1tracing:
2    enabled: true
3    adapters:
4        - 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

AdapterUse CaseConfiguration
FileSystemDevelopment, debugging, simple loggingfilepath: "./logs/traces.jsonl"
OpenTelemetryProduction, monitoring platforms, distributed systemsRequires application-level SDK configuration

Multiple Adapters

Configure multiple adapters simultaneously:

1tracing:
2    enabled: true
3    adapters:
4        - name: FileSystem
5          filepath: "./logs/traces.jsonl"
6        - name: OpenTelemetry

Trace Information

Traces capture the following information:

DataDescription
Rail ActivationWhich rails get triggered during the conversation
LLM CallsLLM invocations, parameters, token usage, and prompts and responses when content capture is enabled
Flow ExecutionColang flow execution paths and timing
ActionsCustom action invocations and results
ErrorsError conditions and debugging information
TimingDuration of each operation

Example Configurations

Development Configuration

1tracing:
2    enabled: true
3    adapters:
4        - name: FileSystem
5          filepath: "./logs/traces.jsonl"

Production Configuration

1tracing:
2    enabled: true
3    adapters:
4        - name: OpenTelemetry

Comprehensive Configuration

1tracing:
2    enabled: true
3    adapters:
4        # Local logs for debugging
5        - name: FileSystem
6          filepath: "./logs/traces.jsonl"
7        # Export to observability platform
8        - name: OpenTelemetry

OpenTelemetry Setup

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

1from opentelemetry import trace
2from opentelemetry.sdk.trace import TracerProvider
3from opentelemetry.sdk.trace.export import BatchSpanProcessor
4from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
5
6# Configure the tracer provider
7provider = TracerProvider()
8processor = BatchSpanProcessor(OTLPSpanExporter())
9provider.add_span_processor(processor)
10trace.set_tracer_provider(provider)
11
12# 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