Observability với OpenTelemetry

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

Khi chạy agent trong production, bạn cần khả năng quan sát những gì chúng đã làm:

chúng đã gọi tool nào
mỗi request tới model mất bao lâu
đã tiêu bao nhiêu token
lỗi xảy ra ở đâu

Agent SDK có thể xuất dữ liệu này dưới dạng trace, metric, và log event OpenTelemetry tới bất kỳ backend nào chấp nhận OpenTelemetry Protocol (OTLP), như Honeycomb, Datadog, Grafana, Langfuse, hoặc một collector tự host.

Hướng dẫn này giải thích cách SDK phát ra telemetry, cách cấu hình việc xuất dữ liệu, và cách gắn tag và lọc dữ liệu sau khi nó tới backend của bạn. Để đọc token usage và cost trực tiếp từ response stream của SDK thay vì xuất sang backend, xem Theo dõi cost và usage.

Telemetry chảy từ SDK như thế nào

Agent SDK chạy Claude Code CLI như một child process và giao tiếp với nó qua một pipe cục bộ. CLI có sẵn OpenTelemetry instrumentation: nó ghi span quanh mỗi request model và tool execution, phát ra metric cho bộ đếm token và cost, và phát ra structured log event cho prompt và kết quả tool. SDK không tự tạo ra telemetry. Thay vào đó, nó truyền cấu hình xuống CLI process, và CLI xuất trực tiếp tới collector của bạn.

Cấu hình được truyền dưới dạng biến môi trường. Theo mặc định, child process kế thừa môi trường của ứng dụng bạn, nên bạn có thể cấu hình telemetry ở một trong hai chỗ:

Môi trường của process: đặt biến trong shell, container, hoặc orchestrator trước khi ứng dụng của bạn khởi động. Mọi lời gọi query() tự động nhận được chúng mà không cần đổi code. Đây là cách tiếp cận khuyến nghị cho triển khai production.
Option theo từng lời gọi: đặt biến trong ClaudeAgentOptions.env (Python) hoặc options.env (TypeScript). Dùng cách này khi các agent khác nhau trong cùng process cần cấu hình telemetry khác nhau. Trong Python, env được merge chồng lên môi trường kế thừa. Trong TypeScript, env thay thế hoàn toàn môi trường kế thừa, nên hãy đưa ...process.env vào object bạn truyền.

CLI xuất ba tín hiệu OpenTelemetry độc lập. Mỗi tín hiệu có công tắc bật riêng và exporter riêng, nên bạn có thể chỉ bật những cái bạn cần.

Signal	Chứa gì	Bật bằng
Metrics	Bộ đếm cho token, cost, session, số dòng code, và quyết định về tool	`OTEL_METRICS_EXPORTER`
Log events	Bản ghi cấu trúc cho mỗi prompt, API request, API error, và kết quả tool	`OTEL_LOGS_EXPORTER`
Traces	Span cho mỗi tương tác, model request, tool call, và hook (beta)	`OTEL_TRACES_EXPORTER` cộng thêm `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`

Để xem danh sách đầy đủ tên metric, tên event, và attribute, xem tham khảo Claude Code Monitoring. Agent SDK phát ra cùng dữ liệu vì nó chạy cùng CLI. Tên span được liệt kê ở Đọc trace của agent bên dưới.

Bật xuất telemetry

Telemetry mặc định tắt cho tới khi bạn đặt CLAUDE_CODE_ENABLE_TELEMETRY=1 và chọn ít nhất một exporter. Cấu hình phổ biến nhất là gửi cả ba tín hiệu qua OTLP HTTP tới một collector.

Ví dụ sau đặt các biến trong một dictionary và truyền qua options.env. Agent chạy một tác vụ duy nhất, và CLI xuất span, metric, và event tới collector tại collector.example.com trong lúc vòng lặp tiêu thụ response stream:

```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions

OTEL_ENV = { “CLAUDE_CODE_ENABLE_TELEMETRY”: “1”, # Required for traces, which are in beta. Metrics and log events do not need this. “CLAUDE_CODE_ENHANCED_TELEMETRY_BETA”: “1”, # Choose an exporter per signal. Use otlp for the SDK; see the Note below. “OTEL_TRACES_EXPORTER”: “otlp”, “OTEL_METRICS_EXPORTER”: “otlp”, “OTEL_LOGS_EXPORTER”: “otlp”, # Standard OTLP transport configuration. “OTEL_EXPORTER_OTLP_PROTOCOL”: “http/protobuf”, “OTEL_EXPORTER_OTLP_ENDPOINT”: “http://collector.example.com:4318”, “OTEL_EXPORTER_OTLP_HEADERS”: “Authorization=Bearer your-token”, }

async def main(): options = ClaudeAgentOptions(env=OTEL_ENV) async for message in query( prompt=“List the files in this directory”, options=options ): print(message)

asyncio.run(main())

```typescript TypeScript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";

const otelEnv = {
  CLAUDE_CODE_ENABLE_TELEMETRY: "1",
  // Required for traces, which are in beta. Metrics and log events do not need this.
  CLAUDE_CODE_ENHANCED_TELEMETRY_BETA: "1",
  // Choose an exporter per signal. Use otlp for the SDK; see the Note below.
  OTEL_TRACES_EXPORTER: "otlp",
  OTEL_METRICS_EXPORTER: "otlp",
  OTEL_LOGS_EXPORTER: "otlp",
  // Standard OTLP transport configuration.
  OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf",
  OTEL_EXPORTER_OTLP_ENDPOINT: "http://collector.example.com:4318",
  OTEL_EXPORTER_OTLP_HEADERS: "Authorization=Bearer your-token",
};

for await (const message of query({
  prompt: "List the files in this directory",
  // env replaces the inherited environment in TypeScript, so spread
  // process.env first to keep PATH, ANTHROPIC_API_KEY, and other variables.
  options: { env: { ...process.env, ...otelEnv } },
})) {
  console.log(message);
}

Vì child process kế thừa môi trường ứng dụng của bạn theo mặc định, bạn có thể đạt kết quả tương tự bằng cách export các biến này trong Dockerfile, Kubernetes manifest, hoặc shell profile và bỏ qua options.env hoàn toàn.

Để xác nhận việc xuất đang hoạt động, kiểm tra log của collector xem có span, metric, và log event đến sau khi tác vụ hoàn tất không. Theo mặc định CLI thất bại âm thầm khi xuất lỗi: nếu endpoint không thể tới hoặc từ chối dữ liệu, agent vẫn chạy bình thường và CLI drop telemetry mà không báo lỗi cho ứng dụng của bạn. Để lỗi exporter hiện ra, đặt CLAUDE_CODE_OTEL_DIAG_STDERR=1 cùng với các biến exporter và đọc diagnostics qua callback stderr của SDK (Python) hoặc option stderr (TypeScript). Yêu cầu Claude Code v2.1.179 trở lên.

Flush telemetry từ lời gọi ngắn hạn

CLI gộp telemetry theo batch và xuất theo interval. Khi process thoát sạch, nó cố flush dữ liệu đang chờ, nhưng flush bị giới hạn bởi timeout ngắn, nên span vẫn có thể bị mất nếu collector phản hồi chậm. Nếu process của bạn bị kill trước khi CLI shutdown, mọi thứ còn trong batch buffer sẽ mất. Giảm export interval sẽ thu hẹp cả hai khoảng thời gian rủi ro này.

Theo mặc định, metric xuất mỗi 60 giây còn trace và log xuất mỗi 5 giây. Ví dụ sau rút ngắn cả ba interval để dữ liệu tới collector trong khi một tác vụ ngắn vẫn đang chạy:

```python Python theme={null} OTEL_ENV = { # ... exporter configuration from the previous example ... "OTEL_METRIC_EXPORT_INTERVAL": "1000", "OTEL_LOGS_EXPORT_INTERVAL": "1000", "OTEL_TRACES_EXPORT_INTERVAL": "1000", } ```

const otelEnv = {
  // ... exporter configuration from the previous example ...
  OTEL_METRIC_EXPORT_INTERVAL: "1000",
  OTEL_LOGS_EXPORT_INTERVAL: "1000",
  OTEL_TRACES_EXPORT_INTERVAL: "1000",
};

Đọc trace của agent

Trace cho bạn cái nhìn chi tiết nhất về một lần chạy agent. Khi đặt CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, mỗi bước của agent loop trở thành một span bạn có thể xem trong tracing backend của mình:

claude_code.interaction: bao bọc một turn của agent loop, từ lúc nhận prompt tới lúc tạo ra phản hồi.
claude_code.llm_request: bao bọc mỗi lời gọi tới Claude API, với model name, latency, và số lượng token làm attribute.
claude_code.tool: bao bọc mỗi lần gọi tool, với các child span cho thời gian chờ permission (claude_code.tool.blocked_on_user) và bản thân việc thực thi (claude_code.tool.execution).
claude_code.hook: bao bọc mỗi lần thực thi hook. Yêu cầu detailed beta tracing (ENABLE_BETA_TRACING_DETAILED=1 và BETA_TRACING_ENDPOINT) thêm vào các biến ở trên.

Các span llm_request, tool, và hook là con của span claude_code.interaction bao ngoài. Khi agent sinh ra một subagent qua Task tool, các span llm_request và tool của subagent lồng dưới span claude_code.tool của agent cha, nên toàn bộ chuỗi delegation hiện ra như một trace duy nhất.

Span mang attribute session.id theo mặc định. Khi bạn thực hiện nhiều lời gọi query() trên cùng một session, hãy lọc theo session.id trong backend của bạn để xem chúng như một timeline. Claude Code bỏ qua attribute này nếu bạn đặt OTEL_METRICS_INCLUDE_SESSION_ID thành giá trị falsy.

Liên kết trace với ứng dụng của bạn

SDK tự động propagate W3C trace context vào CLI subprocess. Khi bạn gọi query() trong lúc có một span OpenTelemetry đang active trong ứng dụng của bạn, SDK inject TRACEPARENT và TRACESTATE vào môi trường của child process, và CLI đọc chúng để span claude_code.interaction của nó trở thành con của span của bạn. Lần chạy agent khi đó xuất hiện bên trong trace của ứng dụng bạn thay vì là một root rời rạc.

Bản ghi OTLP event log phát ra trong lúc chạy mang cùng trace context: khi TRACEPARENT được đặt, trace_id và span_id của mỗi bản ghi khớp với trace của ứng dụng bạn, nên bạn có thể join event với span trong backend của mình. Trước v2.1.212, bản ghi event phát ra ngoài một span đang active không mang trace_id hay span_id.

Khi trace-context propagation được bật, CLI cũng forward TRACEPARENT tới mọi lệnh Bash và PowerShell nó chạy. Nếu một lệnh chạy qua Bash tool tự phát ra span OpenTelemetry riêng, những span đó lồng dưới span claude_code.tool.execution bao quanh lệnh đó.

Auto-injection bị bỏ qua khi bạn đặt TRACEPARENT tường minh trong options.env, nên bạn có thể ghim một parent context cụ thể nếu cần. Session CLI tương tác bỏ qua hoàn toàn TRACEPARENT đến từ bên ngoài; chỉ Agent SDK và claude -p mới tôn trọng nó. Xem Traces (beta) trong tham khảo Monitoring để có tham khảo đầy đủ về span và attribute.

Gắn tag telemetry từ agent của bạn

Theo mặc định, CLI báo cáo service.name là claude-code. Nếu bạn chạy nhiều agent, hoặc chạy SDK cùng các service khác xuất tới cùng collector, hãy ghi đè service name và thêm resource attribute để có thể lọc theo agent trong backend của bạn.

Ví dụ sau đổi tên service và gắn metadata deployment. Các giá trị này được áp dụng làm OpenTelemetry resource attribute trên mọi span, metric, và event mà agent phát ra:

```python Python theme={null} options = ClaudeAgentOptions( env={ # ... exporter configuration from the Enable telemetry export example ... "OTEL_SERVICE_NAME": "support-triage-agent", "OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production", }, ) ```

const options = {
  env: {
    ...process.env,
    // ... exporter configuration from the Enable telemetry export example ...
    OTEL_SERVICE_NAME: "support-triage-agent",
    OTEL_RESOURCE_ATTRIBUTES:
      "service.version=1.4.0,deployment.environment=production",
  },
};

Gán hành động cho end user của bạn

CLI gắn identity attribute vào mỗi event dựa trên credential nó dùng để gọi Anthropic. Khi bạn xây một ứng dụng phục vụ nhiều end user từ một deployment, các attribute này chỉ định danh credential của service bạn, không phải end user mà agent hành động thay mặt.

Để làm cho tool call và hoạt động MCP quy về được end user của ứng dụng bạn, hãy inject identity của end user làm resource attribute trên mỗi lời gọi query(). Percent-encode giá trị trước khi nội suy chúng, vì OTEL_RESOURCE_ATTRIBUTES dành riêng dấu phẩy, khoảng trắng, và dấu bằng. Ví dụ sau gắn user và tenant thực hiện request vào mọi span và event từ một request. Nó giả định có một object request từ web framework của bạn mang user ID và tenant ID:

```python Python theme={null} from urllib.parse import quote

options = ClaudeAgentOptions( env={ # … exporter configuration from the Enable telemetry export example … # request is the incoming request object from your web framework. “OTEL_RESOURCE_ATTRIBUTES”: f”enduser.id={quote(request.user_id)},tenant.id={quote(request.tenant_id)}”, }, )

```typescript TypeScript theme={null}
const options = {
  env: {
    ...process.env,
    // ... exporter configuration from the Enable telemetry export example ...
    // request is the incoming request object from your web framework.
    OTEL_RESOURCE_ATTRIBUTES: `enduser.id=${encodeURIComponent(request.userId)},tenant.id=${encodeURIComponent(request.tenantId)}`,
  },
};

Với identity của end user được gắn kèm, các event tool_decision, tool_result, mcp_server_connection, và permission_mode_changed, vốn được xuất dưới dạng log record có tên bắt đầu bằng prefix claude_code., trở thành một audit trail theo từng người dùng mà bạn có thể forward tới một nền tảng Security Information and Event Management (SIEM). Xem Audit security events trong tham khảo Monitoring để có danh sách đầy đủ các event liên quan tới bảo mật và attribute mỗi event mang theo.

Kiểm soát dữ liệu nhạy cảm trong export

Telemetry mang tính cấu trúc theo mặc định. Duration, model name, và tool name được ghi trên mọi span; số lượng token được ghi khi API request trả về dữ liệu usage, nên span cho các request thất bại hoặc bị hủy có thể thiếu chúng. Nội dung agent của bạn đọc và ghi không được ghi lại theo mặc định. Các biến opt-in sau thêm nội dung vào dữ liệu xuất ra:

Variable	Thêm gì
`OTEL_LOG_USER_PROMPTS=1`	Nội dung prompt trên event `claude_code.user_prompt` và trên span `claude_code.interaction`
`OTEL_LOG_TOOL_DETAILS=1`	Tham số input của tool (đường dẫn file, lệnh shell, pattern tìm kiếm) trên event `claude_code.tool_result`
`OTEL_LOG_TOOL_CONTENT=1`	Toàn bộ nội dung input và output của tool dưới dạng span event trên `claude_code.tool`, mặc định bị cắt ở 60 KB, có thể cấu hình qua `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH`, yêu cầu Claude Code v2.1.214 trở lên. Yêu cầu tracing đã được bật
`OTEL_LOG_RAW_API_BODIES`	Toàn bộ JSON request và response của Anthropic Messages API dưới dạng log event `claude_code.api_request_body` và `claude_code.api_response_body`. Đặt thành `1` để có body inline bị cắt ở 60 KB mặc định, hoặc `file:<dir>` để có body không cắt lưu trên đĩa với một đường dẫn `body_ref` trong event. `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` cấu hình giới hạn cắt inline, và yêu cầu Claude Code v2.1.214 trở lên. Body bao gồm toàn bộ lịch sử hội thoại và có nội dung extended-thinking bị redact. Bật biến này đồng nghĩa với việc chấp nhận mọi thứ ba biến trên có thể tiết lộ

Để các biến này chưa đặt trừ khi observability pipeline của bạn được phê duyệt để lưu trữ dữ liệu agent của bạn xử lý. Xem Security and privacy trong tham khảo Monitoring để có danh sách đầy đủ attribute và hành vi redaction.

Tài liệu liên quan

Các hướng dẫn sau bao gồm các chủ đề liên quan về giám sát và triển khai agent:

Theo dõi cost và usage: đọc dữ liệu token và cost từ message stream mà không cần backend bên ngoài.
Hosting Agent SDK: triển khai agent trong container nơi bạn có thể đặt biến OpenTelemetry ở cấp môi trường.
Monitoring: tham khảo đầy đủ cho mọi biến môi trường, metric, và event mà CLI phát ra.

Phuc Tran

Software Engineer | Learning Claude