Claude Agent Telemetry

Drop-in OpenTelemetry instrumentation for Claude Agent SDK. Add full observability (logs, traces, metrics) with one line of code.

Quick Start

import { withTelemetry } from "@matkirit/claude-agent-telemetry";
import { query } from "@anthropic-ai/claude-agent-sdk";

// Just wrap your query - that's it
for await (const msg of withTelemetry(query({ prompt }))) {
  handleMessage(msg);
}

Configuration

Set the required environment variable:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://your-collector:4318"

All configuration is via environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OTEL_EXPORTER_OTLP_ENDPOINT | Yes | - | Your OTLP collector endpoint | | OTEL_SERVICE_NAME | No | claude-agent | Service name in telemetry | | OTEL_SERVICE_VERSION | No | 1.0.0 | Service version | | OTEL_TRACES_SAMPLER_ARG | No | 1.0 | Trace sample rate (0.0-1.0) | | TELEMETRY_ENABLED | No | true | Master switch for all telemetry |

What You Get

• Traces: Session → Turn → LLM Request / Tool spans
• Logs: Session lifecycle, tool calls, LLM responses, errors
• Metrics: Token usage, costs, durations, error counts

Installation

npm install @matkirit/claude-agent-telemetry

Kubernetes Deployment

env:
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: "http://otel-collector.monitoring:4318"
  - name: OTEL_SERVICE_NAME
    value: "my-agent"
  - name: OTEL_TRACES_SAMPLER_ARG
    value: "0.1"  # 10% sampling in production

Graceful Shutdown

import { registerShutdownHandlers } from "@matkirit/claude-agent-telemetry";

registerShutdownHandlers();  // Call once at startup

Metrics

| Metric | Type | Description | |--------|------|-------------| | agent.sessions | Counter | Total sessions | | agent.tool_calls | Counter | Tool invocations by name | | agent.tokens | Counter | Tokens by type (input/output) | | agent.cost_microdollars | Counter | Cost tracking | | agent.session.duration_ms | Histogram | Session duration | | agent.tool.duration_ms | Histogram | Tool execution time |