مقاييس أدوات 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: مدة الجلسة.

نتيجتان عمليتان. أولًا، يعني استقرار «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. وبدون هذه القاعدة تبقى الأداة التي تفشل «بشكل نظيف» غير مرئية في نسبة فشل مبنية على رموز الحالة.

من جهة الخادم، توضح الاصطلاحات أن بعض الرموز تدل على طلب لم يكن المستقبِل قادرًا على تلبيته ولا يجوز عدّها أخطاء: -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] (بالثواني).

تقبل واجهة 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. هذه الاصطلاحات قيد التطوير: تحقق دائمًا من الأسماء والسمات والمعاملات في الوثائق الرسمية الخاصة بإصدارك.