Telemetry Setup

Enable OTLP telemetry to see per-session costs, token usage, model breakdowns, and anomaly alerts across your Claude Code workstations.

What is OTLP telemetry?

Claude Code ships with built-in OpenTelemetry support. When telemetry is enabled, each Claude Code session emits structured log records, one per tool call, to any OTLP-compatible collector.

Agent Keeper acts as that collector. Events arrive at https://YOUR_AGENTKEEPER_URL/api/v1/otlp, are attributed to the workstation that sent them, and appear immediately in:

• Usage & Costs: per-session token counts, model costs, trend charts
• Workstations: per-developer cost and activity, anomaly detection
• Investigations: cost spikes, unusual tool patterns, policy violations

Telemetry is additive: Runtime Shield and security hooks continue to work regardless of whether telemetry is on.

Quick Setup

The fastest way to enable telemetry on a single workstation. Run these commands in your terminal, then restart Claude Code.

Step 1: Get an API key

1. Log in to YOUR_AGENTKEEPER_URL
2. Go to Settings → API Keys
3. Click Create Key and name it "Telemetry" or similar
4. Copy the key (starts with ak_live_)

Step 2: Set environment variables

Add the following block to your shell rc file (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish):

# >>> agentkeeper-telemetry >>>
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://YOUR_AGENTKEEPER_URL/api/v1/otlp
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ak_live_YOUR_KEY_HERE"
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_RESOURCE_ATTRIBUTES="host.name=$(scutil --get LocalHostName 2>/dev/null || hostname -s | tr ' ' '_')"
# <<< agentkeeper-telemetry <<<

Replace ak_live_YOUR_KEY_HERE with your actual API key.

Step 3: Reload your shell

source ~/.zshrc   # or ~/.bashrc

Step 4: Verify

Open a new Claude Code session and run any tool call (e.g., list files). Within 60 seconds, you should see the workstation appear in Settings → Telemetry.

MDM Setup

For fleet-wide rollout, push the environment variables via your MDM provider. This is the recommended approach for Team and Enterprise customers, no developer action required.

managed-settings.json format

Agent Keeper uses a managed-settings.json file that MDM pushes to each Mac. This file is read-only to the end user and cannot be overridden by individual settings.json.

Create the following payload, replacing ak_live_YOUR_KEY_HERE with your org's Telemetry API key:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://YOUR_AGENTKEEPER_URL/api/v1/otlp",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer ak_live_YOUR_KEY_HERE",
    "OTEL_LOG_TOOL_DETAILS": "1"
  }
}

Note: The host.name resource attribute is intentionally omitted from MDM config. Claude Code automatically uses the system hostname, which ensures each workstation maps to the correct record in Agent Keeper.

Jamf Pro

1. In Jamf Pro, go to Computers → Configuration Profiles
2. Click New and name it "Agent Keeper Telemetry"
3. Add a Files & Processes payload
4. Set the file path: /Library/Application Support/anthropic/managed-settings.json
5. Paste the JSON payload above into the file contents field
6. Set permissions: owner root, group wheel, mode 0644
7. Scope the profile to your developer group and click Save

Kandji

1. In Kandji, go to Library → Custom Scripts
2. Click Add New and name it "Agent Keeper Telemetry Config"
3. Set Execution Frequency to "Run once per device"
4. Paste the following script, replacing the API key:

#!/bin/bash
set -e

MANAGED_DIR="/Library/Application Support/anthropic"
MANAGED_FILE="$MANAGED_DIR/managed-settings.json"

mkdir -p "$MANAGED_DIR"

cat > "$MANAGED_FILE" << 'EOF'
{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://YOUR_AGENTKEEPER_URL/api/v1/otlp",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer ak_live_YOUR_KEY_HERE",
    "OTEL_LOG_TOOL_DETAILS": "1"
  }
}
EOF

chmod 644 "$MANAGED_FILE"
chown root:wheel "$MANAGED_FILE"

echo "Agent Keeper telemetry config written to $MANAGED_FILE"

1. Assign the script to your developer blueprint and click Save

Microsoft Intune (Windows / Linux)

For Windows and Linux developer workstations, deploy the environment variables via a shell script or PowerShell profile. Create a shell script that writes to the user's profile:

#!/bin/bash
# Agent Keeper telemetry, deploy via Intune shell script
RC_FILE="$HOME/.bashrc"

# Remove existing block if present
if grep -q "agentkeeper-telemetry" "$RC_FILE" 2>/dev/null; then
  sed -i '/# >>> agentkeeper-telemetry >>>/,/# <<< agentkeeper-telemetry <<</d' "$RC_FILE"
fi

# Append new block
cat >> "$RC_FILE" << 'EOF'

# >>> agentkeeper-telemetry >>>
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://YOUR_AGENTKEEPER_URL/api/v1/otlp
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ak_live_YOUR_KEY_HERE"
export OTEL_LOG_TOOL_DETAILS=1
# <<< agentkeeper-telemetry <<<
EOF

echo "Telemetry configured."

Using /connect --enable-telemetry

The /agentkeeper:connect skill in Claude Code handles full Agent Keeper setup in one step. When you pass the --enable-telemetry flag, it also writes the OTEL environment variables to your shell rc file automatically.

Usage:

In a Claude Code chat session, run:

/agentkeeper:connect --enable-telemetry

The skill will:

1. Authenticate with Agent Keeper using your existing API key (or prompt you to create one)
2. Install Runtime Shield hooks into ~/.claude/settings.json
3. Detect your shell ($SHELL) and locate the appropriate rc file
4. Write the agentkeeper-telemetry block to your rc file, with your API key embedded
5. Instruct you to source the rc file or restart your terminal

If the telemetry block already exists in your rc file, the skill replaces it with an updated version, it does not create duplicates.

Verifying your setup

After completing setup, verify that telemetry is arriving:

1. Open a new terminal (to load the updated environment variables)
2. Start a Claude Code session and run any tool (e.g., ask Claude to list files)
3. In the Agent Keeper dashboard, go to Settings → Telemetry
4. Look at the Status card

The Status card shows:

If the card shows Active, telemetry is working. Your workstation will appear in the Workstations list within 1–2 minutes of the first event.

Privacy controls

Agent Keeper gives you granular control over what telemetry is collected. Find these settings at Settings → Telemetry → Privacy.

These toggles apply org-wide. Individual workstations cannot override privacy settings set by an admin.

Team rollout

For Team and Enterprise customers, the Workstations page shows a rollout tracker: how many developers have telemetry active vs. total workstations registered.

To check coverage:

1. Go to Settings → Telemetry

2. The Setup Health card lists workstations by status:

   • Reporting: received an OTLP event in the last 7 days
   • Not reporting: workstation is registered but no OTLP events

3. Click a workstation name to open its detail view and see the last event timestamp

To nudge pending workstations:

Use the Copy setup script button in the Setup Health card to generate a one-liner your developers can paste into their terminal. The script is pre-populated with your org's API key.

For MDM-managed fleets, use the MDM Setup instructions above to push config without requiring developer action.

Troubleshooting

"My workstation isn't showing up"

The most common cause is a missing or incorrect host.name resource attribute. Agent Keeper uses this to match OTLP events to workstation records.

Check:

echo $OTEL_RESOURCE_ATTRIBUTES

Expected output: host.name=your-machine-name

Fix:

Add or update the attribute in your shell rc:

export OTEL_RESOURCE_ATTRIBUTES="host.name=$(scutil --get LocalHostName 2>/dev/null || hostname -s | tr ' ' '_')"

On Linux, use hostname -s directly:

export OTEL_RESOURCE_ATTRIBUTES="host.name=$(hostname -s)"

Then reload: source ~/.zshrc and start a new Claude Code session.

"Cost data shows $0.00"

Cost data requires tool detail logging to be enabled. Without tool details, Agent Keeper receives session boundaries but not model or token information.

Check:

echo $OTEL_LOG_TOOL_DETAILS

Expected output: 1

Fix:

export OTEL_LOG_TOOL_DETAILS=1

Add this to your shell rc file and reload. Cost data will appear from the next session onward, existing sessions are not retroactively updated.

"OTLP events aren't arriving"

If no events appear in the dashboard after several Claude Code tool calls, check each variable in sequence:

1. Verify telemetry is enabled:

echo $CLAUDE_CODE_ENABLE_TELEMETRY

Expected: 1

2. Verify the endpoint:

echo $OTEL_EXPORTER_OTLP_ENDPOINT

Expected: https://YOUR_AGENTKEEPER_URL/api/v1/otlp

3. Verify the API key:

echo $OTEL_EXPORTER_OTLP_HEADERS

Expected: Authorization=Bearer ak_live_... (your key)

4. Test the endpoint directly:

curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://YOUR_AGENTKEEPER_URL/api/v1/otlp/v1/logs \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Content-Type: application/x-protobuf"

A 400 response means the endpoint is reachable and your key is valid (the body was empty, which is expected). A 401 means the API key is invalid or missing. A 000 means a network connectivity issue.

5. Check that variables are set in the Claude Code process:

Environment variables must be set before Claude Code starts. If you added them to ~/.zshrc but launched Claude Code from an app launcher (not a terminal), the variables may not be inherited. Try launching Claude Code from a terminal where you've already sourced your rc file.

"Unmapped workstation" in Setup Health

An unmapped workstation means OTLP events arrived from a host.name that doesn't match any registered workstation in your org.

To assign it:

1. Go to Settings → Telemetry → Setup Health
2. Find the workstation in the Unmapped list
3. Click Assign next to the hostname
4. Select the matching workstation record (or create a new one)

To prevent this in the future:

Make sure the host.name in OTEL_RESOURCE_ATTRIBUTES matches the hostname Agent Keeper registered. The easiest way is to use the same command Agent Keeper uses when it registers the host:

scutil --get LocalHostName 2>/dev/null || hostname -s | tr ' ' '_'

Set OTEL_RESOURCE_ATTRIBUTES to the output of that command.