Log ingestion API في Dynatrace: إرسال السجلات وإعادة توجيهها وإثراؤها

Log ingestion API في Dynatrace: أرسل سجلاتك بصيغة JSON أو نص، وأثرِها، ومرّرها عبر ActiveGate أو Collector، وعالج الأخطاء دون فقدان.
Log ingestion API Dynatrace : envoyer, transférer et enrichir vos logs

تفشل مهمة دفعية ليلية، لكن سجلاتها تبقى على آلة افتراضية بلا OneAgent. وفي اليوم التالي لا أحد يعرف لماذا لم يُرسَل التقرير. بالنسبة إلى هذه المصادر اليتيمة (نصوص برمجية وأجهزة جاهزة وحاويات من جهات خارجية ودوال مؤقتة)، تستقبل Log ingestion API في Dynatrace السجلات بصيغة JSON أو نص عبر طلب HTTP بسيط، ويمكن لأداة إعادة توجيه (forwarder) أن تتولى ذلك نيابة عنك.

الهدف: إرسال أول سجل بـ curl، وهيكلة الأحداث وإثراؤها، واختيار مسار إعادة التوجيه (ActiveGate أو OpenTelemetry Collector أو Fluent Bit)، ومعالجة الأخطاء بشكل صحيح. المحتوى صالح لـ Dynatrace SaaS وDynatrace Managed: يختلف عنوان endpoint وبعض الخيارات، وسنشير إليها في موضعها.

لجولة سريعة في معالجة السجلات بعد استيعابها، راجع وحدة التدريب عن السجلات وOpenPipeline.

ثلاث طرق لإرسال السجلات دون OneAgent

  • Log ingestion API (Log Monitoring API v2): endpoint من نوع REST يقبل JSON أو JSON lines أو نصًا خامًا. مثالي لنص برمجي أو تكامل داخلي أو shipper يجيد التخاطب عبر HTTP.
  • OTLP API: سجلات بصيغة OpenTelemetry، عبر OTLP/HTTP protobuf، وغالبًا من خلال OpenTelemetry Collector.
  • أدوات الشحن الموجودة: تذكر الوثائق OpenTelemetry Collector وFluent Bit وFluentd وLogstash، وكلها تعتمد على إحدى هاتين الواجهتين.

يركز هذا الدليل على الطريق الأول، ثم يوضح كيف تتولى أداة إعادة التوجيه المهمة.

المتطلبات المسبقة

  • رمز وصول كلاسيكي بالنطاق logs.ingest. في SaaS يعمل أيضًا platform token أو عميل OAuth بالنطاق openpipeline:logs:ingest (النطاق storage:logs:write موسوم بأنه legacy).
  • عنوان URL للـ endpoint:
    • SaaS: https://<env-id>.live.dynatrace.com/api/v2/logs/ingest؛
    • Managed: https://<votre-domaine>/e/<env-id>/api/v2/logs/ingest؛
    • Environment ActiveGate (SaaS أو Managed): https://<activegate>:9999/e/<env-id>/api/v2/logs/ingest.
  • curl للاختبار، ووصول شبكي صادر عبر المنفذ 443 (أو 9999 نحو ActiveGate).

هل لديك شك في النطاقات أو خطأ 401 مستمر؟ الطريقة موضحة في استكشاف أخطاء رمز API في Dynatrace.

استخدام Log ingestion API خطوة بخطوة

الخطوة 1: أرسل أول سجل

curl -X POST "https://<env-id>.live.dynatrace.com/api/v2/logs/ingest" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Api-Token $DT_API_TOKEN" \
  -d '[
    {
      "content": "Export comptable : échec de connexion à la base",
      "severity": "error",
      "log.source": "/opt/batch/export.log",
      "service.name": "export-comptable",
      "service.namespace": "finance"
    }
  ]'

الاستجابة 204 بلا جسم تعني أن كل شيء قُبل. النقاط المهمة:

  • Content-Type: صرّح بالنوع الدقيق وبترميز UTF-8. النوع text/plain لا يقبل إلا حدثًا واحدًا في الطلب؛ أما application/json فيقبل كائنًا أو مصفوفة.
  • content: نص السجل. وفي غيابه تبحث الواجهة عن message أو payload أو body أو log.
  • يصبح severity (أو status أو level) السمة loglevel؛ ويحدد timestamp (أو @timestamp أو time…) الطابع الزمني، بتوقيت UTC إن لم تُذكر منطقة زمنية. وإذا لم يُعرَف أي طابع زمني يُستخدم الوقت الحالي.

الخطوة 2: أرسل دفعات بصيغة JSON lines

لملف جاهز بصيغة كائن واحد في كل سطر، لا داعي لبناء مصفوفة. استخدم أحد أنواع JSON lines المقبولة (application/jsonl أو application/x-ndjson…):

curl -X POST "https://<env-id>.live.dynatrace.com/api/v2/logs/ingest" \
  -H "Content-Type: application/jsonl; charset=utf-8" \
  -H "Authorization: Api-Token $DT_API_TOKEN" \
  --data-binary @export-2026-10-10.jsonl

في SaaS، التزم بالحدود الموثقة لكل طلب: 10 ميغابايت من الحمولة و50 000 سجل على الأكثر. تُرفض الأحداث التي يسبق طابعها الزمني الوقت الحالي بأكثر من 24 ساعة: الاستجابة 400 إذا كانت كلها كذلك، و200 مع رسالة إذا كان جزء منها فقط كذلك.

الخطوة 3: أثرِ السجلات عند الإرسال

السجل بلا سياق مكلف في التشخيص. ثلاث وسائل، من الأبسط إلى الأكثر مركزية:

  • سمات داخل الحدث: service.name وservice.namespace وlog.source أو مفاتيح خاصة بنشاطك. بها يمكنك التصفية وربط السجل بخدمة.
  • الترويسة X-Dynatrace-Attr: أزواج مفتاح-قيمة تفصل بينها &، تُضاف إلى كل سجل في الطلب. عملية لأداة إعادة توجيه لا تستطيع تعديل الأحداث:
    -H "X-Dynatrace-Attr: deployment.environment=prod&team=finance"
  • OpenPipeline (SaaS): التحليل واستخراج الحقول والإخفاء من جهة Dynatrace، دون لمس المصادر. مع OpenPipeline، تحافظ الواجهة على أنواع JSON للسمات (إصدار SaaS أو ActiveGate 1.295 وما بعده)؛ وإلا تتحول كل القيم إلى سلاسل نصية. يُشرح الإخفاء في OpenPipeline والبيانات الحساسة.

في SaaS فقط، يحدد الوسيط structure (القيمتان raw أو flattened) كيف تتحول كائنات JSON المتداخلة إلى سمات.

الخطوة 4: أوكل الإرسال إلى أداة إعادة توجيه

عبر Environment ActiveGate. وحدة Log analytics collector مفعّلة فيه افتراضيًا. يستقبل ActiveGate الطلبات ويضعها في طابور على القرص ثم يمررها دفعات. يُضبط الطابور في custom.properties:

[generic_ingest]
disk_queue_path=<chemin-vers-un-disque-dédié>
disk_queue_max_size_mb=1024

الحجم الافتراضي 300 ميغابايت. إذا امتلأ الطابور، تعيد الواجهة 503 Usable space limit reached؛ ارفع disk_queue_max_size_mb إذا استمر الخطأ.

عبر OpenTelemetry Collector. يقرأ Collector ملفات السجلات بالمستقبِل file_log ويصدّرها بصيغة OTLP إلى /api/v2/otlp/v1/logs. يقدّم مستودع توزيعة Dynatrace من Collector (ترخيص Apache 2.0) مثالًا لـ pods في Kubernetes:

مقتطف من الملف k8s_pod_logs.yaml في مستودع dynatrace-otel-collector: المستقبِل file_log على /var/log/pods، والمصدِّر otlp_http مع الترويسة Api-Token، وخط المعالجة logs

في الإصدارات الحديثة من Collector، صار filelog يسمى file_log وصار otlphttp يسمى otlp_http؛ وتبقى الأسماء القديمة مقبولة كأسماء بديلة مهجورة.

عبر Fluent Bit. على Kubernetes، هو غالبًا الخيار الأخف: الشرح خطوة بخطوة في Fluent Bit إلى Dynatrace.

معالجة أخطاء Log ingestion API

الرمز المعنى الإجراء
204 استُوعب كل شيء لا شيء
200 استيعاب جزئي (أحداث غير صالحة) اقرأ جسم الاستجابة
400 مدخل غير صالح صحّح الحمولة، ولا تعد المحاولة
402 الترخيص أو ميزانية DPS مستنفدة راجع العقد
404 لا يوجد ActiveGate بوحدة Log analytics collector تحقق من ActiveGate
413 الحمولة أكبر من اللازم قلّل حجم الدفعات
429، 502، 503، 504 حمل زائد أو بوابة غير متاحة أعد المحاولة مع تراجع أسي (backoff)

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

كيف تتحقق من أن الإعداد يعمل

  1. رمز إرجاع curl هو 204 (أضف -w "%{http_code}\n" لعرضه).
  2. في SaaS، داخل Notebook:
    fetch logs, from: now() - 30m
    | filter service.name == "export-comptable"
    | fields timestamp, loglevel, content, log.source, service.namespace
    | sort timestamp desc
  3. في Managed، افتح عارض السجلات، وصفِّ بالسمة log.source، وتحقق من المستوى والطابع الزمني.
  4. من جهة ActiveGate، راقب أخطاء 503 في سجلات أداة إعادة التوجيه: تدل على طابور ممتلئ.

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

  • دائمًا طابع زمني من المصدر: وقت الاستلام يفسد التحليل بعد انقطاع الشبكة.
  • دفعات لا طلبًا لكل سطر: JSON lines ودفعات من بضع مئات من الأحداث تقلل الحمل وأخطاء 429.
  • رمز واحد لكل مصدر، مقصور على logs.ingest، لسحبه دون كسر كل شيء.
  • سمات ثابتة (service.name والبيئة والفريق) منذ الإرسال، بدل التحليل لاحقًا.
  • تراجع أسي في كل عميل داخلي، يُختبر بمحاكاة 503.

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

هل أفضّل Log ingestion API أم OTLP؟

لنص برمجي أو أداة تنتج JSON، واجهة السجلات هي الأبسط. وإن كان لديك Collector أو تطبيقات مزوّدة بالقياس عبر OpenTelemetry، فإن OTLP يحافظ على الارتباط بالتتبعات (راجع سجلات OpenTelemetry وtrace_id).

هل تعمل الواجهة على Dynatrace Managed؟

نعم، على العنوان https://<votre-domaine>/e/<env-id>/api/v2/logs/ingest أو عبر ActiveGate على المنفذ 9999، برمز logs.ingest. خيارات OpenPipeline والوسيط structure خاصة بـ SaaS.

لماذا تختفي أحداث مع الرمز 200؟

يدل الرمز 200 على استيعاب جزئي: بعض الأحداث كانت غير صالحة، مثل أن تكون قديمة جدًا. يوضح جسم الاستجابة عدد المرفوض منها.

الخلاصة

تسدّ Log ingestion API النقاط العمياء التي يتركها OneAgent: طلب HTTP ورمز logs.ingest، فتنضم سجلاتك إلى بقية الإشارات. هيكل الأحداث منذ الإرسال، وأوكل النقل إلى ActiveGate أو Collector أو Fluent Bit حين يكبر الحجم، وعالج الأخطاء القابلة لإعادة المحاولة. بذلك تقلل ثغرات التغطية ووقت التشخيص.

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

Total
0
Shares
Leave a Reply

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

Previous Post
Metadata enrichment Kubernetes dans Dynatrace : namespaceSelector, règles et annotations

Metadata enrichment Kubernetes في Dynatrace: namespaceSelector والقواعد والتعليقات

Next Post
OpenTelemetry Collector Contrib : quels composants choisir pour la production

OpenTelemetry Collector Contrib: أي المكوّنات تختار للإنتاج

Related Posts