Configure GuardrailsConfiguring YAML File

Tracing Configuration for NeMo Guardrails

View as Markdown

Tracing Configuration

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[]

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. NeMo Guardrails 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, prompts, and responses
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