يوضح دليل "معرّفات الترابط من البداية إلى النهاية" كيفية إنشاء معرف في الواجهة، تمريره عبر واجهات API، وإدراجه في السجلات حتى يتمكن الدعم من تتبع المشكلات بسرعة.
نادراً ما يستلم فريق الدعم تقرير خطأ نظيفًا. يقول المستخدم "نقرت دفع وفشل"، لكن هذه النقرة الواحدة قد تلمس المتصفح، بوابة API، خدمة المدفوعات، قاعدة بيانات، ووظيفة خلفية. كل جزء يسجل شريحته من القصة في أوقات مختلفة وعلى آلات مختلفة. بدون وسم مشترك، ستضطر للتخمين أي سطور السجل تنتمي معًا.
معرّف الترابط هو ذلك الوسم المشترك. هو معرف واحد مرتبط بإجراء مستخدم واحد (أو سير عمل منطقي واحد) ويحمله عبر كل طلب وإعادة محاولة وقفزة بين الخدمات. مع تغطية حقيقية من البداية إلى النهاية، يمكنك البدء بشكوى المستخدم وسحب التسلسل الزمني الكامل عبر الأنظمة.
غالبًا ما يخلط الناس بين عدد من المعرفات المتشابهة. هنا فصل واضح:
الشكل الجيد واضح: يبلغ المستخدم عن مشكلة، تطلب منه معرف الترابط المعروض في الواجهة (أو الموجود في شاشة الدعم)، وأي شخص في الفريق يمكنه إيجاد القصة الكاملة في دقائق. ترى طلب الواجهة، استجابة الـ API، خطوات الخلفية، ونتيجة قاعدة البيانات، كلها مرتبطة معًا.
قبل أن تولّد أي شيء، اتفقوا على بعض القواعد. إذا اختار كل فريق اسم رأس مختلف أو حقل سجل مختلف، سيظل الدعم عالقًا في التخمين.
ابدأ باسم مرجعي واحد واستخدمه في كل مكان. اختيار شائع هو رأس HTTP مثل X-Correlation-Id، بالإضافة إلى حقل سجل منظم مثل correlation_id. اختر هجاء واحد وحالة أحرف واحدة، وثّقها، وتأكد أن الوكيل العكسي أو البوابة لن يعيد تسمية الرأس أو يحذفه.
اختر تنسيقًا سهل الإنشاء وآمنًا للمشاركة في التذاكر والدردشات. تعمل UUIDs جيدًا لأنها فريدة ومملة. اجعل المعرف قصيرًا بما يكفي للنسخ، لكن ليس قصيرًا لدرجة حدوث تصادمات. الاتساق أفضل من التفنن.
قرّر أيضًا أين يجب أن يظهر المعرف ليتمكن البشر من استخدامه فعليًا. عمليًا، يعني ذلك أن يظهر في الطلبات، والسجلات، ومخرجات الأخطاء، وأن يكون قابلاً للبحث في الأداة التي يستخدمها فريقك.
حدد مدة حياة المعرف. قيمة افتراضية جيدة هي إجراء مستخدم واحد، مثل "نقر الدفع" أو "حفظ الملف الشخصي". بالنسبة لسير العمل الأطول الذي يمر عبر خدمات وطوابير، احتفظ بنفس المعرف حتى ينتهي سير العمل ثم ابدأ معرفًا جديدًا للعمل التالي. تجنّب "معرف واحد لكل الجلسة" لأن عمليات البحث ستصبح صاخبة بسرعة.
قاعدة صارمة: لا تضع بيانات شخصية في المعرف. لا بريد إلكتروني، لا أرقام هواتف، لا معرفات مستخدمين، ولا أرقام طلبات. إذا احتجت ذلك السياق، سجّله في حقول منفصلة مع ضوابط خصوصية مناسبة.
أسهل مكان لبدء معرف الترابط هو لحظة بدء المستخدم لإجراء تهتم به: النقر على "حفظ"، إرسال نموذج، أو تشغيل تدفق يؤدي إلى عدة طلبات. إذا انتظرت حتى ينشئه الخادم، غالبًا ما تفقد الجزء الأول من القصة (أخطاء الواجهة، إعادة المحاولات، الطلبات الملغاة).
استخدم تنسيقًا عشوائيًا وفريدًا. UUID v4 خيار شائع لأنه سهل الإنشاء ونادر التصادم. اجعله غامضًا (لا أسماء مستخدمين أو رسائل بريد أو طوابع زمنية) حتى لا تكشف بيانات شخصية في الرؤوس والسجلات.
عامل "سير العمل" على أنه إجراء مستخدم واحد قد يشغل عدة طلبات: التحقق، الرفع، إنشاء سجل، ثم تحديث القوائم. أنشئ معرفًا واحدًا عند بدء سير العمل، ثم احتفظ به حتى ينتهي (نجاح، فشل، أو إلغاء من المستخدم). نمط بسيط هو تخزينه في حالة المكون أو في كائن سياق طلب خفيف.
إذا بدأ المستخدم نفس الإجراء مرتين، ولّد معرف ترابط جديد للمحاولة الثانية. هذا يسمح للدعم بتمييز "نفس النقر مع إعادة محاولة" عن "تقديمين منفصلين".
أضف المعرف إلى كل استدعاء API تنتجه سير العمل، عادة عبر رأس مثل X-Correlation-ID. إذا كنت تستخدم عميل API مشترك (غلاف fetch، مثيل Axios، إلخ)، مرّر المعرف مرة ودع العميل يحقنه في كل المكالمات.
// 1) when the user action starts
const correlationId = crypto.randomUUID(); // UUID v4 in modern browsers
// 2) pass it to every request in this workflow
await api.post('/orders', payload, {
headers: { 'X-Correlation-ID': correlationId }
});
await api.get('/orders/summary', {
headers: { 'X-Correlation-ID': correlationId }
});
إذا كانت واجهتك تقوم بطلبات خلفية غير مرتبطة بالإجراء (استطلاع، تحليلات، تحديث تلقائي)، فلا تعيد استخدام معرف سير العمل لتلك الطلبات. حافظ على تركيز معرفات الترابط بحيث يروي المعرف قصة واحدة فقط.
حالما تنشئ معرف الترابط في المتصفح، المهمة بسيطة: يجب أن يغادر الواجهة مع كل طلب ويصل كما هو عند كل حد API. هذا ما يفشل غالبًا عندما يضيف الفرق نقاط نهاية جديدة أو عملاء جدد أو وسائط جديدة.
الافتراضي الأكثر أمانًا هو رأس HTTP في كل استدعاء (مثلاً X-Correlation-Id). الرؤوس سهلة الإضافة في مكان واحد (غلاف fetch، معترض Axios، طبقة الشبكات في الموبايل) ولا تتطلب تغيير الحمولة.
إذا كانت لديك طلبات عبر أصل مختلف، تأكد أن الـ API يسمح بذلك الرأس. وإلا فقد يمنع المتصفح إرساله بصمت وستعتقد أنك ترسله بينما لا يكون كذلك.
إذا اضطررت لوضع المعرف في سلسلة الاستعلام أو جسم الطلب (بعض الأدوات الخارجية أو رفع الملفات تفرض ذلك)، فاحفظ الاتساق ودوّنه. اختر اسم حقل واحد واستخدمه في كل مكان. لا تخلط correlationId وrequestId وcid حسب النقطة النهائية.
إعادة المحاولات فخ شائع آخر. يجب أن تحتفظ إعادة المحاولة بنفس معرف الترابط إذا كانت لا تزال نفس عملية المستخدم. مثال: نقر المستخدم "حفظ"، انقطع الشبك، عميلك يعيد محاولة POST. يجب أن يرى الدعم أثرًا متصلًا واحدًا، لا ثلاثة غير مرتبطين. نقرة مستخدم جديدة (أو وظيفة خلفية جديدة) يجب أن تحصل على معرف جديد.
بالنسبة إلى WebSockets، ضع المعرف في غلاف الرسالة، وليس فقط في المصافحة الأولية. يمكن أن تحمل اتصال واحد عدة إجراءات مستخدم.
لفحص سريع للموثوقية، اجعل الأمور بسيطة:
correlationId صريح.حافة الـ API لديك (البوابة، موازن التحميل، أو أول خدمة تستقبل المرور) هي المكان الذي إما تصبح فيه معرفات الترابط موثوقة أو تتحول إلى تخمين. اعتبر هذه النقطة مصدر الحقيقة.
اقبل معرفًا واردًا إذا أرسله العميل، لكن لا تفترض أنه سيكون موجودًا دائمًا. إذا كان مفقودًا، ولّد واحدًا جديدًا فورًا واستخدمه لبقية الطلب. هذا يبقي الأمور تعمل حتى عندما تكون بعض العملاء أقدم أو مضبوطة بشكل خاطئ.
قم بالتحقق الخفيف حتى لا تلوث القيم السيئة سجلاتك. اجعله متسامحًا: افحص الطول والحروف المسموح بها، لكن تجنّب الصيغ الصارمة التي ترفض المرور الفعلي. على سبيل المثال، اسمح بطول 16-64 حرفًا وحروف وأرقام وواصلات وشرطات سفلية. إذا فشل القيمة في التحقق، استبدلها بمعرف جديد واستمر.
اجعل المعرف مرئيًا للمتصل. أعده دائمًا في رؤوس الاستجابة، وضمّنه في أجسام الأخطاء. بهذه الطريقة يمكن للمستخدم نسخه من الواجهة، أو يطلبه وكيل الدعم ليجد المسار الدقيق.
سياسة حافة عملية تبدو هكذا:
X-Correlation-ID (أو الرأس المختار) من الطلب.X-Correlation-ID إلى كل استجابة، بما في ذلك الأخطاء.مثال حمولة خطأ (ما يجب أن يراه الدعم في التذاكر ولقطات الشاشة):
{
"error": {
"code": "PAYMENT_FAILED",
"message": "We could not confirm the payment.",
"correlation_id": "c3a8f2d1-9b24-4c61-8c4a-2a7c1b9c2f61"
}
}
بمجرد وصول الطلب إلى الخلفية، عامل معرف الترابط كجزء من سياق الطلب، وليس شيئًا تخزنه في متغير عالمي. القيم العالمية تنهار بمجرد أن تتعامل مع طلبين في آن واحد، أو عندما يستمر العمل غير المتزامن بعد الاستجابة.
قاعدة قابلة للتوسع: كل دالة يمكنها تسجيل أو استدعاء خدمة أخرى يجب أن تستقبل السياق الذي يحتوي المعرف. في خدمات Go، هذا يعني عادة تمرير context.Context عبر المعالجات والمنطق وعميل الكود.
عندما تستدعي الخدمة A الخدمة B، انسخ نفس المعرف إلى الطلب الصادر. لا تولد واحدًا جديدًا في منتصف الرحلة ما لم تحتفظ بالأصلي كحقل منفصل (مثلاً parent_correlation_id). إذا غيرت المعرفات، يفقد الدعم الخيط الوحيد الذي يربط القصة.
غالبًا ما يُفقد النشر في بعض الأماكن المتوقعة: الوظائف الخلفية التي تُشغّل أثناء الطلب، إعادة المحاولات داخل مكتبات العملاء، الويبهوكس المفعّلة لاحقًا، والاستدعاءات المتفرعة. أي رسالة غير متزامنة (قائمة انتظار/وظيفة) يجب أن تحمل المعرف، وأي منطق إعادة محاكاة يجب أن يحفظه.
يجب أن تكون السجلات منظمة باسم حقل ثابت مثل correlation_id. اختر هجاء واحد واحتفظ به في كل مكان. تجنّب المزج بين requestId وreq_id وtraceId ما لم تحدد أيضًا مطابقة واضحة.
إذا أمكن، أدرج المعرف في رؤية قاعدة البيانات أيضًا. نهج عملي هو إضافته إلى تعليقات الاستعلام أو بيانات جلسة قاعدة البيانات حتى تظهر سجلات الاستعلام البطيء المعرف. عندما يقول أحدهم "زر الحفظ تعطّل لمدة 10 ثوانٍ"، يمكن للدعم البحث عن correlation_id=abc123 ورؤية سجل الـ API، واستدعاء الخدمة اللاحقة، وعبارة SQL البطيئة الوحيدة التي تسببت في التأخير.
معرّف الترابط يساعد فقط إذا كان الناس قادرين على العثور عليه واتباعه. اجعله حقل سجل من الدرجة الأولى (لا تدفنه داخل سلسلة الرسالة)، واحتفظ بباقي مدخل السجل متناسقًا عبر الخدمات.
زاوج معرف الترابط مع مجموعة صغيرة من الحقول التي تجيب عن: متى؟، أين؟، ماذا؟، ومن؟ (بطريقة آمنة للمستخدم). لمعظم الفرق، هذا يعني:
timestamp (مع المنطقة الزمنية)service وenv (api، worker، prod، staging)route (أو اسم العملية) وmethodstatus وduration_msaccount_id أو معرف مستخدم مُشفر أحادي الاتجاه، وليس بريدًا إلكترونيًا)بهذا، يمكن للدعم البحث بالمعرف، التأكد أنهم ينظرون إلى الطلب الصحيح، ومعرفة أي خدمة تعاملت معه.
استهدف بضعة نقاط أثر قوية لكل طلب، وليس نصًا تفصيليًا.
rows=12).لتجنّب السجلات الصاخبة، حافظ على تفاصيل مستوى التصحيح خارج الوضع الافتراضي وروّج فقط للأحداث التي تساعد في الإجابة عن "أين فشل؟". إذا لم يساعد السطر في تحديد المشكلة أو قياس التأثير، فهو على الأرجح لا ينتمي إلى سجلات مستوى info.
التحرير مهم بقدر الهيكل. لا تضع PII في معرف الترابط أو السجلات: لا بريد إلكتروني، أسماء، أرقام هواتف، عناوين كاملة، أو رموز وصول خام. إذا احتجت لتحديد مستخدم، سجّل معرفًا داخليًا أو تجزئة أحادية الاتجاه.
يرسل مستخدم رسالة للدعم: "فشل الخروج عندما نقرّت الدفع." أفضل سؤال متابعة بسيط: "هل يمكنك لصق معرف الترابط المعروض على شاشة الخطأ؟" يردون بـ cid=9f3c2b1f6a7a4c2f.
الآن لدى الدعم مقبض واحد يوصِل واجهة المستخدم، وAPI، وعمل قاعدة البيانات. الهدف أن يحمل كل سطر سجل لذلك الإجراء نفس المعرف.
يبحث الدعم عن 9f3c2b1f6a7a4c2f ويرى السريان:
frontend INFO cid=9f3c2b1f6a7a4c2f event="checkout_submit" cart=3 items
api INFO cid=9f3c2b1f6a7a4c2f method=POST path=/api/checkout user=1842
api ERROR cid=9f3c2b1f6a7a4c2f msg="payment failed" provider=stripe status=502
من هناك، يتابع المهندس نفس المعرف إلى النقلة التالية. المفتاح أن استدعاءات خدمة الخلفية (وأي وظائف في الطابور) تعيد إرسال المعرف أيضًا.
payments INFO cid=9f3c2b1f6a7a4c2f action="charge" amount=49.00 currency=USD
payments ERROR cid=9f3c2b1f6a7a4c2f err="timeout" upstream=stripe timeout_ms=3000
db INFO cid=9f3c2b1f6a7a4c2f query="insert into failed_payments" rows=1
الآن المشكلة واضحة: خدمة المدفوعات انتهت مهلة انتظارها بعد 3 ثوانٍ، وسُجِّل سجل فشل. يمكن للمهندس التحقق من النشرات الأخيرة، التأكد مما إذا تغيّرت إعدادات المهلة، ومعرفة ما إذا كانت إعادة المحاولات تحدث.
لإغلاق الحلقة، قم بأربع فحوص:
أسرع طريقة لجعل معرفات الترابط عديمة الفائدة هي كسر السلسلة. تأتي معظم الفشلات من قرارات صغيرة تبدو ضارة أثناء البناء، ثم تضر عندما يحتاج الدعم إلى إجابات.
خطأ كلاسيكي هو توليد معرف جديد في كل قفزة. إذا أرسل المتصفح معرفًا، يجب أن يحتفظ به بوابة الـ API، لا أن تستبدله. إذا كنت بحاجة فعلًا إلى معرف داخلي أيضًا (لمهمة طابور أو وظيفة خلفية)، احتفظ بالأصلي كحقل أصل حتى تظل القصة متصلة.
ثغرة شائعة أخرى هي تسجيل جزئي. الفرق تضيف المعرف في أول API، لكنها تنساه في عمليات العمال، الوظائف المجدولة، أو طبقة الوصول إلى قاعدة البيانات. النتيجة مسدودة: ترى الطلب يدخل النظام، لكن لا تعرف أين ذهب بعد ذلك.
حتى عندما يكون المعرف موجودًا في كل مكان، قد يصعب البحث إذا استخدمت كل خدمة اسم حقل أو صيغة مختلفة. اختر اسمًا واحدًا والتزم به عبر الواجهة، وواجهات الـ API، والسجلات (مثلاً correlation_id). اختر أيضًا تنسيقًا واحدًا (غالبًا UUID)، واعتبره حساسًا لحالة الأحرف حتى يعمل النسخ واللصق.
لا تفقد المعرف عندما تسوء الأمور. إذا أعاد API حالة 500 أو خطأ تحقق، أضمن تضمين معرف الترابط في استجابة الخطأ (ومثاليًا في رأس الاستجابة أيضًا). بهذه الطريقة يمكن للمستخدم لصقه في دردشة الدعم، وفريقك سيتتبع المسار فورًا.
اختبار سريع: هل يمكن لشخص دعم أن يبدأ بمعرف واحد ويتتبعه عبر كل سطر سجل مشارك، بما في ذلك حالات الفشل؟
استخدم هذا كفحص سريع قبل أن تقول للدعم "ابحثوا في السجلات فقط." هذا يعمل فقط عندما يتبع كل قفزة نفس القواعد.
correlation_id إلى سجلات الطلب كحقل منظم.اختر أصغر تغيير يجعل السلسلة غير منقطعة.
correlation_id الأصلي وأضف span_id منفصلًا إذا احتجت تفاصيل أكثر.اختبار سريع يكشف الثغرات: افتح أدوات المطور، نفّذ إجراءً واحدًا، انسخ معرف الترابط من الطلب الأول، ثم أكد أنك ترى نفس القيمة في كل طلب API ذي صلة وفي كل سطر سجل مطابق.
معرفات الترابط تفيد فقط عندما يستخدمها الجميع بنفس الطريقة، في كل مرة. عامل سلوك معرف الترابط كجزء مطلوب من الشحن، وليس كتحسين سجلات اختياري.
أضف خطوة صغيرة للقدرة على التتبُّع إلى تعريف جاهزية أي نقطة نهاية أو إجراء واجهة جديدة. غطِّ كيف يُنشأ المعرف (أو يُعاد استخدامه)، أين يعيش خلال التدفق، أي رأس يحمله، وماذا تفعل كل خدمة عندما يكون الرأس مفقودًا.
قائمة تحقق خفيفة الوزن عادةً ما تكون كافية:
correlation_id) عبر التطبيقات والخدمات.يحتاج الدعم أيضًا لسكربت بسيط لكي يصبح التصحيح سريعًا وقابلًا للتكرار. قرر أين يظهر المعرف للمستخدمين (مثلاً زر "نسخ معرف التصحيح" في مربعات حوار الأخطاء)، ودوّن ما يجب أن يطلبه الدعم وأين يبحث.
قبل الاعتماد عليه في الإنتاج، شغّل تدفقًا مرحليًا يطابق الاستخدام الحقيقي: انقر زرًا، استدعِ خطأ تحقق، ثم أكمل الإجراء. تأكد من قدرتك على تتبع نفس المعرف من طلب المتصفح، عبر سجلات الـ API، إلى أي عامل خلفي، وحتى سجلات استعلام قاعدة البيانات إن كنت تسجلها.
إذا كنت تبني تطبيقات على Koder.ai، سيساعدك تسجيل اتفاقية رأس معرف الترابط وقواعد التسجيل في Planning Mode حتى تبدأ مشاريع React وGo المتولدة متسقة افتراضيًا.
معرّف الترابط هو معرف مشترك واحد يعلّم كل ما يتعلق بإجراء مستخدم أو سير عمل واحد عبر المتصفح وواجهات برمجة التطبيقات والخدمات والعمال. يسمح هذا للدعم بالبدء من معرف واحد وسحب التسلسل الزمني الكامل بدل التخمين أي سطور السجل تنتمي معًا.
استخدم معرف الترابط عندما تريد تصحيح حادث واحد بسرعة من البداية للنهاية، مثل: “نقرت على زر الدفع وفشل”. معرف الجلسة واسع جدًا لأنه يغطي عدة أفعال، ومعرّف الطلب ضيّق جدًا لأنه يغطي طلب HTTP واحد ويتغير عند إعادة المحاولة.
أفضل ضابط افتراضي هو في بداية فعل المستخدم في الواجهة، في اللحظة التي يبدأ فيها سير العمل (إرسال نموذج، النقر، أو تدفق متعدد الخطوات). هذا يحفظ أوّل جزء من القصة، بما في ذلك أخطاء الواجهة وإعادة المحاولات والطلبات الملغاة.
استخدم قيمة غامضة مشابهة لـ UUID سهلة النسخ وآمنة للمشاركة في تذاكر الدعم. لا تشفر بيانات شخصية، أسماء مستخدمين، عناوين بريد أو أرقام طلبات أو طوابع زمنية داخل المعرف؛ احتفظ بهذه البيانات في حقول سجل منفصلة وبضوابط خصوصية مناسبة.
اختر اسم رأس واحد مرجعي واستخدمه في كل مكان، مثل X-Correlation-ID، وسجّله تحت حقل منظم ثابت مثل correlation_id. الاتساق أهم من الاسم الدقيق لأن الدعم يحتاج لشيء واحد متوقع للبحث عنه.
احتفظ بنفس معرف الترابط عبر إعادة المحاولة إذا كان لا يزال نفس إجراء المستخدم، حتى تبقى السجلات مرتبطة. أنشئ معرفًا جديدًا فقط عندما يبدأ المستخدم محاولة جديدة منفصلة، مثل النقر مرة أخرى لاحقًا.
نقطة دخول الـ API يجب أن تقبل المعرف عند إرساله وتولّد واحدًا جديدًا عندما يكون مفقودًا أو غير صالح بوضوح. كما يجب أن تعكس المعرف في الاستجابة (بما في ذلك الأخطاء) حتى يتمكن المستخدمون والدعم من نسخه من رسالة الواجهة أو شاشة التصحيح.
مرره بوضع معرف الترابط في سياق الطلب ونسخه إلى كل استدعاء لاحق، بما في ذلك طلبات HTTP/gRPC الداخلية والوظائف المؤجلة في الطابور. تجنّب إنشاء معرف ترابط جديد أثناء الرحلة؛ إذا احتجت لتفصيل إضافي، أضف معرفًا داخليًا منفصلًا دون كسر السلسلة الأصلية.
سجّله كحقل منظم من الدرجة الأولى، لا تدفنه داخل سلسلة الرسالة، حتى يكون قابلاً للبحث والتصفية. أرفقه ببعض الحقول العملية مثل اسم الخدمة، المسار، الحالة، المدة، ومعرف آمن للمستخدم، وتأكد أن حالات الفشل تسجل المعرف أيضًا حتى لا ينتهي المسار عند أهم لحظة.
اختبر سريعًا عن طريق تنفيذ إجراء واحد، ونسخ معرف الترابط من الطلب الأول أو شاشة الخطأ، ثم تأكد من ظهور نفس القيمة في رأس كل طلب ذي صلة وفي كل سطر سجل يتعامل مع سير العمل. إذا اختفى المعرف في العمال أو إعادة المحاولات أو استجابات الخطأ، فهذه هي الثغرة الأولى التي يجب إصلاحها.