شروع پروژه

چیت‌شیت

OpenTelemetry هوش مصنوعی مولد و مشاهده‌پذیری ایجنت‌ها

OpenTelemetry GenAI and Agent Observability

Emit gen_ai.* spans, sample traces, export metrics, pick a platform and debug a trace. Stdlib code from the lessons.

  • ۱۱ بخش
  • ۶ درس مرتبط
  • کد و دستورها عیناً از دوره‌ی اصلی
فهرست مطالب
  1. سلسله‌مراتب اسپن‌های ایجنت
  2. اتریبیوت‌های لازم برای تنظیم
  3. تجهیز در کد
  4. سازنده‌ی اسپن با متریک‌ها
  5. اجرای درس‌ها
  6. دیباگ یک ردگیری محاسبات: agent-trace-debugger
  7. دستورات دیباگر ردگیری محاسبات
  8. پیش‌فرض‌ها و ارقام
  9. عیب‌یابی
  10. انتخاب یک پلتفرم
  11. پرسش‌ها

سلسله‌مراتب اسپن‌های ایجنت

معماری
parentSpanIdparentSpanId_meta.traceparentparentSpanIdاسپن‌هاagent.invoke_agentINTERNAL، اسپن ریشهllm.chatCLIENT، ارائه‌دهنده LLMtool.executeINTERNALmcp.callCLIENT، traceparentsubagent.invokeINTERNALخروجی‌گیرOTLP به هر بک‌اند

اتریبیوت‌های لازم برای تنظیم

مفهوم‌ها
gen_ai.operation.name
chat، embeddings، execute_tool، invoke_agent.
gen_ai.provider.name
openai، anthropic، aws.bedrock، google.vertex.
gen_ai.request.model
مدلی که درخواست می‌کنید.
gen_ai.response.model
مدلی که به فراخوانی پاسخ داد. مسیریابی می‌تواند آن را تغییر دهد.
gen_ai.usage.input_tokens
توکن‌های ورودی. gen_ai.usage.output_tokens توکن‌های خروجی را مشخص می‌کند.
gen_ai.response.id
شناسه پاسخ ارائه‌دهنده برای همبستگی.
gen_ai.tool.name
ابزار. gen_ai.tool.call.id نام یک فراخوانی را مشخص می‌کند.
gen_ai.data_source.id
پیکره متنی یا منبع داده‌ای که یک مرحله RAG آن را خوانده است.

تجهیز در کد

کار و کد
وظیفهکد
شروع یک اسپن فرزندstart_span(name, kind, parent=root)
ساخت یک traceparentf"00-{mcp_span.trace_id}-{mcp_span.span_id}-01"
ذخیره محتوا به عنوان ارجاعtracer.add_content(chat, key, prompt)
قراردادن کار درون یک اسپنwith builder.span(name, attributes=..., parent=...)
نوشتن یک اسپن در هر خطJSONLExporter(path=trace_path)
شمارش فراخوانی ابزارهاmetrics.counter("tools_called_total")
تولید متن Prometheusprometheus_exposition(registry)
نمونه‌برداری در یک خروجی‌گیرmakeSamplingExporter(consoleExporter, 0.05)

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

کد
python
metrics = MetricsRegistry()
builder = SpanBuilder(exporters=[jsonl, in_mem], metrics=metrics)
with builder.span("gen_ai.chat", attributes={GEN_AI_SYSTEM: "anthropic",
        GEN_AI_OPERATION_NAME: "chat"}, kind="CLIENT") as chat_span:
    chat_span.attributes[GEN_AI_USAGE_INPUT_TOKENS] = 412
    with builder.span("gen_ai.tool.execution", parent=chat_span,
            attributes={GEN_AI_TOOL_NAME: "read_file"}) as tool1:
        tool1.attributes[GEN_AI_TOOL_RESULT_BYTES] = 1024
print(prometheus_exposition(metrics))  # tools_called_total، tool_latency_ms

اجرای درس‌ها

دستورها
دستورکاری که انجام می‌دهد
python code/main.pyدرس 13.20 اسپن‌های یک ردگیری محاسبات را چاپ می‌کند
OTEL_CAPTURE_CONTENT=1 python code/main.pyرویدادهای پرامپت و تکمیل را اضافه می‌کند
python3 code/main.pyدرس 14.23 درخت اسپن و منبع ذخیره محتوا را چاپ می‌کند
python3 -m pytest code/tests/ -vدرس 19.28 رفت‌وبرگشت و باکت‌ها را بررسی می‌کند
npm start1200 اسپن مصنوعی را مقداردهی اولیه کرده و تجمیع را چاپ می‌کند
npm run serveدریافت داده و داشبورد را روی PORT سرو می‌کند

دیباگ یک ردگیری محاسبات: agent-trace-debugger

گام‌به‌گام
  1. `parseTrace`یک شیء JSON در هر خط. یک خط نامعتبر همراه با شماره خطش متوقف می‌شود.
  2. `validateTree`شناسه تکراری، چرخه، والد مفقود و فرزند خارج از محدوده والد را رد می‌کند.
  3. `unionDuration`بازه‌های زمانی دارای همپوشانی فرزندان را merge می‌کند، نه جمع جبری.
  4. `analyze`زمان اختصاصی برابر است با زمان کل منهای اجتماع فرزندان.
  5. `analyze`اتریبیوت slowest نام اسپن با بیشترین زمان اختصاصی را مشخص می‌کند.
  6. `render`فایل HTML مستقل با نام‌های escape شده و رنگ‌بندی خطا می‌نویسد.
  7. cli.tsفلگ --baseline مقادیر wall_time_delta_ms، token_delta و error_delta را اضافه می‌کند.

دستورات دیباگر ردگیری محاسبات

کد
bash
python3 scripts/project_test.py agent-trace-debugger --init learning-artifacts/agent-trace-debugger
python3 scripts/project_test.py agent-trace-debugger --stage 1 --path learning-artifacts/agent-trace-debugger --strict
python3 scripts/project_test.py agent-trace-debugger --all --solution --strict
node cli.ts --input samples/trace.jsonl --baseline samples/before.jsonl --output trace.html --json trace.json
node cli.ts --format otlp --input samples/otlp.json --output otlp-trace.html --json otlp-trace.json

پیش‌فرض‌ها و ارقام

پیش‌فرض‌ها
تنظیمپیش‌فرضنکته
OTEL_CAPTURE_CONTENT"0"برای ثبت پرامپت و تکمیل مقدار 1 را تنظیم کنید
`TailSampler` `sample_rate`0.10خطاها و ارزیابی‌های PII همیشه حفظ می‌شوند
`ObservabilityStore` capacity10_000بافر حلقوی از اسپن‌ها
PORT8011برای راه‌اندازی سرور HTTP مقدار SERVE=1 را تنظیم کنید
High-cost spantotalTokens > 8000همیشه توسط خروجی‌گیر نمونه‌برداری نگه‌داری می‌شود
--formatjsonlهمچنین otlp. فایل‌های خط مبنا به فرمت JSONL باقی می‌مانند
--outputtrace.html--json فایل گزارش را می‌نویسد

عیب‌یابی

عیب‌یابی

  • اطلاعات هویتی (PII) و اسرار درون ردگیری محاسبات

    علت
    پرامپت‌های کامل درون اسپن‌ها ضبط شده‌اند
    راه‌حل
    محتوا را بیرون ذخیره کنید و شناسه‌های ارجاع را روی اسپن‌ها قرار دهید

  • خراب شدن داشبورد چند ارائه‌دهنده‌ای

    علت
    عدم وجود gen_ai.provider.name
    راه‌حل
    آن را روی هر اسپن LLM تنظیم کنید

  • اسپن‌های ابزار رهاشده و بدون والد

    علت
    اسپن‌های بدون پیوند والد
    راه‌حل
    همیشه بافت (context) را منتشر کنید

  • تغییر نام اتریبیوت‌ها هنگام ارتقا

    علت
    عدم استفاده از اختیاری‌سازی پایداری
    راه‌حل
    OTEL_SEMCONV_STABILITY_OPT_IN را تنظیم کنید

  • سرور MCP در ردگیری محاسبات نیست

    علت
    ارتباط Stdio هدرهای HTTP را حمل نمی‌کند
    راه‌حل
    مقدار traceparent را در _meta هر درخواست قرار دهید

  • عدم امکان ریشه‌یابی افت کارایی (regression)

    علت
    نسخه‌های پرامپت به ردگیری محاسبات متصل نیستند
    راه‌حل
    نسخه پرامپت را روی ردگیری محاسبات ثبت کنید

  • child outside parent

    علت
    بازه زمانی فرزند از والد فراتر می‌رود
    راه‌حل
    ساعت‌ها را قبل از وارد کردن هماهنگ (نرمال‌سازی) کنید

انتخاب یک پلتفرم

مقایسه
فاکتورLangfusePhoenixOpik
مجوزMITElastic License 2.0Apache 2.0
نقطه قوت اصلی برایمدیریت پرامپت، نشست‌هاارتباط RAG، دریفتبهینه‌سازی، گاردریل‌ها
نسخه‌بندی پرامپتبلهخیرآزمایش‌های A/B
طرح رایگان50K رویداد/ماهمیزبانی شخصیمیزبانی شخصی یا ابری
زمان استفادههمه‌کاره همراه با پرامپت‌هاارزیابی عمیق RAG و دریفتبهینه‌سازی خودکار

پرسش‌ها

پرسش و پاسخ
CLIENT یا INTERNAL؟
نوع CLIENT از مرز فرایند عبور می‌کند. INTERNAL مربوط به حلقه‌ی ایجنت و فراخوانی ابزار است.
کدام نوع invoke_agent؟
نوع CLIENT برای سرویس‌های ایجنت در مخزن راه‌دور. نوع INTERNAL برای فریم‌ورک‌های درون همان فرایند.
در مقیاس بالا چه چیزهایی را نگه دارم؟
100٪ خطاها، 100٪ موارد پرهزینه، 5٪ موارد موفق.
چه زمانی دریفت واقعی است؟
مقدار PSI بالاتر از 0.2 معمولاً نشان‌دهنده دریفت معنادار است.
آیا ردگیری محاسبات کافی است؟
خیر. ردگیری محاسبات بدون ارزیابی صرفاً لاگ‌گیری پرهزینه است.
کدام متریک‌ها هیستوگرام هستند؟
gen_ai.client.token.usage، gen_ai.client.operation.duration، gen_ai.tool.execution.duration.

درس‌هایی که این موضوع را از صفر می‌سازند