# 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/integrations/ai-observability/claude-cowork/index.md) for the admin-panel setup for Claude Cowork.

## Supported environments

- OS: macOS, Linux (\*nix)
- Shell: `bash`, `zsh`

## What you need

- A Coralogix account with a **Send-Your-Data [API key](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key/index.md)**. In Coralogix, navigate to **Settings**, then **API Keys**.
- Your Coralogix OTLP endpoint: `ingress.[[DOMAIN_VALUE]]: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

### 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**.

1. Paste the settings JSON:

   ```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.

1. Select **Add settings**.

   The admin console shows the configured settings JSON:

   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.

### 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

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

```bash
git clone https://github.com/coralogix/ai-agent-instrumentation.git
cd ai-agent-instrumentation/claude-code
```

#### Configure

1. Copy the example environment file:

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

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

   - `CX_API_KEY` — your Send-Your-Data API key
   - `CX_OTLP_ENDPOINT` — your OTLP endpoint (`ingress.[[DOMAIN_VALUE]]:443`)

1. Activate the instrumentation and start Claude Code:

   ```bash
   source activate.sh
   claude
   ```

   Claude Code sessions now stream telemetry to Coralogix.

#### Make it permanent

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

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

#### Advanced: set environment variables directly

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

```bash
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`:

```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

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):

```json
"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.

## 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/integrations/ai-observability/claude-cowork/index.md), Cowork data appears in the same dashboard.

How displayed cost is calculated

The cost shown in the dashboard is derived from the usage metrics Claude Code sends to Coralogix — it does not factor in your Anthropic subscription plan. This works the same way as usage-based Enterprise billing: Coralogix displays the metric value as-is.

As a result, the displayed cost is accurate for Enterprise plans, which are billed on usage, but only an estimate for every other plan. If you're on a fixed-price plan such as Team, the figure shown may be higher than what you actually pay Anthropic — for example, a $100/month Team plan whose usage metrics report $1,000 will display as $1,000.

To tell plans apart in the dashboard, set `cx.subsystem.name` to the plan or team name as recommended under [Application name and subsystem](#application-name-and-subsystem). You can then filter to separate Enterprise usage from Team and other fixed-price plans.

## 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.
1. Navigate to **Logs** and filter by your application and subsystem names to see prompts and tool call events.
1. Open [Code Agents Observability](https://coralogix.com/docs/user-guides/ai-observability/code-agents/index.md) to see the full session dashboard.

## Monitor data in Coralogix

### Import the dashboard

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

### Data available

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

### Code Agents Observability

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

## Complete configuration

For the full configuration reference including all available environment variables, see [claude-code in the GitHub repository](https://github.com/coralogix/ai-agent-instrumentation/tree/master/claude-code).

## Configuration examples

### Reduce the metric export interval during testing

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

```bash
export OTEL_METRIC_EXPORT_INTERVAL=10000
```

### Activate prompt logging

Set `OTEL_LOG_USER_PROMPTS=1` to include prompt text in `claude_code.user_prompt` log events. Prompt logging is off by default.

### 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. Tool detail logging is off by default.

### Add custom resource dimensions

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

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

## 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

### 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) |

### Log events

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

| Event type                  | Key attributes                                                |
| --------------------------- | ------------------------------------------------------------- |
| `claude_code.user_prompt`   | `session.id`, `user.account_uuid`, `prompt` (opt-in), `model` |
| `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

| 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_USER_PROMPTS`             | off        | Set to `1` to include prompt text in log events                                     |
| `OTEL_LOG_TOOL_DETAILS`             | off        | Set to `1` to add Model Context Protocol (MCP) server and tool names to tool events |
| `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

##### **No data appears in Coralogix**

Cause: environment variables were not exported into the active shell. Fix: run `source activate.sh` again in the same terminal you use to run `claude`, or add the permanent setup to your shell profile.

##### **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`.

## Next steps

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