Phase 13: Tools & Protocols

OpenTelemetry GenAI أداة تتبع المكالمات من نهاية إلى نهاية

Type: Build

Languages: Python (stdlib, OTel span emitter)

Prerequisites: Phase 13 · 07 (MCP server), Phase 13 · 08 (MCP client)

Time: ~75 minutes

أهداف التعلم

• أسمائ صفات OTel GenAI المطلوبة لفترة LLM وفترة تنفيذ الأدوات.
• بناء تسلسل تسلسل تتبع يغطي حلقة وكيل، LLM المكالمة، أداة المكالمة، و MCP العميل إرسال.
• قرر أي محتوى يجب استيعابه (التخيار) مقابل التحرير (الخطط الافتراضية).
• إصدار المجموعات المحلية (Jaeger، Langfuse) دون إعادة كتابة رمز الأداة.

المشكلة

تحذير من فبراير 2026: يبلغ المستخدم "يستغرق وكيلي في بعض الأحيان 30 ثانية للرد؛ في بعض الأحيان 3 ثوان". لا يوجد آثار. تسجلات تظهر مكالمة LLM، ولكن ليس إرسال الأداة، وليس الخادم MCP ذهابًا وإياباً، وليس الخادم الفرعي. تخمن. في النهاية تجد: خادم MCP واحد معلق في بعض الأحيان على بدء بارد.

بدون تعقب من نهاية إلى نهاية، لن تجد هذا

تم تسوية الاتفاقيات في عام 2025-2026 تحت مجموعة الاتفاقيات الترجمية OpenTelemetry. تحدد أسماء الصفات المستقرة بحيث يقوم Datadog ، Langfuse ، Phoenix ، OpenLLMetry ، و AgentOps بتحليل نفس المدى.

المفهوم

تسلسل تسلسل

Copyagent.invoke_agent  (top, INTERNAL span)
 ├── llm.chat       (CLIENT span)
 ├── tool.execute   (INTERNAL)
 │    └── mcp.call  (CLIENT span)
 ├── llm.chat       (CLIENT span)
 └── subagent.invoke (INTERNAL)

كل شيء يقع تحت هوية واحدة و هوية المعلومات يربط بين العلاقات بين الوالدين و الطفل

الميزات المطلوبة

في الفترة من 2025 إلى 2026,

• gen_ai.operation.name "chat"،"text_completion"،"embeddings"،"execute_tool"،"invoke_agent". . .
• gen_ai.provider.name "openai"،"anthropic"،"google"،"azure_openai". . .
• gen_ai.request.model سلسلة النموذج المطلوبة (مثل "gpt-4o-2024-08-06")
• 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.tool.description وصف الأداة (اختياري).

لفترات العملاء:

• gen_ai.agent.name- لا ، لاgen_ai.agent.id- لا ، لاgen_ai.agent.description. . .

أنواع السباق

• SpanKind.CLIENTللاتصالات التي تتجاوز حدود العملية (مدفوع لـLLM، خادم MCP).
• SpanKind.INTERNALلخطوات الحلقة الخاصة بالعميل وإجراء الأداة.

التقاط المحتوى المختار

افتراضيا، تحمل المدة المقاييس والتوقيت وليس الإشارات أو الإكمال. الحملات المفيدة الكبيرة و PII غير فعالة افتراضيا.OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimentalووضع بيانات محددة لتحقيق المحتوى.

الأحداث على المدى

يمكن إضافة أحداث مستوى الرمز كحوادث فترة:

• gen_ai.content.promptرسائل إدخال
• gen_ai.content.completionرسائل إخراج
• gen_ai.content.tool_call دعوة الأداة كما تم تسجيلها.

الأحداث في التسلسل الزمني في فترة لإعادة عرض مفصل.

المصدرون

وتتجاوز نطاق تصدير OTel إلى:

• Jaeger / Tempo.أوس، على موقع.
• Langfuse.خاصة بملاحظة القانون؛ تظهر استخدام الرمز.
• Arize Phoenix.المواصفات + التتبع مجتمعة
• Datadog.التجارية ، والفحص الأصلي gen_ai.*الصفات
• Honeycomb.المتحركات العمودية، ودية الاستفسار.

كلّهم يتحدثون بـ (أوتل بي) ، و تنسيقات الأسلاك، رمزك لا يهتم.

التنشر عبر MCP

عندما يتصل عميل MCP بخادم ، قم بتحريك رأس W3C traceparent في الطلب. تدعم HTTP المباشرة القياسية. لا يحمل Stdio رؤوس HTTP بشكل أصلي ؛ يتناقش خريطة الطريق 2026 الخاصة بالتفصيل إضافة _meta.traceparentالحقل على مكالمات JSON-RPC.

حتى تلك السفن: تضمين العبارة في _metaكل طلب يدويًا، يقوم الخادم بتسجيل هوية التتبع

المقاييس

إلى جانب المدة، تعريف GenAI semconv المقاييس:

• gen_ai.client.token.usage التشخيص الهستومي
• gen_ai.client.operation.duration التشخيص الهستومي
• gen_ai.tool.execution.duration التشخيص الهستومي

استخدم هذه لأجهزة التحكم التي لا تحتاج إلى تفاصيل كل مكالمة.

طبقة AgentOps

AgentOps (مؤسسة عام 2024) متخصصة في قابلية مراقبة GenAI. يضم الإطارات الشعبية (LangGraph ، Pydantic AI ، CrewAI) لإصدار امتدادات OTel تلقائيًا. مفيد إذا استخدم كومة البيانات الإطار المدعوم ؛ استخدم الأدوات اليدوية خلاف ذلك.

استخدمها

code/main.pyيُصدِر فترات تشكيلة OTel إلى stdout (في شكل OTLP-JSON) لوكيل يدعو LLM ، ويرسل أدواتًا ، ويقوم برحلة ذهابًا وإياباً واحدة من MCP. لا يوجد مصدر حقيقي يركز الدروس على مجموعة شكل الفترات وصفوص. ضعي الخروج في متفرج متوافق مع OTLP أو اقرأه فقط.

ما الذي يجب أن ننظر إليه:

• يتم مشاركة رقم التتبع على جميع المراحل
• الروابط بين الوالدين والأطفال يتم ترميزها عبر parentSpanId. . .
• مطلوبgen_ai.*المصفوفات مكتظة.
• يتم إيقاف استيعاب المحتوى بطبيعة الحال؛ سيناريو واحد يُشغيله عبر env var.

أرسله

هذا الدرس يُنتجoutputs/skill-otel-genai-instrumentation.md. بالنظر إلى قاعدة رمزية للعامل، فإن المهارة تنتج خطة أدوات: أين تضيف المنتجات، ما الذي يعطي السكان، وما الذي يستهدف المصدرين.

التمارين

1. أركضcode/main.pyعدّ المدة و حدّد أيّ من العملاء مقابل الداخليين

1. قم بتشغيل تسجيل المحتوى (env var) و تأكيد gen_ai.content.promptوgen_ai.content.completionلاحظ الآثار على PII

1. إضافة مقياس أداة تنفيذ gen_ai.tool.execution.durationويعطيها على شكل عينة من أوراق التاريخ لكل مكالمة.

1. نشر العبارة عن أحد الوالدين من وكيل الأم في عرض طلب MCP _meta.traceparentالتحقق من أن خادم MCP يرى نفس الهوية التتبعية

1. اقرأ تحديدات OTel GenAI semconv. حدد صفة واحدة المدرجة في semconv التي لا ينبعثها رمز هذا الدروس. أضفها.

الشروط الرئيسية

المزيد من القراءة

• OpenTelemetry — GenAI semconv اتفاقيات طائفية لمتوسعات ومتراكمات وحدثات GenAI
• OpenTelemetry — GenAI spans قائمة خصائص المجال التدريبي ومدة تنفيذ الأدوات
• OpenTelemetry — GenAI agent spans مستوى الوكيل invoke_agentالمدة
• open-telemetry/semantic-conventions — GenAI spans مصدر الحقيقة المضمن في GitHub
• Datadog — LLM OTel semantic convention إدماج الإنتاج

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.