Skip to content

[Feature] agents: OTel GenAI semconv spans + Prometheus metrics #426

Description

@pathosDev

Part of the agents epic #421.

Rationale

Agent workloads are opaque without per-call telemetry: which model, how many tokens, what did the turn cost, which tool failed. The framework already ships OTel tracing (W3C traceparent across actor hops and cluster links) and a Prometheus exporter — the agents module wires into both, following the OpenTelemetry GenAI semantic conventions.

Scope

  • Spans via the existing tracing extension: agent.turnchat <model> (gen_ai.* attributes: system, request.model, usage input/output tokens, finish reason) ⊃ execute_tool <name> (tool name, call id); the trace carrier flows through ToolInvoke (cluster-compatible).
  • Prometheus metrics via MetricsExtension: agent_tokens_total{direction,model}, agent_cost_usd_total{model}, agent_tool_calls_total{tool,outcome}, agent_model_latency_ms, agent_turn_iterations, agent_sessions_active.
  • Cost derived from a config-driven price table (actor-ts.agents.pricing.*) — never hardcoded.
  • Mind label cardinality ([Security] Prometheus cardinality attack via user-controlled label values #131): model/tool names only, never session ids as label values.

Documentation

"Observability for agents" docs page (EN + DE); JSDoc; CHANGELOG.

Acceptance

  • RecordingTracer-based tests assert span hierarchy + gen_ai attributes for a scripted turn incl. a tool call; metrics assertions for tokens/cost/outcome counters.

Relates

Epic #421; #131 (cardinality), #196 (histograms). Depends on the ChatModel/ToolRegistry/AgentActor issues.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions