سجلات OpenTelemetry في Dynatrace: الربط بين السجلات والتتبعات عبر trace_id

سجلات OpenTelemetry في Dynatrace: يربطها بالتتبعات عبر trace_id. التصدير من SDK أو Collector، ثم التحقق من الربط بـ DQL.
Logs OpenTelemetry : Dynatrace et la corrélation logs-traces par trace_id

يصلك تنبيه: يرتفع معدل الأخطاء في خدمة. تجد التتبع البطيء، ثم تبحث يدويًا عن السجلات المقابلة له بالطابع الزمني، في ثلاثة pods مختلفة. مع سجلات OpenTelemetry في Dynatrace تختفي هذه الخطوة بفضل trace_id: من التتبع تفتح مباشرة أسطر السجل التي أنتجها.

هدف هذا الدرس التطبيقي: جعل كل سجل يحمل سياق التتبع (trace_id وspan_id) عبر مسارين — OpenTelemetry SDK الذي يصدّر السجلات بـ OTLP، وCollector الذي يقرأ ملفات سجلات موجودة —، ثم التحقق من الربط. يستهدف المحتوى Dynatrace SaaS (سجلات على Grail)؛ أما في Dynatrace Managed فاستيعاب سجلات OTLP موجود أيضًا، لكن تحقق من الحد الأدنى للإصدار والشاشات المتاحة في وثائق عنقودك.

يكمل هذا الموضوع Collector الخاص بـ OpenTelemetry نحو Dynatrace ونشره على Kubernetes.

المتطلبات

  • رمز API مميّز بالنطاق logs.ingest (وopenTelemetryTrace.ingest للتتبعات).
  • تطبيق متتبَّع أصلًا بـ OpenTelemetry. يستخدم المثال Python 3.10+؛ والمبدأ نفسه في Java وGo و.NET.
  • لجزء الملفات: Collector من نوع contrib (المستقبِل filelog، وقد أصبح اسمه file_log في الإصدارات الحديثة؛ ويبقى الاسم القديم مقبولًا كاسم بديل مهجور).
  • نقطة OTLP: https://<env-id>.live.dynatrace.com/api/v2/otlp (SaaS) أو https://<votre-domaine>/e/<env-id>/api/v2/otlp (Managed).

سجلات OpenTelemetry في Dynatrace والربط عبر trace_id

سجل OpenTelemetry هو تسجيل مهيكل. وينص نموذج البيانات على حقلين مخصصين، TraceId وSpanId. وحين يصدر السجل داخل span نشط يملؤهما SDK تلقائيًا. فيخزّن Dynatrace هذين المعرّفين مع السجل، مما يتيح الانتقال من التتبع إلى السجل وبالعكس. وبدون هذين الحقلين يعتمد الربط على الوقت، ولا يصمد تحت الحمل.

تذكّر: السجل ليس span. لا تصدر أحداث span بدلًا من السجلات، ولا العكس.

المسار 1: تصدير سجلات OpenTelemetry إلى Dynatrace من SDK

الخطوة 1: تثبيت الحزم

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

الخطوة 2: ربط معالج السجلات

import logging
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry._logs import set_logger_provider
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

resource = Resource.create({"service.name": "checkout"})

tp = TracerProvider(resource=resource)
tp.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(tp)

lp = LoggerProvider(resource=resource)
lp.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
set_logger_provider(lp)

logging.getLogger().addHandler(LoggingHandler(level=logging.INFO, logger_provider=lp))
logging.getLogger().setLevel(logging.INFO)

tracer = trace.get_tracer("checkout")
log = logging.getLogger("checkout")

with tracer.start_as_current_span("payer-commande"):
    log.warning("paiement refusé", extra={"order.id": "A-1042"})

الأسطر الحرجة:

  • الـ Resource نفسه للتتبعات والسجلات: وبذلك يربط Dynatrace الاثنين بالخدمة نفسها.
  • يحوّل LoggingHandler كل تسجيل من logging إلى سجل OpenTelemetry، مع trace_id الخاص بالـ span النشط.
  • تحمل الوحدات _logs شرطة سفلية: فواجهة السجلات في Python SDK ما زالت موسومة بأنها تجريبية. وابتداءً من opentelemetry-sdk 1.40 صار LoggingHandler مهجورًا لصالح الحزمة opentelemetry-instrumentation-logging (LoggingInstrumentor)؛ وما زالت الشيفرة أعلاه تعمل، لكن ثبّت إصداراتك وخطط للترحيل.
  • يصبح extra سمات للسجل: أبقِ المفاتيح ثابتة وقليلة.

الخطوة 3: ضبط التصدير بمتغيرات البيئة

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<env-id>.live.dynatrace.com/api/v2/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20dt0c01.XXXX"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

المسافة بعد Api-Token مرمَّزة بـ %20. وتضيف المصدّرات بنفسها /v1/traces و/v1/logs إلى النقطة. وفي الإنتاج وجّه بدلًا من ذلك إلى Collector محلي.

المسار 2: قراءة ملفات السجلات بواسطة Collector

تكتب تطبيقات كثيرة سجلات JSON على الخرج القياسي أصلًا. وإن كانت تتضمن فيها trace_id (مثلًا عبر قياس logging الذي يضيف otelTraceID إلى التنسيق) فيستطيع Collector ترقيته إلى حقل تتبع.

receivers:
  filelog:
    include: [/var/log/pods/*/*/*.log]
    include_file_path: true
    operators:
      - type: container          # retire l'enveloppe du runtime
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: trace_parser
        trace_id:
          parse_from: attributes.trace_id
        span_id:
          parse_from: attributes.span_id

processors:
  batch: {}

exporters:
  otlphttp/dynatrace:
    endpoint: ${env:DT_ENDPOINT}
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"

service:
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/dynatrace]
  • container: يتعرف العامل (operator) على تنسيقي CRI وDocker. وفي إصدارات Collector القديمة لا وجود له؛ فاستخدم عندئذ عوامل التحليل الموصوفة في وثائق المستقبِل.
  • trace_parser: ينسخ السمة إلى حقلي TraceId/SpanId في نموذج OTel. وهذا ما يجعل الربط أصليًا.
  • كيّف attributes.trace_id مع الاسم الحقيقي للحقل في سجلاتك (traceId أو otelTraceID…).

في Kubernetes أضف k8sattributes لاستعادة الـ pod والـ namespace. وإن فضّلت تحويل السجلات من جهة Dynatrace فإن استيعاب السجلات بخدمة ذاتية وOpenPipeline يقدمان بديلًا.

كيف تتحقق من أن كل شيء يعمل

  1. من جهة Collector ابحث عن أخطاء التصدير:
    kubectl -n observability logs ds/otel-node-opentelemetry-collector | grep -iE "logs|error|401|413"

    يدل 413 على دفعة كبيرة جدًا: قلّل send_batch_size.

  2. في SaaS، في Notebook:
    fetch logs, from: now() - 30m
    | filter isNotNull(trace_id)
    | summarize logs = count(), by: {service.name, loglevel}

    قد يختلف الاسم الدقيق لحقول التتبع في السجلات بحسب المصدر؛ افحص سجلًا بـ fetch logs | limit 1 قبل التصفية.

  3. خذ trace_id وجدته، ثم:
    fetch spans, from: now() - 30m
    | filter trace.id == "<trace_id>"
    | fields start_time, span.name, duration

    إن ظهر التتبع والسجلات بالمعرّف نفسه فالربط قائم. وفي الواجهة يجب أن يقترح عرض التتبع السجلات المرتبطة به أيضًا.

  4. في Managed افتح عارض السجلات، وصفِّ على الخدمة وتحقق من أن السجل يعرض رابطًا إلى التتبع. يعتمد الموضع الدقيق على الإصدار: راجع docs.dynatrace.com.

أفضل الممارسات

  • مسار واحد لكل سجل: إن كان التطبيق يصدّر بـ OTLP فلا تقرأ ملفه أيضًا، وإلا وصل كل سطر مرتين.
  • مستوى INFO كحد أدنى في الإنتاج: فحجم السجلات هو غالبًا أول بند في التكلفة.
  • لا بيانات شخصية في المتن أو السمات؛ أخفها في Collector أو في OpenPipeline.
  • سجلات مهيكلة: يُحلَّل JSON الثابت مرة واحدة وينهي الأمر، ويقلل الجهد المتكرر (toil).
  • أخذ عيّنات متسق: إن أخذت عيّنات من التتبعات فستشير بعض السجلات إلى تتبع غائب. هذا طبيعي؛ فاحتفظ بكل سجلات الأخطاء.

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

هل ينجز OneAgent هذا الربط أصلًا؟

بالنسبة إلى التقنيات التي يقيسها يستطيع OneAgent إثراء السجلات بسياق التتبع. ويفيد مسار OpenTelemetry حين لا يكون OneAgent موجودًا أو حين توحّد معيارك على OTel.

لماذا تصل سجلاتي بلا trace_id؟

صدر السجل خارج span نشط (بدء التشغيل أو مهمة خلفية)، أو لم يجد التحليل الحقل. تحقق من اسم الحقل وسياق التنفيذ.

هل أرسل السجلات بـ gRPC أم بـ HTTP؟

تقبل واجهة OTLP في Dynatrace بروتوكول HTTP مع protobuf. استخدم otlphttp نحو Dynatrace؛ ويبقى gRPC ممكنًا بين تطبيقاتك وCollector.

الخلاصة

سجلات OpenTelemetry التي تحمل trace_id توفر دقائق ثمينة في كل حادثة: يُظهر التتبع أين، ويشرح السجل لماذا. ابدأ بخدمة حرجة واحدة، وتحقق من الربط بـ DQL، ثم وسّع إلى بقية أحمالك. وللخطوة التالية اربط هذه الإشارات بأهدافك مع SLO لـ OpenTelemetry بـ DQL.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. تتطور الحقول والشاشات: تحقق منها في الوثائق الرسمية.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Collector OpenTelemetry Kubernetes vers Dynatrace : Helm, Operator et k8sattributes

Collector الخاص بـ OpenTelemetry على Kubernetes إلى Dynatrace: Helm وOperator وk8sattributes

Next Post
Propagation contexte Kafka : des traces W3C de bout en bout dans Dynatrace

نشر السياق في Kafka: تتبعات W3C من البداية إلى النهاية في Dynatrace

Related Posts