Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fintegrations%2Fai-observability%2Fclaude-code.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fintegrations%2Fai-observability%2Fclaude-code.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# Claude Code integration with Coralogix

Claude Code ships with built-in OpenTelemetry support, which means you can send its full telemetry — token usage, model costs, tool calls, code changes, and session activity — directly to Coralogix with no custom code required. Once connected, every Claude Code session in your organization streams live data to a dedicated dashboard, giving you cost visibility, usage patterns, and code impact in one place.

Setting up Claude Cowork instead?

See the [Claude Cowork integration](https://coralogix.com/docs/docs/integrations/ai-observability/claude-cowork/.md) for the admin-panel setup for Claude Cowork.

## Supported environments[​](#supported-environments "Direct link to Supported environments")

* **OS:** macOS, Linux, and Windows (native or WSL).
* **Shell:** `bash` or `zsh`. The shell-based [per-developer setup](#per-developer-setup) runs on macOS, Linux, and Windows Subsystem for Linux (WSL).

## What you need[​](#what-you-need "Direct link to What you need")

* A Coralogix account with a **Send-Your-Data [API key](https://coralogix.com/docs/docs/user-guides/account-management/api-keys/send-your-data-api-key/.md)**. In Coralogix, navigate to **Settings**, then **API Keys**.
* Your Coralogix OTLP endpoint: `ingress.eu2.coralogix.com:443`. Use the domain selector at the top of this page to select your region.
* Claude Code installed and running on your machine.

## Set up[​](#set-up "Direct link to Set up")

### Deploy org-wide with managed settings[​](#deploy-org-wide-with-managed-settings "Direct link to Deploy org-wide with managed settings")

For Claude for Teams or Enterprise (Claude Code 2.1.38 or newer), use [server-managed settings](https://code.claude.com/docs/en/server-managed-settings) to push the Coralogix configuration to every developer automatically. No shell scripts, no `.env` distribution, no per-developer action required.

1. In [Claude.ai](https://claude.ai/), navigate to **Admin Settings**, then **Claude Code**, then **Managed Settings** and select **Manage**.

2. Paste the settings JSON:

   ```
   {

     "env": {

       "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

       "OTEL_METRICS_EXPORTER": "otlp",

       "OTEL_LOGS_EXPORTER": "otlp",

       "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",

       "OTEL_EXPORTER_OTLP_ENDPOINT": "<YOUR_CX_OTLP_ENDPOINT>",

       "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer <YOUR_CX_API_KEY>",

       "OTEL_RESOURCE_ATTRIBUTES": "cx.application.name=claude-code,cx.subsystem.name=<TEAM_NAME>",

       "OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE": "delta"

     }

   }
   ```

   Replace the placeholders with your Coralogix values.

3. Select **Add settings**.

   The admin console shows the configured settings JSON:

   [![Claude.ai admin console showing the managed settings dialog with OTLP configuration](/docs/assets/images/managed-settings-admin-c3e8b5072993e31be216b3f4704439ef.webp)](https://coralogix.com/docs/docs/assets/images/managed-settings-admin-c3e8b5072993e31be216b3f4704439ef.webp)

   Settings reach all Claude Code clients at their next startup or within the hourly polling cycle.

On their next `claude` startup, developers see a one-time approval dialog listing the configured environment variables. They select **Yes, I trust these settings** and Claude Code restarts with telemetry active.

[![Claude Code terminal showing the managed settings approval prompt](/docs/assets/images/managed-settings-approval-715f170eddf429253d641bf7b709f638.webp)](https://coralogix.com/docs/docs/assets/images/managed-settings-approval-715f170eddf429253d641bf7b709f638.webp)

### Deploy org-wide without a Claude account[​](#deploy-org-wide-without-a-claude-account "Direct link to Deploy org-wide without a Claude account")

If your organization runs Claude Code against a third-party endpoint — for example, Amazon Bedrock or LiteLLM — rather than a managed Claude account, server-managed settings don't apply, so you can't push the Coralogix configuration from the Claude.ai admin console. Distribute it instead through a dedicated [managed settings file](https://code.claude.com/docs/en/settings#settings-files) deployed with your device-management (MDM) tooling.

1. Create a `managed-settings.json` file.

2. Add the same telemetry `env` block shown in [Deploy org-wide with managed settings](#deploy-org-wide-with-managed-settings), replacing the placeholders with your Coralogix values.

3. Distribute the file to every developer with your MDM tooling, following Claude Code's [managed settings guide](https://code.claude.com/docs/en/settings#settings-files). The settings reach all Claude Code clients at their next startup.

For the file locations on each platform and how this channel behaves when a proxy is active, see [Telemetry stops when Claude Code routes through a proxy or gateway](#troubleshoot-proxy-bypass).

### Per-developer setup[​](#per-developer-setup "Direct link to Per-developer setup")

Use this if your organization is not on Claude for Teams or Enterprise, or if you prefer not to use server-managed settings.

#### Install[​](#install "Direct link to Install")

Clone the Coralogix AI agent instrumentation repository and navigate to the Claude Code directory:

```
git clone https://github.com/coralogix/ai-agent-instrumentation.git

cd ai-agent-instrumentation/claude-code
```

#### Configure[​](#configure "Direct link to Configure")

1. Copy the example environment file:

   ```
   cp .env.example .env
   ```

2. Open `.env` and set the following values:

   * `CX_API_KEY` — your Send-Your-Data API key
   * `CX_OTLP_ENDPOINT` — your OTLP endpoint (`ingress.eu2.coralogix.com:443`)

3. Activate the instrumentation and start Claude Code:

   ```
   source activate.sh

   claude
   ```

   Claude Code sessions now stream telemetry to Coralogix.

#### Make it permanent[​](#make-it-permanent "Direct link to Make it permanent")

To activate instrumentation automatically in every new terminal session, add the following line to `~/.zshrc`:

```
source /path/to/claude-code/activate.sh
```

#### Advanced: set environment variables directly[​](#advanced-set-environment-variables-directly "Direct link to Advanced: set environment variables directly")

If you prefer to set the environment variables without the activation script, add the following to `~/.zshrc` or `~/.bashrc`:

```
if [ -f "$HOME/path/to/claude-code-coralogix/.env" ]; then

  set -a; source "$HOME/path/to/claude-code-coralogix/.env"; set +a

fi

export CLAUDE_CODE_ENABLE_TELEMETRY=1

export OTEL_METRICS_EXPORTER=otlp

export OTEL_LOGS_EXPORTER=otlp

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

export OTEL_EXPORTER_OTLP_ENDPOINT="${CX_OTLP_ENDPOINT}"

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${CX_API_KEY}"

export OTEL_RESOURCE_ATTRIBUTES="cx.application.name=claude-code,cx.subsystem.name=${CX_SUBSYSTEM_NAME}"

export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
```

Alternatively, set these values in Claude Code's settings file at `~/.claude/settings.json`:

```
{

  "env": {

    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

    "OTEL_METRICS_EXPORTER": "otlp",

    "OTEL_LOGS_EXPORTER": "otlp",

    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",

    "OTEL_EXPORTER_OTLP_ENDPOINT": "<YOUR_CX_OTLP_ENDPOINT>",

    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer <YOUR_CX_API_KEY>",

    "OTEL_RESOURCE_ATTRIBUTES": "cx.application.name=claude-code,cx.subsystem.name=<TEAM_NAME>",

    "OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE": "delta"

  }

}
```

## Application name and subsystem[​](#application-name-and-subsystem "Direct link to Application name and subsystem")

Coralogix organizes incoming telemetry by two resource attributes: **Application name** and **Subsystem**. For Claude Code, we recommend:

| Attribute             | Recommended value                                              | Why                                                                                                          |
| --------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `cx.application.name` | `claude-code`                                                  | Lets you filter dashboards and queries by Claude surface (e.g., distinguish Claude Code from Claude Cowork). |
| `cx.subsystem.name`   | The team name — for example, `team1`, `enterprise`, `data-eng` | Lets you filter by team and compare usage across teams.                                                      |

Example (managed settings):

```
"OTEL_RESOURCE_ATTRIBUTES": "cx.application.name=claude-code,cx.subsystem.name=platform"
```

With this convention in place, the shared Claude dashboard can be filtered by agent (which Claude surface) and by team (who's using it) from a single dropdown.

## Repository breakdown[​](#github-repository-breakdown "Direct link to Repository breakdown")

Claude Code's native telemetry reports cost and tokens per session, but not which Git repository the work touched. The Coralogix repository-tracking hook adds that dimension: it runs after every tool call, resolves the Git repository for the files Claude Code touched, and reports it to Coralogix. AI Center then attributes session cost and tokens to repositories and separates **Managed** repositories (those owned by an Organization you configure in **Settings → AI Center → Code agent**) from **Unmanaged** ones — see [Repositories](https://coralogix.com/docs/docs/user-guides/ai/code-agents/claude-code/.md#github-repos).

### How it works[​](#how-it-works "Direct link to How it works")

The hook is a Claude Code [PostToolUse hook](https://code.claude.com/docs/en/hooks): a small script that Claude Code runs after each tool call. It identifies which Git repository the files Claude Code touched belong to and reports that repository to Coralogix, so AI Center can attribute the session to it. On macOS the hook is a shell script (`claude.sh`); on Windows it's a PowerShell script (`claude.ps1`). Both use only tools that ship with the operating system — no Node, Python, or other runtime to install — and both read their Coralogix configuration from the same Claude Code settings that carry your telemetry, so there are no separate hook credentials to manage. Repositories are identified by name — for example, `your-org/your-service`; work that doesn't belong to any repository is reported as `unknown`.

A single session can touch several repositories. AI Center splits the session's cost evenly across them.

### What you need[​](#what-you-need-1 "Direct link to What you need")

The repository-tracking hook runs on **macOS and Windows**.

* The hook script for each platform — `claude.sh` (macOS) and `claude.ps1` (Windows) — from the [Coralogix AI agent instrumentation repository](https://github.com/coralogix/ai-agent-instrumentation/tree/master/claude-code).
* A Coralogix Send-Your-Data API key — the same key you use for OTLP.
* No extra runtime. The macOS hook uses `/bin/sh`, `plutil`, and `curl`; the Windows hook uses Windows PowerShell 5.1. All ship with the operating system, so there is nothing to install, sign, or build per architecture.
* **`git`** is optional. The hook calls `git` to resolve repository names; without it, that machine reports `repository_name="unknown"`.

The hook reads its configuration from your Claude Code settings

Claude Code doesn't reliably pass its `env` block to hook subprocesses — it strips `OTEL_*` variables, and on Windows drops the block entirely ([claude-code#20112](https://github.com/anthropics/claude-code/issues/20112)). Instead, the hook reads `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`, and `OTEL_RESOURCE_ATTRIBUTES` directly from the same Claude Code settings files that hold your telemetry configuration. Configure those values once in the `env` block — there are no separate hook credentials.

### Per-operating-system values[​](#per-operating-system-values "Direct link to Per-operating-system values")

Deploy each platform's hook script to a stable path. A single hook command (shown below) detects the operating system and runs the matching script.

| Operating system | Hook script  | Deploy path                                       | Built-in runtime            |
| ---------------- | ------------ | ------------------------------------------------- | --------------------------- |
| macOS            | `claude.sh`  | `/usr/local/bin/claude.sh`                        | `/bin/sh`, `plutil`, `curl` |
| Windows          | `claude.ps1` | `C:\ProgramData\Coralogix\claude-code\claude.ps1` | Windows PowerShell 5.1      |

On macOS, make `claude.sh` readable and executable by the account that runs Claude Code.

### Deploy org-wide with device management[​](#deploy-org-wide-with-device-management "Direct link to Deploy org-wide with device management")

To roll the hook out to every developer, deploy each platform's hook script with your device-management tooling — Jamf for macOS, Microsoft Intune for Windows — then distribute the `hooks` block through managed settings. Deploy the script files before the managed settings reach a machine; the hook command exits cleanly when the script isn't present yet, so an out-of-order rollout produces no session errors. Developers approve the settings once, exactly as with the base telemetry configuration.

The managed-settings block is your base telemetry `env` block plus a single `hooks.PostToolUse` command that dispatches by operating system — no hook-specific keys:

```
{

  "env": {

    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

    "OTEL_METRICS_EXPORTER": "otlp",

    "OTEL_LOGS_EXPORTER": "otlp",

    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",

    "OTEL_EXPORTER_OTLP_ENDPOINT": "<YOUR_CX_OTLP_ENDPOINT>",

    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer <YOUR_CX_API_KEY>",

    "OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE": "delta",

    "OTEL_RESOURCE_ATTRIBUTES": "cx.application.name=claude-code,cx.subsystem.name=<TEAM_NAME>"

  },

  "hooks": {

    "PostToolUse": [

      {

        "hooks": [

          { "type": "command", "command": "case \"$(uname -s)\" in Darwin) [ -x /usr/local/bin/claude.sh ] && exec /bin/sh /usr/local/bin/claude.sh; exit 0;; MINGW*|MSYS*|CYGWIN*) [ -f \"C:/ProgramData/Coralogix/claude-code/claude.ps1\" ] && exec powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:/ProgramData/Coralogix/claude-code/claude.ps1; exit 0;; *) exit 0;; esac" }

        ]

      }

    ]

  }

}
```

On Windows, Claude Code runs hook commands through Git Bash, which is why one `uname`-based command serves both platforms. The [Coralogix AI agent instrumentation repository](https://github.com/coralogix/ai-agent-instrumentation/tree/master/claude-code) provides ready-to-use deployment scripts: `deploy-jamf.sh` installs `claude.sh` to `/usr/local/bin` on macOS, and `deploy-windows.ps1` installs `claude.ps1` to `C:\ProgramData\Coralogix\claude-code` on Windows.

### Install for one developer[​](#install-for-one-developer "Direct link to Install for one developer")

1. Copy your platform's hook script to its stable path — `claude.sh` to `/usr/local/bin/claude.sh` on macOS, or `claude.ps1` to `C:\ProgramData\Coralogix\claude-code\claude.ps1` on Windows.

2. Register it as a PostToolUse hook in `~/.claude/settings.json`. The hook reads its Coralogix configuration from the same `env` block, so there are no extra credentials to set. The full file looks like this:

   ```
   {

     "env": {

       "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

       "OTEL_METRICS_EXPORTER": "otlp",

       "OTEL_LOGS_EXPORTER": "otlp",

       "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",

       "OTEL_EXPORTER_OTLP_ENDPOINT": "<YOUR_CX_OTLP_ENDPOINT>",

       "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer <YOUR_CX_API_KEY>",

       "OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE": "delta",

       "OTEL_RESOURCE_ATTRIBUTES": "cx.application.name=claude-code,cx.subsystem.name=<TEAM_NAME>"

     },

     "hooks": {

       "PostToolUse": [

         {

           "hooks": [

             { "type": "command", "command": "case \"$(uname -s)\" in Darwin) [ -x /usr/local/bin/claude.sh ] && exec /bin/sh /usr/local/bin/claude.sh; exit 0;; MINGW*|MSYS*|CYGWIN*) [ -f \"C:/ProgramData/Coralogix/claude-code/claude.ps1\" ] && exec powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:/ProgramData/Coralogix/claude-code/claude.ps1; exit 0;; *) exit 0;; esac" }

           ]

         }

       ]

     }

   }
   ```

   The only addition on top of the base telemetry configuration is the `hooks.PostToolUse` entry, which registers the platform's hook script to run after every tool call.

3. Start a new Claude Code session. The hook reports a repository the first time Claude Code touches a file.

### Classify repositories as Managed or Unmanaged[​](#classify-repositories-as-managed-or-unmanaged "Direct link to Classify repositories as Managed or Unmanaged")

Repository names alone don't tell AI Center which repositories belong to your company. In **Settings → AI Center → Code agent**, configure the **Organizations** that own your repositories — sessions on a matched repository are labeled **Managed**, and everything else is **Unmanaged**. Until you configure an Organization, every repository appears as Unmanaged.

For the steps and the full classification rules, see [Classify repositories as Managed or Unmanaged](https://coralogix.com/docs/docs/user-guides/ai/code-agents/repository-breakdown/.md#classify-repositories).

## View in AI Center[​](#view-in-ai-center "Direct link to View in AI Center")

Once your Claude Code sessions are streaming telemetry, navigate to **AI Center > Code Agents > Claude** to see the unified Claude dashboard. The **Select an application** dropdown lists every `<application> - <subsystem>` pair you configured (for example, `claude-code - team1`, `claude-code - team2`), so you can slice usage, cost, sessions, and token data by team. If you also instrument [Claude Cowork](https://coralogix.com/docs/docs/integrations/ai-observability/claude-cowork/.md), Cowork data appears in the same dashboard.

[![AI Center Code Agents Claude tab showing the application dropdown with claude-code and claude-cowork entries grouped by team, alongside total sessions, token usage, estimated cost, and cost-over-time widgets](/docs/assets/images/ai-center-claude-tab-c2889f694a25cdd86addaa5436a98f19.webp)](https://coralogix.com/docs/docs/assets/images/ai-center-claude-tab-c2889f694a25cdd86addaa5436a98f19.webp)

How displayed cost is calculated

The dashboard cost is derived from the usage metrics Claude Code sends to Coralogix, displayed as-is — it does not factor in your Anthropic subscription plan, so it is accurate for usage-billed **Enterprise** plans and an estimate for others.

To tell plans apart, set `cx.subsystem.name` to the plan or team name (see [Application name and subsystem](#application-name-and-subsystem)) and filter on it. For the full accuracy caveats, see [Dashboard costs don't match the Anthropic invoice](#troubleshoot-cost-accuracy).

## Validate the integration[​](#validate-the-integration "Direct link to Validate the integration")

After running a Claude Code session, confirm that data is flowing:

1. In Coralogix, navigate to **Metrics Explorer** and search for the metric prefix `claude_code`. Token usage and cost data appear here.
2. Navigate to **Logs** and filter by your application and subsystem names to see tool call and session events.
3. Open [Code Agents Intelligence](https://coralogix.com/docs/docs/user-guides/ai/code-agents/.md) to see the full session dashboard.

## Monitor data in Coralogix[​](#monitor-data-in-coralogix "Direct link to Monitor data in Coralogix")

### Import the dashboard[​](#import-the-dashboard "Direct link to Import the dashboard")

1. In Coralogix, navigate to **Dashboards**, then select **New Dashboard**, then **Import from JSON**.
2. Upload `coralogix-dashboard.json` from the cloned repository.

### Data available[​](#data-available "Direct link to Data available")

| Signal                   | Where in Coralogix                      |
| ------------------------ | --------------------------------------- |
| Token usage and costs    | Metrics Explorer (`claude_code` prefix) |
| Tool calls               | Logs                                    |
| Code changes and commits | Dashboard                               |

### Code Agents Intelligence[​](#code-agents-intelligence "Direct link to Code Agents Intelligence")

Use the [Code Agents Intelligence](https://coralogix.com/docs/docs/user-guides/ai/code-agents/.md) dashboard to track costs, usage, code impact, and user activity across all sessions in your organization — filterable by Application name and Subsystem.

### Data scopes[​](#data-scopes "Direct link to Data scopes")

The Claude Code dashboard runs on metrics. Support for [data scopes](https://coralogix.com/docs/docs/user-guides/account-management/user-management/scopes/.md) on Claude Code metrics is **forthcoming**. See [Code agents observability — Data scopes](https://coralogix.com/docs/docs/user-guides/ai/code-agents/.md#data-scopes) for the per-agent breakdown.

## Configuration examples[​](#configuration-examples "Direct link to Configuration examples")

### Reduce the metric export interval during testing[​](#reduce-the-metric-export-interval-during-testing "Direct link to Reduce the metric export interval during testing")

Lower the export interval to see data faster while validating your setup:

```
export OTEL_METRIC_EXPORT_INTERVAL=10000
```

### Activate tool detail logging[​](#activate-tool-detail-logging "Direct link to Activate tool detail logging")

Set `OTEL_LOG_TOOL_DETAILS=1` to add Model Context Protocol (MCP) server and tool names to `claude_code.tool_result` log events, and to populate `tool_parameters` for MCP and Skill tool calls (Bash tool parameters ship by default). Tool detail logging is off by default.

### Add custom resource dimensions[​](#add-custom-resource-dimensions "Direct link to Add custom resource dimensions")

Attach extra labels (for example, environment) to every signal:

```
export OTEL_RESOURCE_ATTRIBUTES="cx.application.name=claude-code,cx.subsystem.name=platform,env=prod"
```

## Telemetry reference[​](#telemetry-reference "Direct link to Telemetry reference")

The AI Center Code Agents dashboard surfaces the most common cost, usage, and activity signals out of the box. To explore every metric, log event, and attribute that Claude Code emits — and use those signals as the basis for your own Custom Dashboards or alerts — see the [Claude Code monitoring usage reference](https://code.claude.com/docs/en/monitoring-usage).

## Data reference[​](#data-reference "Direct link to Data reference")

### Metrics[​](#metrics "Direct link to Metrics")

All metrics use delta temporality and appear in Metrics Explorer under the `claude_code` prefix.

| Metric                                      | Labels                                        | What it tracks                                                                                                   |
| ------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `claude_code_session_count_total`           | `session_id`, `user_account_uuid`             | Sessions started                                                                                                 |
| `claude_code_token_usage_tokens_total`      | `model`, `type`                               | Tokens by model and type (`input`, `output`, `cacheRead`, `cacheCreation`)                                       |
| `claude_code_cost_usage_USD_total`          | `model`                                       | Estimated USD cost per model                                                                                     |
| `claude_code_lines_of_code_count_total`     | `type`                                        | Lines added and removed                                                                                          |
| `claude_code_commit_count_total`            | —                                             | Git commits made                                                                                                 |
| `claude_code_pull_request_count_total`      | —                                             | Pull requests created                                                                                            |
| `claude_code_code_edit_tool_decision_total` | `decision`, `source`, `tool_name`, `language` | Accept and reject decisions on code edits                                                                        |
| `claude_code_active_time_total_s_total`     | `type`                                        | Seconds Claude Code was actively processing (`cli` = AI/tool work, `user` = keyboard interaction)                |
| `claude_code_session_repo_info`             | `session_id`, `repository_name`, `user_email` | Git repository worked on in each session (requires the [repository-tracking hook](#github-repository-breakdown)) |

### Log events[​](#log-events "Direct link to Log events")

Query log events using DataPrime or Lucene, filtered by your application and subsystem names.

| Event type                  | Key attributes                       |
| --------------------------- | ------------------------------------ |
| `claude_code.api_request`   | `model`, token counts, cost, latency |
| `claude_code.api_error`     | `status`, error message              |
| `claude_code.tool_result`   | tool name, duration, outcome         |
| `claude_code.tool_decision` | tool name, `decision`, `source`      |

Every signal carries `session.id`, `user.account_uuid`, `user.email`, `organization.id`, `app.version`, and `terminal.type`.

## Advanced configuration[​](#advanced-configuration "Direct link to Advanced configuration")

| Variable                            | Default    | Purpose                                                                                                                                  |
| ----------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `OTEL_METRIC_EXPORT_INTERVAL`       | `60000` ms | How often the exporter flushes metrics                                                                                                   |
| `OTEL_LOGS_EXPORT_INTERVAL`         | `5000` ms  | Log flush interval                                                                                                                       |
| `OTEL_LOG_TOOL_DETAILS`             | off        | Set to `1` to add Model Context Protocol (MCP) server and tool names to tool events, plus `tool_parameters` for MCP and Skill tool calls |
| `OTEL_METRICS_INCLUDE_SESSION_ID`   | `true`     | Attaches `session.id` to metric labels — turn off to reduce cardinality                                                                  |
| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | `true`     | Attaches `user.account_uuid` to metric labels                                                                                            |

## Troubleshoot[​](#troubleshoot "Direct link to Troubleshoot")

Metrics do not appear but logs do

Cause: `OTEL_METRICS_EXPORTER` is missing or the export interval is too long.

Fix: confirm you exported `OTEL_METRICS_EXPORTER=otlp` and lower `OTEL_METRIC_EXPORT_INTERVAL` to `10000` while testing.

Costs show as zero

Cause: cost metrics require delta temporality.

Fix: confirm you set `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta`.

Telemetry stops when Claude Code routes through a proxy or gateway

If Claude Code routes through a proxy, router, gateway, or third-party model provider — for example, LiteLLM, Amazon Bedrock, or a cost-tracking proxy — Claude Code treats it as a third-party provider and silently stops applying server-managed settings, including the OpenTelemetry configuration that streams usage and cost data to Coralogix. Telemetry stops with no error.

#### Why telemetry stops[​](#why-telemetry-stops "Direct link to Why telemetry stops")

Claude Code fetches server-managed settings from Anthropic at startup, and those settings aren't applied when a third-party model provider is configured — a non-default `ANTHROPIC_BASE_URL`, or one of the provider flags `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, or `CLAUDE_CODE_USE_ANTHROPIC_AWS`. Any tool that sets one of these turns off dashboard-delivered telemetry for that developer.

The bypass is triggered by, among others:

* **Claude Code routers and cost proxies** — Headroom, claude-code-router, claude-code-proxy, y-router, and ccflare.
* **AI gateways and LLM proxies** — LiteLLM, Portkey, OpenRouter, Cloudflare AI Gateway, Kong AI Gateway, Apache APISIX, TrueFoundry, Requesty, Vercel AI Gateway, Braintrust, Martian, and Helicone in proxy mode (Helicone's async-logging mode does not trigger the bypass).
* **Enterprise provider backends** — Amazon Bedrock, Bedrock Mantle, Google Vertex AI, and Microsoft Foundry.

#### Fix[​](#fix "Direct link to Fix")

Deliver the OpenTelemetry environment variables through a channel that survives the bypass:

* A `managed-settings.json` file deployed with your MDM tooling — recommended for fleets. See [Deploy org-wide without a Claude account](#deploy-org-wide-without-a-claude-account) for the `env` block, then deploy it to the platform path below.
* A per-user `~/.claude/settings.json` file holding the same `env` block — suitable for individual developers or small teams. It is not tamper-resistant and must be configured on each machine.

| Platform    | `managed-settings.json` path                                    |
| ----------- | --------------------------------------------------------------- |
| macOS       | `/Library/Application Support/ClaudeCode/managed-settings.json` |
| Windows     | `C:\Program Files\ClaudeCode\managed-settings.json`             |
| Linux / WSL | `/etc/claude-code/managed-settings.json`                        |

On macOS, you can instead push a configuration profile with your MDM that targets the `com.anthropic.claudecode` managed-preferences domain with the same keys — harder for developers to tamper with than a file.

OpenTelemetry configuration is an advanced setting, so developers must fully restart Claude Code for the change to take effect — on Desktop, quit the menu-bar or tray icon as well.

#### Settings priority[​](#settings-priority "Direct link to Settings priority")

Managed settings take precedence over command-line arguments and the local, project, and user settings files. Within the managed tier, Claude Code applies the first source that delivers a non-empty configuration and does not merge sources — a policy helper (`policyHelper`), if configured, then server-managed (dashboard) settings, then the `managed-settings.json` file. This makes the MDM file a clean complement to the dashboard: developers without a proxy get the dashboard settings, and developers with a proxy fall through to the MDM file. The dashboard configuration must also contain the telemetry `env` block, and the `managed-settings.json` file should stay scoped to that block.

For the underlying conditions and precedence rules, see Claude Code's [server-managed settings](https://code.claude.com/docs/en/server-managed-settings) and [settings](https://code.claude.com/docs/en/settings) references.

Dashboard costs don't match the Anthropic invoice

Claude Code computes cost on the developer's machine: Anthropic returns token counts with each response, and the client multiplies them by a price list embedded in the client, then exports the cost and token-usage metrics to Coralogix (see [Metrics](#metrics)).

Because the embedded price list reflects public list prices, dashboard cost is an estimate and can differ from your actual Anthropic invoice:

* **Outdated clients** compute with outdated prices until developers update Claude Code.
* **Introductory or promotional pricing** — a client without the updated price table reports a higher cost than billed for that model until it updates, for example during a model's launch-pricing period.
* **US data-residency organizations** — requests pinned to US infrastructure are billed at a higher rate than the global list price the client uses (see Claude's [data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) pricing), so dashboard cost is understated by roughly 10%.
* **Negotiated pricing** — enterprise discounts and committed-use rates aren't known to the client.

Treat the dashboard cost as directional usage telemetry — useful for trends, per-team breakdowns, and anomaly detection. For billing-accurate spend, use the Anthropic Console or your invoice.

Debug the repository-tracking hook

The hook swallows every error by design so it never disrupts a Claude Code session — which also means a failure is silent. To find out why repository data isn't reaching Coralogix, run the hook by hand with a sample event and confirm delivery with a query.

#### Run the hook the way Claude Code does[​](#run-the-hook-the-way-claude-code-does "Direct link to Run the hook the way Claude Code does")

From inside a Git repository, pipe a sample PostToolUse event to the deployed script. Pass configuration with the override flags instead of reading it from settings files, and give the event a unique `session_id` you can search for afterward.

On macOS:

```
printf '{"session_id":"debug-1","cwd":"'"$(pwd)"'","tool_name":"Read","tool_input":{"file_path":"'"$(pwd)"'/README.md"},"user_email":"you@example.com"}' \

  | /bin/sh /usr/local/bin/claude.sh \

    --otlp-endpoint=ingress.eu2.coralogix.com:443 \

    --otlp-headers="Authorization=Bearer <YOUR_CX_API_KEY>"
```

On Windows:

```
'{"session_id":"debug-1","cwd":"C:/path/to/repo","tool_name":"Read","tool_input":{"file_path":"C:/path/to/repo/README.md"},"user_email":"you@example.com"}' |

  powershell -NoProfile -File C:\ProgramData\Coralogix\claude-code\claude.ps1 -OtlpEndpoint "ingress.eu2.coralogix.com:443" -OtlpHeaders "Authorization=Bearer <YOUR_CX_API_KEY>"
```

The [Coralogix AI agent instrumentation repository](https://github.com/coralogix/ai-agent-instrumentation/tree/master/claude-code) includes `test-hook-local.sh`, a macOS harness that runs this and prints the exact query to check.

#### Confirm delivery[​](#confirm-delivery "Direct link to Confirm delivery")

The hook exits 0 even on failure, so the exit code confirms nothing — query the metric instead. After 30–60 seconds, search Metrics Explorer for your marker:

```
claude_code_session_repo_info{session_id="debug-1"}
```

If the series appears, the hook works and the metric is landing. If it doesn't, work through the causes below.

#### Common causes[​](#common-causes "Direct link to Common causes")

| Symptom                              | Cause and fix                                                                                                                                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `repository_name` is `unknown`       | `git` isn't installed or on `PATH`, or the path isn't inside a Git repository. Confirm `git -C <dir> rev-parse --show-toplevel` resolves.                                                              |
| Nothing is sent at all               | No configuration resolved. The hook reads `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` from your Claude Code settings files — confirm they're set, or pass the override flags above. |
| Metric never appears, HTTP 401 / 403 | Auth problem — wrong key, not a Send-Your-Data key, or missing metrics-ingestion permission.                                                                                                           |
| Metric never appears, HTTP 400 / 404 | Wrong endpoint — it must be the ingress host (for example, `https://ingress.eu1.coralogix.com`); the hook appends `/v1/metrics`.                                                                       |
| Connection times out or TLS fails    | A firewall or TLS-intercepting proxy is blocking egress to the ingress host on port 443.                                                                                                               |

To see the HTTP status directly, reissue the same request with `curl -v` (macOS) against `<endpoint>/v1/metrics` with the `Authorization` header, or inspect the response from `Invoke-WebRequest` in an interactive PowerShell session on Windows.

## Next steps[​](#next-steps "Direct link to Next steps")

Once your integration is set up, explore [Code agents](https://coralogix.com/docs/docs/user-guides/ai/code-agents/.md) to monitor token usage, costs, tool calls, code changes, and session data across all your coding agents.