مقاييس أدوات MCP: العدّادات والـ histograms ونسبة الفشل

مقاييس أدوات MCP: histograms للمدة وerror.type وtool_error، ونسبة الفشل لكل أداة عبر OpenTelemetry والموصل span_metrics.
Métriques outils MCP : compteurs, histogrammes et taux d'échec

مقاييس أدوات MCP تجيب عن ثلاثة أسئلة لا تعالجها التتبعات (traces) وحدها جيدًا: كم استدعاءً تتلقى كل أداة، وما زمن الاستجابة المعتاد، وما نسبة الفشل. يعرض خادم MCP أدوات يستدعيها نموذج لغوي في حلقة متكررة؛ وبلا تجميعات يكون أول مؤشر على أداة معطوبة شكوى من مستخدم لا تنبيهًا.

تناول المقال مراقبة وكلاء MCP مع OpenTelemetry الـ spans. أما هذا المقال فيركّز على المقاييس: ما الذي تعرّفه اصطلاحات OpenTelemetry الدلالية لـ MCP، وما الذي لا تعرّفه (لا يوجد عدّاد مخصص)، وكيف نحصل على نسبة فشل لكل أداة دون تضخيم الـ cardinality. المحتوى مستقل عن الـ backend؛ وهو صالح لـ Dynatrace SaaS وManaged ما دامت المقاييس تصل عبر OTLP.

الهدف من جهة SRE: تحويل «الوكيل بطيء» إلى SLI قابل للقياس لكل أداة، يستند إليه SLO وميزانية أخطاء، وتقليص MTTR بتحديد الأداة المسؤولة باستعلام واحد.

مقاييس أدوات MCP: ما الذي تنص عليه الاصطلاحات

تقع اصطلاحات MCP في مستودع open-telemetry/semantic-conventions-genai (تحيل إليه الصفحة القديمة في موقع OpenTelemetry). يعلن الملف model/mcp/metrics.yaml، المقروء بحالة المستودع في 30 أكتوبر 2026، أربعة مقاييس، كلها histograms بالثواني، بمستوى «recommended» واستقرار «development»:

  • mcp.client.operation.duration: مدة طلب أو إشعار، تُقاس عند المُرسِل من لحظة الإرسال إلى استلام الاستجابة؛
  • mcp.server.operation.duration: مدة تُقاس عند المستقبِل من لحظة الاستلام إلى إرسال النتيجة؛
  • mcp.client.session.duration وmcp.server.session.duration: مدة الجلسة.
مقطع من model/mcp/metrics.yaml في مستودع semantic-conventions-genai: تعريف mcp.client.operation.duration وmcp.server.operation.duration، histograms بالثواني، استقرار development

نتيجتان عمليتان. أولًا، يعني استقرار «development» أن الأسماء والسمات قد تتغير بعد: ثبّت إصدار الاصطلاح الذي تتبعه واقرأ سجل التغييرات (changelog) قبل أي تحديث. ثانيًا، لا تعرّف الاصطلاحات أي عدّاد للاستدعاءات ولا للأخطاء: يُستنتج عدد الاستدعاءات وعدد حالات الفشل من العدّاد المدمج في كل histogram (قيمة «count» فيه)، مصفّىً بالسمة error.type.

السمات التي تمنح القياس قيمته

بالنسبة لمقاييس العمليات، تسرد صفحة docs/gen-ai/mcp.md في المستودع نفسه السمات التالية:

  • mcp.method.name: إلزامية (مثل tools/call وtools/list وinitialize)؛
  • gen_ai.tool.name: مطلوبة بشرط، عندما تتعلق العملية بأداة محددة؛
  • error.type: مطلوبة إذا فشلت العملية، وفقط حينئذ؛
  • rpc.response.status_code: مطلوبة إذا تضمنت الاستجابة رمز خطأ JSON-RPC؛
  • gen_ai.operation.name: موصى بها، بالقيمة execute_tool لاستدعاء أداة؛
  • mcp.resource.uri: اختيارية (opt-in) فقط.

النقطة الأخيرة تستحق الانتباه. قد يأخذ معرّف URI لمورد ملايين القيم: لذلك تُبقيه الاصطلاحات معطّلًا افتراضيًا عن قصد. أما اسم الأداة فمحدود بكتالوج الخادم. وهذا هو البعد المناسب: يبقى mcp.method.name × gen_ai.tool.name × error.type منخفض الـ cardinality. ولمنهج القياس وتقليص السلاسل غير المفيدة، راجع cardinality مقاييس Kubernetes.

عدّ حالات الفشل: ثلاث حالات يجب التمييز بينها

يتوقف حساب نسبة الفشل على ما تصنّفه الاصطلاحات خطأً. يميّز تعريف error.type في model/mcp/common.yaml بين:

  • استجابة تحمل رمز خطأ JSON-RPC: تتلقى error.type هذا الرمز في صورة سلسلة نصية؛
  • استجابة HTTP خاطئة دون رمز JSON-RPC: رمز حالة HTTP؛
  • انتهاء مهلة أو خطأ في النقل: الاسم المعياري للاستثناء أو الخطأ.

وهناك حالة رابعة خاصة بالأدوات: ينجح استدعاء JSON-RPC لكن النتيجة (CallToolResult) تحمل isError بالقيمة true. عندئذ تطلب الاصطلاحات أن تساوي error.type القيمة tool_error. وبدون هذه القاعدة تبقى الأداة التي تفشل «بشكل نظيف» غير مرئية في نسبة فشل مبنية على رموز الحالة.

مقطع من model/mcp/common.yaml: تساوي error.type القيمة tool_error عندما تحمل نتيجة أداة isError بالقيمة true، وتأخذ rpc.response.status_code رمز خطأ JSON-RPC

من جهة الخادم، توضح الاصطلاحات أن بعض الرموز تدل على طلب لم يكن المستقبِل قادرًا على تلبيته ولا يجوز عدّها أخطاء: -32700 (Parse error) و-32600 (Invalid Request) و-32601 (Method not found) و-32602 (Invalid params، ويُعاد أيضًا عندما لا توجد الأداة المطلوبة) و-32002 (Resource not found). وأي رمز آخر يُعدّ خطأً. أما من جهة العميل فتُحتسب جميع رموز أخطاء JSON-RPC. النتيجة: نسبة الفشل التي يراها العميل أعلى عادةً مما يراه الخادم، ولا تصح المقارنة بينهما دون هذا التوضيح.

الخطوة 1: تسجيل الـ histogram بالحدود الموصى بها

إذا كان الخادم مزوّدًا بالأدوات يدويًا، فإن الاصطلاحات تشير إلى أن كل مقياس مدة ينبغي أن يُعلن بالحدود الصريحة [0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300] (بالثواني).

مقطع من docs/gen-ai/mcp.md: يجب تحديد المقياس مع ExplicitBucketBoundaries من 0.01 إلى 300 ثانية

تقبل واجهة OpenTelemetry لـ Python هذه الحدود عبر المعامل explicit_bucket_boundaries_advisory في create_histogram (موجود في مستودع opentelemetry-python المقروء أثناء التحرير). مثال أدنى من جهة الخادم:

import time
from opentelemetry import metrics

meter = metrics.get_meter("mon-serveur-mcp")
duration = meter.create_histogram(
    "mcp.server.operation.duration",
    unit="s",
    description="MCP request or notification duration as observed on the receiver",
    explicit_bucket_boundaries_advisory=[0.01, 0.02, 0.05, 0.1, 0.2, 0.5,
                                         1, 2, 5, 10, 30, 60, 120, 300],
)

def appeler(nom_outil, fonction, **arguments):
    attrs = {"mcp.method.name": "tools/call",
             "gen_ai.tool.name": nom_outil,
             "gen_ai.operation.name": "execute_tool"}
    debut = time.perf_counter()
    try:
        resultat = fonction(**arguments)
        if getattr(resultat, "isError", False):
            attrs["error.type"] = "tool_error"
        return resultat
    except Exception as exc:
        attrs["error.type"] = type(exc).__name__
        raise
    finally:
        duration.record(time.perf_counter() - debut, attrs)

الأسطر الحاسمة: الوحدة هي الثانية (لا الميلي ثانية)، ولا تُضبط error.type إلا عند الفشل، ولا يدخل أي وسيط من وسائط الاستدعاء في السمات. واسم الأداة لا يحتوي على معرّف مستخدم ولا على قيمة حرة.

الخطوة 2: اشتقاق العدّادات والـ histograms من التتبعات عبر Collector

عندما تكون spans الخاصة بـ MCP موجودة أصلًا، لا داعي لتكرار التزويد بالأدوات: يجمّع الموصل span_metrics في Collector (توزيعة contrib) الـ spans في مقاييس. ووفق README الخاص به، ينتج عدّاد استدعاءات (traces.span.metrics.calls) وhistogram للمدة (traces.span.metrics.duration)، مع بُعد status.code للتمييز بين الأخطاء. حالته «alpha» ووحدته الافتراضية الميلي ثانية، وفق README نفسه: تحقق من ذلك في الإصدار المنشور لديك.

connectors:
  span_metrics:
    histogram:
      unit: s
      explicit:
        buckets: [10ms, 20ms, 50ms, 100ms, 200ms, 500ms, 1s, 2s, 5s, 10s, 30s, 60s]
    dimensions:
      - name: mcp.method.name
      - name: gen_ai.tool.name
    aggregation_cardinality_limit: 500

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [span_metrics]
    metrics:
      receivers: [span_metrics]
      exporters: [otlp]

المفاتيح histogram.unit وhistogram.explicit.buckets وdimensions وaggregation_cardinality_limit مذكورة في README الموصل. القيمة 500 مثال يجب تكييفه. يصف README هذا الحد بأنه قاطع دائرة: فما بعده تُجمَّع التركيبات الإضافية تحت otel.metric.overflow="true". وتختلف الأسماء الناتجة (traces.span.metrics.*) عن mcp.server.operation.duration: اختر إحدى العائلتين للوحات المعلومات لا كلتيهما. وللاطلاع على إعداد Collector، راجع OpenTelemetry Collector على Kubernetes.

كيف تتحقق من أن الأمر يعمل

استدعِ عمدًا أداة بوسيط غير صالح، ثم أداة تعيد isError: true. في الـ backend يجب أن تظهر السلسلة error.type="tool_error" للثانية، وأن يزداد عدّاد الـ histogram للأولى. وإذا كان Collector يعمل مع المُصدِّر debug، فإن نقاط المقاييس تظهر في سجلاته قبل أن تصل إلى الـ backend.

الخطوة 3: تحديد SLI لكل أداة

يكفي مؤشران للبدء:

  • التوافر لكل أداة: الاستدعاءات التي لا تحمل error.type مقسومة على كل استدعاءات tools/call، حسب gen_ai.tool.name؛
  • زمن الاستجابة لكل أداة: نسبة مئوية (percentile) مثل 95 مقدّرة انطلاقًا من الـ buckets؛ ولا يكون التقدير دقيقًا إلا في حدود عرض الـ bucket، ومن هنا أهمية الحدود الموصى بها.

حدّد الهدف مع الفريق المالك للأداة، ونبّه على استهلاك ميزانية الأخطاء لا على ذروة معزولة، كما في التنبيه على الأعراض لا على الأسباب. ويُفصَّل الفرق بين هذه القياسات والمراقبة البسيطة في قابلية الملاحظة والمراقبة.

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

  • نقطة قياس واحدة لكل جانب: الخادم للحمل الفعلي، والعميل لتجربة الوكيل (بما فيها الشبكة).
  • لا قيمة حرة كبُعد: لا URI لمورد ولا وسيط ولا معرّف جلسة.
  • توثيق القاعدة «-32602 ليس خطأً من جهة الخادم» في الـ runbook، لتفادي الجدل أثناء الحادثة.
  • وضع سقف للـ cardinality عند المنبع (aggregation_cardinality_limit) ومراقبة تجاوزه.
  • مراجعة بلا لوم: نسبة الفشل المرتفعة تشير إلى أداة تحتاج إلى تحسين لا إلى شخص.

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

هل نحتاج إلى عدّاد استدعاءات إضافة إلى الـ histogram؟

لا. لا تعرّف اصطلاحات MCP أي عدّاد: عدد مشاهدات الـ histogram يعطي عدد الاستدعاءات. أما الموصل span_metrics فيوفّر عدّادًا مخصصًا مشتقًا من الـ spans.

هل تُحتسب الأداة التي تعيد isError بالقيمة true فشلًا؟

نعم، وفق الاصطلاحات: يجب أن تساوي error.type القيمة tool_error. وبدون هذه السمة يبدو الاستدعاء ناجحًا من جهة البروتوكول.

هل هذه المقاييس مستقرة؟

لا، فهي موسومة «development» في المستودع المقروء. ثبّت الإصدار الذي تتبعه واقرأ سجل التغييرات قبل كل تحديث.

الخلاصة

تتلخص مقاييس أدوات MCP في أربعة histograms بالثواني، وثلاث سمات مفيدة (الطريقة والأداة ونوع الخطأ)، وقاعدة دقيقة لـ tool_error. والباقي يُشتق: الاستدعاءات والإخفاقات والنسب المئوية. المصادر: مستودع اصطلاحات GenAI وMCP وREADME الموصل span_metrics. ولأمان هذه الخوادم، راجع تدقيق خوادم MCP.

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

Total
0
Shares
Leave a Reply

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

Previous Post
Correlation ID ou trace ID : lequel utiliser dans vos logs

correlation ID أم trace ID: أيّهما تستخدم في سجلاتك

Next Post
Seuil statique Dynatrace ou baseline : configurer la détection d'anomalies

العتبة الثابتة Dynatrace أم baseline: ضبط اكتشاف الشذوذ

Related Posts