مراقبة وكلاء MCP باستخدام OpenTelemetry: spans الأدوات والسمات وزمن الاستجابة والأخطاء

مراقبة وكلاء MCP باستخدام OpenTelemetry: spans استدعاءات الأدوات وسمات GenAI ونشر السياق، مع تتبع زمن الاستجابة والأخطاء بـ DQL.
Observer les agents MCP avec OpenTelemetry : spans d'appels d'outils, attributs, latence et erreurs

مراقبة وكلاء MCP باستخدام OpenTelemetry تصبح لا غنى عنها بمجرد أن يستدعي مساعد ذكاء اصطناعي أدواتك في الإنتاج. وكيل يستجيب ببطء، أو يخطئ في اختيار الأداة، أو يتسلسل عشرة استدعاءات حيث يكفي اثنان، لا يثير أي تنبيه تقليدي: العملية تعمل، والمنفذ يستجيب، ومع ذلك تتدهور التجربة وترتفع الفاتورة.

والخبر الجيد أن استدعاء أداة MCP ليس سوى عملية موزّعة: عميل يرسل طلبًا، وخادم يعالجه، وربما يستدعي خدمات أخرى. فالتتبعات الموزّعة (distributed tracing) التي تعرفها فرق SRE تنطبق عليه مباشرة، بشرط اختيار أسماء spans وسمات مناسبة.

يبيّن هذا المقال كيف تتتبع خادم MCP ووكيلًا، وما السمات التي تُتابَع، وكيف تستخلص منها مؤشرات زمن استجابة وأخطاء قابلة للاستخدام.

لماذا نراقب وكلاء MCP باستخدام OpenTelemetry؟

في معمارية MCP (الموصوفة في دليلنا عن بروتوكول سياق النموذج) قد يطلق سؤال واحد من المستخدم سلسلة: استدعاء النموذج، واختيار أداة، وطلب إلى خادم MCP، ثم استدعاءات من الخادم إلى قاعدة بيانات أو واجهة API أو منصة قابلية الملاحظة. ومن دون تتبع تكون كل حلقة صندوقًا أسود.

يقدم OpenTelemetry ثلاثة أشياء: صيغة معيارية مستقلة عن المزوّد؛ واصطلاحات دلالية (semantic conventions) مشتركة لتسمية عمليات الذكاء الاصطناعي التوليدي؛ ونشر السياق الذي يربط الوكيل وخادم MCP والخدمات اللاحقة في تتبع واحد. وهو المنطق نفسه المشروح في OpenTelemetry من البداية إلى النهاية، مطبَّقًا على نوع جديد من الاستدعاءات.

ما الذي يجب أن يحتويه span استدعاء الأداة

يصف الـ span عملية: اسمًا ونوعًا (kind) وبداية ونهاية وحالة وسمات، وربما أحداثًا. وفي MCP تقترح الاصطلاحات الدلالية للذكاء الاصطناعي التوليدي (GenAI) في OpenTelemetry، وهي ما تزال بحالة «development»، مفردات دقيقة.

اسم منخفض الكاردينالية

يتبع الاسم الموصى به الصيغة {méthode MCP} {cible}، مثل tools/call chercher_runbooks. نضع فيه اسم الأداة، ولا نضع وسائطها ولا معرّفًا، حتى تتجمع الاستدعاءات بشكل سليم في واجهات التحليل.

السمات المفيدة

  • mcp.method.name: طريقة JSON-RPC (tools/call وresources/read…)؛
  • gen_ai.operation.name = execute_tool وgen_ai.tool.name: وهما ما يتيح معاملة استدعاء MCP كأي استدعاء أداة لوكيل؛
  • mcp.protocol.version وmcp.session.id وjsonrpc.request.id للتشخيص؛
  • mcp.resource.uri لقراءات الموارد؛
  • error.type عند الفشل.

توجد وسائط الأدوات ونتائجها أيضًا كسمات اختيارية (opt-in). وهي ثمينة للتصحيح، لكنها قد تحتوي بيانات شخصية أو أسرارًا: لا تفعّلها إلا عن علم.

سياق يعبر البروتوكول

لا يكفي سياق التتبع في HTTP: فقد يحمل طلب HTTP واحد عدة رسائل MCP، ولا ترويسات في stdio. لذلك تنص الاصطلاحات على حقن traceparent (وربما baggage) في الحقل params._meta من كل طلب MCP. ويستخرجه الخادم ويربط الـ span الخاص به بـ span العميل.

عمليًا

الخطوة 1: فعّل spans الخادم

مفاجأة سارة إن كان خادمك يستخدم SDK الرسمي لـ Python بإصداره 2: فهو يصدر أصلًا span من نوع SERVER لكل رسالة مستلمة، بالسمات المذكورة أعلاه. وهو لا يعتمد إلا على واجهة OpenTelemetry البرمجية؛ وما دام لا يوجد SDK مثبَّت فتكلفة هذه الـ spans شبه معدومة. ولجمعها يكفي إضافة SDK ومصدِّر OTLP:

pip install opentelemetry-sdk opentelemetry-exporter-otlp

أما بقية حزم SDK والأطر فتحقق في وثائقها هل توجد أداة قياس أم عليك إنشاء هذه الـ spans بنفسك.

الخطوة 2: اضبط التصدير

يتم الإعداد القياسي عبر متغيرات البيئة. وللإرسال المباشر إلى Dynatrace يلزم عنوان OTLP الخاص بالبيئة ورمز API مخوَّل باستيعاب التتبعات؛ تحقق من العنوان والنطاق الدقيقين في الوثائق:

export OTEL_SERVICE_NAME=runbooks-mcp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://VOTRE-ENV.live.dynatrace.com/api/v2/otlp
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20<JETON>"

في الشيفرة، هيّئ مزوّد التتبعات عند البدء، قبل تشغيل الخادم. انتبه مع قناة stdio: لا تستخدم أبدًا مصدِّرًا للطرفية يكتب على الخرج القياسي المخصص للبروتوكول.

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)

الخطوة 3: تتبّع الوكيل في جانب العميل

في جانب الوكيل، غلّف كل دورة استدلال بـ span أب. وتلتحق به استدعاءات الأدوات الجارية داخله، وينشر SDK السياق نحو الخادم عندما يستخدمه الطرفان:

tracer = trace.get_tracer("agent-astreinte")

async def traiter_question(client, question: str):
    with tracer.start_as_current_span("invoke_agent agent-astreinte") as span:
        span.set_attribute("gen_ai.operation.name", "invoke_agent")
        resultat = await client.call_tool(
            "chercher_runbooks", {"mots_cles": question}
        )
        span.set_attribute("agent.outils_appeles", 1)
        return resultat

السمة agent.outils_appeles مثال على سمة خاصة: ضع بادئة لسماتك المخصصة حتى لا تختلط بالاصطلاحات الرسمية.

الخطوة 4: ميّز أنواع الأخطاء

قد يفشل استدعاء الأداة بطريقتين: خطأ تنفيذ يُعاد إلى النموذج (تحمل النتيجة مؤشر خطأ ويمكن للنموذج إعادة المحاولة)، أو خطأ بروتوكول JSON-RPC. وفي الحالتين يجب أن ينتقل span الخادم إلى حالة خطأ مع تعبئة error.type. جرّب ذلك عمدًا بوسيط غير صالح وتحقق مما يصل إلى الواجهة الخلفية.

الخطوة 5: ابنِ المؤشرات

حالما تصل الـ spans إلى Grail يكفي استعلام DQL لمتابعة زمن الاستجابة والأخطاء لكل أداة. أسماء الحقول تتوقف على الاستيعاب؛ كيّفها مع ما تراه في تتبعاتك:

fetch spans, from: now() - 24h
| filter gen_ai.operation.name == "execute_tool"
| summarize appels = count(),
            erreurs = countIf(isNotNull(error.type)),
            p95 = percentile(duration, 95),
            by: { gen_ai.tool.name }
| sort appels desc

ومن هنا حدّد أهدافًا بسيطة: زمن الاستجابة عند المئين 95 لكل أداة، ومعدل الأخطاء، ومتوسط عدد استدعاءات الأدوات لكل سؤال. وارتفاع مفاجئ في الأخير يدل غالبًا على وكيل يدور في حلقة مفرغة.

أفضل الممارسات

  • سمِّ الـ spans بالطريقة والأداة، لا بالوسائط أو المعرّفات.
  • اتبع اصطلاحات GenAI وMCP، وضع بادئة للسمات الخاصة.
  • أبقِ التقاط وسائط الأدوات ونتائجها معطّلًا افتراضيًا.
  • انشر سياق التتبع من الوكيل حتى الخدمات التي يستدعيها الخادم.
  • لا تكتب أي قياسات عن بُعد على الخرج القياسي لخادم stdio.
  • اربط هذه التتبعات بسجلات التدقيق الموصوفة في تأمين خادم MCP.

الأسئلة الشائعة

هل اصطلاحات MCP في OpenTelemetry مستقرة؟

لا، فهي بحالة «development» ونُقلت إلى مستودع مخصص لاصطلاحات GenAI. وقد تتغير أسماء السمات بعد.

هل يجب قياس العميل أم الخادم أم كليهما؟

الأفضل كلاهما: العميل يُظهر مسار الوكيل، والخادم يُظهر التكلفة الفعلية لكل أداة. ويربطهما نشر السياق.

هل يُتتبَّع خادمي بلغة Python دون أي إجراء؟

مع SDK الرسمي بإصداره 2 تُنشأ الـ spans تلقائيًا؛ ويبقى تثبيت SDK لـ OpenTelemetry ومصدِّر. انظر أيضًا درسنا عن إنشاء خادم MCP بلغة Python.

الخلاصة

لا يفلت وكيل MCP من قواعد قابلية الملاحظة: كل استدعاء أداة يستحق span باسم ثابت وسمات معيارية وحالة موثوقة. وبالاعتماد على اصطلاحات OpenTelemetry وعلى القياس عن بُعد المدمج في SDK لـ Python، نحصل سريعًا على زمن الاستجابة والأخطاء وسلوك الوكلاء في الواجهات نفسها مع بقية الإنتاج.

للمزيد: OpenTelemetry series: Anatomy of an OTel span (مدونة Dynatrace، بالإنجليزية).

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا للمشاريع المذكورة. العلامات التجارية المذكورة ملك لأصحابها. الأدوات تتطور بسرعة، لذا تحقق دائمًا من الأوامر والخيارات في وثائقها الرسمية.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Créer un serveur MCP Python pour exposer vos runbooks d'exploitation

إنشاء خادم MCP بلغة Python لعرض أدلة التشغيل (runbooks)

Next Post
Observabilité IA de bout en bout : ce que le rachat d'Arize par Dynatrace change, du prototype à la production

قابلية ملاحظة الذكاء الاصطناعي من البداية إلى النهاية: ما الذي يغيّره استحواذ Dynatrace على Arize، من النموذج الأولي إلى الإنتاج

Related Posts