Instrument with OpenTelemetry

Agents are instrumented out of the box. Logs, traces, and metrics are produced without any code on your part, and you turn export on with environment variables at startup. This guide shows how to wire an agent to a backend. For what each signal means, see Observability.

Point the agent at an OTLP endpoint

Set a common OTLP/HTTP endpoint for export:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export APP_ENV=production
./artifacts/build/my_agent serve

For a receiver that accepts traces only, disable metric and log export:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.example.com
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
./artifacts/build/my_agent serve

Application logs continue to appear on stdout. For signal-specific endpoints and all exporter settings, see the observability reference.

Send to a collector or a vendor

The natural target for OTEL_EXPORTER_OTLP_ENDPOINT is an OpenTelemetry Collector, which receives all three signals and routes each one onward to the backends you use, for example a tracing store for traces, Prometheus for metrics, and a log store for logs. Because the export is standard OTLP, you can also point the agent directly at any OTLP-compatible vendor such as Honeycomb or Datadog without a collector in between.

Remove content before external export

Direct export to a backend includes full agent input and terminal state, rendered model instructions, model input and output, and local tool arguments and successful results. When that content must not leave your infrastructure, place an OpenTelemetry Collector between the agent and the external backend:

agent server
    -> OTLP/HTTP
    -> OpenTelemetry Collector
        -> delete selected content attributes
        -> batch
        -> observability backend

The Collector Contrib attributes processor can delete the large content attributes from traces:

processors:
  batch:

  attributes/remove_agent_content:
    actions:
      - key: gen_ai.system_instructions
        action: delete
      - key: gen_ai.input.messages
        action: delete
      - key: gen_ai.output.messages
        action: delete
      - key: gen_ai.tool.call.arguments
        action: delete
      - key: gen_ai.tool.call.result
        action: delete
      - key: agentc.agent.input
        action: delete
      - key: agentc.agent.output
        action: delete

service:
  pipelines:
    traces:
      processors:
        - attributes/remove_agent_content
        - batch

Deleting these attributes removes model, tool, and full agent-state content while retaining span hierarchy, operation identity, timing, provider and model identity, token usage, finish reasons, terminal status fields outside the content attributes, and errors.

Set the log level

Logs are written as structured JSON to standard output regardless of OTLP. Control their verbosity with LOG_LEVEL, which accepts trace, debug, info, warn, or error and defaults to info:

export LOG_LEVEL=debug

For target filters, see the logging reference.

Report errors to Sentry

Error reporting is separate from OTLP telemetry. Set SENTRY_DSN to capture unhandled errors and panics; the release reported is the agent version from the manifest, and APP_ENV tags the environment. When SENTRY_DSN is unset, Sentry is not initialized and adds no overhead:

export SENTRY_DSN=https://[email protected]/0
export APP_ENV=production

Where to go next

• Observability: the signals an agent emits and why they matter.
• Observability reference: every telemetry environment variable and its default.
• Deploy a standalone binary: where these variables fit in a deployment.