قابلية ملاحظة API: ما هي وكيفية تحقيقها

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

ماذا تعني قابلية مراقبة الـ API في الواقع

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

هذا الجزء الأخير مهم. مع قابلية المراقبة، عندما يبلغ عميل عن طلبات دفع بطيئة في الساعة 2 صباحًا لمستخدمين في منطقة واحدة على إصدار واحد من الـ API، يجب أن تكون قادرًا على الإجابة عن "لماذا" من البيانات التي تجمعها بالفعل. تقوم بتجهيز النظام بشكل غني بما يكفي للتحقيق في أنماط الفشل التي لم تتوقعها. هذا هدف مختلف عن فحوصات التوفر (uptime checks)، التي تجيب فقط عن الأسئلة التي كنت تعرف بالفعل كيف تسألها.

قابلية المراقبة مقابل المراقبة

يستخدم الناس هذه الكلمات بالتبادل، لكنها تصف أشياء مختلفة.

تراقب المراقبة الإشارات المعروفة وتطلق التنبيهات عندما تتجاوز عتبة معينة. تقرر مسبقًا ما يجب تتبعه (معدل الخطأ، وحدة المعالجة المركزية، زمن الاستجابة p99) وما يعتبر سيئًا. تجيب المراقبة عن السؤال "هل الشيء الذي توقعت أن يتعطل يتعطل؟"

قابلية المراقبة هي خاصية للنظام: مدى قدرة بياناته القياسية (telemetry) على السماح لك بطرح أسئلة عشوائية حول حالته الداخلية. تجيب عن "لماذا يتصرف هذا بهذه الطريقة؟" حتى عندما يكون "هذا" شيئًا لم تبنِ له لوحة معلومات أبدًا.

ببساطة، تخبرك المراقبة أن هناك خطأ ما. تساعدك قابلية المراقبة على معرفة السبب. أنت بحاجة إلى كليهما. تمنحك المراقبة التنبيه؛ وتمنحك قابلية المراقبة المسار من التنبيه إلى السبب الجذري. إذا كنت ترغب في معالجة أعمق لجانب التنبيه، فإن دليلنا لمراقبة الـ API يغطيه بالتفصيل.

إليك الفارق في جدول.

الأعمدة الثلاثة: المقاييس، السجلات، التتبعات

ترتكز قابلية المراقبة على ثلاثة أنواع من البيانات القياسية (telemetry)، والتي تُعرف غالبًا بالأعمدة الثلاثة. OpenTelemetry، المعيار المحايد للموردين، يُضفي الطابع الرسمي على هذه البيانات كـ "إشارات" بيانات قياسية. يدعم OpenTelemetry حاليًا التتبعات والمقاييس والسجلات والحمولات، مع تطوير الأحداث والملفات الشخصية. تتوافق الأعمدة الثلاثة الكلاسيكية مع إشاراته الثلاثة الأولى.

المقاييس

المقاييس هي قياسات رقمية مجمعة على مدى فترة زمنية. بالنسبة للـ API، الأهم هو معدل الطلبات، معدل الأخطاء، وتوزيع زمن الاستجابة. أبلغ عن زمن الاستجابة كنسب مئوية (p95 و p99)، وليس فقط كمتوسطات. يخفي المتوسط الذيل البطيء الذي يشعر به المستخدمون الحقيقيون.

المقاييس رخيصة التخزين وسريعة الاستعلام، مما يجعلها مثالية للوحات المعلومات والتنبيهات. نقطة ضعفها هي الكاردينالية المنخفضة: تخبرك أن زمن الاستجابة p99 قد ارتفع، ولكن ليس أي الطلبات تسببت في ذلك.

السجلات

السجلات هي سجلات مؤرخة لأحداث منفصلة. السجلات المنظمة، التي تصدر بتنسيق JSON مع حقول متسقة، هي أكثر فائدة بكثير من أسطر النص الحر لأنه يمكنك تصفيتها وتجميعها.

{
  "timestamp": "2026-06-22T02:14:09Z",
  "level": "error",
  "method": "POST",
  "path": "/v2/checkout",
  "status": 503,
  "duration_ms": 4812,
  "trace_id": "8f3a1c9d2e7b4a16",
  "user_region": "ap-southeast-1",
  "api_version": "2026-05"
}

لاحظ حقل trace_id. هذا المعرف هو ما يربط سطر السجل بتدفق الطلب الأوسع، مما يقودنا إلى العمود الثالث.

التتبعات

تتبع موزع يتبع طلبًا واحدًا وهو يتنقل عبر الخدمات. تصبح كل قفزة امتدادًا (span)، وتتشارك الامتدادات معرف تتبع (trace ID) بحيث يمكنك إعادة بناء المسار الكامل ومعرفة أين استُهلك الوقت. عندما يمر طلب عبر بوابة، وخدمة مصادقة، وثلاثة خدمات مصغرة، يوضح التتبع أي قفزة أضافت الثواني الأربع.

التتبعات هي ما يجعل تصحيح أخطاء الخدمات المصغرة قابلاً للإدارة. بدونها، ستكون تخمن أي خدمة في السلسلة بطيئة.

تعمل الأعمدة الثلاثة معًا. ينبه تنبيه المقياس إلى الارتفاع المفاجئ. يشير التتبع إلى الخدمة البطيئة. تخبرك السجلات من تلك الخدمة، المصفاة بواسطة معرف التتبع، بما حدث بالضبط.

طريقة RED والإشارات الذهبية

لا تحتاج إلى تتبع كل شيء. تمنحك طريقة RED نقطة انطلاق مركزة لأي خدمة تعتمد على الطلبات. قدمها توم ويلكي في عام 2015 أثناء عمله في Weaveworks، وهي مستوحاة من الإشارات الذهبية الأربعة لجوجل.

تشير RED إلى:

• المعدل (Rate): الطلبات في الثانية التي يتعامل معها الـ API الخاص بك.
• الأخطاء (Errors): عدد أو معدل الطلبات الفاشلة، مثل استجابات 5xx واستجابات 4xx غير المتوقعة.
• المدة (Duration): توزيع فترات استجابة الطلبات، المبلغ عنها كـ p95 و p99.

Rate     = requests/sec
Errors   = % of 5xx (and unexpected 4xx) responses
Duration = latency distribution, report p95 and p99 (not just average)

تتمحور طريقة RED حول الطلبات، مما يناسب الـ APIs والبوابات وشبكات الخدمات (service meshes) بشكل جيد. نظيرها، USE (الاستخدام، التشبع، الأخطاء)، يستهدف موارد البنية التحتية مثل وحدة المعالجة المركزية والقرص. بالنسبة للـ API، ابدأ بـ RED وأضف USE للمضيفات الأساسية.

SLIs و SLOs: تحويل الإشارات إلى أهداف

تصبح بيانات قابلية المراقبة قابلة للتنفيذ عندما تربطها بأهداف. يحدد كتاب Google SRE مصطلحين هنا.

مؤشر مستوى الخدمة (SLI) هو مقياس كمي لجانب واحد من خدمتك. مؤشرات SLI الشائعة هي زمن استجابة الطلب، ومعدل الخطأ (نسبة جميع الطلبات الفاشلة)، والإنتاجية بعدد الطلبات في الثانية. تتوافق هذه بوضوح مع RED.

هدف مستوى الخدمة (SLO) هو قيمة مستهدفة أو نطاق لمؤشر SLI. على سبيل المثال: "99.9 بالمائة من الطلبات على مدار فترة 28 يومًا تكتمل في أقل من 300 مللي ثانية." يخبرك الـ SLO أنت وفريقك متى يكون الـ API سليمًا بما يكفي، ومتى يجب قضاء وقت الهندسة على الموثوقية بدلاً من الميزات.

تمنح مؤشرات SLI وأهداف SLO مقاييسك معنى. بدونها، يكون مخطط زمن الاستجابة مجرد خط مموج؛ معها، يصبح عقدًا يمكنك القياس بناءً عليه.

الأدوات: OpenTelemetry والخلفيات

يمكنك تقسيم أدوات قابلية المراقبة إلى طبقتين: كيفية إنشاء البيانات القياسية (telemetry)، وإلى أين ترسلها.

لإنشاء البيانات، OpenTelemetry هو المعيار الذي يستحق التعلم. إنه مشروع لمؤسسة Cloud Native Computing Foundation (CNCF)، وقد تشكل بدمج OpenTracing و OpenCensus. إنه مستقل عن الموردين والأدوات، لذا فهو يعمل مع مجموعة واسعة من الخلفيات (backends). مبدأه الأساسي هو أنك تمتلك البيانات التي تنشئها، دون قيود على المورد. يوفر واجهات برمجة التطبيقات (APIs)، وحزم تطوير البرامج (SDKs) للغات، والاتفاقيات الدلالية، وبروتوكول OTLP السلكي، والأتمتة التلقائية، و OpenTelemetry Collector.

للتخزين والتحليل، لديك خيارات. بروميثيوس (Prometheus) مقترنًا بـ جرافانا (Grafana) هو حزمة مفتوحة المصدر شائعة للمقاييس ولوحات المعلومات. المنصات التجارية مثل Datadog و Honeycomb تستوعب التتبعات والمقاييس والسجلات وتقدم استعلامات عالية الكاردينالية. إذا كنت تستخدم Datadog، فإن شرحنا لـ Datadog API يوضح كيفية دفع وسحب البيانات برمجيًا.

الفكرة من OpenTelemetry هي أن تقوم بالتجهيز مرة واحدة، ثم تبديل الخلفيات دون الحاجة لإعادة التجهيز. هذه قابلية النقل هي السبب الرئيسي لتبنيه مبكرًا.

أين تتناسب الاختبارات والفحوصات الاصطناعية

قابلية المراقبة ليست مجرد شاغل إنتاجي. بعض الإشارات الأكثر فائدة تأتي من الاختبارات التي تقوم بتشغيلها عمدًا، سواء قبل النشر أو بعده.

النقل إلى اليسار: اختبارات العقود وتشغيل CI

قبل نشر الكود، تتحقق اختبارات العقود من أن الـ API الخاص بك لا يزال يتوافق مع مواصفاته. يؤدي تشغيل هذه الاختبارات في CI إلى اكتشاف التغييرات التي قد تتسبب في كسر قبل وصولها إلى المستخدمين. كل عملية تشغيل اختبار CI هي إشارة: نجاح أو فشل مرتبط بالتزام (commit) وبيئة وطابع زمني. هذا التاريخ هو بيانات قابلية مراقبة حول جودة إصدارك.

يقوم Apidog CLI بتشغيل سيناريوهات الاختبار الخاصة بك في مسار (pipeline). إنه مبني على Node.js ويحتاج إلى Node v16 أو أحدث.

npm install -g apidog-cli
# verify the install
node -v && apidog -v

قم بتشغيل سيناريو اختبار مقابل بيئة. علامة البيئة مطلوبة، وتمرر رمزك المميز بشكل صريح.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli

هنا -t هو معرف سيناريو الاختبار، و -e هو معرف البيئة، و -r يحدد تنسيقات التقرير (`cli`، `html`، `json`، `junit`). المبلّغ الافتراضي هو `cli`. لتشغيل السيناريو من ملف CSV أو JSON، أضف -d ./data.csv (تأخذ العلامة -d، أو --iteration-data، مسار ملف). يمكنك أيضًا دفع نظرة عامة على التقرير إلى سحابة Apidog.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli --upload-report

للحصول على مسار كامل يمكنك نسخه وتعديله، راجع دليل Apidog CLI لـ CI/CD، أو المرجع الكامل لـ CLI لكل علامة.

المراقبة الاصطناعية في الإنتاج

تقوم المراقبة الاصطناعية بتشغيل طلبات مبرمجة مقابل الـ API الحي الخاص بك بجدول زمني، من الخارج، بالطريقة التي سيتعامل بها المستخدم معه. تكتشف المشاكل قبل أن يفعلها حركة المرور الحقيقية وتمنحك تدفقًا ثابتًا من نقاط بيانات زمن الاستجابة والتوفر. فحص صحة الـ API الأساسي هو أبسط أشكاله. المراقبة الاصطناعية الكاملة تمدده ليشمل تدفقات متعددة الخطوات مثل تسجيل الدخول ثم الدفع.

هذه الفحوصات هي إشارات قابلية مراقبة بحد ذاتها. عملية تشغيل اصطناعية فاشلة في الساعة 02:00 بمدة 4 ثوانٍ هي بالضبط نوع الحدث الذي ترغب في تغذية تتبعاتك وسجلاتك به. لاستطلاع الأدوات المتخصصة، راجع مجموعتنا لأدوات الاختبار الاصطناعية، وبالنسبة لمنصات مراقبة الإنتاج، قائمة أدوات مراقبة الـ API.

توليد إشارات حقيقية باستخدام مهام Apidog المجدولة

يمكن لـ Apidog إنتاج إشارات اصطناعية متكررة من خلال المهام المجدولة. تعمل هذه الميزة تلقائيًا على تشغيل سيناريوهات الاختبار المكونة في أوقات محددة، وتلتقط النتائج، وتدعم اختبار الانحدار المجدول. تجدها تحت وحدة الاختبارات (Tests module)، في المهام المجدولة (Scheduled Tasks).

بضع نقاط يجب معرفتها قبل الاعتماد عليها. المهام المجدولة حاليًا في مرحلة بيتا (تجريبية)، لذا تعامل معها كخاصية تتطور بدلاً من كونها خاصية مستقرة منذ فترة طويلة. كما أنها تتطلب مُشغل (Runner) مستضاف ذاتيًا ومُكوّن؛ تعرض خيارات "يعمل على" (Runs On) مُشغلًا مستضافًا ذاتيًا اليوم، مع إدراج Apidog Cloud كقادم قريبًا. لذلك لا يوجد فحص مجدول مستضاف بالكامل على السحابة حتى الآن.

عند إعداد واحد، تختار:

• سيناريوهات الاختبار: سيناريو واحد أو أكثر للتنفيذ.
• وضع التشغيل: دورة توقيت، مثل كل يوم أحد في الساعة 11 مساءً أو كل 6 ساعات.
• الإشعار: تنبيهات بعد كل تشغيل، أو عند الفشل فقط.

تعتمد أعداد التشغيل على خطة اشتراكك. لإنشاء عملي، راجع شرح مهام Apidog المجدولة.

القيمة هنا تكمن في إغلاق الحلقة. تقوم بتصميم واختبار الـ API الخاص بك في مكان واحد، ثم تقوم بتشغيل نفس السيناريوهات بانتظام بحيث تستمر في توليد إشارات النجاح/الفشل وزمن الاستجابة التي يمكنك التصرف بناءً عليها. جرب Apidog مجانًا، بدون الحاجة لبطاقة ائتمان، وحوّل سيناريوهات الاختبار الحالية إلى إشارات متكررة.

مسار عملي نحو API قابل للمراقبة

إذا كنت تبدأ من الصفر، اعمل بهذا الترتيب:

1. أصدر سجلات منظمة بمخطط متسق ومعرف تتبع (trace ID) لكل طلب.
2. جهز باستخدام OpenTelemetry بحيث تشارك التتبعات والمقاييس والسجلات السياق وتظل محمولة عبر الخلفيات.
3. تتبع مقاييس RED (المعدل، الأخطاء، المدة مع p95 و p99) وضعها على لوحة معلومات.
4. حدد مؤشرات SLI وأهداف SLO بحيث تكون لمقاييسك أهداف، وليس مجرد اتجاهات.
5. أضف اختبارات العقود في CI لاكتشاف التغييرات التي قد تسبب كسرًا قبل الإصدار.
6. قم بتشغيل فحوصات اصطناعية بجدول زمني مقابل بيئة الإنتاج، على سبيل المثال باستخدام مهام Apidog المجدولة.

لا يتعين عليك القيام بالخطوات الستة كلها دفعة واحدة. حتى الخطوة الأولى، السجلات المنظمة بمعرفات التتبع، تنقلك بعيدًا عن السجلات النصية المسطحة.

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

ما هي قابلية مراقبة الـ API؟

قابلية مراقبة الـ API هي القدرة على فهم الحالة الداخلية للـ API من البيانات القياسية (telemetry) التي يصدرها، وهي المقاييس والسجلات والتتبعات. يتيح لك الـ API القابل للمراقبة التحقيق في سبب تصرفه بطريقة معينة، بما في ذلك المشاكل التي لم تتوقعها، دون إضافة تجهيزات جديدة أولاً.

قابلية مراقبة الـ API مقابل المراقبة: ما الفرق؟

تراقب المراقبة الإشارات المحددة مسبقًا وتطلق التنبيهات عندما تتجاوز عتبة معينة، مجيبة على السؤال "هل الشيء الذي توقعت أن يتعطل يتعطل؟" قابلية المراقبة هي خاصية للنظام تسمح لك بطرح أسئلة جديدة وعشوائية حول سلوكه، مجيبة على السؤال "لماذا يحدث هذا؟" تخبرك المراقبة بوجود خطأ ما؛ وتساعدك قابلية المراقبة في العثور على السبب. أنت بحاجة إلى كليهما.

ما هي الأعمدة الثلاثة لقابلية المراقبة؟

الأعمدة الثلاثة هي المقاييس والسجلات والتتبعات. المقاييس هي أرقام مجمعة مثل معدل الطلبات والنسب المئوية لزمن الاستجابة. السجلات هي سجلات مؤرخة لأحداث منفصلة، ومن الأفضل أن تكون منظمة بتنسيق JSON. تتبع التتبعات طلبًا واحدًا عبر الخدمات حتى تتمكن من رؤية أين استُهلك الوقت. يُضفي OpenTelemetry الطابع الرسمي على هذه البيانات كـ إشارات بيانات قياسية.

كيف تجعل الـ API قابلاً للمراقبة؟

ابدأ بإصدار سجلات منظمة مع معرف تتبع (trace ID) لكل طلب. جهز كودك باستخدام OpenTelemetry بحيث تتشارك المقاييس والسجلات والتتبعات السياق. تتبع مقاييس RED، وحدد مؤشرات SLI وأهداف SLO كأهداف، وأضف اختبارات العقود في CI، وقم بتشغيل فحوصات اصطناعية مجدولة مقابل بيئة الإنتاج. كل خطوة تضيف إشارة قابلة للاستعلام.

هل OpenTelemetry مطلوب لقابلية المراقبة؟

لا. قابلية المراقبة هي خاصية يمكنك تحقيقها بأي أدوات بيانات قياسية، وقد استخدمت العديد من الفرق وكلاء مملوكين قبل وجود OpenTelemetry بوقت طويل. ومع ذلك، OpenTelemetry هو معيار CNCF المحايد للموردين، لذا فإن تبنيه يتيح لك التجهيز مرة واحدة وتبديل الخلفيات مثل Prometheus أو Datadog أو Honeycomb دون إعادة التجهيز. إنه خيار افتراضي قوي، وليس شرطًا.