Skip to content

Configure Claude Code to publish to the collector

Claude Code publishes telemetry through the standard OpenTelemetry exporter. Set the documented Claude Code environment variables to point at the local collector.

This page covers only what you need to set. For the full list of variables, signals, and the data each one emits, follow the upstream reference: Claude Code → Monitoring usage.

Prerequisites

Finish Deploy the collector on the host first. The collector must be running and aris-collector status must show a healthy forwarder before Claude Code has anywhere to send envelopes to.

Quick start

Set the Claude Code telemetry environment variables and start claude in a fresh shell:

# Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# Pick the OTLP exporter for both metrics and logs/events
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp

# Point at the local collector
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Run Claude Code
claude

The collector also accepts OTLP/HTTP on 127.0.0.1:4318 if you prefer OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf with OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318.

No OTEL_EXPORTER_OTLP_HEADERS is needed — the collector does not require auth on its loopback receiver.

The default export intervals (60 seconds for metrics, 5 seconds for logs) are fine for steady-state use. While verifying the install, the upstream docs suggest shorter intervals such as OTEL_METRIC_EXPORT_INTERVAL=10000 so you do not have to wait a full minute for the first envelope to land.

Optional: enable tracing

Distributed tracing is opt-in on the Claude Code side. To get span data alongside metrics and events, follow the Traces (beta) section of the upstream docs and set:

export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp

The collector accepts traces over the same 127.0.0.1:4317 listener; no extra ARIS configuration is required.

Verify the connection

In another shell on the same host, watch the collector's view of incoming envelopes:

aris-collector status --config /etc/aris/collector/collector.yaml

You should see counts on the OTLP source increase within a minute of running claude. If they don't, check:

  1. aris-collector status shows the OTLP source as enabled. If it is missing, set sources.otel.enabled: true in collector.yaml and restart.
  2. lsof -iTCP:4317 -sTCP:LISTEN -P on the host shows aris-collector listening on 127.0.0.1:4317 (or :4318 if you chose HTTP).
  3. Claude Code is reading the variables. The simplest check is to also enable console export with OTEL_METRICS_EXPORTER=console,otlp and confirm metric records print to the terminal.
  4. The shell that launched claude actually has the variables exported. Variables set after claude started are not picked up.

Distribute the configuration to a fleet

For a single workstation the env-var approach is fine. For a fleet, use Claude Code's managed settings file, which can be pushed by MDM. The same values go in:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317"
  }
}

Per the upstream docs, environment variables defined in the managed settings file have high precedence and cannot be overridden by users — that is the right setting to use when telemetry to ARIS is a policy, not a preference.

Tag sessions with team or cost-centre attributes

If you want to slice ARIS reports by team, department, or cost centre, use Claude Code's standard OTEL_RESOURCE_ATTRIBUTES variable:

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

The collector preserves these resource attributes through to core, where they become facets you can filter on. Mind the strict formatting rules — no spaces, no quotes, comma-separated key=value.

Privacy: what ARIS sees by default

Claude Code redacts a number of fields unless you explicitly opt in. The defaults are conservative and ARIS is happy to operate on the redacted stream — most reports work from metrics and event metadata, not prompt content.

The relevant gates, all defined by Claude Code itself, are documented in the Security and privacy section of the upstream docs. The short version:

Variable Default What enabling it gives ARIS
OTEL_LOG_USER_PROMPTS off Verbatim prompt text on user_prompt events
OTEL_LOG_TOOL_DETAILS off Bash commands, MCP/skill names, tool input arguments on tool_result events
OTEL_LOG_TOOL_CONTENT off Tool input/output bodies on trace spans (requires tracing)
OTEL_LOG_RAW_API_BODIES off Full Anthropic Messages API request/response bodies as separate events

Enable these only after a deliberate decision about what your ARIS deployment should retain. They each broaden what is sent over the wire to the collector and into core's storage. For most observability use cases the defaults are sufficient.

Claude Desktop

Claude Code launched inside the Claude desktop app reads the same OTEL_* environment variables as the standalone CLI. No additional configuration is needed — once the variables are set in the user's environment, Desktop-hosted sessions report through the same path.

If you want to slice ARIS reports by surface (CLI vs. Desktop), keep sources.process.enabled: true in collector.yaml. Without it, ARIS cannot distinguish CLI from Desktop sessions. See Deploy the collector §4 for the relevant config block.

For the dedicated Cowork surface, see the Claude Cowork page — it has its own admin settings path inside Claude Desktop.

See also