Skip to navigation
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:

tracing:
  enabled: true
  adapters:
    - name: FileSystem
      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):

tracing:
  enabled: true
  adapters:
    - name: FileSystem
      filepath: "./logs/traces.jsonl"
OptionDescription
filepathPath 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. 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:

tracing:
  enabled: true
  adapters:
    - name: FileSystem
      filepath: "./logs/traces.jsonl"
    - 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

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