Collect Claude Code usage metrics with Kimchi

This tutorial walks you through setting up OpenTelemetry (OTel) collection for Claude Code using kimchi setup and kimchi setup-tools. By the end, Kimchi will be collecting token usage, cost, and tool activity from your Claude Code sessions — and surfacing it in the Kimchi console.

Overview

In this tutorial, you'll learn how to configure Kimchi to collect OTel logs and metrics from Claude Code. This tutorial is intended for individual developers who already use Claude Code and want visibility into what their agent sessions are actually doing.

By the end of this tutorial, you'll be able to:

Configure Claude Code to export OTel data to Kimchi
Understand what data is collected and why
View per-session usage, costs, and tool activity in the Kimchi console

⚠️
Administrator setup does not support per-user tracking.
If Claude Code is configured via managed settings with a shared API key, all team members' usage is attributed to that single key — you won't be able to break down costs or activity per user.
If per-user tracking matters to your team, each developer should follow this guide individually using their own API key.
If you're an administrator and per-user tracking is not a requirement, see Report coding tool metrics to Kimchi for the managed settings setup path.

Before you start

Before you start, ensure:

Claude Code is installed — see Claude Code installation if you haven't set it up yet.

Kimchi is installed — if not, install it with:

curl -fsSL https://github.com/getkimchi/kimchi/releases/latest/download/install.sh | bash

You have a Kimchi API key — generate one at app.kimchi.dev/settings under API Keys.

⚠️
Your API key must be unique to you. Kimchi uses it to attribute usage data per user. Don't share it or reuse a team key here — if you do, all users will appear as one in the console.

Step 1: Configure OTel collection

If you haven't already set up your API key, run the setup wizard first:

kimchi setup

Then run the tool configuration command:

kimchi setup-tools

When prompted, select Claude Code from the tool list. The command writes the OTel configuration automatically.

After setup completes, the following environment variables are written to ~/.claude/settings.json:

Variable	Value	Purpose
`CLAUDE_CODE_ENABLE_TELEMETRY`	`1`	Enable Claude Code telemetry
`OTEL_LOGS_EXPORTER`	`otlp`	Exports logs using the OpenTelemetry Protocol
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	`https://api.cast.ai/ai-optimizer/v1beta/logs:ingest`	Points the logs exporter at Kimchi's ingestion endpoint
`OTEL_EXPORTER_OTLP_LOGS_HEADERS`	`Authorization=Bearer <key>`	Authenticates log exports with your Kimchi API key
`OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`	`http/json`	Sets the log transport to HTTP with JSON encoding
`OTEL_LOGS_EXPORT_INTERVAL`	`15000`	Exports logs every 15 seconds
`OTEL_LOG_TOOL_DETAILS`	`1`	Includes full tool call inputs and outputs in log events
`OTEL_METRICS_EXPORTER`	`otlp`	Exports metrics using the OpenTelemetry Protocol
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	`https://api.cast.ai/ai-optimizer/v1beta/metrics:ingest`	Points the metrics exporter at Kimchi's ingestion endpoint
`OTEL_EXPORTER_OTLP_METRICS_HEADERS`	`Authorization=Bearer <key>`	Authenticates metrics exports with your Kimchi API key
`OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`	`http/json`	Sets the metric transport to HTTP with JSON encoding
`OTEL_METRIC_EXPORT_INTERVAL`	`15000`	Exports metrics every 15 seconds
`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`	`cumulative`	Uses cumulative aggregation for metric reporting

These settings take effect the next time Claude Code starts.

Step 2: Start a Claude Code session

No further configuration needed. Start Claude Code as you normally would:

claude

Kimchi begins collecting data from your first session. Logs and metrics are exported in the background every 15 seconds.

Step 3: View your data in the Kimchi console

Open app.kimchi.dev.
Navigate to Coding Agent Report.

You'll see your Claude Code activity broken down by:

Token usage — input and output tokens per session and per model
Cost — estimated spend based on model pricing
Tool activity — which tools were invoked and how often
Session activity — start and end times, prompt count

Data typically appears within a few minutes of your first session completing.

What data does Kimchi collect?

Kimchi collects two types of OTel data from Claude Code:

Logs

Claude Code emits structured log events for each agent interaction. With OTEL_LOG_TOOL_DETAILS=1 enabled, log events include full tool call details.

Each log event covers:

API requests — each model call Claude Code makes, including model name, token counts, and cost
Tool executions — tool name, inputs, and outputs for every tool invoked
Session events — session start, end, and prompt submission

Raw file contents and code snippets are not included. For full details on what Claude Code exports, see Claude Code monitoring.

Metrics

Metrics are exported as cumulative OTLP over HTTP/JSON and include:

Token usage (input and output) per session and model
Estimated cost per session
Tool invocation counts
Tool execution duration
Model activity frequency

All data is attributed to your API key, so your activity is isolated from other users in the console.

Troubleshooting

No data appearing after 15 minutes

Confirm kimchi setup and kimchi setup-tools completed without errors.
Check that ~/.claude/settings.json contains the OTel variables for both logs and metrics:
```
cat ~/.claude/settings.json | grep OTEL
```
Restart Claude Code — the variables only take effect on a fresh start.
Verify your API key is active at app.kimchi.dev/settings.

I already ran `kimchi setup` and `kimchi setup-tools` before — do I need to run them again?

Only if you've rotated your API key. Otherwise your existing configuration is valid.

`kimchi setup-tools` updated variables I didn't expect

kimchi setup-tools writes to ~/.claude/settings.json and updates existing OTel variables in place. If you had a previous OTel configuration pointing elsewhere, check that the endpoint and header values now point to Kimchi. You can inspect the file directly to confirm.

Summary

In this tutorial, you learned how to:

Run kimchi setup and kimchi setup-tools to configure Claude Code OTel collection
Understand the variables written to ~/.claude/settings.json and what each one does
Verify that data is flowing to the Kimchi console
Distinguish between log and metric data collected from Claude Code sessions