رفتن به محتوا
Claude Code Docs غیر رسمی

پایش

استفاده، هزینه و فعالیتِ ابزارِ Claude Code را در سراسرِ سازمانت با خروجی‌گرفتن از داده‌های تله‌متری از طریقِ OpenTelemetry (OTel) رصد کن. Claude Code متریک‌ها را به‌صورتِ داده‌ی سری‌زمانی از طریقِ پروتکلِ استانداردِ متریک، رویدادها را از طریقِ پروتکلِ logs/events، و به‌صورتِ اختیاری ردهای توزیع‌شده (traces) را از طریقِ پروتکلِ traces صادر می‌کند. بک‌اندهای متریک، لاگ و ردِ خود را مطابقِ نیازهای پایشت پیکربندی کن.

شروعِ سریع

Section titled “شروعِ سریع”

OpenTelemetry را با متغیرهای محیطی پیکربندی کن:

Terminal window
# 1. Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1


# 2. Choose exporters (both are optional - configure only what you need)
export OTEL_METRICS_EXPORTER=otlp       # Options: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # Options: otlp, console, none


# 3. Configure OTLP endpoint (for OTLP exporter)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317


# 4. Set authentication (if required)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"


# 5. For debugging: reduce export intervals
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 seconds (default: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 seconds (default: 5000ms)


# 6. Run Claude Code
claude

برای گزینه‌های کاملِ پیکربندی، به مشخصاتِ OpenTelemetry مراجعه کن.

پیکربندیِ مدیر

Section titled “پیکربندیِ مدیر”

مدیران می‌توانند تنظیماتِ OpenTelemetry را برای همه‌ی کاربران از طریقِ فایلِ تنظیماتِ مدیریت‌شده پیکربندی کنند. این امکانِ کنترلِ متمرکزِ تنظیماتِ تله‌متری در سراسرِ یک سازمان را می‌دهد. برای اطلاعاتِ بیشتر درباره‌ی نحوه‌ی اعمالِ تنظیمات، اولویتِ تنظیمات را ببین.

نمونه‌ی پیکربندیِ تنظیماتِ مدیریت‌شده:

{
  "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"
  }
}

Claude Code متغیرهای محیطیِ OTEL_* را به زیرفرایندهایی که راه می‌اندازد — از جمله ابزارِ Bash، هوک‌ها، سرورهای MCP و سرورهای زبان — پاس نمی‌دهد. یک اپلیکیشنِ ابزارگذاری‌شده با OpenTelemetry که از طریقِ ابزارِ Bash اجرا می‌کنی، endpoint یا هدرهای exporterِ Claude Code را به ارث نمی‌برد، پس اگر آن اپلیکیشن نیاز دارد تله‌متریِ خودش را صادر کند، آن متغیرها را مستقیماً در دستور تنظیم کن.

جزئیاتِ پیکربندی

Section titled “جزئیاتِ پیکربندی”

متغیرهای پیکربندیِ مشترک

Section titled “متغیرهای پیکربندیِ مشترک”
متغیرِ محیطیتوضیحمقادیرِ نمونه
CLAUDE_CODE_ENABLE_TELEMETRYجمع‌آوریِ تله‌متری را فعال می‌کند (الزامی)1
OTEL_METRICS_EXPORTERنوع‌های exporterِ متریک، جداشده با کاما. برای غیرفعال‌کردن از none استفاده کنconsole, otlp, prometheus, none
OTEL_LOGS_EXPORTERنوع‌های exporterِ logs/events، جداشده با کاما. برای غیرفعال‌کردن از none استفاده کنconsole, otlp, none
OTEL_EXPORTER_OTLP_PROTOCOLپروتکلِ exporterِ OTLP، به همه‌ی سیگنال‌ها اعمال می‌شودgrpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTendpointِ collectorِ OTLP برای همه‌ی سیگنال‌هاhttp://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOLپروتکلِ متریک‌ها، تنظیمِ کلی را بازنویسی می‌کندgrpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTendpointِ متریکِ OTLP، تنظیمِ کلی را بازنویسی می‌کندhttp://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOLپروتکلِ لاگ‌ها، تنظیمِ کلی را بازنویسی می‌کندgrpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTendpointِ لاگِ OTLP، تنظیمِ کلی را بازنویسی می‌کندhttp://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERSهدرهای احراز هویت برای OTLPAuthorization=Bearer token
OTEL_METRIC_EXPORT_INTERVALبازه‌ی خروجی به میلی‌ثانیه (پیش‌فرض: 60000)5000, 60000
OTEL_LOGS_EXPORT_INTERVALبازه‌ی خروجیِ لاگ به میلی‌ثانیه (پیش‌فرض: 5000)1000, 10000
OTEL_LOG_USER_PROMPTSلاگ‌کردنِ محتوای پرامپتِ کاربر را فعال می‌کند (پیش‌فرض: غیرفعال)1 برای فعال‌کردن
OTEL_LOG_TOOL_DETAILSلاگ‌کردنِ پارامترها و آرگومان‌های ورودیِ ابزار را در رویدادهای ابزار و صفاتِ span ردها فعال می‌کند: دستورهای Bash، نام‌های سرور و ابزارِ MCP، نام‌های مهارت (skill) و ورودیِ ابزار. همچنین نام‌های دستورِ سفارشی، پلاگین و MCP را روی رویدادهای user_prompt فعال می‌کند (پیش‌فرض: غیرفعال)1 برای فعال‌کردن
OTEL_LOG_TOOL_CONTENTلاگ‌کردنِ محتوای ورودی و خروجیِ ابزار را در رویدادهای span فعال می‌کند (پیش‌فرض: غیرفعال). نیازمندِ tracing است. محتوا در 60 KB کوتاه می‌شود1 برای فعال‌کردن
OTEL_LOG_RAW_API_BODIESکلِ JSONِ درخواست و پاسخِ Anthropic Messages API را به‌صورتِ رویدادهای لاگِ api_request_body / api_response_body صادر می‌کند (پیش‌فرض: غیرفعال). بدنه‌ها کلِ تاریخچه‌ی گفت‌وگو را دربردارند. فعال‌کردنِ این به‌معنای رضایت به هر چیزی است که OTEL_LOG_USER_PROMPTS، OTEL_LOG_TOOL_DETAILS و OTEL_LOG_TOOL_CONTENT آشکار می‌کنند1 برای بدنه‌های خطی کوتاه‌شده در 60 KB، یا file:<dir> برای بدنه‌های کوتاه‌نشده روی دیسک همراه با اشاره‌گرِ body_ref در رویداد
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCEترجیحِ زمان‌مندیِ متریک‌ها (پیش‌فرض: delta). اگر بک‌اندت زمان‌مندیِ تجمعی می‌خواهد روی cumulative بگذارdelta, cumulative
CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MSبازه‌ی تازه‌سازیِ هدرهای پویا (پیش‌فرض: 1740000ms / ۲۹ دقیقه)900000

احراز هویت mTLS

Section titled “احراز هویت mTLS”

نحوه‌ی پیکربندیِ گواهی‌های کلاینت برای exporterِ OTLP به پروتکلِ OTLPی که برای آن سیگنال در استفاده است بستگی دارد، که از طریقِ OTEL_EXPORTER_OTLP_PROTOCOL یا بازنویسیِ هر-سیگنال تنظیم می‌شود. همین پیکربندی به متریک‌ها، لاگ‌ها و ردها اعمال می‌شود.

پروتکلمتغیرهای گواهیِ کلاینتاعتماد به CAی collector با
http/protobuf, http/jsonCLAUDE_CODE_CLIENT_CERT، CLAUDE_CODE_CLIENT_KEY و به‌صورت اختیاری CLAUDE_CODE_CLIENT_KEY_PASSPHRASE. Network configuration را ببینNODE_EXTRA_CA_CERTS
grpcOTEL_EXPORTER_OTLP_CLIENT_KEY و OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE، یا گونه‌های هر-سیگنال مانند OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY برای استفاده از گواهیِ متفاوت برای هر سیگنالOTEL_EXPORTER_OTLP_CERTIFICATE

برای grpc، خودِ OpenTelemetry SDK متغیرهای استانداردِ OTLP را مستقیماً می‌خواند، پس پیکربندی‌های موجودی که متغیرهای متریکِ هر-سیگنال را تنظیم می‌کنند همچنان کار می‌کنند.

کنترلِ کاردینالیتیِ متریک‌ها

Section titled “کنترلِ کاردینالیتیِ متریک‌ها”

متغیرهای محیطیِ زیر کنترل می‌کنند که کدام صفات در متریک‌ها گنجانده شوند تا کاردینالیتی مدیریت شود:

متغیرِ محیطیتوضیحمقدارِ پیش‌فرضنمونه برای غیرفعال‌کردن
OTEL_METRICS_INCLUDE_SESSION_IDگنجاندنِ صفتِ session.id در متریک‌هاtruefalse
OTEL_METRICS_INCLUDE_VERSIONگنجاندنِ صفتِ app.version در متریک‌هاfalsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUIDگنجاندنِ صفاتِ user.account_uuid و user.account_id در متریک‌هاtruefalse
OTEL_METRICS_INCLUDE_ENTRYPOINTگنجاندنِ صفتِ app.entrypoint در متریک‌هاfalsetrue
OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTESگنجاندنِ کلیدهای OTEL_RESOURCE_ATTRIBUTES به‌عنوانِ صفات روی نقاطِ داده‌ی متریکtruefalse

این متغیرها به کنترلِ کاردینالیتیِ متریک‌ها کمک می‌کنند که بر نیازهای ذخیره‌سازی و کاراییِ کوئری در بک‌اندِ متریکِ تو اثر می‌گذارد. کاردینالیتیِ پایین‌تر معمولاً به‌معنای کاراییِ بهتر و هزینه‌ی ذخیره‌سازیِ کمتر است، اما داده‌ی کم‌جزئیات‌تری برای تحلیل می‌دهد.

ردها (بتا)

Section titled “ردها (بتا)”

ردگیریِ توزیع‌شده، spanهایی را صادر می‌کند که هر پرامپتِ کاربر را به درخواست‌های API و اجراهای ابزاری که برمی‌انگیزد پیوند می‌دهند، تا بتوانی یک درخواستِ کامل را به‌عنوانِ یک ردِ واحد در بک‌اندِ ردگیریت ببینی.

ردگیری به‌صورت پیش‌فرض خاموش است. برای فعال‌کردنش، هم CLAUDE_CODE_ENABLE_TELEMETRY=1 و هم CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 را تنظیم کن، سپس OTEL_TRACES_EXPORTER را برای انتخابِ این‌که spanها کجا فرستاده شوند تنظیم کن. ردها برای endpoint، پروتکل، هدرها و mTLS از پیکربندیِ مشترکِ OTLP استفاده‌ی مجدد می‌کنند.

متغیرِ محیطیتوضیحمقادیرِ نمونه
CLAUDE_CODE_ENHANCED_TELEMETRY_BETAردگیریِ span را فعال می‌کند (الزامی). ENABLE_ENHANCED_TELEMETRY_BETA هم پذیرفته می‌شود1
OTEL_TRACES_EXPORTERنوع‌های exporterِ ردها، جداشده با کاما. برای غیرفعال‌کردن از none استفاده کنconsole, otlp, none
OTEL_EXPORTER_OTLP_TRACES_PROTOCOLپروتکلِ ردها، OTEL_EXPORTER_OTLP_PROTOCOL را بازنویسی می‌کندgrpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTendpointِ ردهای OTLP، OTEL_EXPORTER_OTLP_ENDPOINT را بازنویسی می‌کندhttp://localhost:4318/v1/traces
OTEL_TRACES_EXPORT_INTERVALبازه‌ی خروجیِ دسته‌ایِ span به میلی‌ثانیه (پیش‌فرض: 5000)1000, 10000

spanها به‌صورت پیش‌فرض متنِ پرامپتِ کاربر، جزئیاتِ ورودیِ ابزار و محتوای ابزار را پنهان (redact) می‌کنند. برای گنجاندنشان، OTEL_LOG_USER_PROMPTS=1، OTEL_LOG_TOOL_DETAILS=1 و OTEL_LOG_TOOL_CONTENT=1 را تنظیم کن.

وقتی ردگیری فعال است، زیرفرایندهای Bash و PowerShell به‌صورت خودکار یک متغیرِ محیطیِ TRACEPARENT را به ارث می‌برند که کانتکستِ ردِ W3Cِ spanِ اجرای ابزارِ فعال را دربردارد. این کار به هر زیرفرایندی که TRACEPARENT را می‌خواند اجازه می‌دهد spanهای خودش را زیرِ همان رد قرار دهد و ردگیریِ توزیع‌شده‌ی سرتاسری را در اسکریپت‌ها و دستورهایی که Claude اجرا می‌کند ممکن می‌سازد.

وقتی ردگیری فعال است و Claude Code مستقیماً به Anthropic API متصل است، هر درخواستِ مدل یک هدرِ traceparent به‌سبکِ W3C حمل می‌کند که روی کانتکستِ spanِ claude_code.llm_request تنظیم شده، و هدرِ traceresponseِ API به‌عنوانِ یک پیوندِ span ثبت می‌شود. این دو با هم، spanهای سمتِ کلاینتِ Claude Code را از طریقِ هر واسطه‌ی منطبق به ردِ سمتِ سرور وصل می‌کنند. درخواست‌های خروجیِ HTTP MCP هم traceparent را به همین شکل حمل می‌کنند. این هدر به ارائه‌دهندگانِ شخصِ ثالث فرستاده نمی‌شود.

به‌صورت پیش‌فرض، هدرِ traceparent روی درخواست‌های مدل و HTTP MCP فقط زمانی فرستاده می‌شود که ANTHROPIC_BASE_URL تنظیم نشده باشد یا به Anthropic API اشاره کند، چون برخی پراکسی‌ها هدرهای ناشناس را رد می‌کنند. متغیرِ TRACEPARENTِ زیرفرایند هم برای سازگاری با همین کلید کنترل می‌شود. اگر Claude Code را از طریقِ یک پراکسیِ سفارشیِ ANTHROPIC_BASE_URL اجرا می‌کنی و می‌خواهی کانتکستِ رد منتشر شود، CLAUDE_CODE_PROPAGATE_TRACEPARENT=1 را تنظیم کن.

در Agent SDK و نشست‌های غیرتعاملیِ شروع‌شده با -p، Claude Code هنگامِ شروعِ هر spanِ تعامل، TRACEPARENT و TRACESTATE را هم از محیطِ خودش می‌خواند. این به یک فرایندِ تعبیه‌کننده اجازه می‌دهد کانتکستِ ردِ فعالِ W3Cِ خودش را به زیرفرایند پاس بدهد تا spanهای Claude Code به‌عنوانِ فرزندانِ ردِ توزیع‌شده‌ی فراخوان ظاهر شوند. نشست‌های تعاملی TRACEPARENTِ ورودی را نادیده می‌گیرند تا به‌طورِ تصادفی مقادیرِ محیطی از CI یا کانتینرها را به ارث نبرند.

سلسله‌مراتبِ span

Section titled “سلسله‌مراتبِ span”

هر پرامپتِ کاربر یک spanِ ریشه‌ی claude_code.interaction را آغاز می‌کند. فراخوانی‌های API، فراخوانی‌های ابزار و اجراهای هوک به‌عنوانِ فرزندانش ثبت می‌شوند. spanهای ابزار دو spanِ فرزندِ خودشان را دارند: یکی برای زمانِ صرف‌شده در انتظارِ تصمیمِ دسترسی و یکی برای خودِ اجرا. وقتی ابزارِ Agent — یا ابزارِ قدیمیِ Task — یک ساب‌ایجنت را راه می‌اندازد، spanهای API و ابزارِ ساب‌ایجنت زیرِ spanِ claude_code.toolِ والد قرار می‌گیرند.

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (requires detailed beta tracing)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agent tool) subagent claude_code.llm_request / claude_code.tool spans

در نشست‌های Agent SDK و claude -p، خودِ claude_code.interaction وقتی TRACEPARENT در محیط تنظیم شده باشد به فرزندِ spanِ فراخوان تبدیل می‌شود.

صفاتِ span

Section titled “صفاتِ span”

هر span صفاتِ استاندارد را به‌علاوه‌ی یک صفتِ span.type که با نامش می‌خواند حمل می‌کند. جدول‌های زیر صفاتِ اضافی‌ای را که روی هر span تنظیم می‌شوند فهرست می‌کنند. spanهای llm_request، tool.execution و hook هنگامِ ثبتِ یک شکست، وضعیتِ OpenTelemetryِ ERROR را تنظیم می‌کنند؛ بقیه‌ی spanها همیشه با وضعیتِ UNSET پایان می‌یابند.

claude_code.interaction

صفتتوضیحمشروط به
user_promptمتنِ پرامپت. مقدار <REDACTED> است مگر کلید تنظیم شده باشدOTEL_LOG_USER_PROMPTS
user_prompt_lengthطولِ پرامپت به‌کاراکتر
interaction.sequenceشمارنده‌ی ۱-پایه‌ی تعامل‌ها در این نشست
interaction.duration_msمدتِ زمانِ ساعتی نوبت

claude_code.llm_request

صفتتوضیحمشروط به
modelشناسه‌ی مدل
gen_ai.systemهمیشه anthropic. قراردادِ معناییِ GenAIِ OpenTelemetry
gen_ai.request.modelهمان مقدارِ model. قراردادِ معناییِ GenAIِ OpenTelemetry
query_sourceزیرسیستمی که درخواست را صادر کرد، مانند repl_main_thread یا نامِ یک ساب‌ایجنت
agent_idشناسه‌ی ساب‌ایجنت یا هم‌تیمی‌ای که درخواست را صادر کرد. در نشستِ اصلی وجود ندارد
parent_agent_idشناسه‌ی ایجنتی که این یکی را راه انداخته. برای نشستِ اصلی و برای ایجنت‌هایی که مستقیماً از آن راه افتاده‌اند وجود ندارد
speedfast یا normal
llm_request.contextinteraction، tool یا standalone بسته به spanِ والد
duration_msمدتِ زمانِ ساعتی شاملِ تلاش‌های مجدد
ttft_msزمان تا نخستین توکن به میلی‌ثانیه
input_tokensشمارشِ توکنِ ورودی از بلاکِ usageِ API
output_tokensشمارشِ توکنِ خروجی
cache_read_tokensتوکن‌های خوانده‌شده از کشِ پرامپت
cache_creation_tokensتوکن‌های نوشته‌شده در کشِ پرامپت
request_idشناسه‌ی درخواستِ Anthropic API از هدرِ پاسخِ request-id
gen_ai.response.idهمان مقدارِ request_id. قراردادِ معناییِ GenAIِ OpenTelemetry
client_request_idx-client-request-idِ تولیدشده‌ی کلاینت برای آخرین تلاش
attemptتعدادِ کلِ تلاش‌ها برای این درخواست
successtrue یا false
status_codeکدِ وضعیتِ HTTP وقتی درخواست شکست خورد
errorپیامِ خطا وقتی درخواست شکست خورد
response.has_tool_calltrue وقتی پاسخ شاملِ بلاک‌های tool-use بود
stop_reasonstop_reasonِ پاسخِ API، مانند end_turn، tool_use، max_tokens، stop_sequence، pause_turn یا refusal
gen_ai.response.finish_reasonsهمان مقدارِ stop_reason، پیچیده در یک آرایه‌ی رشته‌ای. قراردادِ معناییِ GenAIِ OpenTelemetry

هر تلاشِ مجدد هم به‌صورتِ یک رویدادِ spanِ gen_ai.request.attempt با صفاتِ attempt و client_request_id ثبت می‌شود.

claude_code.tool

صفتتوضیحمشروط به
tool_nameنامِ ابزار
duration_msمدتِ زمانِ ساعتی شاملِ انتظارِ دسترسی و اجرا
result_tokensاندازه‌ی تقریبیِ توکنیِ نتیجه‌ی ابزار
agent_idشناسه‌ی ساب‌ایجنت یا هم‌تیمی‌ای که ابزار را اجرا کرد. در نشستِ اصلی وجود ندارد
parent_agent_idشناسه‌ی ایجنتی که این یکی را راه انداخته. برای نشستِ اصلی و برای ایجنت‌هایی که مستقیماً از آن راه افتاده‌اند وجود ندارد
tool_use_idشناسه‌ی بلاکِ tool_useِ مدل برای این فراخوانی. با tool_use_idِ روی رویدادهای tool_result و tool_decision و در payloadهای هوک می‌خواند، پس می‌توانی span را به آن رکوردها وصل کنی
gen_ai.tool.call.idهمان مقدارِ tool_use_id. قراردادِ معناییِ GenAIِ OpenTelemetry
file_pathمسیرِ فایلِ هدف برای ابزارهای Read، Edit و WriteOTEL_LOG_TOOL_DETAILS
full_commandرشته‌ی دستور برای ابزارِ BashOTEL_LOG_TOOL_DETAILS
skill_nameنامِ مهارت برای ابزارِ SkillOTEL_LOG_TOOL_DETAILS
subagent_typeنوعِ ساب‌ایجنت برای ابزارِ Agent یا ابزارِ قدیمیِ TaskOTEL_LOG_TOOL_DETAILS

وقتی OTEL_LOG_TOOL_CONTENT=1 باشد، این span یک رویدادِ spanِ tool.output هم ثبت می‌کند که صفاتش بدنه‌های ورودی و خروجیِ ابزار را دربردارند، که در هر صفت در 60 KB کوتاه شده‌اند.

claude_code.tool.blocked_on_user

صفتتوضیحمشروط به
duration_msزمانِ صرف‌شده در انتظارِ تصمیمِ دسترسی
decisionaccept یا reject
sourceمنبعِ تصمیم، منطبق با رویدادِ تصمیمِ ابزار

claude_code.tool.execution

صفتتوضیحمشروط به
duration_msزمانِ صرف‌شده برای اجرای بدنه‌ی ابزار
tool_use_idهمان مقدارِ روی spanِ والدِ claude_code.tool
gen_ai.tool.call.idهمان مقدارِ tool_use_id. قراردادِ معناییِ GenAIِ OpenTelemetry
successtrue یا false
errorرشته‌ی دسته‌ی خطا وقتی اجرا شکست خورد، مانند Error:ENOENT یا ShellError. وقتی کلید تنظیم شده باشد به‌جایش پیامِ کاملِ خطا را دربرداردOTEL_LOG_TOOL_DETAILS

claude_code.hook

این span فقط وقتی صادر می‌شود که ردگیریِ بتای جزئی‌نگر فعال باشد، که علاوه بر پیکربندیِ exporterِ ردِ بالا، نیازمندِ ENABLE_BETA_TRACING_DETAILED=1 و BETA_TRACING_ENDPOINT است. در نشست‌های تعاملیِ CLI، این همچنین نیازمندِ آن است که سازمانت برای این قابلیت allowlist شده باشد. نشست‌های Agent SDK و غیرتعاملیِ -p مشمولِ این محدودیت نیستند. وقتی فقط CLAUDE_CODE_ENHANCED_TELEMETRY_BETA تنظیم شده باشد صادر نمی‌شود.

صفتتوضیحمشروط به
hook_eventنوعِ رویدادِ هوک، مانند PreToolUse
hook_nameنامِ کاملِ هوک، مانند PreToolUse:Write
num_hooksتعدادِ دستورهای هوکِ منطبقِ اجراشده
hook_definitionsپیکربندیِ هوکِ سریالایزشده به JSONOTEL_LOG_TOOL_DETAILS
duration_msمدتِ زمانِ ساعتیِ همه‌ی هوک‌های منطبق
num_successشمارشِ هوک‌هایی که با موفقیت تمام شدند
num_blockingشمارشِ هوک‌هایی که تصمیمِ مسدودکننده برگرداندند
num_non_blocking_errorشمارشِ هوک‌هایی که بدونِ مسدودکردن شکست خوردند
num_cancelledشمارشِ هوک‌هایی که پیش از اتمام لغو شدند

هدرهای پویا

Section titled “هدرهای پویا”

برای محیط‌های سازمانی‌ای که احراز هویتِ پویا می‌خواهند، می‌توانی یک اسکریپت برای تولیدِ پویای هدرها پیکربندی کنی. هدرهای پویا فقط به پروتکل‌های http/protobuf و http/json اعمال می‌شوند. exporterِ grpc فقط از مقدارِ ایستای OTEL_EXPORTER_OTLP_HEADERS استفاده می‌کند.

پیکربندیِ تنظیمات

Section titled “پیکربندیِ تنظیمات”

به .claude/settings.jsonِ خود اضافه کن:

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

مقدار می‌تواند مسیرِ یک فایلِ اجرایی — از جمله مسیری که فاصله دارد — یا یک خطِ دستورِ شل با آرگومان باشد. روی Windows، مقدار همیشه از طریقِ شل اجرا می‌شود، پس مسیری را که فاصله دارد داخلِ مقدارِ JSON در گیومه بگذار.

نیازمندی‌های اسکریپت

Section titled “نیازمندی‌های اسکریپت”

اسکریپت باید JSONِ معتبر با جفت‌های کلید-مقدارِ رشته‌ای که نماینده‌ی هدرهای HTTP هستند خروجی بدهد:

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

اگر helper شکست بخورد یا خروجی‌ای بدهد که این نیازمندی‌ها را برآورده نکند، Claude Code خطا را در این‌ها گزارش می‌کند:

  • خروجیِ /doctor
  • لاگِ دیباگ، هنگامِ اجرا با --debug یا پس از اجرای /debug در نشست
  • stderr، در نشست‌های غیرتعاملیِ شروع‌شده با -p

رفتارِ تازه‌سازی

Section titled “رفتارِ تازه‌سازی”

اسکریپتِ helperِ هدرها هنگامِ راه‌اندازی و سپس به‌صورتِ دوره‌ای برای پشتیبانی از تازه‌سازیِ توکن اجرا می‌شود. به‌صورت پیش‌فرض، اسکریپت هر ۲۹ دقیقه اجرا می‌شود. بازه را با متغیرِ محیطیِ CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS سفارشی کن.

پشتیبانیِ سازمان‌های چندتیمی

Section titled “پشتیبانیِ سازمان‌های چندتیمی”

سازمان‌هایی با چند تیم یا بخش می‌توانند با استفاده از متغیرِ محیطیِ OTEL_RESOURCE_ATTRIBUTES صفاتِ سفارشی برای تفکیکِ گروه‌های مختلف اضافه کنند:

Terminal window
# Add custom attributes for team identification
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

این صفاتِ سفارشی در همه‌ی متریک‌ها و رویدادها گنجانده می‌شوند و به تو اجازه می‌دهند:

  • متریک‌ها را بر اساسِ تیم یا بخش فیلتر کنی
  • هزینه‌ها را به‌ازای هر مرکزِ هزینه ردیابی کنی
  • داشبوردهای مخصوصِ هر تیم بسازی
  • برای تیم‌های خاص هشدار تنظیم کنی

Claude Code این مقادیر را علاوه بر فرستادنشان در بلاکِ منبعِ OTLP، به‌عنوانِ صفات روی هر نقطه‌ی داده‌ی متریک و رکوردِ رویداد می‌چسباند. چون بیشترِ بک‌اندهای متریک، صفاتِ نقطه‌ی داده را به‌عنوانِ برچسب‌های قابل‌کوئری ارائه می‌دهند، می‌توانی متریک‌ها را مستقیماً بر اساسِ کلیدهای سفارشیت گروه‌بندی و فیلتر کنی. کلیدهای سفارشی هرگز صفاتِ استاندارد مانند user.id یا session.id را بازنویسی نمی‌کنند: وقتی یک کلید تداخل داشته باشد، Claude Code مقدارِ توکار را نگه می‌دارد.

هر کلیدِ سفارشی به یک برچسب روی هر سریِ متریک تبدیل می‌شود، پس مقادیرِ پرکاردینالیتی هزینه‌ی ذخیره‌سازی را در بک‌اندِ متریکِ تو بالا می‌برند. برای فرستادنِ صفاتِ سفارشی فقط در بلاکِ منبع و حذفشان از برچسب‌های نقطه‌ی داده، OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false را تنظیم کن. کنترلِ کاردینالیتیِ متریک‌ها را ببین.

نمونه‌های پیکربندی

Section titled “نمونه‌های پیکربندی”

این متغیرهای محیطی را پیش از اجرای claude تنظیم کن. هر بلاک یک پیکربندیِ کامل برای یک exporter یا سناریوی استقرارِ متفاوت نشان می‌دهد:

Terminal window
# Console debugging (1-second intervals)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000


# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317


# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus


# Multiple exporters
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json


# Different endpoints/backends for metrics and logs
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317


# Metrics only (no events/logs)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317


# Events/logs only (no metrics)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

متریک‌ها و رویدادهای موجود

Section titled “متریک‌ها و رویدادهای موجود”

صفاتِ استاندارد

Section titled “صفاتِ استاندارد”

همه‌ی متریک‌ها و رویدادها این صفاتِ استاندارد را به اشتراک می‌گذارند:

صفتتوضیحکنترل‌شده توسطِ
session.idشناسه‌ی یکتای نشستOTEL_METRICS_INCLUDE_SESSION_ID (پیش‌فرض: true)
app.versionنسخه‌ی کنونیِ Claude CodeOTEL_METRICS_INCLUDE_VERSION (پیش‌فرض: false)
app.entrypointنحوه‌ی راه‌اندازیِ نشست، مانند cli، sdk-cli، sdk-ts، sdk-py یا claude-vscodeOTEL_METRICS_INCLUDE_ENTRYPOINT (پیش‌فرض: false)
organization.idUUIDِ سازمان (هنگامِ احراز هویت)همیشه وقتی در دسترس باشد گنجانده می‌شود
user.account_uuidUUIDِ حساب (هنگامِ احراز هویت)OTEL_METRICS_INCLUDE_ACCOUNT_UUID (پیش‌فرض: true)
user.account_idشناسه‌ی حساب در قالبِ برچسب‌دار که با APIهای مدیریتیِ Anthropic می‌خواند (هنگامِ احراز هویت)، مانند user_01BWBeN28...OTEL_METRICS_INCLUDE_ACCOUNT_UUID (پیش‌فرض: true)
user.idشناسه‌ی ناشناسِ تصادفیِ تولیدشده در نخستین اجرا و ماندگارشده در ~/.claude.json. هیچ اطلاعاتِ شخصی‌ای ندارد و از حسابِ Claudeِ تو مشتق نمی‌شود. حذفِ فایل در اجرای بعدی یک مقدارِ بی‌ربطِ جدید تولید می‌کند.همیشه گنجانده می‌شود
user.emailآدرسِ ایمیلِ کاربر (هنگامِ احراز هویت از طریقِ OAuth)همیشه وقتی در دسترس باشد گنجانده می‌شود
terminal.typeنوعِ ترمینال، مانند iTerm.app، vscode، cursor یا tmuxهمیشه وقتی شناسایی شود گنجانده می‌شود
کلیدهای OTEL_RESOURCE_ATTRIBUTESصفاتِ سفارشی‌ای که تنظیم می‌کنی، مانند department یا team.id. پشتیبانیِ سازمان‌های چندتیمی را ببینOTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES (پیش‌فرض: true)

رویدادها به‌علاوه صفاتِ زیر را دربردارند. این‌ها هرگز به متریک‌ها چسبانده نمی‌شوند، چون کاردینالیتیِ بی‌حدومرز ایجاد می‌کنند:

  • prompt.id: UUIDی که یک پرامپتِ کاربر را با همه‌ی رویدادهای بعدی تا پرامپتِ بعدی همبسته می‌کند. صفاتِ همبستگیِ رویداد را ببین.
  • workspace.host_paths: پوشه‌های فضای‌کاریِ میزبان که در اپلیکیشنِ دسکتاپ انتخاب شده‌اند، به‌صورتِ آرایه‌ی رشته‌ای

متریک‌ها

Section titled “متریک‌ها”

Claude Code متریک‌های زیر را صادر می‌کند:

نامِ متریکتوضیحواحد
claude_code.session.countشمارشِ نشست‌های CLIِ شروع‌شدهcount
claude_code.lines_of_code.countشمارشِ خطوطِ کدِ تغییریافتهcount
claude_code.pull_request.countتعدادِ pull requestهای ساخته‌شدهcount
claude_code.commit.countتعدادِ کامیت‌های git ساخته‌شدهcount
claude_code.cost.usageهزینه‌ی نشستِ Claude CodeUSD
claude_code.token.usageتعدادِ توکن‌های استفاده‌شدهtokens
claude_code.code_edit_tool.decisionشمارشِ تصمیم‌های دسترسیِ ابزارِ ویرایشِ کدcount
claude_code.active_time.totalکلِ زمانِ فعال به‌ثانیهs

جزئیاتِ متریک

Section titled “جزئیاتِ متریک”

هر متریک صفاتِ استانداردِ فهرست‌شده‌ی بالا را دربردارد. متریک‌هایی با صفاتِ اضافیِ مختصِ کانتکست در زیر یادداشت شده‌اند.

شمارنده‌ی نشست

Section titled “شمارنده‌ی نشست”

در آغازِ هر نشست افزایش می‌یابد.

صفات:

شمارنده‌ی خطوطِ کد

Section titled “شمارنده‌ی خطوطِ کد”

وقتی کد افزوده یا حذف می‌شود افزایش می‌یابد.

صفات:

  • همه‌ی صفاتِ استاندارد
  • type: ("added"، "removed")
  • model: شناسه‌ی مدلی که تغییر را ایجاد کرد (برای مثال «claude-sonnet-4-6»). {/* min-version: 2.1.172 */}نیازمندِ Claude Code نسخه‌ی v2.1.172 یا جدیدتر است

شمارنده‌ی pull request

Section titled “شمارنده‌ی pull request”

وقتی Claude Code از طریقِ یک دستورِ شل یا یک ابزارِ MCP یک pull request یا merge request می‌سازد افزایش می‌یابد.

صفات:

شمارنده‌ی کامیت

Section titled “شمارنده‌ی کامیت”

هنگامِ ساختِ کامیت‌های git از طریقِ Claude Code افزایش می‌یابد.

صفات:

شمارنده‌ی هزینه

Section titled “شمارنده‌ی هزینه”

پس از هر درخواستِ API افزایش می‌یابد.

صفات:

  • همه‌ی صفاتِ استاندارد
  • model: شناسه‌ی مدل (برای مثال «claude-sonnet-4-6»)
  • query_source: دسته‌ی زیرسیستمی که درخواست را صادر کرد. یکی از "main"، "subagent" یا "auxiliary"
  • speed: وقتی درخواست از حالتِ سریع استفاده کرد "fast". در غیر این صورت وجود ندارد
  • effort: سطحِ تلاشِ اعمال‌شده بر درخواست: "low"، "medium"، "high"، "xhigh" یا "max". وقتی مدل effort را پشتیبانی نکند وجود ندارد.
  • agent.name: نوعِ ساب‌ایجنتی که درخواست را صادر کرد. نام‌های ایجنتِ توکار و ایجنت‌های پلاگین‌های official-marketplace عیناً ظاهر می‌شوند. دیگر نام‌های ایجنتِ تعریف‌شده‌ی کاربر با "custom" جایگزین می‌شوند. وقتی درخواست توسطِ یک نوعِ ساب‌ایجنتِ نام‌دار صادر نشده باشد وجود ندارد.
  • skill.name: مهارتِ فعال برای درخواست، که توسطِ ابزارِ Skill، یک دستورِ /، یا با وراثت توسطِ ساب‌ایجنتِ راه‌افتاده تنظیم می‌شود. نام‌های مهارتِ توکار، همراه‌بسته‌شده، تعریف‌شده‌ی کاربر و پلاگین‌های official-marketplace عیناً ظاهر می‌شوند. نام‌های مهارتِ پلاگینِ شخصِ ثالث با "third-party" جایگزین می‌شوند. وقتی هیچ مهارتی فعال نباشد وجود ندارد.
  • plugin.name: پلاگینِ مالک وقتی مهارت یا ساب‌ایجنتِ فعال توسطِ یک پلاگین فراهم شده باشد. نام‌های پلاگینِ official-marketplace عیناً ظاهر می‌شوند. نام‌های پلاگینِ شخصِ ثالث با "third-party" جایگزین می‌شوند. وقتی نه مهارت و نه ساب‌ایجنت پلاگینِ مالک نداشته باشد وجود ندارد.
  • marketplace.name: مارکت‌پلیسی که پلاگینِ مالک از آن نصب شده. فقط برای پلاگین‌های official-marketplace صادر می‌شود. در غیر این صورت وجود ندارد.
  • mcp_server.name: سرورِ MCPی که ابزارش در نوبتِ تولیدکننده‌ی این درخواست اجرا شد. نام‌های سرورِ توکار، پراکسی‌شده‌ی claude.ai و official-registry عیناً ظاهر می‌شوند. نام‌های سرورِ پیکربندی‌شده‌ی کاربر با "custom" جایگزین می‌شوند. وقتی هیچ ابزارِ MCPی اجرا نشده باشد وجود ندارد.
  • mcp_tool.name: ابزارِ MCPی که در نوبتِ تولیدکننده‌ی این درخواست اجرا شد، با همان پنهان‌سازیِ mcp_server.name. وقتی هیچ ابزارِ MCPی اجرا نشده باشد وجود ندارد.

شمارنده‌ی توکن

Section titled “شمارنده‌ی توکن”

پس از هر درخواستِ API افزایش می‌یابد.

صفات:

  • همه‌ی صفاتِ استاندارد
  • type: ("input"، "output"، "cacheRead"، "cacheCreation")
  • model: شناسه‌ی مدل (برای مثال «claude-sonnet-4-6»)
  • query_source: دسته‌ی زیرسیستمی که درخواست را صادر کرد. یکی از "main"، "subagent" یا "auxiliary"
  • speed: وقتی درخواست از حالتِ سریع استفاده کرد "fast". در غیر این صورت وجود ندارد
  • effort: سطحِ تلاشِ اعمال‌شده بر درخواست. برای جزئیات شمارنده‌ی هزینه را ببین.
  • agent.name، skill.name، plugin.name، marketplace.name، mcp_server.name، mcp_tool.name: انتسابِ مهارت، پلاگین، ایجنت و MCP برای درخواست. برای تعریف‌ها و رفتارِ پنهان‌سازی، شمارنده‌ی هزینه را ببین.

شمارنده‌ی تصمیمِ ابزارِ ویرایشِ کد

Section titled “شمارنده‌ی تصمیمِ ابزارِ ویرایشِ کد”

وقتی کاربر استفاده از ابزارِ Edit، Write یا NotebookEdit را می‌پذیرد یا رد می‌کند افزایش می‌یابد.

صفات:

  • همه‌ی صفاتِ استاندارد
  • tool_name: نامِ ابزار ("Edit"، "Write"، "NotebookEdit")
  • decision: تصمیمِ کاربر ("accept"، "reject")
  • source: تصمیم از کجا آمد. یکی از "config"، "hook"، "user_permanent"، "user_temporary"، "user_abort" یا "user_reject". برای معنای هر مقدار، رویدادِ تصمیمِ ابزار را ببین.
  • language: زبانِ برنامه‌نویسیِ فایلِ ویرایش‌شده، مانند "TypeScript"، "Python"، "JavaScript" یا "Markdown". برای پسوندهای فایلِ ناشناس "unknown" برمی‌گرداند.

شمارنده‌ی زمانِ فعال

Section titled “شمارنده‌ی زمانِ فعال”

زمانِ واقعیِ صرف‌شده در استفاده‌ی فعال از Claude Code را ردیابی می‌کند، با حذفِ زمانِ بیکاری. این متریک در حینِ تعامل‌های کاربر (تایپ، خواندنِ پاسخ‌ها) و در حینِ پردازشِ CLI (اجرای ابزار، تولیدِ پاسخِ هوشِ‌مصنوعی) افزایش می‌یابد.

صفات:

  • همه‌ی صفاتِ استاندارد
  • type: "user" برای تعامل‌های صفحه‌کلید، "cli" برای اجرای ابزار و پاسخ‌های هوشِ‌مصنوعی

رویدادها

Section titled “رویدادها”

Claude Code رویدادهای زیر را از طریقِ logs/eventsِ OpenTelemetry صادر می‌کند (وقتی OTEL_LOGS_EXPORTER پیکربندی شده باشد):

صفاتِ همبستگیِ رویداد

Section titled “صفاتِ همبستگیِ رویداد”

وقتی کاربر یک پرامپت ثبت می‌کند، Claude Code ممکن است چند فراخوانیِ API انجام دهد و چند ابزار اجرا کند. صفتِ prompt.id به تو اجازه می‌دهد همه‌ی آن رویدادها را به همان پرامپتِ واحدی که برانگیخت گره بزنی.

صفتتوضیح
prompt.idشناسه‌ی UUID v4 که همه‌ی رویدادهای تولیدشده در حینِ پردازشِ یک پرامپتِ کاربرِ واحد را پیوند می‌دهد

برای ردیابیِ همه‌ی فعالیتِ برانگیخته‌شده توسطِ یک پرامپتِ واحد، رویدادهایت را بر اساسِ یک مقدارِ مشخصِ prompt.id فیلتر کن. این کار رویدادِ user_prompt، هر رویدادِ api_request و هر رویدادِ tool_result را که در حینِ پردازشِ آن پرامپت رخ داد برمی‌گرداند.

رویدادِ پرامپتِ کاربر

Section titled “رویدادِ پرامپتِ کاربر”

وقتی کاربر یک پرامپت ثبت می‌کند لاگ می‌شود.

نامِ رویداد: claude_code.user_prompt

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "user_prompt"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • prompt_length: طولِ پرامپت
  • prompt: محتوای پرامپت (به‌صورت پیش‌فرض پنهان‌شده، با OTEL_LOG_USER_PROMPTS=1 فعال کن)
  • command_name: نامِ دستور وقتی پرامپت یکی را فرامی‌خواند. نام‌های دستورِ توکار و همراه‌بسته‌شده مانند compact یا debug همان‌طور که هستند صادر می‌شوند؛ نام‌های مستعار مانند reset همان‌طور که تایپ شده‌اند صادر می‌شوند نه نامِ متعارف. نام‌های دستورِ سفارشی، پلاگین و MCP به custom یا mcp فروکاسته می‌شوند مگر OTEL_LOG_TOOL_DETAILS=1 تنظیم شده باشد
  • command_source: منشأ دستور وقتی وجود داشته باشد: builtin، custom یا mcp. دستورهای فراهم‌شده توسطِ پلاگین به‌صورتِ custom گزارش می‌شوند

رویدادِ نتیجه‌ی ابزار

Section titled “رویدادِ نتیجه‌ی ابزار”

وقتی یک ابزار اجرایش را تمام می‌کند لاگ می‌شود. اگر فراخوانیِ ابزار رد شده باشد صادر نمی‌شود؛ برای ردها، رویدادِ تصمیمِ ابزار را ببین.

نامِ رویداد: claude_code.tool_result

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "tool_result"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • tool_name: نامِ ابزار
  • tool_use_id: شناسه‌ی یکتا برای این فراخوانیِ ابزار. با tool_use_idِ پاس‌داده‌شده به هوک‌ها می‌خواند و امکانِ همبستگی میانِ رویدادهای OTel و داده‌ی ضبط‌شده‌ی هوک را می‌دهد.
  • success: "true" یا "false"
  • duration_ms: زمانِ اجرا به میلی‌ثانیه
  • error_type: رشته‌ی دسته‌ی خطا وقتی ابزار شکست خورد، مانند "Error:ENOENT" یا "ShellError"
  • error (وقتی OTEL_LOG_TOOL_DETAILS=1): پیامِ کاملِ خطا وقتی ابزار شکست خورد
  • decision_type: همیشه "accept"، چون این رویداد فقط پس از اجرای ابزار صادر می‌شود (فراخوانی‌های ردشده نتیجه‌ی ابزار تولید نمی‌کنند)
  • decision_source: تصمیمِ دسترسی از کجا آمد. یکی از "config"، "hook"، "user_permanent" یا "user_temporary". برای معنای هر مقدار، رویدادِ تصمیمِ ابزار را ببین. منابعِ فقط-ردِ "user_abort" و "user_reject" هرگز روی این رویداد ظاهر نمی‌شوند.
  • tool_input_size_bytes: اندازه‌ی ورودیِ سریالایزشده‌ی JSONِ ابزار به بایت
  • tool_result_size_bytes: اندازه‌ی نتیجه‌ی ابزار به بایت
  • mcp_server_scope: شناسه‌ی دامنه‌ی سرورِ MCP (برای ابزارهای MCP)
  • tool_parameters (وقتی OTEL_LOG_TOOL_DETAILS=1): رشته‌ی JSON که پارامترهای مختصِ ابزار را دربردارد:
    • برای ابزارِ Bash: شاملِ bash_command، full_command، timeout، description، dangerouslyDisableSandbox و git_commit_id (هشِ کامیت، وقتی یک دستورِ git commit موفق شود)
    • برای ابزارِ WorkspaceBash: شاملِ bash_command، full_command، timeout
    • برای ابزارهای MCP: شاملِ mcp_server_name، mcp_tool_name
    • برای ابزارِ Skill: شاملِ skill_name
    • برای ابزارِ Agent یا ابزارِ قدیمیِ Task: شاملِ subagent_type
  • tool_input (وقتی OTEL_LOG_TOOL_DETAILS=1): آرگومان‌های سریالایزشده‌ی JSONِ ابزار. مقادیرِ تک‌تک بالای ۵۱۲ کاراکتر کوتاه می‌شوند، و کلِ payload به ~4 K کاراکتر کران می‌خورد. به همه‌ی ابزارها از جمله ابزارهای MCP اعمال می‌شود.

رویدادِ درخواستِ API

Section titled “رویدادِ درخواستِ API”

برای هر درخواستِ API به Claude لاگ می‌شود.

نامِ رویداد: claude_code.api_request

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "api_request"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • model: مدلِ استفاده‌شده (برای مثال «claude-sonnet-4-6»)
  • cost_usd: هزینه‌ی برآوردی به USD
  • duration_ms: مدتِ درخواست به میلی‌ثانیه
  • input_tokens: تعدادِ توکن‌های ورودی
  • output_tokens: تعدادِ توکن‌های خروجی
  • cache_read_tokens: تعدادِ توکن‌های خوانده‌شده از کش
  • cache_creation_tokens: تعدادِ توکن‌های استفاده‌شده برای ساختِ کش
  • request_id: شناسه‌ی درخواستِ Anthropic API از هدرِ request-idِ پاسخ، مانند "req_011...". فقط وقتی API یکی برگرداند حاضر است.
  • speed: "fast" یا "normal"، که نشان می‌دهد حالتِ سریع فعال بوده یا نه
  • query_source: زیرسیستمی که درخواست را صادر کرد، مانند "repl_main_thread"، "compact" یا نامِ یک ساب‌ایجنت
  • effort: سطحِ تلاشِ اعمال‌شده بر درخواست: "low"، "medium"، "high"، "xhigh" یا "max". وقتی مدل effort را پشتیبانی نکند وجود ندارد.
  • agent.name، skill.name، plugin.name، marketplace.name، mcp_server.name، mcp_tool.name: انتسابِ مهارت، پلاگین، ایجنت و MCP برای درخواست. برای تعریف‌ها و رفتارِ پنهان‌سازی، شمارنده‌ی هزینه را ببین.

رویدادِ خطای API

Section titled “رویدادِ خطای API”

وقتی یک درخواستِ API به Claude شکست می‌خورد لاگ می‌شود.

نامِ رویداد: claude_code.api_error

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "api_error"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • model: مدلِ استفاده‌شده (برای مثال «claude-sonnet-4-6»)
  • error: پیامِ خطا
  • status_code: کدِ وضعیتِ HTTP به‌صورتِ عدد. برای خطاهای غیرHTTP مانند شکستِ اتصال وجود ندارد.
  • duration_ms: مدتِ درخواست به میلی‌ثانیه
  • attempt: تعدادِ کلِ تلاش‌ها، از جمله درخواستِ اولیه (1 یعنی هیچ تلاشِ مجددی رخ نداد)
  • request_id: شناسه‌ی درخواستِ Anthropic API از هدرِ request-idِ پاسخ، مانند "req_011...". فقط وقتی API یکی برگرداند حاضر است.
  • speed: "fast" یا "normal"، که نشان می‌دهد حالتِ سریع فعال بوده یا نه
  • query_source: زیرسیستمی که درخواست را صادر کرد، مانند "repl_main_thread"، "compact" یا نامِ یک ساب‌ایجنت
  • effort: سطحِ تلاشِ اعمال‌شده بر درخواست. وقتی مدل effort را پشتیبانی نکند وجود ندارد.
  • agent.name، skill.name، plugin.name، marketplace.name، mcp_server.name، mcp_tool.name: انتسابِ مهارت، پلاگین، ایجنت و MCP برای درخواست. برای تعریف‌ها و رفتارِ پنهان‌سازی، شمارنده‌ی هزینه را ببین.

رویدادِ امتناعِ API

Section titled “رویدادِ امتناعِ API”

وقتی یک درخواستِ API مقدارِ stop_reason: "refusal" برمی‌گرداند لاگ می‌شود. امتناع‌ها روی یک جریانِ پاسخِ موفق می‌رسند نه به‌صورتِ خطای HTTP، پس رویدادِ api_error برایشان شلیک نمی‌شود. این رویداد به تو اجازه می‌دهد فراوانیِ امتناع را ردیابی کنی.

نامِ رویداد: claude_code.api_refusal

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "api_refusal"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • model: شناسه‌ی مدل از درخواست
  • request_id: شناسه‌ی درخواستِ Anthropic API از هدرِ request-idِ پاسخ، مانند "req_011...". فقط وقتی API یکی برگرداند حاضر است.

رویدادِ بدنه‌ی درخواستِ API

Section titled “رویدادِ بدنه‌ی درخواستِ API”

برای هر تلاشِ درخواستِ API وقتی OTEL_LOG_RAW_API_BODIES تنظیم شده باشد لاگ می‌شود. یک رویداد در هر تلاش صادر می‌شود، پس تلاش‌های مجدد با پارامترهای تنظیم‌شده هرکدام رویدادِ خودشان را تولید می‌کنند.

نامِ رویداد: claude_code.api_request_body

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "api_request_body"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • body: پارامترهای سریالایزشده‌ی JSONِ درخواستِ Messages API (system prompt، پیام‌ها، ابزارها و غیره)، کوتاه‌شده در 60 KB. محتوای extended-thinking در نوبت‌های دستیارِ پیشین پنهان می‌شود. فقط در حالتِ خطی (OTEL_LOG_RAW_API_BODIES=1) صادر می‌شود.
  • body_ref: مسیرِ مطلق به یک فایلِ <dir>/<uuid>.request.json که بدنه‌ی کوتاه‌نشده را دربردارد. فقط در حالتِ فایل (OTEL_LOG_RAW_API_BODIES=file:<dir>) صادر می‌شود.
  • body_length: طولِ بدنه‌ی کوتاه‌نشده. بایت‌های UTF-8 وقتی OTEL_LOG_RAW_API_BODIES=file:<dir>، یا واحدهای کدِ UTF-16 وقتی =1
  • body_truncated: "true" وقتی کوتاه‌سازیِ خطی رخ داده. در حالتِ فایل و وقتی کوتاه‌سازی رخ نداده وجود ندارد.
  • model: شناسه‌ی مدل از پارامترهای درخواست
  • query_source: زیرسیستمی که درخواست را صادر کرد (برای مثال "compact")

رویدادِ بدنه‌ی پاسخِ API

Section titled “رویدادِ بدنه‌ی پاسخِ API”

برای هر پاسخِ موفقِ API وقتی OTEL_LOG_RAW_API_BODIES تنظیم شده باشد لاگ می‌شود.

نامِ رویداد: claude_code.api_response_body

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "api_response_body"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • body: پاسخِ سریالایزشده‌ی JSONِ Messages API (id، بلاک‌های محتوا، usage، علتِ توقف)، کوتاه‌شده در 60 KB. محتوای extended-thinking پنهان می‌شود. فقط در حالتِ خطی (OTEL_LOG_RAW_API_BODIES=1) صادر می‌شود.
  • body_ref: مسیرِ مطلق به یک فایلِ <dir>/<request_id>.response.json که بدنه‌ی کوتاه‌نشده را دربردارد. فقط در حالتِ فایل (OTEL_LOG_RAW_API_BODIES=file:<dir>) صادر می‌شود.
  • body_length: طولِ بدنه‌ی کوتاه‌نشده. بایت‌های UTF-8 وقتی OTEL_LOG_RAW_API_BODIES=file:<dir>، یا واحدهای کدِ UTF-16 وقتی =1
  • body_truncated: "true" وقتی کوتاه‌سازیِ خطی رخ داده. در حالتِ فایل و وقتی کوتاه‌سازی رخ نداده وجود ندارد.
  • model: شناسه‌ی مدل
  • query_source: زیرسیستمی که درخواست را صادر کرد
  • request_id: شناسه‌ی درخواستِ Anthropic API از هدرِ request-idِ پاسخ، مانند "req_011...". فقط وقتی API یکی برگرداند حاضر است.

رویدادِ تصمیمِ ابزار

Section titled “رویدادِ تصمیمِ ابزار”

وقتی یک تصمیمِ دسترسیِ ابزار گرفته می‌شود (پذیرش/رد) لاگ می‌شود.

نامِ رویداد: claude_code.tool_decision

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "tool_decision"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • tool_name: نامِ ابزار (برای مثال «Read»، «Edit»، «Write»، «NotebookEdit»)
  • tool_use_id: شناسه‌ی یکتا برای این فراخوانیِ ابزار. با tool_use_idِ پاس‌داده‌شده به هوک‌ها می‌خواند و امکانِ همبستگی میانِ رویدادهای OTel و داده‌ی ضبط‌شده‌ی هوک را می‌دهد.
  • decision: یا "accept" یا "reject"
  • source: تصمیم از کجا آمد:
    • "config": به‌صورت خودکار و بدونِ پرسش تصمیم گرفته شد، بر اساسِ تنظیماتِ پروژه، قواعدِ allow یا deny در تنظیماتِ شخصیِ کاربر، سیاستِ مدیریت‌شده‌ی سازمانی، پرچم‌های --allowedTools یا --disallowedTools، حالتِ دسترسیِ فعال، یک اعطای نشست‌محور از پرامپتی پیشین در همان نشستِ تعاملیِ CLI، یا چون ابزار ذاتاً امن است. این رویداد نشان نمی‌دهد کدام‌یک از این منابع منطبق شده.
    • "hook": یک هوکِ PreToolUse یا PermissionRequest تصمیم را برگرداند.
    • "user_permanent": وقتی صادر می‌شود که کاربر در یک پرامپتِ دسترسی «Yes, and don’t ask again for …» را انتخاب کند، که یک قاعده‌ی allow را در تنظیماتِ شخصی‌اش ذخیره می‌کند. در CLIِ تعاملی این فقط برای خودِ همان انتخاب صادر می‌شود؛ فراخوانی‌های بعدی که با قاعده‌ی ذخیره‌شده می‌خوانند به‌جایش "config" صادر می‌کنند. در نشست‌های Agent SDK یا غیرتعاملیِ -p، هم انتخابِ اولیه و هم تطبیق‌های بعدیِ قاعده "user_permanent" صادر می‌کنند. به‌عنوانِ پذیرش تلقی می‌شود.
    • "user_temporary": وقتی صادر می‌شود که کاربر در یک پرامپتِ دسترسی «Yes» را برای تأییدِ یک‌باره انتخاب کند، یا یکی از گزینه‌های «… during this session» را روی یک پرامپتِ ویرایش یا خواندنِ فایل انتخاب کند. در CLIِ تعاملی این فقط برای خودِ همان انتخاب صادر می‌شود؛ فراخوانی‌های بعدی که با آن اعطای نشست‌محور مجاز شده‌اند به‌جایش "config" صادر می‌کنند. در نشست‌های Agent SDK یا غیرتعاملیِ -p، هم انتخاب و هم تطبیق‌های بعدی "user_temporary" صادر می‌کنند. به‌عنوانِ پذیرش تلقی می‌شود.
    • "user_abort": وقتی صادر می‌شود که کاربر پرامپتِ دسترسی را بدونِ پاسخ کنار بزند. به‌عنوانِ رد تلقی می‌شود.
    • "user_reject": وقتی صادر می‌شود که کاربر هنگامِ پرسش «No» را انتخاب کند. در CLIِ تعاملی این فقط برای خودِ همان انتخاب صادر می‌شود؛ فراخوانی‌هایی که با یک قاعده‌ی deny در تنظیماتِ شخصیِ کاربر می‌خوانند به‌جایش "config" صادر می‌کنند. در نشست‌های Agent SDK یا غیرتعاملیِ -p، فراخوانی‌هایی که با یک قاعده‌ی deny در تنظیماتِ شخصی می‌خوانند "user_reject" صادر می‌کنند. به‌عنوانِ رد تلقی می‌شود.
  • tool_parameters (وقتی OTEL_LOG_TOOL_DETAILS=1): رشته‌ی JSON که پارامترهای مختصِ ابزار را دربردارد. همان شکلِ رویدادِ نتیجه‌ی ابزار، منهای فیلدهای پس‌از‌اجرا مانند git_commit_id. مقادیر ممکن است برای یک فراخوانیِ پذیرفته‌شده با tool_result فرق کند، اگر تصمیمِ دسترسی ورودیِ ابزار را از طریقِ updatedInput بازنویسی کند. از این صفت برای دیدنِ این‌که کدام دستور رد شد وقتی decision برابرِ "reject" است استفاده کن.
    • برای ابزارِ Bash: شاملِ bash_command، full_command، timeout، description، dangerouslyDisableSandbox
    • برای ابزارِ WorkspaceBash: شاملِ bash_command، full_command، timeout
    • برای ابزارهای MCP: شاملِ mcp_server_name، mcp_tool_name
    • برای ابزارِ Skill: شاملِ skill_name
    • برای ابزارِ Agent یا ابزارِ قدیمیِ Task: شاملِ subagent_type

رویدادِ تغییرِ حالتِ دسترسی

Section titled “رویدادِ تغییرِ حالتِ دسترسی”

وقتی حالتِ دسترسی تغییر می‌کند لاگ می‌شود، برای مثال از چرخشِ Shift+Tab، خروج از حالتِ برنامه‌ریزی، یا یک بررسیِ دروازه‌ی حالتِ خودکار.

نامِ رویداد: claude_code.permission_mode_changed

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "permission_mode_changed"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • from_mode: حالتِ دسترسیِ پیشین، برای مثال "default"، "plan"، "acceptEdits"، "auto" یا "bypassPermissions"
  • to_mode: حالتِ دسترسیِ جدید
  • trigger: چه چیزی باعثِ تغییر شد. یکی از "shift_tab"، "exit_plan_mode"، "auto_gate_denied" یا "auto_opt_in". وقتی گذار از SDK یا bridge منشأ بگیرد وجود ندارد

رویدادِ احراز هویت

Section titled “رویدادِ احراز هویت”

وقتی /login یا /logout تمام می‌شود لاگ می‌شود.

نامِ رویداد: claude_code.auth

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "auth"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • action: "login" یا "logout"
  • success: "true" یا "false"
  • auth_method: روشِ احراز هویت، مانند "oauth"
  • error_category: نوعِ دسته‌ایِ خطا وقتی اقدام شکست خورد. پیامِ خامِ خطا هرگز گنجانده نمی‌شود
  • status_code: کدِ وضعیتِ HTTP به‌صورتِ رشته وقتی اقدام با یک خطای HTTP شکست خورد

رویدادِ اتصالِ سرورِ MCP

Section titled “رویدادِ اتصالِ سرورِ MCP”

وقتی یک سرورِ MCP متصل، قطع، یا در اتصال ناموفق می‌شود لاگ می‌شود.

نامِ رویداد: claude_code.mcp_server_connection

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "mcp_server_connection"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • status: "connected"، "failed" یا "disconnected"
  • transport_type: انتقالِ سرور، مانند "stdio"، "sse" یا "http"
  • server_scope: دامنه‌ای که سرور در آن پیکربندی شده، مانند "user"، "project" یا "local"
  • duration_ms: مدتِ تلاشِ اتصال به میلی‌ثانیه
  • error_code: کدِ خطا وقتی اتصال شکست خورد
  • is_plugin: true وقتی سرور توسطِ یک پلاگین فراهم شده، در غیر این صورت false
  • plugin_id_hash (وقتی is_plugin برابرِ true): هشِ پایدارِ نامِ پلاگین و مارکت‌پلیس، برای گروه‌بندیِ رویدادها بر اساسِ پلاگین بدونِ افشای نام
  • plugin.name (وقتی is_plugin برابرِ true): نامِ پلاگینی که سرور را فراهم می‌کند. برای پلاگین‌های شخصِ ثالث این رشته‌ی تحت‌اللفظیِ "third-party" است مگر OTEL_LOG_TOOL_DETAILS=1؛ این از ظاهرشدنِ پیش‌فرضِ نام‌های پلاگینِ شخصِ ثالث در لاگ‌ها محافظت می‌کند. پلاگین‌هایی از منابعِ رسمیِ Anthropic همیشه با نام شناسایی می‌شوند. صفاتِ plugin_id_hash و plugin.name به بک‌اندِ پایشِ خودت جاری می‌شوند و به Anthropic فرستاده نمی‌شوند
  • server_name (وقتی OTEL_LOG_TOOL_DETAILS=1): نامِ پیکربندی‌شده‌ی سرور
  • error (وقتی OTEL_LOG_TOOL_DETAILS=1): پیامِ کاملِ خطا وقتی اتصال شکست خورد

رویدادِ خطای داخلی

Section titled “رویدادِ خطای داخلی”

وقتی Claude Code یک خطای داخلیِ غیرمنتظره را می‌گیرد لاگ می‌شود. فقط نامِ کلاسِ خطا و یک کدِ به‌سبکِ errno ثبت می‌شود. پیامِ خطا و ردِ پشته هرگز گنجانده نمی‌شوند. این رویداد هنگامِ اجرا در برابرِ Bedrock، Vertex یا Foundry، یا وقتی DISABLE_ERROR_REPORTING تنظیم شده باشد، صادر نمی‌شود.

نامِ رویداد: claude_code.internal_error

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "internal_error"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • error_name: نامِ کلاسِ خطا، مانند "TypeError" یا "SyntaxError"
  • error_code: کدِ errnoِ Node.js مانند "ENOENT" وقتی روی خطا حاضر باشد

رویدادِ نصبِ پلاگین

Section titled “رویدادِ نصبِ پلاگین”

وقتی یک پلاگین نصبش را تمام می‌کند لاگ می‌شود، هم از دستورِ CLIِ claude plugin install و هم از رابطِ تعاملیِ /plugin.

نامِ رویداد: claude_code.plugin_installed

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "plugin_installed"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • marketplace.is_official: "true" اگر مارکت‌پلیس یک مارکت‌پلیسِ رسمیِ Anthropic باشد، در غیر این صورت "false"
  • install.trigger: "cli" یا "ui"
  • plugin.name: نامِ پلاگینِ نصب‌شده. برای مارکت‌پلیس‌های شخصِ ثالث این فقط وقتی OTEL_LOG_TOOL_DETAILS=1 باشد گنجانده می‌شود
  • plugin.version: نسخه‌ی پلاگین وقتی در ورودیِ مارکت‌پلیس اعلام شده باشد. برای مارکت‌پلیس‌های شخصِ ثالث این فقط وقتی OTEL_LOG_TOOL_DETAILS=1 باشد گنجانده می‌شود
  • marketplace.name: مارکت‌پلیسی که پلاگین از آن نصب شد. برای مارکت‌پلیس‌های شخصِ ثالث این فقط وقتی OTEL_LOG_TOOL_DETAILS=1 باشد گنجانده می‌شود

رویدادِ بارگذاریِ پلاگین

Section titled “رویدادِ بارگذاریِ پلاگین”

یک بار به‌ازای هر پلاگینِ فعال در آغازِ نشست لاگ می‌شود. از این رویداد برای فهرست‌برداری از این‌که چه پلاگین‌هایی در سراسرِ ناوگانت فعال‌اند استفاده کن، به‌عنوانِ مکملی برای plugin_installed که خودِ اقدامِ نصب را ثبت می‌کند.

نامِ رویداد: claude_code.plugin_loaded

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "plugin_loaded"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • plugin.name: نامِ پلاگین. برای پلاگین‌های خارج از مارکت‌پلیسِ رسمی و بسته‌ی توکار، مقدار "third-party" است مگر OTEL_LOG_TOOL_DETAILS=1
  • marketplace.name: مارکت‌پلیسی که پلاگین از آن نصب شد، وقتی شناخته‌شده باشد. تحتِ همان شرطِ plugin.name به "third-party" پنهان می‌شود
  • plugin.version: نسخه از مانیفستِ پلاگین. فقط وقتی نام پنهان نشده باشد و مانیفست نسخه‌ای اعلام کند گنجانده می‌شود
  • plugin.scope: دسته‌ی منشأ پلاگین: "official"، "org"، "user-local" یا "default-bundle"
  • enabled_via: نحوه‌ی فعال‌شدنِ پلاگین: "default-enable"، "org-policy"، "seed-mount" یا "user-install"
  • plugin_id_hash: هشِ قطعیِ نامِ پلاگین و مارکت‌پلیس، که فقط به exporterِ پیکربندی‌شده‌ی تو فرستاده می‌شود. به تو اجازه می‌دهد بشماری چند پلاگینِ شخصِ ثالثِ متمایز در سراسرِ ناوگانت بارگذاری شده‌اند بدونِ ثبتِ نامشان
  • has_hooks: این‌که پلاگین هوک‌هایی مشارکت می‌دهد یا نه
  • has_mcp: این‌که پلاگین سرورهای MCP مشارکت می‌دهد یا نه
  • host_owned_mcp: true وقتی میزبانِ SDK اتصال‌های MCPِ این پلاگین را مدیریت می‌کند و Claude Code از خواندنِ پیکربندیِ سرورِ MCPِ پلاگین صرف‌نظر کرده، در غیر این صورت false. {/* min-version: 2.1.172 */}نیازمندِ Claude Code نسخه‌ی v2.1.172 یا جدیدتر است
  • skill_path_count: تعدادِ پوشه‌های مهارتی که پلاگین اعلام می‌کند
  • command_path_count: تعدادِ پوشه‌های دستوری که پلاگین اعلام می‌کند
  • agent_path_count: تعدادِ پوشه‌های ایجنتی که پلاگین اعلام می‌کند
  • safe_mode: "true" وقتی نشست با --safe-mode شروع شده، در غیر این صورت "false". در حالتِ امن این رویداد فقط فهرستِ پیکربندی‌شده را گزارش می‌کند؛ دستورها، مهارت‌ها، هوک‌ها و سرورهای MCPِ پلاگین بارگذاری نمی‌شوند. {/* min-version: 2.1.169 */}نیازمندِ Claude Code نسخه‌ی v2.1.169 یا جدیدتر است

رویدادِ فعال‌سازیِ مهارت

Section titled “رویدادِ فعال‌سازیِ مهارت”

وقتی یک مهارت فراخوانی می‌شود لاگ می‌شود، چه Claude آن را از طریقِ ابزارِ Skill فراخواند چه تو آن را به‌عنوانِ یک دستورِ / اجرا کنی.

نامِ رویداد: claude_code.skill_activated

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "skill_activated"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • skill.name: نامِ مهارت. برای مهارت‌های تعریف‌شده‌ی کاربر و پلاگینِ شخصِ ثالث، مقدار جانگهدارِ "custom_skill" است مگر OTEL_LOG_TOOL_DETAILS=1
  • invocation_trigger: نحوه‌ی برانگیخته‌شدنِ مهارت ("user-slash"، "claude-proactive" یا "nested-skill")
  • skill.source: مهارت از کجا بارگذاری شد (برای مثال "bundled"، "userSettings"، "projectSettings"، "plugin")
  • skill.kind: "workflow" وقتی مهارت یک مهارتِ ورک‌فلو باشد. در غیر این صورت وجود ندارد
  • plugin.name (وقتی OTEL_LOG_TOOL_DETAILS=1 یا پلاگین از یک مارکت‌پلیسِ رسمی باشد): نامِ پلاگینِ مالک وقتی مهارت توسطِ یک پلاگین فراهم شده باشد
  • marketplace.name (وقتی OTEL_LOG_TOOL_DETAILS=1 یا پلاگین از یک مارکت‌پلیسِ رسمی باشد): مارکت‌پلیسی که پلاگینِ مالک از آن نصب شد، وقتی مهارت توسطِ یک پلاگین فراهم شده باشد

رویدادِ منشن (at mention)

Section titled “رویدادِ منشن (at mention)”

وقتی Claude Code یک منشنِ @ در یک پرامپت را resolve می‌کند لاگ می‌شود. هر منشنی رویداد صادر نمی‌کند: مسیرهای خروجِ زودهنگام مانند ردهای دسترسی، فایل‌های بیش‌ازحد بزرگ، پیوست‌های مرجعِ PDF و شکست‌های فهرست‌کردنِ پوشه بدونِ لاگ‌کردن بازمی‌گردند.

نامِ رویداد: claude_code.at_mention

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "at_mention"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • mention_type: نوعِ منشن ("file"، "directory"، "agent"، "mcp_resource")
  • success: این‌که منشن با موفقیت resolve شد یا نه ("true" یا "false")

رویدادِ پایان‌یافتنِ تلاش‌های مجددِ API

Section titled “رویدادِ پایان‌یافتنِ تلاش‌های مجددِ API”

یک بار وقتی یک درخواستِ API پس از بیش از یک تلاش شکست می‌خورد لاگ می‌شود. در کنارِ رویدادِ نهاییِ api_error صادر می‌شود.

نامِ رویداد: claude_code.api_retries_exhausted

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "api_retries_exhausted"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • model: مدلِ استفاده‌شده
  • error: پیامِ نهاییِ خطا
  • status_code: کدِ وضعیتِ HTTP به‌صورتِ عدد. برای خطاهای غیرHTTP وجود ندارد.
  • total_attempts: تعدادِ کلِ تلاش‌های انجام‌شده
  • total_retry_duration_ms: کلِ زمانِ ساعتی در سراسرِ همه‌ی تلاش‌ها
  • speed: "fast" یا "normal"

رویدادِ ثبتِ هوک

Section titled “رویدادِ ثبتِ هوک”

یک بار به‌ازای هر هوکِ پیکربندی‌شده در آغازِ نشست لاگ می‌شود. از این رویداد برای فهرست‌برداری از این‌که چه هوک‌هایی در سراسرِ ناوگانت فعال‌اند استفاده کن، به‌عنوانِ مکملی برای رویدادهای هر-اجرای hook_execution_start و hook_execution_complete.

نامِ رویداد: claude_code.hook_registered

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "hook_registered"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • hook_event: نوعِ رویدادِ هوک، مانند "PreToolUse" یا "PostToolUse"
  • hook_type: نوعِ پیاده‌سازیِ هوک: "command"، "prompt"، "mcp_tool"، "http" یا "agent"
  • hook_source: جایی که هوک تعریف شده: "userSettings"، "projectSettings"، "localSettings"، "flagSettings"، "policySettings" یا "pluginHook"
  • safe_mode: "true" وقتی نشست با --safe-mode شروع شده، در غیر این صورت "false". {/* min-version: 2.1.169 */}نیازمندِ Claude Code نسخه‌ی v2.1.169 یا جدیدتر است
  • hook_matcher (وقتی OTEL_LOG_TOOL_DETAILS=1): رشته‌ی matcher از پیکربندیِ هوک، وقتی یکی تنظیم شده باشد
  • plugin.name (وقتی hook_source برابرِ "pluginHook"): نامِ پلاگینِ مشارکت‌کننده. برای پلاگین‌های خارج از مارکت‌پلیسِ رسمی و بسته‌ی توکار، مقدار "third-party" است مگر OTEL_LOG_TOOL_DETAILS=1
  • plugin_id_hash (وقتی hook_source برابرِ "pluginHook"): هشِ قطعیِ نامِ پلاگین و مارکت‌پلیس، که فقط به exporterِ پیکربندی‌شده‌ی تو فرستاده می‌شود. به تو اجازه می‌دهد پلاگین‌های مشارکت‌کننده‌ی متمایز را بشماری بدونِ ثبتِ نامشان

رویدادِ شروعِ اجرای هوک

Section titled “رویدادِ شروعِ اجرای هوک”

وقتی یک یا چند هوک برای یک رویدادِ هوک شروع به اجرا می‌کنند لاگ می‌شود.

نامِ رویداد: claude_code.hook_execution_start

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "hook_execution_start"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • hook_event: نوعِ رویدادِ هوک، مانند "PreToolUse" یا "PostToolUse"
  • hook_name: نامِ کاملِ هوک شاملِ matcher، مانند "PreToolUse:Write"
  • num_hooks: تعدادِ دستورهای هوکِ منطبق
  • managed_only: "true" وقتی فقط هوک‌های سیاستِ مدیریت‌شده مجاز باشند
  • hook_source: "policySettings" یا "merged"
  • safe_mode: "true" وقتی نشست با --safe-mode شروع شده، در غیر این صورت "false". {/* min-version: 2.1.169 */}نیازمندِ Claude Code نسخه‌ی v2.1.169 یا جدیدتر است
  • hook_definitions: پیکربندیِ هوکِ سریالایزشده به JSON. فقط وقتی هم ردگیریِ بتای جزئی‌نگر و هم OTEL_LOG_TOOL_DETAILS=1 فعال باشند گنجانده می‌شود

رویدادِ اتمامِ اجرای هوک

Section titled “رویدادِ اتمامِ اجرای هوک”

وقتی همه‌ی هوک‌های یک رویدادِ هوک تمام شده‌اند لاگ می‌شود.

نامِ رویداد: claude_code.hook_execution_complete

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "hook_execution_complete"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • hook_event: نوعِ رویدادِ هوک
  • hook_name: نامِ کاملِ هوک شاملِ matcher
  • num_hooks: تعدادِ دستورهای هوکِ منطبق
  • num_success: شمارشی که با موفقیت تمام شد
  • num_blocking: شمارشی که تصمیمِ مسدودکننده برگرداند
  • num_non_blocking_error: شمارشی که بدونِ مسدودکردن شکست خورد
  • num_cancelled: شمارشی که پیش از اتمام لغو شد
  • total_duration_ms: مدتِ زمانِ ساعتیِ همه‌ی هوک‌های منطبق
  • managed_only: "true" وقتی فقط هوک‌های سیاستِ مدیریت‌شده مجاز باشند
  • hook_source: "policySettings" یا "merged"
  • safe_mode: "true" وقتی نشست با --safe-mode شروع شده، در غیر این صورت "false". {/* min-version: 2.1.169 */}نیازمندِ Claude Code نسخه‌ی v2.1.169 یا جدیدتر است
  • hook_definitions: پیکربندیِ هوکِ سریالایزشده به JSON. فقط وقتی هم ردگیریِ بتای جزئی‌نگر و هم OTEL_LOG_TOOL_DETAILS=1 فعال باشند گنجانده می‌شود

رویدادِ متریک‌های پلاگینِ هوک

Section titled “رویدادِ متریک‌های پلاگینِ هوک”

وقتی یک هوکِ پلاگینِ official-marketplace متریک‌های هر-فراخوانی صادر می‌کند لاگ می‌شود. فقط پلاگین‌های نصب‌شده از یک مارکت‌پلیسِ رسمیِ Anthropic می‌توانند این‌ها را صادر کنند. پلاگین‌های مارکت‌پلیسِ شخصِ ثالث و هوک‌های پیکربندی‌شده‌ی کاربر به این رویداد صادر نمی‌کنند. از این رویداد برای پایشِ رفتارِ پلاگین مانند نرخِ یافته‌ها، هزینه‌ها و مدت‌زمان‌ها از پشته‌ی مشاهده‌پذیریِ خودت استفاده کن.

نامِ رویداد: claude_code.hook_plugin_metrics

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "hook_plugin_metrics"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • plugin_id: شناسه‌ی پلاگین به قالبِ <name>@<marketplace>
  • hook_event: نوعِ رویدادِ هوکی که متریک‌ها را صادر کرد
  • تا ۲۰ کلیدِ متریکِ صادرشده توسطِ پلاگین. نام‌ها با ^[a-z][a-z0-9_]{0,39}$ می‌خوانند. مقادیر بولی یا عددی هستند.

رویدادِ فشرده‌سازی (compaction)

Section titled “رویدادِ فشرده‌سازی (compaction)”

وقتی فشرده‌سازیِ گفت‌وگو تمام می‌شود لاگ می‌شود.

نامِ رویداد: claude_code.compaction

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "compaction"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • trigger: "auto" یا "manual"
  • success: "true" یا "false"
  • duration_ms: مدتِ فشرده‌سازی
  • pre_tokens: شمارشِ تقریبیِ توکن پیش از فشرده‌سازی
  • post_tokens: شمارشِ تقریبیِ توکن پس از فشرده‌سازی
  • error: پیامِ خطا وقتی فشرده‌سازی شکست خورد
  • precompute_reuse: فقط وقتی trigger برابرِ "manual" باشد تنظیم می‌شود. فشرده‌سازیِ خودکار می‌تواند پیش از پرشدنِ پنجره‌ی کانتکست یک خلاصه را در پس‌زمینه آماده کند، و این صفت ثبت می‌کند که آیا /compact آن خلاصه‌ی آماده‌شده را استفاده‌ی مجدد کرد یا نه. "hit" یعنی استفاده‌ی مجدد شد؛ "miss_custom_instructions"، "miss_hook" و "miss_not_ready" علتِ این‌که به‌جایش یک خلاصه‌ی تازه محاسبه شد را می‌دهند. {/* min-version: 2.1.153 */}نیازمندِ Claude Code نسخه‌ی v2.1.153 یا جدیدتر است

رویدادِ نظرسنجیِ بازخورد

Section titled “رویدادِ نظرسنجیِ بازخورد”

وقتی یک نظرسنجیِ کیفیتِ نشست نشان داده یا پاسخ داده می‌شود لاگ می‌شود. برای این‌که نظرسنجی‌ها چه چیزی جمع می‌کنند و چگونه کنترلشان کنی، نظرسنجی‌های کیفیتِ نشست را ببین.

نامِ رویداد: claude_code.feedback_survey

صفات:

  • همه‌ی صفاتِ استاندارد
  • event.name: "feedback_survey"
  • event.timestamp: مهرِ زمانیِ ISO 8601
  • event.sequence: شمارنده‌ی یکنواخت‌افزایشی برای ترتیب‌دهیِ رویدادها در یک نشست
  • event_type: رویدادِ چرخه‌ی حیاتِ نظرسنجی، برای مثال "appeared"، "responded" یا "transcript_prompt_appeared"
  • appearance_id: شناسه‌ی یکتا که رویدادهای صادرشده برای یک نمونه‌ی نظرسنجی را پیوند می‌دهد
  • survey_type: کدام نظرسنجی رویداد را تولید کرد. "session" همان پرامپتِ امتیازدهیِ «How is Claude doing?» است
  • response: انتخابِ کاربر روی رویدادهای responded
  • enabled_via_override: true وقتی CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL تنظیم شده باشد. به‌صورتِ بولی صادر می‌شود نه رشته. روی رویدادهای نظرسنجیِ session حاضر است. روی این صفت فیلتر کن تا تأیید کنی override در سراسرِ یک ناوگان اعمال شده

تفسیرِ داده‌ی متریک‌ها و رویدادها

Section titled “تفسیرِ داده‌ی متریک‌ها و رویدادها”

متریک‌ها و رویدادهای صادرشده طیفی از تحلیل‌ها را پشتیبانی می‌کنند:

پایشِ استفاده

Section titled “پایشِ استفاده”
متریکفرصتِ تحلیل
claude_code.token.usageتفکیک بر اساسِ type (ورودی/خروجی)، کاربر، تیم، مدل، skill.name، plugin.name یا agent.name
claude_code.session.countردیابیِ پذیرش و درگیریِ کاربر در طولِ زمان
claude_code.lines_of_code.countاندازه‌گیریِ بهره‌وری با ردیابیِ افزودن‌ها و حذف‌های کد، تفکیک‌شده بر اساسِ مدل
claude_code.commit.count و claude_code.pull_request.countدرکِ اثر بر ورک‌فلوهای توسعه

پایشِ هزینه

Section titled “پایشِ هزینه”

متریکِ claude_code.cost.usage به این‌ها کمک می‌کند:

  • ردیابیِ روندهای استفاده در سراسرِ تیم‌ها یا افراد
  • شناساییِ نشست‌های پراستفاده برای بهینه‌سازی
  • انتسابِ هزینه به مهارت‌ها، پلاگین‌ها یا نوع‌های ساب‌ایجنتِ خاص از طریقِ صفاتِ skill.name، plugin.name و agent.name

هشدار و بخش‌بندی

Section titled “هشدار و بخش‌بندی”

هشدارهای رایجی که می‌توانی در نظر بگیری:

  • جهش‌های هزینه
  • مصرفِ غیرعادیِ توکن
  • حجمِ بالای نشست از کاربرانِ خاص

همه‌ی متریک‌ها را می‌توان بر اساسِ صفاتِ استاندارد بخش‌بندی کرد. صفتِ model روی claude_code.token.usage، claude_code.cost.usage و {/* min-version: 2.1.172 */}از نسخه‌ی v2.1.172، claude_code.lines_of_code.count در دسترس است. تفکیکِ هر-مدلِ کامیت‌ها را فقط می‌توان با اتصال به متریک‌های توکن یا هزینه بر اساسِ session.id تقریب زد، چون یک نشست می‌تواند چند مدل را دربر بگیرد.

تشخیصِ پایان‌یافتنِ تلاش‌های مجدد

Section titled “تشخیصِ پایان‌یافتنِ تلاش‌های مجدد”

Claude Code درخواست‌های ناموفقِ API را به‌صورتِ داخلی دوباره تلاش می‌کند و فقط پس از تسلیم‌شدن یک رویدادِ تکیِ claude_code.api_error صادر می‌کند، پس خودِ رویداد سیگنالِ نهایی برای آن درخواست است. تلاش‌های مجددِ میانی به‌صورتِ رویدادهای جداگانه لاگ نمی‌شوند.

صفتِ attempt روی رویداد ثبت می‌کند که در مجموع چند تلاش انجام شد. مقداری بزرگ‌تر از CLAUDE_CODE_MAX_RETRIES (پیش‌فرض 10) نشان می‌دهد که درخواست همه‌ی تلاش‌های مجدد را روی یک خطای گذرا تمام کرده. مقداری پایین‌تر نشان‌دهنده‌ی یک خطای غیرقابل‌تلاش‌مجدد مانند پاسخِ 400 است.

برای تمایزِ نشستی که بهبود یافته از نشستی که گیر کرده، رویدادها را بر اساسِ session.id گروه‌بندی کن و بررسی کن که آیا یک رویدادِ api_requestِ بعدی پس از خطا وجود دارد یا نه.

تحلیلِ رویداد

Section titled “تحلیلِ رویداد”

داده‌ی رویداد بینش‌های مفصلی درباره‌ی تعامل‌های Claude Code فراهم می‌کند:

الگوهای استفاده از ابزار: رویدادهای نتیجه‌ی ابزار را تحلیل کن تا این‌ها را شناسایی کنی:

  • پراستفاده‌ترین ابزارها
  • نرخِ موفقیتِ ابزارها
  • میانگینِ زمان‌های اجرای ابزار
  • الگوهای خطا بر اساسِ نوعِ ابزار

پایشِ کارایی: مدت‌زمانِ درخواست‌های API و زمان‌های اجرای ابزار را ردیابی کن تا گلوگاه‌های کارایی را شناسایی کنی.

ممیزیِ رویدادهای امنیتی

Section titled “ممیزیِ رویدادهای امنیتی”

رویدادهای OpenTelemetry منبعِ داده‌ی ممیزی برای فعالیتِ Claude Code هستند. هر رویداد صفاتِ هویتی حمل می‌کند که فراخوانی‌های ابزار، فعالیتِ MCP و تصمیم‌های دسترسی را به کاربری که برانگیخته‌شان گره می‌زند، و exporterِ logsِ OTLP می‌تواند این رویدادها را به هر پلتفرمِ مدیریتِ اطلاعات و رویدادهای امنیتی (SIEM) با یک گیرنده‌ی OTLP، یا به یک OpenTelemetry Collector که به SIEMِ تو ارجاع می‌دهد، تحویل دهد.

انتسابِ اقدامات به کاربران

Section titled “انتسابِ اقدامات به کاربران”

صفاتِ استاندارد روی هر رویداد، هویتِ کاربرِ احرازشده را دربردارند: user.email، user.account_uuid، user.account_id و organization.id وقتی با یک حسابِ Claude وارد شده باشی، به‌علاوه‌ی user.idِ نصب‌محور و session.idِ هر-نشست.

فراخوانی‌های ابزارِ MCP، دستورهای Bash و ویرایش‌های فایل بنابراین به توسعه‌دهنده‌ای که نشست را شروع کرد منتسب می‌شوند. Claude Code تحتِ یک حسابِ سرویسِ جداگانه عمل نمی‌کند؛ هویتِ ثبت‌شده روی هر رویداد، حسابِ Claudeِ خودِ توسعه‌دهنده است.

وقتی Claude Code با یک کلیدِ APIِ مستقیم، یا در برابرِ Bedrock، Vertex AI یا Microsoft Foundry احراز هویت می‌کند، هیچ حسابِ Claudeی در نشست نیست و فقط user.id و session.id پر می‌شوند. در این استقرارها، هویتِ کاربر را خودت با OTEL_RESOURCE_ATTRIBUTES بچسبان، که از طریقِ فایلِ تنظیماتِ مدیریت‌شده یا یک wrapperِ راه‌اندازی به‌ازای هر کاربر تنظیم می‌شود:

Terminal window
export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

ممیزیِ فعالیتِ MCP

Section titled “ممیزیِ فعالیتِ MCP”

برای ضبطِ فعالیتِ سرورِ MCP با جزئیاتِ کاملِ فراخوانی، exporterِ logs را فعال کن و OTEL_LOG_TOOL_DETAILS=1 را تنظیم کن. سپس هر عملیاتِ MCP رویدادهای ساختاریافته‌ای تولید می‌کند که نامِ سرور، نامِ ابزار و آرگومان‌های فراخوانی را در کنارِ صفاتِ استانداردِ هویت حمل می‌کنند:

رویدادچه چیزی را برای MCP ثبت می‌کند
mcp_server_connectionاتصال، قطعِ اتصال و شکستِ اتصالِ سرور با server_name، transport_type، server_scope و جزئیاتِ خطا
tool_resultهر فراخوانیِ ابزارِ MCP با tool_name و mcp_server_scope، یک payloadِ tool_parameters که mcp_server_name و mcp_tool_name را دربردارد، و یک payloadِ tool_input که آرگومان‌های فراخوانی را دربردارد
tool_decisionاین‌که فراخوانی مجاز یا رد شد، این‌که تصمیم از config، یک هوک، یا کاربر آمد، و یک payloadِ tool_parameters که mcp_server_name و mcp_tool_name را دربردارد

بدونِ OTEL_LOG_TOOL_DETAILS، این رویدادها جزئیاتِ شناسایی‌کننده را حذف می‌کنند:

  • tool_result: tool_name و mcp_server_scope را نگه می‌دارد، mcp_server_name، mcp_tool_name و آرگومان‌ها را حذف می‌کند
  • tool_decision: tool_name را نگه می‌دارد، tool_parameters را حذف می‌کند
  • mcp_server_connection: server_name و پیامِ خطا را حذف می‌کند، اما is_plugin، plugin_id_hash و plugin.name را نگه می‌دارد، با نام‌های پلاگینِ غیرAnthropic که به رشته‌ی تحت‌اللفظیِ "third-party" پنهان شده‌اند، پس سرورهای فراهم‌شده توسطِ پلاگین بدونِ لاگ‌کردنِ جزئی‌نگر همچنان قابلِ‌تمایز می‌مانند

نگاشتِ پرسش‌های امنیتی به رویدادها

Section titled “نگاشتِ پرسش‌های امنیتی به رویدادها”

هنگامِ ساختِ قواعدِ تشخیص، سیگنالی را که می‌خواهی پایش کنی پیدا کن و بک‌اندت را برای رویداد و صفاتِ متناظر کوئری بزن:

سیگنالرویدادصفاتِ کلیدی
فراخوانیِ ابزار مجاز یا رد شد، و با چه چیزیtool_decisiondecision، source، tool_name، tool_parameters
تشدیدِ حالتِ دسترسیpermission_mode_changedfrom_mode، to_mode، trigger
هوکِ سیاست یک اقدام را مسدود کردhook_execution_completehook_event، num_blocking
ورود، خروج و شکستِ احراز هویتauthaction، success، error_category
اتصال یا شکستِ سرورِ MCPmcp_server_connectionstatus، server_name، is_plugin، error_code
پلاگینِ نصب‌شده و منبعشplugin_installedplugin.name، marketplace.name، marketplace.is_official
دستورهای اجراشده و فایل‌های دست‌خوردهtool_result (اجراشده) یا tool_decision (ردشده) با OTEL_LOG_TOOL_DETAILS=1tool_parameters؛ tool_input (فقط tool_result)

Claude Code فقط جریانِ خامِ رویداد را صادر می‌کند. تشخیصِ ناهنجاری، تعیینِ خط‌مبنا، همبستگی در سراسرِ نشست‌ها و هشداردهی بر عهده‌ی SIEM یا بک‌اندِ مشاهده‌پذیریِ توست.

فرستادنِ رویدادها به یک SIEM

Section titled “فرستادنِ رویدادها به یک SIEM”

OTEL_EXPORTER_OTLP_LOGS_ENDPOINT را به سمتِ گیرنده‌ی OTLPِ SIEMِ خود، یا به سمتِ یک OpenTelemetry Collector که به APIِ ingestِ نیتیوِ SIEMت ارجاع می‌دهد، نشانه برو. نمونه‌ی تنظیماتِ مدیریت‌شده‌ی زیر فقط رویدادها را صادر می‌کند، با جزئیاتِ کاملِ ابزار فعال‌شده برای ممیزیِ MCP و Bash:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"
  }
}

ملاحظاتِ بک‌اند

Section titled “ملاحظاتِ بک‌اند”

انتخابِ بک‌اندهای متریک، لاگ و ردِ تو تعیین می‌کند که چه نوع تحلیل‌هایی می‌توانی انجام دهی:

برای متریک‌ها

Section titled “برای متریک‌ها”
  • پایگاه‌های داده‌ی سری‌زمانی (برای مثال Prometheus): محاسباتِ نرخ، متریک‌های تجمیع‌شده
  • انبارهای ستونی (برای مثال ClickHouse): کوئری‌های پیچیده، تحلیلِ کاربرِ یکتا
  • پلتفرم‌های کاملِ مشاهده‌پذیری (برای مثال Honeycomb، Datadog، Grafana Cloud): کوئری‌گیریِ پیشرفته، مصورسازی، هشداردهی

برای رویدادها/لاگ‌ها

Section titled “برای رویدادها/لاگ‌ها”
  • سیستم‌های تجمیعِ لاگ (برای مثال Elasticsearch، Loki): جست‌وجوی تمام‌متن، تحلیلِ لاگ
  • انبارهای ستونی (برای مثال ClickHouse): تحلیلِ ساختاریافته‌ی رویداد
  • پلتفرم‌های کاملِ مشاهده‌پذیری (برای مثال Honeycomb، Datadog، Grafana Cloud): همبستگی میانِ متریک‌ها و رویدادها

برای ردها

Section titled “برای ردها”

بک‌اندی انتخاب کن که ذخیره‌سازِ ردِ توزیع‌شده و همبستگیِ span را پشتیبانی کند:

  • سیستم‌های ردگیریِ توزیع‌شده (برای مثال Jaeger، Zipkin، Grafana Tempo): مصورسازیِ span، آبشارهای درخواست، تحلیلِ تأخیر
  • پلتفرم‌های کاملِ مشاهده‌پذیری (برای مثال Honeycomb، Datadog، Grafana Cloud): جست‌وجوی رد و همبستگی با متریک‌ها و لاگ‌ها

برای سازمان‌هایی که به متریک‌های کاربرِ فعالِ روزانه/هفتگی/ماهانه (DAU/WAU/MAU) نیاز دارند، بک‌اندهایی را در نظر بگیر که کوئری‌های کارآمدِ مقادیرِ یکتا را پشتیبانی کنند.

اطلاعاتِ سرویس

Section titled “اطلاعاتِ سرویس”

همه‌ی متریک‌ها و رویدادها با صفاتِ منبعِ زیر صادر می‌شوند:

  • service.name: claude-code
  • service.version: نسخه‌ی کنونیِ Claude Code
  • os.type: نوعِ سیستم‌عامل (برای مثال linux، darwin، windows)
  • os.version: رشته‌ی نسخه‌ی سیستم‌عامل
  • host.arch: معماریِ میزبان (برای مثال amd64، arm64)
  • wsl.version: شماره‌ی نسخه‌ی WSL (فقط هنگامِ اجرا روی Windows Subsystem for Linux حاضر است)
  • نامِ Meter: com.anthropic.claude_code

منابعِ سنجشِ ROI

Section titled “منابعِ سنجشِ ROI”

برای راهنمایی جامع درباره‌ی سنجشِ بازگشتِ سرمایه‌گذاری برای Claude Code — از جمله راه‌اندازیِ تله‌متری، تحلیلِ هزینه، متریک‌های بهره‌وری و گزارش‌دهیِ خودکار — به Claude Code ROI Measurement Guide مراجعه کن. این مخزن پیکربندی‌های آماده‌ی Docker Compose، راه‌اندازی‌های Prometheus و OpenTelemetry، و قالب‌هایی برای تولیدِ گزارش‌های بهره‌وریِ یکپارچه‌شده با ابزارهایی مانند Linear فراهم می‌کند.

امنیت و حریمِ خصوصی

Section titled “امنیت و حریمِ خصوصی”
  • خروجیِ OpenTelemetry به بک‌اندِ تو opt-in است و نیازمندِ پیکربندیِ صریح. برای تله‌متریِ عملیاتیِ جداگانه‌ی Anthropic و نحوه‌ی غیرفعال‌کردنش، Data usage را ببین
  • محتوای خامِ فایل و قطعه‌های کد در متریک‌ها یا رویدادها گنجانده نمی‌شوند. spanهای رد یک مسیرِ داده‌ی جداگانه‌اند: بولتِ OTEL_LOG_TOOL_CONTENTِ زیر را ببین
  • وقتی از طریقِ OAuth احراز هویت شده باشی، user.email در صفاتِ تله‌متری گنجانده می‌شود. اگر این برای سازمانت نگران‌کننده است، با بک‌اندِ تله‌متریت کار کن تا این فیلد را فیلتر یا پنهان کند
  • محتوای پرامپتِ کاربر به‌صورت پیش‌فرض جمع‌آوری نمی‌شود. فقط طولِ پرامپت ثبت می‌شود. برای گنجاندنِ محتوای پرامپت، OTEL_LOG_USER_PROMPTS=1 را تنظیم کن
  • آرگومان‌ها و پارامترهای ورودیِ ابزار به‌صورت پیش‌فرض لاگ نمی‌شوند. برای گنجاندنشان، OTEL_LOG_TOOL_DETAILS=1 را تنظیم کن. این داده فقط به endpointِ OTELی که پیکربندی می‌کنی فرستاده می‌شود، هرگز به Anthropic. آرگومان‌ها ممکن است همچنان مقادیرِ حساس داشته باشند، پس بک‌اندِ تله‌متریت را طوری پیکربندی کن که این صفات را در صورتِ لزوم فیلتر یا پنهان کند. وقتی فعال باشد:
    • رویدادهای tool_result و tool_decision یک صفتِ tool_parameters با دستورهای Bash، نام‌های سرور و ابزارِ MCP و نام‌های مهارت دربردارند. فیلدهایی مانند full_command کوتاه‌نشده صادر می‌شوند
    • رویدادهای tool_result به‌علاوه یک صفتِ tool_input با مسیرهای فایل، URLها، الگوهای جست‌وجو و دیگر آرگومان‌ها دربردارند. مقادیرِ تک‌تک بالای ۵۱۲ کاراکتر کوتاه می‌شوند و کل به ~4 K کاراکتر کران می‌خورد
    • رویدادهای user_prompt مقدارِ تحت‌اللفظیِ command_name را برای دستورهای سفارشی، پلاگین و MCP دربردارند
    • spanهای رد همان صفتِ tool_input و صفاتِ مشتق‌شده از ورودی مانند file_path را دربردارند، با همان کوتاه‌سازیِ tool_input
  • محتوای ورودی و خروجیِ ابزار به‌صورت پیش‌فرض در spanهای رد لاگ نمی‌شود. برای گنجاندنش، OTEL_LOG_TOOL_CONTENT=1 را تنظیم کن. وقتی فعال باشد، رویدادهای span محتوای کاملِ ورودی و خروجیِ ابزار را که در هر span در 60 KB کوتاه شده دربردارند. این می‌تواند شاملِ محتوای خامِ فایل از نتایجِ ابزارِ Read و خروجیِ دستورِ Bash باشد. بک‌اندِ تله‌متریت را طوری پیکربندی کن که این صفات را در صورتِ لزوم فیلتر یا پنهان کند
  • بدنه‌های خامِ درخواست و پاسخِ Anthropic Messages API به‌صورت پیش‌فرض لاگ نمی‌شوند. برای گنجاندنشان، OTEL_LOG_RAW_API_BODIES را تنظیم کن. با =1، هر فراخوانیِ API رویدادهای لاگِ api_request_body و api_response_body صادر می‌کند که صفتِ bodyشان payloadِ سریالایزشده‌ی JSON است، کوتاه‌شده در 60 KB. با =file:<dir>، بدنه‌های کوتاه‌نشده در فایل‌های .request.json و .response.json زیرِ آن پوشه نوشته می‌شوند و رویدادها به‌جای بدنه‌ی خطی یک مسیرِ body_ref حمل می‌کنند. آن پوشه را به‌جای جریانِ تله‌متری با یک log collector یا sidecar ارسال کن. در هر دو حالت، بدنه‌ها کلِ تاریخچه‌ی گفت‌وگو (system prompt، هر نوبتِ پیشینِ کاربر و دستیار، نتایجِ ابزار) را دربردارند، پس فعال‌کردنِ این به‌معنای رضایت به هر چیزی است که دیگر پرچم‌های محتواییِ OTEL_LOG_* آشکار می‌کنند. محتوای extended-thinkingِ Claude همیشه صرف‌نظر از دیگر تنظیمات از این بدنه‌ها پنهان می‌شود

پایشِ Claude Code روی Amazon Bedrock

Section titled “پایشِ Claude Code روی Amazon Bedrock”

برای راهنماییِ مفصلِ پایشِ استفاده از Claude Code برای Amazon Bedrock، به Claude Code Monitoring Implementation (Bedrock) مراجعه کن.