Monitoring

Theo dõi usage và hoạt động Cowork trong tổ chức bằng cách export event qua OpenTelemetry (OTel). Cowork export event qua OTel logs/events protocol, cho bạn thấy được prompt của user, response của model, API request, tool usage, và lỗi.

Ghi chú

Monitoring chỉ dùng được trên plan Team và Enterprise. OTel monitoring cần Claude desktop app bản 1.1.4173 hoặc mới hơn.

Thiết lập

Cấu hình monitoring từ Cowork admin settings:

1. Vào Admin settings > Cowork

2. Cấu hình các trường sau:

   Trường	Mô tả	Ví dụ
   OTLP endpoint	URL của OpenTelemetry collector	http://collector.example.com:4318
   OTLP protocol	Transport protocol	http/json hoặc http/protobuf
   OTLP headers	Header xác thực cho collector của bạn	Authorization=Bearer your-token

3. Lưu cấu hình

4. Bắt đầu session Cowork mới - cấu hình được nạp lúc bắt đầu session, session đang chạy sẽ không nhận cấu hình mới

Ghi chú

OTel exporter chạy trong VM của Cowork, nên chịu quy tắc egress của session đó. Nếu tổ chức bạn giới hạn network egress, Cowork tự thêm hostname của collector vào egress allowlist của session - bạn không cần thêm tay ở Admin settings > Capabilities > Network egress.

Các event

Cowork export các event sau tới OTel collector. Theo mặc định, event chỉ chứa metadata. Nội dung prompt của user, text response của model, và chi tiết tool chỉ được đưa vào khi bạn bật bằng setting otlpContentCapture.

Liên kết các event (event correlation)

Khi user gửi một prompt, Cowork có thể gọi nhiều API và chạy nhiều tool. Attribute prompt.id liên kết tất cả event về đúng prompt đã tạo ra chúng.

Attribute	Mô tả
prompt.id	UUID v4 định danh, liên kết mọi event sinh ra trong lúc xử lý một prompt

Lọc event theo một giá trị prompt.id cụ thể để trace toàn bộ hoạt động do một prompt gây ra.

Trên các bản deploy third-party, bạn có thể bật thêm OpenTelemetry trace export bằng setting otlpTracesEnabled (beta). Khi bật, các event phát ra lúc xử lý prompt sẽ có thêm trace_id và span_id, liên kết với trace span của session để phục vụ correlation đầu-cuối trong hệ thống observability của bạn.

Attribute chuẩn

Mọi event đều có các attribute sau:

Attribute	Mô tả
session.id	ID session
organization.id	UUID của tổ chức
user.account_uuid	UUID tài khoản user
user.account_id	Account ID dạng tag, khớp với Anthropic admin API (ví dụ user_01BWBeN28...)
user.id	ID thiết bị/bản cài đặt, ẩn danh
user.email	Email user
workspace.host_paths	Các thư mục workspace trên host đã chọn trong desktop app (array chuỗi)
terminal.type	Loại terminal (non-interactive cho Cowork)

Event user_prompt

Ghi log khi user gửi một prompt.

Tên event: user_prompt

Ngoài các attribute chuẩn, có thêm:

Attribute	Mô tả
event.timestamp	Timestamp ISO 8601
event.sequence	Counter tăng dần để sắp thứ tự event trong session
prompt_length	Độ dài prompt
prompt	Nội dung prompt

Event assistant_response

Ghi log khi model hoàn thành một response có text output. Cần Claude desktop app bản 1.17377 hoặc mới hơn.

Tên event: assistant_response

Ngoài các attribute chuẩn:

Attribute	Mô tả
event.timestamp	Timestamp ISO 8601
event.sequence	Counter tăng dần
model	Model tạo ra response
request_id	ID request API
response_length	Độ dài response
response	Text response của model (không gồm nội dung “thinking”). Bị cắt ở 60 KB. Khi tắt capture response, giá trị là chuỗi <REDACTED>

Response của model chỉ được ghi khi otlpContentCapture có assistantResponses, hoặc bất cứ khi nào prompt của user được capture.

Event tool_result

Ghi log khi một tool chạy xong.

Tên event: tool_result

Attribute	Mô tả
event.timestamp	Timestamp ISO 8601
event.sequence	Counter tăng dần
tool_name	Tên tool
success	"true" hoặc "false"
duration_ms	Thời gian chạy (ms)
error	Thông báo lỗi (nếu fail)
decision_type	"accept" hoặc "reject"
decision_source	Nguồn quyết định - "config", "hook", "user_permanent", "user_temporary", "user_abort", hoặc "user_reject"
tool_result_size_bytes	Kích thước kết quả tool (byte)
mcp_server_scope	ID scope của MCP server (cho tool MCP)
tool_parameters	Chuỗi JSON chứa tham số của tool, gồm mcp_server_name và mcp_tool_name cho tool MCP
tool_input	Tham số tool dạng JSON. Chuỗi dài hơn 512 ký tự bị cắt; toàn bộ giới hạn khoảng 4K ký tự. Áp dụng cho mọi tool, kể cả MCP

Event api_request

Ghi log cho mỗi API request tới Claude.

Tên event: api_request

Attribute	Mô tả
event.timestamp	Timestamp ISO 8601
event.sequence	Counter tăng dần
model	Model dùng (vd. claude-sonnet-5)
cost_usd	Chi phí ước tính (USD)
duration_ms	Thời gian request
input_tokens	Số token input
output_tokens	Số token output
cache_read_tokens	Số token đọc từ cache
cache_creation_tokens	Số token dùng để tạo cache
speed	"fast" hoặc "normal"

Event api_error

Ghi log khi một API request tới Claude bị lỗi.

Tên event: api_error

Attribute	Mô tả
event.timestamp	Timestamp ISO 8601
event.sequence	Counter tăng dần
model	Model dùng
error	Thông báo lỗi
status_code	HTTP status code dạng chuỗi, hoặc "undefined" nếu không phải lỗi HTTP
duration_ms	Thời gian request
attempt	Số lần thử (cho request bị retry)
speed	"fast" hoặc "normal"

Event tool_decision

Ghi log khi có quyết định cấp quyền cho một tool.

Tên event: tool_decision

Attribute	Mô tả
event.timestamp	Timestamp ISO 8601
event.sequence	Counter tăng dần
tool_name	Tên tool
decision	"accept" hoặc "reject"
source	Nguồn quyết định - "config", "hook", "user_permanent", "user_temporary", "user_abort", hoặc "user_reject"

Phân tích event

Các event export ra hỗ trợ nhiều loại phân tích:

• Pattern dùng tool - phân tích event tool_result để tìm tool dùng nhiều nhất, tỷ lệ thành công, thời gian chạy trung bình, pattern lỗi.
• Theo dõi chi phí - theo dõi cost_usd từ event api_request để hiểu xu hướng usage theo user/team. Group theo user.account_uuid hoặc organization.id.
• Theo dõi hiệu năng - theo dõi thời gian API request và thời gian chạy tool để tìm điểm nghẽn hiệu năng.

Ghi chú

Giá trị chi phí từ event chỉ là ước tính. Số liệu billing chính thức lấy từ billing dashboard.

Chọn backend

Backend log bạn chọn quyết định loại phân tích bạn có thể làm:

• Hệ thống log aggregation (Elasticsearch, Loki…): full-text search và phân tích log.
• Columnar store (ClickHouse…): phân tích event có cấu trúc, query phức tạp.
• Nền tảng observability (Honeycomb, Datadog…): query nâng cao, visualization, alerting.

Thông tin service

Mọi event export kèm các resource attribute:

Attribute	Mô tả
service.name	cowork
service.version	Phiên bản Claude app
host.arch	Kiến trúc host (vd. arm64)
os.type	Loại hệ điều hành (vd. darwin)
os.version	Phiên bản hệ điều hành

Bảo mật và quyền riêng tư

• Event chỉ được export khi admin cấu hình OTLP endpoint.
• Nội dung prompt của user chỉ được đưa vào khi bạn bật userPrompts trong otlpContentCapture.
• Từ Claude desktop app bản 1.17377, text response của model được đưa vào khi bạn bật assistantResponses trong otlpContentCapture, và cả khi nội dung prompt của user được capture.
• Attribute tool_input (đường dẫn file, URL, pattern tìm kiếm và tham số khác) chỉ được đưa vào khi bạn bật toolDetails trong otlpContentCapture.
• user.email luôn có trong attribute của event - hãy cấu hình backend telemetry để lọc/redact nếu đây là vấn đề với bạn.

Nguồn

Trang này dịch từ Monitoring trong tài liệu chính thức.