Observability

Parlant includes built-in support for OpenTelemetry, the industry-standard framework for observability. This allows you to export traces, metrics, and logs to your preferred backend, whether that's Jaeger, Grafana, Datadog, or any other OpenTelemetry-compatible system.

Enabling OpenTelemetry

OpenTelemetry is enabled through environment variables. Each pillar (traces, metrics, logs) can be enabled independently by setting its corresponding endpoint.

Variable	Purpose
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	Enable tracing and specify the OTLP endpoint
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	Enable metrics and specify the OTLP endpoint
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	Enable log export and specify the OTLP endpoint

Additional configuration options:

Variable	Purpose	Default
OTEL_EXPORTER_OTLP_PROTOCOL	Protocol for OTLP export (grpc or http/protobuf)	grpc
OTEL_EXPORTER_OTLP_INSECURE	Allow insecure connections (disable TLS)	false
OTEL_SERVICE_NAME	Service name for resource attributes	parlant
OTEL_METRIC_EXPORT_INTERVAL	Metrics export interval in milliseconds	3000

Example Configuration

OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://grafana-alloy.XYZ.svc.cluster.local:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://grafana-alloy.XYZ.svc.cluster.local:4318/v1/logs
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://grafana-alloy.XYZ.svc.cluster.local:4318/v1/traces

When you start the Parlant server with these variables set, you'll see confirmation messages:

OpenTelemetry tracing is enabled.
OpenTelemetry metrics is enabled.
OpenTelemetry logging is enabled.

What Gets Traced

Parlant automatically instruments key operations with spans and metrics. This gives you visibility into your agent's behavior without any code changes.

HTTP Requests

Every HTTP request to the Parlant API creates a span with:

• http.request.id - Unique request identifier
• http.request.operation - The API operation (e.g., create_event, list_events)
• http.request.method - HTTP method (GET, POST, etc.)
• Path parameters from the request

Engine Operations

The conversation engine creates spans for many operations, among which are:

Span Name	Description
process	Main processing loop for handling events
utter	Agent utterance generation
message_generation	Message composition pipeline
guideline_matcher	Guideline matching (includes phase: "initial" or "reevaluation")
tool_caller	Tool execution
response_analysis	Response quality analysis

You'll also see spans for more granular operations like LLM or embedder calls.

Metrics

Here are some of the useful metrics that Parlant exports (among others):

Metric	Type	Description
message_generation_duration	Histogram	Time to generate a response message end-to-end
ttfm_duration	Histogram	Time-to-first-message within a single response
match_duration	Histogram	Guideline matching duration

Correlating Traces with Sessions

Parlant's trace IDs are designed to help you correlate telemetry data with specific sessions and events. Each event in a session includes a trace_id field that corresponds to the OpenTelemetry trace that produced it.

This means you can:

1. See a problematic response in your frontend
2. Look up the event's trace_id
3. Search for that trace in your observability backend
4. Inspect the full processing pipeline that led to that response

Fallback Behavior

If OpenTelemetry endpoints are not configured, Parlant falls back to lightweight local implementations:

• Tracing: Uses an in-memory tracer
• Metrics: Uses a local, logging meter
• Logging: Logs to parlant-data/parlant.log

In other words, you can develop locally without any observability infrastructure, and enable it only when needed.

Need help with observability?