Giám sát với OpenTelemetry

Theo dõi usage, chi phí và hoạt động tool của Claude Code trên toàn tổ chức bằng cách export dữ liệu telemetry qua OpenTelemetry (OTel). Claude Code export metrics dạng time series qua metrics protocol chuẩn, events qua logs/events protocol, và tùy chọn distributed traces qua traces protocol (beta). Bạn cấu hình backend cho metrics, logs, traces theo nhu cầu giám sát của mình.

Bắt đầu nhanh

Cấu hình OpenTelemetry bằng biến môi trường:

# 1. Bật telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Chọn exporter (cả hai đều tùy chọn - chỉ cấu hình cái bạn cần)
export OTEL_METRICS_EXPORTER=otlp       # Tùy chọn: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # Tùy chọn: otlp, console, none

# 3. Cấu hình OTLP endpoint (cho exporter otlp)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Thiết lập xác thực (nếu cần)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Để debug: giảm export interval
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 giây (mặc định: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 giây (mặc định: 5000ms)

# 6. Chạy Claude Code
claude

Ghi chú

Export interval mặc định là 60 giây cho metrics và 5 giây cho logs. Trong quá trình setup, bạn có thể muốn dùng interval ngắn hơn để debug - nhớ đặt lại về mặc định khi vào production.

Để xác minh setup export metrics, kiểm tra backend của bạn xem có metric claude_code.session.count không - metric này được Claude Code emit khi một session bắt đầu. Để xác minh setup chỉ có logs, gửi một prompt rồi kiểm tra event claude_code.user_prompt. Nếu không thấy gì, chạy claude --debug và xem debug log để tìm lỗi export OTel.

Cấu hình cho admin (quản trị viên)

Admin có thể cấu hình OpenTelemetry cho toàn bộ user qua managed settings file, giúp kiểm soát tập trung cấu hình telemetry trên toàn tổ chức.

Ví dụ managed settings:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

Ghi chú

Managed settings có thể phân phối qua MDM (Mobile Device Management) hoặc các giải pháp quản lý thiết bị khác. Biến môi trường khai báo trong managed settings có độ ưu tiên cao và user không thể ghi đè.

Claude Code không truyền biến OTEL_* xuống các subprocess mà nó spawn ra - bao gồm Bash tool, hooks, MCP server, và language server. Một ứng dụng được instrument OpenTelemetry mà bạn chạy qua Bash tool sẽ không tự kế thừa exporter endpoint hay headers của Claude Code; nếu ứng dụng đó cần export telemetry riêng, hãy set các biến đó trực tiếp trong command.

Managed settings khóa đích OTLP như thế nào

Khi bạn set một biến OTEL_EXPORTER_OTLP_* trong managed settings, Claude Code sẽ xóa các biến do developer tự set bị xung đột lúc khởi động, và log cảnh báo (xem được bằng claude --debug). Cụ thể:

• Endpoint: set OTEL_EXPORTER_OTLP_ENDPOINT sẽ xóa mọi endpoint theo từng signal (per-signal) mà developer đã set - developer không thể trỏ một signal sang collector khác.
• Protocol: set OTEL_EXPORTER_OTLP_PROTOCOL sẽ xóa mọi protocol per-signal do developer set.
• Credentials: set OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_CLIENT_KEY, hoặc OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE sẽ xóa các biến credential per-signal tương ứng, cộng với mọi endpoint developer đã set (generic lẫn per-signal) - vì credentials đó có thể lọt tới một collector mà managed settings không hề chọn.
• Exporter selector: OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, và OTEL_TRACES_EXPORTER (beta) vẫn theo thứ tự ưu tiên bình thường theo key - developer vẫn có thể tắt một signal hoặc chuyển sang console exporter, nên nếu muốn khóa hẳn, hãy set các selector này trong managed settings luôn.

Claude Code không xóa các biến per-signal mà chính managed settings đặt ra, nên bạn có thể route một signal riêng tới collector khác (xem ví dụ SIEM bên dưới).

Chú ý

Hành vi xóa biến ở trên chỉ đúng từ Claude Code v2.1.217 trở đi. Trước đó, mọi biến đều theo per-key precedence độc lập - hãy kiểm tra lại version thực tế bạn đang dùng.

Chi tiết cấu hình

Biến cấu hình chung

Biến môi trường	Mô tả	Ví dụ
CLAUDE_CODE_ENABLE_TELEMETRY	Bật thu thập telemetry (bắt buộc)	1
OTEL_METRICS_EXPORTER	Loại exporter cho metrics, phân cách bằng dấu phẩy. Dùng none để tắt	console, otlp, prometheus, none
OTEL_LOGS_EXPORTER	Loại exporter cho logs/events. Dùng none để tắt	console, otlp, none
OTEL_EXPORTER_OTLP_PROTOCOL	Protocol cho OTLP exporter, áp dụng cho mọi signal	grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT	Endpoint OTLP collector cho mọi signal	http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	Endpoint metrics riêng, ghi đè setting chung	http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	Endpoint logs riêng, ghi đè setting chung	http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERS	Header xác thực cho OTLP	Authorization=Bearer token
OTEL_METRIC_EXPORT_INTERVAL	Interval export (ms, mặc định 60000)	5000, 60000
OTEL_LOGS_EXPORT_INTERVAL	Interval export logs (ms, mặc định 5000)	1000, 10000
OTEL_LOG_USER_PROMPTS	Bật log nội dung prompt của user (mặc định tắt)	1
OTEL_LOG_ASSISTANT_RESPONSES	Bật log nội dung phản hồi assistant (mặc định theo OTEL_LOG_USER_PROMPTS)	1 bật, 0 giữ redacted
OTEL_LOG_TOOL_DETAILS	Bật log tham số tool (Bash command, tên MCP server/tool, skill, v.v.)	1
OTEL_LOG_TOOL_CONTENT	Bật log nội dung input/output của tool trong span events (cần bật tracing)	1
OTEL_LOG_RAW_API_BODIES	Emit toàn bộ request/response JSON của Messages API	1 (inline, cắt ở 60 KB) hoặc file:<dir> (không cắt, ghi file)
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH	Giới hạn độ dài nội dung các attribute (mặc định 61440, ~60 KB)	262144
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE	Temporality cho metrics (mặc định delta)	delta, cumulative

Với protocol http/protobuf và http/json, Claude Code gửi mỗi request kèm header Content-Length.

Ghi chú

Danh sách trên chỉ liệt kê các biến phổ biến nhất. Còn nhiều biến per-signal khác (protocol/endpoint riêng cho metrics, logs, traces) - xem tài liệu gốc để có bảng đầy đủ.

Xác thực mTLS

Cách cấu hình client certificate cho OTLP exporter phụ thuộc vào protocol đang dùng:

Protocol	Biến client certificate	Trust CA của collector qua
http/protobuf, http/json	CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY, tùy chọn CLAUDE_CODE_CLIENT_KEY_PASSPHRASE	NODE_EXTRA_CA_CERTS
grpc	OTEL_EXPORTER_OTLP_CLIENT_KEY và OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, hoặc biến per-signal tương ứng	OTEL_EXPORTER_OTLP_CERTIFICATE

Kiểm soát cardinality của metrics

Biến môi trường	Mô tả	Mặc định
OTEL_METRICS_INCLUDE_SESSION_ID	Đưa session.id vào metrics	true
OTEL_METRICS_INCLUDE_VERSION	Đưa app.version vào metrics	false
OTEL_METRICS_INCLUDE_ACCOUNT_UUID	Đưa user.account_uuid/user.account_id vào metrics	true
OTEL_METRICS_INCLUDE_ENTRYPOINT	Đưa app.entrypoint vào metrics	false
OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES	Đưa key từ OTEL_RESOURCE_ATTRIBUTES vào datapoint metrics	true

Các biến này giúp kiểm soát cardinality của metrics - ảnh hưởng đến chi phí lưu trữ và tốc độ truy vấn ở backend metrics của bạn. Cardinality thấp thường đồng nghĩa hiệu năng tốt hơn, chi phí thấp hơn, nhưng dữ liệu ít chi tiết hơn.

Traces (beta)

Distributed tracing export các span liên kết mỗi user prompt với các API request và tool execution mà nó kích hoạt, giúp bạn xem một request đầy đủ dưới dạng một trace duy nhất trong backend tracing.

Tracing mặc định tắt. Để bật, set cả CLAUDE_CODE_ENABLE_TELEMETRY=1 và CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, rồi chọn OTEL_TRACES_EXPORTER. Traces dùng chung cấu hình OTLP (endpoint, protocol, headers, mTLS) với metrics/logs.

Cấu trúc span:

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (cần detailed beta tracing)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agent tool) span llm_request/tool của subagent

Mặc định, span redact nội dung user prompt, tool input, và tool content - bật OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1, OTEL_LOG_TOOL_CONTENT=1 để đưa chúng vào.

Header động (dynamic headers)

Với môi trường enterprise cần xác thực động, bạn có thể cấu hình một script để sinh header theo thời gian thực. Thêm vào .claude/settings.json:

{
  "otelHeadersHelper": "/path/to/generate-otel-headers.sh"
}

Script phải output JSON hợp lệ dạng key-value string:

#!/bin/bash
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

Script chạy lúc khởi động và định kỳ sau đó (mặc định mỗi 29 phút) để hỗ trợ refresh token - tùy chỉnh bằng CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS.

Hỗ trợ tổ chức nhiều team

Tổ chức có nhiều team/phòng ban có thể thêm attribute tùy chỉnh để phân biệt các nhóm bằng OTEL_RESOURCE_ATTRIBUTES:

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Các attribute này được gắn vào mọi metric datapoint và event record, cho phép bạn filter theo team, tính cost theo cost center, hoặc dựng dashboard/alert riêng cho từng team.

Chú ý

OTEL_RESOURCE_ATTRIBUTES có yêu cầu định dạng nghiêm ngặt: không được có khoảng trắng trong giá trị, phải dạng key1=value1,key2=value2, chỉ dùng ký tự US-ASCII (không dấu ngoặc kép, dấu phẩy, chấm phẩy, backslash). Ký tự đặc biệt phải percent-encode. Dùng underscore hoặc camelCase thay cho khoảng trắng.

Metrics và events có sẵn

Attribute chuẩn

Mọi metric và event đều có các attribute chuẩn sau: session.id, app.version, app.entrypoint, organization.id, user.account_uuid/user.account_id, user.id (định danh ẩn danh ngẫu nhiên, không liên quan tài khoản Claude), user.email, terminal.type, và các key tùy chỉnh từ OTEL_RESOURCE_ATTRIBUTES.

Events có thêm prompt.id (UUID liên kết mọi event sinh ra từ một user prompt) - dùng để trace toàn bộ hoạt động từ một prompt cụ thể.

Danh sách metrics

Tên metric	Mô tả	Đơn vị
claude_code.session.count	Số session CLI đã bắt đầu	không
claude_code.lines_of_code.count	Số dòng code đã sửa	không
claude_code.pull_request.count	Số pull request đã tạo	không
claude_code.commit.count	Số git commit đã tạo	không
claude_code.cost.usage	Chi phí session	USD
claude_code.token.usage	Số token đã dùng	tokens
claude_code.code_edit_tool.decision	Số quyết định permission cho tool sửa code	không
claude_code.active_time.total	Tổng thời gian hoạt động thực tế	giây

Mỗi metric có thêm attribute ngữ cảnh riêng - ví dụ cost.usage có model, query_source, agent.name, skill.name, plugin.name, mcp_server.name… Xem tài liệu gốc để có bảng chi tiết từng metric.

Events chính

Claude Code export nhiều loại event qua logs/events (khi OTEL_LOGS_EXPORTER được cấu hình), gồm: user_prompt, assistant_response, tool_result, api_request, api_error, api_refusal, api_request_body/api_response_body (khi bật raw bodies), tool_decision, permission_mode_changed, auth, mcp_server_connection, internal_error, plugin_installed, plugin_loaded.

Mỗi event mang các attribute chuẩn cộng thêm attribute riêng - ví dụ tool_decision có tool_name, decision (accept/reject), source (config, hook, user_permanent, user_temporary, user_abort, user_reject). Các nội dung nhạy cảm (prompt text, tool input/output, error message chi tiết) đều bị redact mặc định và cần bật cờ tương ứng (OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT) để hiển thị đầy đủ.

Mẹo

Bảng attribute đầy đủ của từng event khá dài (event tool_result, api_request… có hàng chục attribute). Nếu bạn cần build dashboard chi tiết hoặc pipeline join theo tool_use_id/request_id, tham khảo bảng gốc đầy đủ tại link Nguồn bên dưới.

See also

• Quản lý chi phí hiệu quả
• Theo dõi usage với analytics

Nguồn

Dịch và biên soạn từ Monitoring.