ربط السجلات بالتتبعات في Elastic APM يعني كتابة معرّف التتبع الجاري، أي الحقل trace.id، في كل سطر من السجل. أثناء حادثة تشغيلية تنتقل من معاملة بطيئة إلى سجلاتها، ومن خطأ في سجل إلى التتبع الكامل، دون البحث بالطابع الزمني. يتبع هذا الدرس ثلاث خطوات: تفعيل الربط في الوكيل، ثم حقن المعرّفات، ثم استيعاب السجلات.
يغطي الدرس حالتين: Node.js مع Pino، و.NET مع Serilog. المعلومات مأخوذة من وثائق Elastic التي روجعت في 30 أكتوبر 2026؛ يجب إعادة التحقق من أسماء الحزم والحقول لإصدارك من المنظومة.
بالنسبة لفريق SRE، الرهان هو زمن الحل (MTTR): كل انتقال يدوي بين أداتين يطيل الحادثة. هذه المقالة تخص Elastic، لا Dynatrace Managed ولا Dynatrace SaaS؛ ويبيّن القسم الأخير موقع Dynatrace.
باختصار
- يكون السجل مرتبطًا حين يحتوي على
trace.idوعلىtransaction.idأوspan.id. - يوفّر وكيل APM المعرّفات، ويكتبها منسّق ECS (Elastic Common Schema) في السجل.
- يجب أن تصل السجلات إلى Elasticsearch نفسه الذي توجد فيه بيانات APM.
ربط السجلات بالتتبعات في Elastic APM: المبدأ
وفق وثائق Elastic عن سجلات التطبيقات، يتيح الربط رؤية سياق السجل، وكل سجلات التتبع، والتنقل بين السجلات والتتبعات. يحمل سجل ECS بصيغة JSON حقولًا مثل log.level وservice.name وtrace.id وtransaction.id.
ميّز بين الإشارات. يجمع التتبع وحدات span، أي عمليات مقيسة زمنيًا. أما السجل فهو حدث نصي. لا شيء يربط بينهما سوى المعرّف الذي تضيفه إلى السجل. ومن هنا الخطوات الثلاث التالية.
تذكر الوثائق أيضًا ثلاث طرق لإرسال السجلات. يجمع Filebeat أو Elastic Agent الملفات النصية مهما كانت اللغة. ويكتب ملحق ECS ملف JSON جاهزًا للاستخدام مباشرة، مقابل تغيير إعداد المسجِّل. أما إعادة التنسيق بواسطة وكيل APM فلا تتوفر إلا لـ Ruby وPython وJava، والإرسال المباشر من الوكيل لـ Java فقط؛ لذلك لا يخص هذان الخياران أمثلتنا.
الخطوة 1: تفعيل الربط في الوكيل
في Node.js، يوفّر الوكيل elastic-apm-node الخاصية apm.currentTraceIds. وفق وثائق واجهة البرمجة، تعيد هذه الخاصية كائنًا فيه trace.id وtransaction.id أو span.id بحسب العنصر النشط؛ وخارج أي معاملة يكون الكائن فارغًا. وهي متاحة منذ الإصدار 2.17 من الوكيل.

يجب أن يبدأ الوكيل قبل بقية التطبيق. بلا معاملة نشطة لا يوجد معرّف: السجل المكتوب عند الإقلاع أو في مهمة خارج أي طلب لن يكون مرتبطًا.
في .NET، تسرد وثائق الوكيل إطاري سجلات مدعومين: Serilog وNLog. أما مع مسجِّل آخر فتحيل إلى دليل لحقن المعرّفات يدويًا.
الخطوة 2: حقن المعرّفات في كل سجل
Node.js مع Pino
مع حزمة تنسيق ECS لـ Pino أو Winston أو Morgan، توضح الوثائق أن الوكيل يستدعي الواجهة نيابةً عنك وأن المعرّفات تُحقن تلقائيًا. بالنسبة إلى Pino الحزمة هي @elastic/ecs-pino-format. وفق صفحتها، تدعم Pino 6 و7 و8، وتضيف trace.id وtransaction.id وspan.id عندما يكون وكيل APM لـ Node.js نشطًا. الخيار apmIntegration: false يعطّل هذه الإضافة.

const apm = require('elastic-apm-node').start(); // en premier
const { ecsFormat } = require('@elastic/ecs-pino-format');
const pino = require('pino');
const log = pino(ecsFormat());
log.info('commande reçue');
قيد تشير إليه الصفحة نفسها: الحقول الممرَّرة إلى child() لا تُحوَّل، ولذلك لا يحصل كائن req الموضوع في مسجِّل فرعي على حقول HTTP الخاصة بـ ECS. وبلا حزمة ECS، أضف بنفسك ...apm.currentTraceIds إلى كل مُدخل، كما في لقطة الخطوة 1.
.NET مع Serilog
يصف المستودع elastic/ecs-dotnet حزمتين. تضيف Elastic.Apm.SerilogEnricher معرّفي التتبع والمعاملة إلى أحداث Serilog المنشأة أثناء معاملة. وتوفّر Elastic.CommonSchema.Serilog الفئة EcsTextFormatter التي تكتب الأحداث بصيغة JSON ECS؛ وعند الجمع بينهما تظهر المعرّفات في مخرجات ECS.

في NLog، توفّر الحزمة Elastic.Apm.NLog العلامتين ${ElasticApmTraceId} و${ElasticApmTransactionId}، ويضعهما EcsLayout في مخرجات ECS. وخارج أي معاملة تبقى هاتان العلامتان فارغتين.
الخطوة 3: استيعاب السجلات في Elasticsearch
تُكتب سجلات JSON ECS على الخرج القياسي أو في ملف، ثم يجمعها Filebeat أو Elastic Agent. تطلب صفحة Node.js إرسال السجلات إلى نسخة Elasticsearch نفسها التي توجد فيها بيانات APM. وتؤكد صفحة .NET أن Filebeat يتيح إرسال السجلات وربط التتبعات بالسجلات والانتقال من APM إلى استكشاف السجلات.
تفاصيل تثبيت Filebeat (الملفات، Kubernetes، Docker) تتعلق ببيئتك وترد في وثائق مكتبة ECS؛ وتوضح صفحة Pino أن Filebeat غير متاح على Elastic Cloud Serverless. لا تفصّل هذه المقالة ذلك، لأننا لم نتحقق منه في كل حالة.
كيف تتحقق من أن الربط يعمل
- أرسل طلبًا إلى الخدمة المزوّدة بالأجهزة، ثم اقرأ سطر السجل الخام: يجب أن يحتوي على
trace.idوtransaction.id. - في Kibana، افتح الخدمة في Observability ثم تبويب Logs. وفق الوثائق، يمكنك القفز من سجل مرتبط إلى تتبعه، وتُحفظ مرشّحات البيئة والاستعلام والفترة الزمنية.
- في Log Events، ابحث عن
trace.idصادر من معاملة فاشلة، ثم اختر Open logs in Discover لتوسيع الاستعلام.
يستعلم تبويب Logs عن الفهارس المحددة في الإعداد المتقدم observability:logSources؛ وتتطلب الفهارس المخصصة إعدادًا إضافيًا.
إذا لم يكن في السطر الخام معرّف، فارجع إلى الخلف: وكيل بدأ متأخرًا، أو لا مُثرٍ (enricher)، أو خارج معاملة. وإذا كان فيه معرّف ولا يعرض Kibana شيئًا، فتحقق من الاستيعاب والفهارس.
وماذا عن OpenTelemetry وDynatrace؟
تسرد وثائق Elastic أيضًا أدلة ربط لحزم SDK الخاصة بـ OpenTelemetry من Elastic (Java و.NET وNode.js وPHP وPython)؛ لم نفتحها واحدًا واحدًا. المبدأ نفسه: يحمل السجل معرّف التتبع ومعرّف span للسياق النشط. لفهم دور كل إشارة اقرأ الرصد والمراقبة؛ ولتوجيه السجلات والتتبعات عبر Collector انظر Collector على Kubernetes.
لمقارنة Elastic بمزوّد آخر، راجع مقارنة Dynatrace وDatadog، ولتقليل حجم التتبعات المحفوظة راجع أخذ العيّنات المتأخر (tail sampling) مع OpenTelemetry. لا نزعم وجود أي تكامل بين Elastic APM وDynatrace.
ممارسات جيدة
- شغّل الوكيل قبل أي وحدة أخرى، وإلا أفلتت بعض الطلبات من الأجهزة.
- سجّل بصيغة JSON ECS بدل نص يجب تحليله: فالصيغة تتحدد عند الكتابة.
- لا تضع أبدًا بيانات شخصية أو رموزًا في رسائل السجل.
- اختبر الربط في خط التسليم لديك: سجل بلا
trace.idعلى مسار حرج عيب يجب إصلاحه.
الأسئلة الشائعة
ما الحقول المطلوبة في السجل لربطه بتتبع؟
وفق وثائق Elastic الخاصة بـ Node.js، الحقل trace.id مع transaction.id أو span.id.
لماذا لا يحمل بعض السجلات trace.id؟
لا يوجد المعرّف إلا أثناء معاملة أو span نشط؛ وخارج هذا السياق تعيد apm.currentTraceIds كائنًا فارغًا. لذلك لا يحمل السجل المكتوب عند الإقلاع أو من مهمة خلفية أي معرّف.
هل يلزم Filebeat للربط؟
يلزم وسيلة لاستيعاب السجلات في Elasticsearch نفسه الذي يضم APM. تذكر الوثائق Filebeat وElastic Agent؛ أما الإرسال المباشر من الوكيل فموثّق لـ Java فقط.
الخلاصة
تكفي ثلاث خطوات: وكيل نشط، ومنسّق يكتب trace.id في كل سجل، واستيعاب نحو المجموعة الصحيحة. يظهر المكسب عند أول عطل: تتبع بطيء يقود إلى سجلاته بنقرة واحدة.
المصادر
- Log correlation، وكيل Node.js، وثائق Elastic
- Agent API لـ Node.js، وثائق Elastic
- Stream application logs، وثائق Elastic
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا لشركة Elastic N.V.. Dynatrace علامة تجارية لشركة Dynatrace LLC. العلامات المذكورة تعود إلى مالكيها؛ والقيم مأخوذة من وثائق Elastic: تحقق دائمًا من القيم في الوثائق الرسمية الخاصة بإصدارك.