تفشل مهمة دفعية ليلية، لكن سجلاتها تبقى على آلة افتراضية بلا 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.
- SaaS:
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:

في الإصدارات الحديثة من 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 يفقد سجلات بصمت؛ ولاكتشاف هذا النوع من الثغرات، راجع مراقبة استيعاب السجلات.
كيف تتحقق من أن الإعداد يعمل
- رمز إرجاع
curlهو204(أضف-w "%{http_code}\n"لعرضه). - في SaaS، داخل Notebook:
fetch logs, from: now() - 30m | filter service.name == "export-comptable" | fields timestamp, loglevel, content, log.source, service.namespace | sort timestamp desc - في Managed، افتح عارض السجلات، وصفِّ بالسمة
log.source، وتحقق من المستوى والطابع الزمني. - من جهة 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 والنطاقات والحدود، لذا تحقق منها في الوثائق الرسمية للواجهة.