Legion.OpenTelemetry (Legion v0.7.0)

View Source

Turns Legion's work into OpenTelemetry traces: an invoke_agent <agent> span per turn, an execute_tool sandbox span per code evaluation, and ReqLLM's chat spans, which Legion attaches under its own handler. See the Observability guide for the trace shape and vendor setup.

Legion only depends on opentelemetry_api, optionally; without it attach/1 returns {:error, :opentelemetry_unavailable}. Options can also be set in config :legion, Legion.OpenTelemetry; options given to attach/1 win.

Message content is recorded by default

Unlike ReqLLM.OpenTelemetry, Legion defaults to content: :attributes, so prompts, replies, generated code, tool results and error messages reach the tracing backend. Attach with content: :none to keep them out.

That covers every ReqLLM call in the app: while attached, Legion sets payloads: :raw in config :req_llm, telemetry:, unless you set :payloads there, so your other handlers of ReqLLM's telemetry events receive raw prompts and replies too. detach/0 puts your setting back. A call that passes its own telemetry: option needs payloads: :raw in it, since ReqLLM then reads that option instead of the config.

Options

  • :adapter - a Legion.OpenTelemetry.Adapter, or :braintrust, :datadog, :otel. Defaults to Legion.OpenTelemetry.Adapter.OTel. Legion.OpenTelemetry.Exporter always exports to the vendor adapter named in config.
  • :vendor - the vendor adapter's own settings, such as its API key. Only read from config, since the exporter starts before attach/1 runs.
  • :content - :attributes (default) records message content, :none leaves it out, and a failed span's status then names only its error.type.
  • :max_attribute_bytes - longest content attribute on Legion's own spans, cut on a UTF-8 boundary. Defaults to 100_000, above the 40 KB an agent shows the model per message by default.
  • :iteration_spans - true adds an iteration N span per executor iteration. Defaults to false.
  • :conversation_traces - true puts an agent's turns in one trace under a conversation <agent> root span. Defaults to false.
  • :req_llm - extra options for ReqLLM.OpenTelemetry.attach/2, or false for hosts that attach it themselves. A host's own attach or :adapter there gets chat spans' error text and server-side tool arguments unfiltered, whatever :content says.

Example

# application.ex
:ok = Legion.OpenTelemetry.attach()

Summary

Functions

Attaches the OpenTelemetry integration. See the module docs for options.

Returns the active configuration, or nil when not attached.

Detaches the integration.

Returns the handler id Legion attaches ReqLLM.OpenTelemetry under.

Functions

attach(opts \\ [])

Attaches the OpenTelemetry integration. See the module docs for options.

Safe to call again: the new options replace the earlier attachment. Raises on unknown options, and on an incomplete vendor setup in config (naming the option, never its value).

config()

Returns the active configuration, or nil when not attached.

detach()

Detaches the integration.

req_llm_handler_id()

Returns the handler id Legion attaches ReqLLM.OpenTelemetry under.