omcustom-monitoring-setup

name	omcustom:monitoring-setup
description	Enable/disable OpenTelemetry console monitoring for Claude Code usage tracking
scope	package
argument-hint	[enable|disable|status]
user-invocable	true

Monitoring Setup Skill

Enable or disable OpenTelemetry console monitoring. When enabled, Claude Code outputs usage metrics (cost, tokens, sessions, LOC, commits, PRs, active time) and events (tool results, API requests) to the terminal.

Natural Language Triggers

This skill activates when the user mentions any of:

• Korean: "모니터링", "텔레메트리", "사용량 추적", "메트릭", "모니터링 켜줘", "텔레메트리 활성화"
• English: "monitoring", "telemetry", "usage tracking", "metrics", "enable monitoring"
• Combined with actions: "켜", "끄", "활성화", "비활성화", "설정", "enable", "disable", "setup"

Commands

enable (default)

1. Read .claude/settings.local.json (create if not exists)
2. Add or update env field with:

   {
     "env": {
       "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
       "OTEL_METRICS_EXPORTER": "console",
       "OTEL_LOGS_EXPORTER": "console"
     }
   }
   

3. Preserve all existing settings
4. Report to user:

   [Done] OpenTelemetry Console Monitoring enabled
   
   Configured in: .claude/settings.local.json
   Metrics: sessions, cost, tokens, LOC, commits, PRs, active time
   Events: tool results, API requests, tool decisions
   
   Note: Takes effect on next `claude` session restart.
   To disable: /monitoring-setup disable
   

disable

1. Read .claude/settings.local.json
2. Remove OTel-related keys from env:
   • CLAUDE_CODE_ENABLE_TELEMETRY
   • OTEL_METRICS_EXPORTER
   • OTEL_LOGS_EXPORTER
3. If env object becomes empty, remove env field entirely
4. Report:

   [Done] OpenTelemetry Monitoring disabled
   
   Removed from: .claude/settings.local.json
   Takes effect on next session restart.
   

status

1. Read .claude/settings.local.json
2. Check for OTel env vars
3. Report current state:

   [Monitoring Status]
   ├── Enabled: Yes/No
   ├── Metrics exporter: console / otlp / none
   ├── Logs exporter: console / otlp / none
   └── Config: .claude/settings.local.json
   

Implementation Notes

• settings.local.json is NOT git-tracked (local to user)
• Each user enables monitoring independently
• No infrastructure required for console mode
• Metrics appear in stderr during Claude Code execution
• Default export interval: 60s for metrics, 5s for events

Available Metrics

Metric	Description	Unit
claude_code.session.count	CLI sessions started	count
claude_code.cost.usage	Session cost	USD
claude_code.token.usage	Tokens used (input/output/cache)	tokens
claude_code.lines_of_code.count	Code lines modified (added/removed)	count
claude_code.commit.count	Git commits created	count
claude_code.pull_request.count	Pull requests created	count
claude_code.active_time.total	Active usage time	seconds

Available Events

Event	Description
claude_code.tool_result	Tool execution results with duration
claude_code.api_request	API request details with cost/tokens
claude_code.api_error	API error details
claude_code.tool_decision	Tool accept/reject decisions
claude_code.user_prompt	User prompt metadata (content redacted by default)
claude_code.assistant_response	Assistant response text (v2.1.193+; redacted unless opted in)

v2.1.193+ security note (R012): The claude_code.assistant_response log event carries the model's response text. It is redacted unless OTEL_LOG_ASSISTANT_RESPONSES=1; when that variable is unset it FOLLOWS OTEL_LOG_USER_PROMPTS. A deployment already logging prompt content therefore begins receiving response content immediately on upgrade. To keep prompts-only logging, set OTEL_LOG_ASSISTANT_RESPONSES=0 explicitly.

Upgrade Path

For production monitoring, upgrade from console to OTLP:

# In settings.local.json env:
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Advanced OTel Configuration

Additional Metrics

Metric	Description	Unit
code_edit_tool.decision	Edit tool accept/reject decisions	count

Exporter Configuration

{
  "env": {
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
    "OTEL_RESOURCE_ATTRIBUTES": "service.name=claude-code,service.version=2.1.197"
  }
}

Cardinality Controls

Variable	Description	Default
OTEL_LOG_TOOL_DETAILS	Include tool input/output in logs	false
OTEL_METRICS_INCLUDE_TOOL_NAME	Include tool name dimension	true
OTEL_METRICS_INCLUDE_MODEL	Include model dimension	true

Multi-Exporter Syntax

# Send metrics to both console and OTLP
OTEL_METRICS_EXPORTER=console,otlp
OTEL_LOGS_EXPORTER=console,otlp

Prometheus Exporter

OTEL_METRICS_EXPORTER=prometheus
OTEL_EXPORTER_PROMETHEUS_PORT=9464

Data Privacy

Environment variables to control data collection and telemetry:

Variable	Description
DISABLE_TELEMETRY	Disable all telemetry collection
DISABLE_ERROR_REPORTING	Disable error reporting to Anthropic
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	Disable non-essential network traffic
CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY	Disable feedback survey prompts
DO_NOT_TRACK	Standard DNT signal

Enterprise Configuration

{
  "env": {
    "DISABLE_TELEMETRY": "1",
    "DISABLE_ERROR_REPORTING": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

HTTP-Level Inspection (Optional)

For deeper payload-level debugging beyond aggregated metrics, Claude Inspector provides MITM proxy inspection of Claude Code HTTP traffic.

Aspect	OTel Monitoring (this skill)	Claude Inspector
Layer	Application (hooks, stdout)	HTTP (MITM proxy)
Metrics	Aggregated (cost, tokens, duration)	Per-request payload breakdown
Cache visibility	Not available	Prompt Cache hit/miss rates
Sub-agent view	Summary via hooks	Full parent vs sub-agent context comparison
Setup	Built-in (hooks + statusline)	External tool (Homebrew on macOS)

When to Use

• OTel monitoring: Daily operations, cost tracking, performance trends
• Claude Inspector: Debugging specific payload issues, measuring CLAUDE.md token impact, verifying ecomode (R013) effectiveness, profiling sub-agent context inheritance

Setup

# macOS
brew install kangraemin/tap/claude-inspector

# Run proxy
claude-inspector

Claude Inspector is external to oh-my-customcode and does not require any project configuration changes.

Agent Trajectory Export Mode

Toggle: /monitoring-setup trajectory-otel on|off

When enabled, agent-eval-framework 4-metric data is emitted as OpenTelemetry spans for external analysis.

trajectory-otel on

1. Read .claude/settings.local.json (create if not exists)
2. Add or update env field with trajectory export configuration:

   {
     "env": {
       "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
       "OTEL_METRICS_EXPORTER": "console",
       "OTEL_LOGS_EXPORTER": "console",
       "CLAUDE_TRAJECTORY_OTEL": "1"
     }
   }
   

3. If OTEL_EXPORTER_OTLP_ENDPOINT is set in the environment, also add:

   {
     "env": {
       "OTEL_TRACES_EXPORTER": "otlp"
     }
   }
   

   Otherwise default to "OTEL_TRACES_EXPORTER": "console".
4. Preserve all existing settings
5. Report:

   [Done] Agent Trajectory Export enabled
   
   Configured in: .claude/settings.local.json
   Span exporter: console (default) | otlp (if OTEL_EXPORTER_OTLP_ENDPOINT set)
   Metrics: correctness, step_ratio, tool_call_ratio, latency_ratio
   Events: tool_call (tool_name, duration_ms, exit_code)
   
   Note: Takes effect on next `claude` session restart.
   To disable: /monitoring-setup trajectory-otel off
   

trajectory-otel off

1. Read .claude/settings.local.json
2. Remove trajectory-related keys from env:
   • CLAUDE_TRAJECTORY_OTEL
   • OTEL_TRACES_EXPORTER
3. Report:

   [Done] Agent Trajectory Export disabled
   
   Removed from: .claude/settings.local.json
   Takes effect on next session restart.
   

Span Schema

operation: agent.invocation
attributes:
  agent.type: string          // e.g. "lang-golang-expert"
  agent.model: string         // e.g. "claude-sonnet-4-6"
  task.id: string             // eval task identifier
  task.capability: string     // research | implement | review | debug | manage
  metric.correctness: bool
  metric.step_ratio: float
  metric.tool_call_ratio: float
  metric.latency_ratio: float
events:
  - tool_call
      attrs: tool_name (string), duration_ms (int), exit_code (int)
duration: total wall clock time of agent invocation

Activation Notes

• Independent from the existing console monitoring mode (enable/disable). Both can be active simultaneously.
• trajectory-otel on does NOT implicitly call enable — console metrics monitoring remains a separate toggle.
• Console exporter (default): prints span JSON to stdout for local dev / debugging.
• OTLP exporter (optional): activated when OTEL_EXPORTER_OTLP_ENDPOINT env var is set. Compatible with Grafana, Datadog, Honeycomb, and any OTLP-compliant collector. No LangSmith dependency.
• Actual OTEL SDK emission is handled by the Claude Code telemetry layer. This skill configures the env vars that activate the trajectory span pipeline.

status (extended)

When trajectory-otel is active, status command output includes:

[Monitoring Status]
├── Enabled: Yes/No
├── Metrics exporter: console / otlp / none
├── Logs exporter: console / otlp / none
├── Trajectory export: Yes/No
├── Traces exporter: console / otlp / none
└── Config: .claude/settings.local.json