📘 תיעוד 148

יכולת צפייה עם OpenTelemetry

ייצוא עקבות (traces), מדדים (metrics) ואירועים מ-Agent SDK אל מערכת יכולת הצפייה (observability backend) שלך באמצעות OpenTelemetry.

כשאתה מריץ סוכנים בסביבת ייצור (production), אתה צריך נראות לגבי מה שהם עשו:

• באילו כלים הם קראו
• כמה זמן ארכה כל בקשת מודל
• כמה אסימונים (tokens) נוצלו
• היכן התרחשו כשלים

ה-Agent SDK יכול לייצא נתונים אלה כעקבות (traces), מדדים (metrics) ואירועי יומן (log events) של OpenTelemetry לכל backend שמקבל את פרוטוקול OpenTelemetry Protocol (OTLP), בין אם מדובר בפלטפורמת יכולת צפייה מתארחת (hosted) ובין אם ב-collector באירוח עצמי (self-hosted).

מדריך זה מסביר כיצד ה-SDK פולט טלמטריה, כיצד להגדיר את הייצוא, וכיצד לתייג ולסנן את הנתונים ברגע שהם מגיעים ל-backend שלך. כדי לקרוא את השימוש באסימונים ואת העלות ישירות מזרם התגובה (response stream) של ה-SDK במקום לייצא ל-backend, ראה מעקב אחר עלות ושימוש (Track cost and usage).

#כיצד זורמת טלמטריה מה-SDK

ה-Agent SDK מריץ את ה-CLI של Claude Code כתהליך בן (child process) ומתקשר איתו דרך צינור מקומי (pipe). ל-CLI יש מכשור (instrumentation) מובנה של OpenTelemetry: הוא מתעד מקטעים (spans) סביב כל בקשת מודל והרצת כלי, פולט מדדים עבור מוני אסימונים ועלויות, ופולט אירועי יומן מובנים עבור הנחיות (prompts) ותוצאות כלים. ה-SDK אינו מייצר טלמטריה משל עצמו. במקום זאת, הוא מעביר הגדרות תצורה אל תהליך ה-CLI, וה-CLI מייצא ישירות אל ה-collector שלך.

הגדרות התצורה מועברות כמשתני סביבה. כברירת מחדל, תהליך הבן יורש את סביבת היישום שלך, כך שתוכל להגדיר טלמטריה באחד משני מקומות:

• סביבת תהליך (Process environment): הגדר את המשתנים ב-shell, במיכל (container), או במנהל התזמור (orchestrator) לפני שהיישום שלך מתחיל. כל קריאת query() אוספת אותם באופן אוטומטי ללא שום שינוי קוד. זוהי הגישה המומלצת לפריסות בסביבת ייצור (production).
• אפשרויות לפי קריאה (Per-call options): הגדר את המשתנים ב-ClaudeAgentOptions.env (ב-Python) או ב-options.env (ב-TypeScript). השתמש בזה כאשר סוכנים שונים באותו תהליך זקוקים להגדרות טלמטריה שונות. ב-Python, הערך env ממוזג על גבי הסביבה המורשת. ב-TypeScript, הערך env מחליף את הסביבה המורשת במלואה, לכן כלול את ...process.env באובייקט שאתה מעביר.

ה-CLI מייצא שלושה אותות (signals) עצמאיים של OpenTelemetry. לכל אחד מהם יש מתג הפעלה משלו ו-exporter משלו, כך שתוכל להפעיל רק את אלה שאתה צריך.

לרשימה המלאה של שמות מדדים, שמות אירועים ותכונות (attributes), עיין במדריך התיעוד Monitoring של Claude Code. ה-Agent SDK פולט את אותם נתונים מכיוון שהוא מריץ את אותו CLI. שמות המקטעים (spans) מפורטים בסעיף קריאת עקבות סוכן להלן.

#הפעלת ייצוא טלמטריה

הטלמטריה כבויה עד שתגדיר CLAUDE_CODE_ENABLE_TELEMETRY=1 ותבחר לפחות exporter אחד. התצורה הנפוצה ביותר שולחת את כל שלושת האותות דרך OTLP HTTP אל collector.

הדוגמה הבאה מגדירה את המשתנים במילון ומעבירה אותם דרך options.env. הסוכן מריץ משימה בודדת, וה-CLI מייצא מקטעים, מדדים ואירועים אל ה-collector בכתובת collector.example.com בזמן שהלולאה צורכת את זרם התגובה:

#Python

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

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);
}

מכיוון שתהליך הבן יורש את סביבת היישום שלך כברירת מחדל, תוכל להשיג את אותה תוצאה על ידי ייצוא משתנים אלה ב-Dockerfile, ב-manifest של Kubernetes, או בפרופיל של ה-shell, ולהשמיט את options.env לחלוטין.

כדי לוודא שהייצוא פועל, בדוק את יומני ה-collector שלך עבור מקטעים (spans), מדדים ואירועי יומן נכנסים לאחר השלמת המשימה. כברירת מחדל, ה-CLI נכשל בשקט בשגיאות ייצוא: אם נקודת הקצה (endpoint) אינה נגישה או דוחה את הנתונים, הסוכן עדיין רץ כרגיל וה-CLI משליך את הטלמטריה מבלי להציג שגיאה ביישום שלך. כדי להציג שגיאות של ה-exporter, הגדר את CLAUDE_CODE_OTEL_DIAG_STDERR=1 לצד משתני ה-exporter וקרא את נתוני האבחון דרך ה-callback של stderr ב-SDK (ב-Python) או אפשרות stderr (ב-TypeScript). דורש את Claude Code בגרסה v2.1.179 ומעלה.

הערה: ה-exporter מסוג console כותב טלמטריה לפלט הסטנדרטי (standard output), שבו ה-SDK משתמש כערוץ ההודעות שלו. אל תגדיר את console כערך של exporter בעת הפעלה דרך ה-SDK. כדי לבחון טלמטריה באופן מקומי, כוון את OTEL_EXPORTER_OTLP_ENDPOINT אל OpenTelemetry Collector מקומי במקום זאת.

#שטיפת (Flush) טלמטריה מקריאות קצרות מועד

ה-CLI מקבץ טלמטריה באצוות (batches) ומייצא במרווחי זמן קבועים. ביציאה נקייה של התהליך הוא מנסה לבצע flush לנתונים הממתינים, אך פעולת ה-flush מוגבלת על ידי פסק זמן קצר (timeout), כך שמקטעים עדיין יכולים להישמט אם ה-collector איטי בתגובתו. אם התהליך שלך מופסק (killed) לפני שה-CLI נסגר, כל מה שעדיין נמצא במאגר האצווה (batch buffer) אובד. קיצור מרווחי הזמן של הייצוא מצמצם את שני חלונות הזמן הללו.

כברירת מחדל, מדדים מיוצאים כל 60 שניות, ועקבות ויומנים מיוצאים כל 5 שניות. הדוגמה הבאה מקצרת את כל שלושת המרווחים כך שהנתונים יגיעו אל ה-collector בזמן שמשימה קצרה עדיין רצה:

#Python

OTEL_ENV = {
    
# ... exporter configuration from the previous example ...
    "OTEL_METRIC_EXPORT_INTERVAL": "1000",
    "OTEL_LOGS_EXPORT_INTERVAL": "1000",
    "OTEL_TRACES_EXPORT_INTERVAL": "1000",
}

#TypeScript

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

#קריאת עקבות סוכן

עקבות (traces) מעניקות לך את המבט המפורט ביותר על ריצת סוכן. כאשר CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 מוגדר, כל שלב בלולאת הסוכן הופך למקטע (span) שתוכל לבחון ב-tracing backend שלך:

• claude_code.interaction: עוטף סיבוב יחיד (turn) של לולאת הסוכן, החל מקבלת הנחיה (prompt) ועד להפקת תגובה.
• claude_code.llm_request: עוטף כל קריאה ל-Claude API, עם שם המודל, זמני השהיה (latency) וספירת אסימונים כתכונות (attributes).
• claude_code.tool: עוטף כל הפעלת כלי, עם מקטעי בן (child spans) עבור ההמתנה להרשאה (claude_code.tool.blocked_on_user) וההרצה עצמה (claude_code.tool.execution).
• claude_code.hook: עוטף כל הרצה של hook. דורש מעקב מפורט בבטא (ENABLE_BETA_TRACING_DETAILED=1 ו-BETA_TRACING_ENDPOINT), צמד שגם משנה לאן היומנים והעקבות שלך נשלחים.

המקטעים llm_request, tool ו-hook הם מקטעי בן של מקטע ה-claude_code.interaction העוטף אותם. כאשר הסוכן מפעיל תת-סוכן (subagent) דרך הכלי Agent, מקטעי ה-llm_request וה-tool של תת-הסוכן מקוננים תחת מקטע ה-claude_code.tool של סוכן האב, כך שכל שרשרת ההאצלה (delegation chain) מופיעה כעקבה (trace) אחת.

מקטעים נושאים תכונת session.id כברירת מחדל. כאשר אתה מבצע מספר קריאות query() מול אותה הפעלה (session), סנן לפי session.id ב-backend שלך כדי לראות אותן כציר זמן אחד. Claude Code משמיט את התכונה אם אתה מגדיר את OTEL_METRICS_INCLUDE_SESSION_ID לערך falsy.

הערה: עקבות (Tracing) נמצאות בגרסת בטא. שמות מקטעים ותכונות עשויים להשתנות בין גרסאות. ראה עקבות (בטא) במדריך התיעוד של Monitoring עבור משתני התצורה של trace exporter.

#קישור עקבות ליישום שלך

ה-SDK מעביר (propagates) באופן אוטומטי הקשר עקבות (trace context) בתקן W3C אל תת-התהליך של ה-CLI. כאשר אתה קורא ל-query() בזמן שמקטע OpenTelemetry פעיל ביישום שלך, ה-SDK מזריק את TRACEPARENT ואת TRACESTATE לתוך סביבת תהליך הבן, וה-CLI קורא אותם כך שמקטע ה-claude_code.interaction שלו הופך למקטע בן של המקטע שלך. לאחר מכן ריצת הסוכן מופיעה בתוך העקבה של היישום שלך במקום כשורש (root) מנותק.

רשומות יומן אירועים של OTLP הנפלטות במהלך הריצה נושאות את אותו הקשר עקבות: כאשר TRACEPARENT מוגדר, ה-trace_id וה-span_id של כל רשומה תואמים לעקבה של היישום שלך, כך שתוכל לצרף אירועים למקטעים ב-backend שלך. לפני גרסה v2.1.212, רשומות אירועים שנפלטו מחוץ למקטע פעיל לא נשאו trace_id או span_id.

כאשר העברת הקשר עקבות (trace-context propagation) מופעלת, ה-CLI מעביר בנוסף את TRACEPARENT לכל פקודת Bash ו-PowerShell שהוא מריץ. אם פקודה שהופעלה דרך הכלי Bash פולטת מקטעי OpenTelemetry משל עצמה, מקטעים אלה מקוננים תחת מקטע ה-claude_code.tool.execution שעוטף את הפקודה.

הזרקה אוטומטית נמנעת כאשר אתה מגדיר את TRACEPARENT במפורש ב-options.env, כך שתוכל להצמיד הקשר אב ספציפי במידת הצורך. הפעלות CLI אינטראקטיביות מתעלמות לחלוטין מ-TRACEPARENT נכנס; רק ריצות של Agent SDK ושל claude -p מכבדות אותו. עיין בסעיף עקבות (בטא) במדריך התיעוד של Monitoring עבור הפירוט המלא של מקטעים ותכונות.

#תיוג טלמטריה מהסוכן שלך

כברירת מחדל, ה-CLI מדווח על service.name בתור claude-code. אם אתה מריץ מספר סוכנים, או מריץ את ה-SDK לצד שירותים אחרים שמייצאים לאותו collector, דרוס את שם השירות והוסף תכונות משאב (resource attributes) כדי שתוכל לסנן לפי סוכן ב-backend שלך.

הדוגמה הבאה משנה את שם השירות ומצרפת מטא-נתונים של פריסה (deployment metadata). ערכים אלה מוחלים כתכונות משאב של OpenTelemetry על כל מקטע, מדד ואירוע שהסוכן פולט:

#Python

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",
    },
)

#TypeScript

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",
  },
};

#ייחוס פעולות למשתמשי הקצה שלך

ה-CLI מצרף תכונות זהות לכל אירוע על בסיס פרטי האימות (credential) שבהם הוא משתמש כדי לקרוא ל-Anthropic. כאשר אתה בונה יישום שמשרת משתמשי קצה רבים מפריסה בודדת, תכונות אלו מזהות את פרטי האימות של השירות שלך, ולא את משתמש הקצה שבשמו פעל הסוכן.

כדי שקריאות כלים ופעילות MCP יהיו ניתנות לייחוס למשתמשי הקצה של היישום שלך, הזרק את זהות משתמש הקצה כתכונות משאב בכל קריאת query(). בצע קידוד אחוזים (percent-encode) לערכים לפני שילובם, מכיוון ש-OTEL_RESOURCE_ATTRIBUTES שומר פסיקים, רווחים וסימני שווה. הדוגמה הבאה מצרפת את המשתמש והדייר (tenant) המבקשים לכל מקטע ואירוע מבקשה אחת. היא מניחה קיומו של אובייקט request ממסגרת הווב (web framework) שלך הנושא את מזהי המשתמש והדייר:

#Python

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

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)}`,
  },
};

כאשר זהות משתמש הקצה מצורפת, האירועים tool_decision, tool_result, mcp_server_connection ו-permission_mode_changed, המיוצאים כרשומות יומן בעלות קידומת claude_code., הופכים לנתיב ביקורת (audit trail) לכל משתמש שתוכל להעביר לפלטפורמת ניהול מידע ואירועי אבטחה (SIEM). עיין בסעיף ביקורת אירועי אבטחה (Audit security events) במדריך התיעוד של Monitoring עבור הרשימה המלאה של אירועים רלוונטיים לאבטחה והתכונות שכל אחד מהם נושא.

#בקרה על נתונים רגישים בייצוא

הטלמטריה היא מבנית כברירת מחדל. משכי זמן, שמות מודלים ושמות כלים מתועדים בכל מקטע; ספירת אסימונים מתועדת כאשר בקשת ה-API הבסיסית מחזירה נתוני שימוש, כך שמקטעים עבור בקשות שנכשלו או בוטלו עשויים להשמיט אותם. התוכן שהסוכן שלך קורא וכותב אינו מתועד כברירת מחדל. משתנים אלה, הדורשים הפעלה מפורשת (opt-in), מוסיפים תוכן לנתונים המיוצאים:

השאר משתנים אלה ריקים אלא אם צינור יכולת הצפייה (observability pipeline) שלך מאושר לאחסון הנתונים שהסוכן שלך מטפל בהם. ראה אבטחה ופרטיות (Security and privacy) במדריך התיעוד של Monitoring עבור הרשימה המלאה של תכונות והתנהגות צנזורה.

#תיעוד קשור

מדריכים אלה מכסים נושאים סמוכים לניטור ופריסה של סוכנים:

• מעקב אחר עלות ושימוש (Track cost and usage): קריאת נתוני אסימונים ועלויות מזרם ההודעות ללא backend חיצוני.
• אירוח ה-Agent SDK (Hosting the Agent SDK): פריסת סוכנים במיכלים (containers) שבהם תוכל להגדיר משתני OpenTelemetry ברמת הסביבה.
• ניטור (Monitoring): מדריך העזר המלא עבור כל משתנה סביבה, מדד ואירוע שה-CLI פולט.