Connecting Claude Code

Connect Claude Code to CloudZero to bring your Claude Code usage and cost data into a unified view of all your cloud and AI spend. Claude Code (Anthropic's coding agent) exports its own OpenTelemetry traces natively, so you can send telemetry straight to CloudZero from the CLI. There is no gateway, proxy, or macOS agent to install. Once connected, you organize Claude Code costs alongside your other costs using Dimensions that matter to your business, such as team, product, or environment.

This guide covers enabling Claude Code's enhanced telemetry and pointing its OTLP trace exporter at the dedicated CloudZero route.

How it works

Claude Code exports OpenTelemetry traces over OTLP/HTTP. CloudZero recognizes Claude Code's spans by name and turns each one into a cost and usage event. Activity appears in AI Signals within a few minutes of usage, and full cost exploration in the Explorer follows within about 24 hours.

CloudZero displays exactly the metadata Claude Code sends. Nothing is added, inferred, or reshaped. CloudZero never reads or stores prompt or response content. Only model, token, timing, and status metadata are ingested.

What you need

• A CloudZero user with API key access
• Claude Code installed and in use by the team you are onboarding
• Outbound HTTPS connectivity from every machine running Claude Code to telemetry.cloudzero.com on port 443

Step 1: Create a CloudZero API key

1. In CloudZero, go to Settings > API Keys.
2. Create a new API key.
3. Under Scopes, open the Ai-Telemetry-Ingest category and select ingest-claude-code-v1.
4. Copy the key value and store it securely. You set it as an environment variable in Step 2. Treat it like any other secret.

Step 2: Enable telemetry and point it at CloudZero

Set these environment variables wherever Claude Code runs, such as a developer's shell profile, a CI environment, or the managed settings file for an org-wide rollout (Step 3):

CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://telemetry.cloudzero.com/v2/telemetry/claude-code
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=Authorization=<your-cloudzero-api-key>

Step 3: Roll out org-wide (optional)

Once you have confirmed data is flowing from one machine (Step 4), put the same variables in Claude Code's managed settings file so every developer picks them up automatically, with nothing to set themselves:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux: /etc/claude-code/managed-settings.json

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": "https://telemetry.cloudzero.com/v2/telemetry/claude-code",
    "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=<your-cloudzero-api-key>"
  }
}

Managed settings take precedence over anything a user sets themselves and cannot be overridden, so this is the reliable way to guarantee every developer's Claude Code reports to CloudZero. See Claude Code's settings documentation for other operating systems or MDM-based deployment.

Step 4: Send traffic and verify

1. Export the variables from Step 2, or deploy the managed settings from Step 3, on a machine running Claude Code.
2. Use Claude Code normally for a few minutes.
3. Open CloudZero and watch the AI Signals view for activity.

You should see activity in the AI Signals view within a few minutes of usage. The Explorer follows within about 24 hours.

Smoke-test authentication and routing

Before you wait on real usage, you can confirm your key and route work. An empty POST should return HTTP 202:

curl -i -X POST \
  "https://telemetry.cloudzero.com/v2/telemetry/claude-code" \
  -H "Authorization: <your-cloudzero-api-key>" \
  -H "Content-Type: application/x-protobuf" \
  --data-binary $'\x00'

Expected response:

HTTP/2 202
content-type: application/json

{"status":"accepted"}

A 202 confirms authentication, scope, and routing are good. A 403 means the key is missing the ingest-claude-code-v1 scope, so re-check Step 1.

What to expect

After you connect, Claude Code activity works like any other cost data in CloudZero:

• AI Signals: normalized Claude Code inference events as they arrive, showing model, token counts, and timing. Events appear within a few minutes of usage.
• Explorer: the downstream exploration experience, breaking down cost by model over time. This data is processed downstream of ingest, so allow about 24 hours after activity for it to appear here.

From there, you can explore your Claude Code costs in the Explorer, organize them by team or product using Dimensions, track trends in Dashboards, set Budgets, or ask questions in the AI Hub.

Data privacy

Claude Code redacts prompt and tool content from its telemetry by default, so there is nothing you need to configure to keep that data from leaving the machine. As with every CloudZero telemetry route, CloudZero never reads or stores prompt or response content even when it is present. Only model, token, and timing metadata are ingested.

Troubleshooting

If data is not appearing in the AI Signals view 5 minutes after confirmed Claude Code usage, work through these in order.

1. Missing the enhanced-telemetry beta flag. The most common cause. CLAUDE_CODE_ENABLE_TELEMETRY=1 alone is not enough. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 is also required for traces. Re-check Step 2.
2. Wrong endpoint variable (appends /v1/traces). Use OTEL_EXPORTER_OTLP_TRACES_ENDPOINT set to https://telemetry.cloudzero.com/v2/telemetry/claude-code. Do not use the generic OTEL_EXPORTER_OTLP_ENDPOINT.
3. Pointed at the wrong CloudZero route. Claude Code must go to /v2/telemetry/claude-code, not the generic /v2/telemetry/otel-genai. The generic route does not recognize Claude Code's spans and silently drops them.
4. Wrong protocol. OTEL_EXPORTER_OTLP_TRACES_PROTOCOL must be http/protobuf. CloudZero's ingest does not accept gRPC.
5. Bearer prefix on the API key. The header value must be the raw key, such as Authorization=<your-cloudzero-api-key>, not Authorization=Bearer <your-cloudzero-api-key>.
6. Missing scope. A 403 on the smoke test means the key lacks ingest-claude-code-v1. Re-check Step 1.
7. Old Claude Code version. Enhanced telemetry is a beta feature. If the flags have no effect, update Claude Code and retry.
8. Config not picked up. Environment variables are read at startup. Open a new terminal or restart the process after any change. If you are using managed settings, confirm the file is at the exact path Claude Code expects for the operating system.