يمر طلب شراء عبر الـ API، ثم يُرسل إلى موضوع (topic) في Kafka، ثم يعالجه مستهلك (consumer) بعد ثانيتين. في Dynatrace ترى تتبعين غير مترابطين: استدعاء HTTP من جهة ومعالجته من جهة أخرى. غياب نشر السياق في Kafka يضيع وقت فريق المناوبة في لصق القطع يدويًا أثناء الحادثة.
هدف هذا الدرس التطبيقي: جعل سياق W3C Trace Context (الترويس traceparent) ينتقل ضمن ترويسات رسائل Kafka، للحصول على تتبع واحد من المنتِج (producer) إلى المستهلك في Dynatrace. المحتوى صالح لـ Dynatrace SaaS ولـ Dynatrace Managed في ما يخص استيعاب OTLP؛ أما استعلامات DQL للتحقق فتفترض بيئة SaaS على Grail.
إذا لم تصل التتبعات إلى Dynatrace أصلًا، فابدأ بـ تشخيص التتبعات المفقودة من OpenTelemetry ثم عد إلى هنا.
المشكلة: تتبع مقطوع إلى نصفين
في HTTP يكون النشر بديهيًا: يضيف العميل traceparent إلى ترويسات الطلب ويقرؤه الخادم. أما مع Kafka فلا يوجد طلب مباشر. يكتب المنتِج رسالة، ويخزنها الوسيط (broker)، ويقرؤها المستهلك لاحقًا. وإذا لم يكتب أحد السياق في الرسالة، بدأ المستهلك تتبعًا جديدًا.
النتيجة على صعيد SRE: لا يمكن قياس الزمن الكلي للطلب، ويستحيل حساب مؤشر SLI لزمن الاستجابة «طلب معالَج»، ويزداد MTTR لأن الربط يتم بالطابع الزمني.
نشر السياق في Kafka: كيف يعمل
منذ Kafka 0.11 يمكن لكل رسالة (record) أن تحمل ترويسات من نوع مفتاح-قيمة. المبدأ بسيط:
- من جهة المنتِج يُنشأ span من نوع
PRODUCERويكتب مُنشِر W3C (propagator) الترويسtraceparent(وtracestateإن وُجد) في ترويسات الرسالة. - من جهة المستهلك يقرأ المُنشِر هذه الترويسات ويعيد بناء السياق ويبدأ span من نوع
CONSUMERمرتبطًا بالتتبع نفسه (كابن أو عبر رابط span، بحسب القياس البرمجي).
تتبع السمات المفيدة اصطلاحات الدلالات (semantic conventions) الخاصة بالمراسلة في OpenTelemetry: messaging.system = kafka، وmessaging.destination.name = اسم الموضوع، وmessaging.operation.type (publish وprocess…، وهي تحل محل messaging.operation القديمة المُهمَلة). تحقق من الأسماء السارية في اصطلاحات دلالات Kafka في OpenTelemetry.
المتطلبات
- خدمات منتِج ومستهلك مقيسة بـ OpenTelemetry (وكيل Java أو Python SDK وغيرها) أو بـ OneAgent.
- تصدير OTLP إلى Dynatrace، مباشرًا أو عبر Collector: انظر Collector من OpenTelemetry لـ Dynatrace.
- رمز API بالنطاق
openTelemetryTrace.ingest(في SaaS وManaged). - وسطاء Kafka بإصدار 0.11 أو أحدث (ترويسات الرسائل).
الخطوة 1 — Java: دع وكيل OpenTelemetry يحقن السياق
يقيس وكيل OpenTelemetry لـ Java عملاء kafka-clients دون تعديل الشيفرة. يحقن traceparent عند الإرسال ويستخرجه عند الاستقبال. يكفي الإعداد الأساسي:
export OTEL_SERVICE_NAME=order-api
export OTEL_PROPAGATORS=tracecontext,baggage
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<environment-id>.live.dynatrace.com/api/v2/otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20${DT_API_TOKEN}"
java -javaagent:opentelemetry-javaagent.jar -jar order-api.jar
أسطر حاسمة: يجب أن يتضمن OTEL_PROPAGATORS القيمة tracecontext في الجهتين، وإلا لم يفهم المستهلك الترويس. في Managed يأخذ عنوان OTLP الشكل https://<cluster>/e/<environment-id>/api/v2/otlp. تفاصيل الوكيل في وكيل OpenTelemetry لـ Java مع Dynatrace.
نقطة انتباه: بحسب إصدار الوكيل وخياراته المتعلقة ببيانات الاستقبال (receive)، يكون span المعالجة ابنًا لـ span المنتِج أو span مرتبطًا به. يظهر الاثنان في العرض الموزّع نفسه في Dynatrace إذا حُفظ الرابط، لكن طريقة العرض تختلف. راجع ملف README الخاص بالقياس البرمجي لـ Kafka في إصدارك.
الخطوة 2 — Python: انشر السياق يدويًا
مع confluent-kafka يوجد قياس تلقائي لكنه جزئي بحسب الإصدارات. النشر اليدوي قصير وصريح:
from opentelemetry import trace, propagate
from opentelemetry.trace import SpanKind
tracer = trace.get_tracer("order-api")
def send_order(producer, payload: bytes):
with tracer.start_as_current_span("orders publish", kind=SpanKind.PRODUCER) as span:
span.set_attribute("messaging.system", "kafka")
span.set_attribute("messaging.destination.name", "orders")
carrier = {}
propagate.inject(carrier) # writes traceparent (and tracestate)
producer.produce("orders", value=payload, headers=list(carrier.items()))
من جهة المستهلك نقرأ الترويسات (بايتات) ونعيد بناء السياق:
def handle(msg):
carrier = {k: v.decode("utf-8") for k, v in (msg.headers() or []) if v is not None}
ctx = propagate.extract(carrier)
with tracer.start_as_current_span("orders process", context=ctx, kind=SpanKind.CONSUMER) as span:
span.set_attribute("messaging.system", "kafka")
span.set_attribute("messaging.destination.name", "orders")
process(msg.value())
السطر الحاسم: context=ctx. من دونه يصبح span المستهلك جذر تتبع جديد. المُنشِر الافتراضي في Python SDK هو tracecontext,baggage.
الخطوة 3 — حالة مختلطة بين OneAgent وOpenTelemetry
إذا كان المنتِج مراقَبًا بـ OneAgent والمستهلك بـ OpenTelemetry (أو العكس)، فيجب أن يتحدث الاثنان W3C Trace Context. يدعم OneAgent هذا المعيار، لكن النشر عبر المراسلة يتوقف على التقنية والإصدار: راجع صفحة Kafka في وثائق OneAgent على docs.dynatrace.com. وتجنب كذلك قياس العميل نفسه مرتين: فهذا هو المصدر الكلاسيكي لـ تكرار وحدات span بين OneAgent وOpenTelemetry.
الخطوة 4 — لا تكسر السياق في الطريق
- Kafka Streams وMirrorMaker والموصِّلات (connectors): قد يفقد المكوّن الذي ينسخ رسالة الترويسات أو يحتفظ بها. اختبر كل قفزة.
- المعالجة على دفعات: يعيد استدعاء poll واحد عدة رسائل من تتبعات مختلفة. أنشئ span لكل رسالة، أو span للدفعة مع روابط إلى كل سياق.
- أخذ العيّنات: مع مُعيِّن عيّنات
parentbased_*يتبع المستهلك قرار المنتِج. يؤدي اختلاف أخذ العيّنات بين الجهتين إلى تتبعات ناقصة.
كيف تتحقق من أن كل شيء يعمل
أولًا، اطلع على رسالة خام: kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic orders --property print.headers=true --from-beginning --max-messages 1. يجب أن ترى traceparent:00-<trace-id>-<span-id>-01.
ثم، في Dynatrace SaaS، افتح Notebook وعُدّ التتبعات التي تحتوي على span للمنتِج وspan للمستهلك معًا:
fetch spans, from: now() - 1h
| filter messaging.system == "kafka"
| summarize kinds = collectDistinct(span.kind), services = collectDistinct(service.name), by: { trace.id }
| filter arraySize(kinds) >= 2
| limit 20
إذا لم يُرجع الاستعلام شيئًا مع أن الخدمتين ترسلان وحدات span، فقد ضاع السياق بينهما. قد تختلف القيم الدقيقة لـ span.kind وأسماء الحقول: تحقق منها أولًا بالاستعلام fetch spans | limit 10. في Managed افتح PurePath لخدمة المستهلك في عرض التتبعات الموزّعة وتحقق من ظهور خدمة المنتِج في المنبع.
أفضل الممارسات
- صيغة نشر واحدة في السلسلة كلها:
tracecontext. أزل الصيغ الخاصة بالمصنّعين متى أمكن. - سمِّ وحدات span بالصيغتين «
<topic> publish» و«<topic> process»: يبقى البحث مقروءًا. - قِس التأخير بين الإنتاج والمعالجة: فهو غالبًا أفضل مؤشر SLI لخط معالجة غير متزامن.
- لا تضع بيانات شخصية في
baggage: فهو ينتقل في كل رسالة.
الأسئلة الشائعة
هل يجب تعديل وسطاء Kafka؟
لا. تُنقل الترويسات كما هي عبر الوسيط. فقط عميلا المنتِج والمستهلك يشاركان في النشر.
لماذا يظهر المستهلك في تتبع منفصل رغم وجود الترويس؟
في الغالب لأن مُنشِر المستهلك ليس tracecontext، أو لأن السياق المستخرج لم يُمرَّر إلى span، أو لأن القياس البرمجي ينتج رابط span بدل علاقة أب-ابن. تحقق من هذه النقاط الثلاث بهذا الترتيب.
هل يعمل هذا مع Dynatrace Managed؟
نعم لاستيعاب تتبعات OTLP والعرض الموزّع. أما استعلامات DQL على fetch spans فتتطلب بيئة SaaS على Grail.
الخلاصة
تكفي بضعة أسطر من الإعداد ليبقى الطلب تتبعًا واحدًا من الـ API إلى المستهلك. تكسب زمن استجابة كليًا قابلًا للقياس وتحقيقات أقصر. الخطوة التالية: تحويل هذا التأخير إلى مؤشر SLI، كما في OpenTelemetry من البداية إلى النهاية.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. تتطور الميزات بسرعة: تحقق من توافرها في بيئتك وفي الوثائق الرسمية.