استيعاب الأحداث باستخدام واجهة برمجة تطبيقات استيعاب السجلات في Datadog

مقدمة

استخدم واجهة برمجة تطبيقات (API) استيعاب السجلات من Datadog لإرسال أحداث السجلات بتنسيق JSON من التطبيقات السحابية أو الخدمات الصغيرة أو أي نظام يصدر بيانات القياس عن بُعد مباشرةً إلى إدارة السجلات في Datadog. بمجرد استيعاب السجلات، تصبح متاحة في مستكشف السجلات في غضون ثوانٍ. يمكنك معالجتها وتوجيهها وأرشفتها باستخدام خطوط أنابيب السجلات.

تدعم نقطة النهاية هذه الاستيعاب عالي الإنتاجية وفي الوقت الفعلي لحمولات JSON المنظمة و شبه المنظمة.

الإجراءات التي تدعمها واجهة برمجة التطبيقات هذه

• إرسال السجلات مباشرةً من التطبيقات السحابية دون تثبيت وكيل Datadog.
• تطبيق معالجات خطوط الأنابيب، مثل Grok Parser وRemapper وLookup Processor، على البيانات الواردة.
• توجيه السجلات إلى الفهارس أو الأرشيفات أو وجهات التنبيهات بناءً على المحتوى.
• تقليل تكلفة الفهرسة من خلال الجمع بين نقطة النهاية هذه وقواعد أخذ العينات والتصفية.

ملاحظة

تعرف على المزيد حول واجهة برمجة تطبيقات Datadog ومفاتيح واجهة برمجة التطبيقات هنا.

قبل البدء

تأكد من توفر ما يلي:

• مفتاح واجهة برمجة تطبيقات Datadog مع أذونات استيعاب السجلات. يمكنك العثور عليه في إعدادات المؤسسة → مفاتيح واجهة برمجة التطبيقات.

• عنوان موقع Datadog الخاص بك. يختلف هذا العنوان حسب المنطقة:

  المنطقة	عنوان الموقع
  الولايات المتحدة (الشرق)	datadoghq.com
  الولايات المتحدة 3 (الغرب)	us3.datadoghq.com
  الولايات المتحدة 5 (الوسط)	us5.datadoghq.com
  الاتحاد الأوروبي (أوروبا)	datadoghq.eu
  AP1 (اليابان)	ap1.datadoghq.com
  AP2 (أستراليا)	ap2.datadoghq.com

• تثبيت curl أو Postman.

• حمولات سجلات بتنسيق JSON.

نظرة عامة على خط الأنابيب

صورة Mermaid

كود Mermaid

flowchart LR
    A[تطبيق سحابي<br/>أو خدمة صغيرة] -->|إرسال /api/v2/logs| B[واجهة برمجة تطبيقات<br/>استيعاب سجلات Datadog]
    B --> C[خط أنابيب السجلات<br/>• محلل Grok<br/>• أداة إعادة التعيين<br/>• معالج البحث]
    C --> D[محرك التوجيه<br/>• المرشحات<br/>• الفهارس<br/>• قواعد المعاينة]
    D --> E{{الوجهات<br/>مستكشف السجلات · S3 · SIEM · التنبيهات}}

ASCII

 [تطبيق سحابي]      إرسال /api/v2/logs    [واجهة برمجة]
 [أو خدمة صغيرة] ----------------------> [استيعاب السجلات]
                                               |
                                               v
                                        [خط أنابيب السجلات]
                                        (تحليل، إثراء، إخفاء)
                                               |
                                               v
                                        [محرك التوجيه]
                                        (مرشحات، فهارس)
                                               |
                                               v
                                        {    الوجهات    }
                                        (مستكشف، S3، SIEM)

نقطة نهاية الاستيعاب

POST https://http-intake.logs.{dd_site}/api/v2/logs

استبدل {dd_site} بعنوان موقع منطقتك، على سبيل المثال، datadoghq.com أو ap2.datadoghq.com.

رؤوس الطلب

الرأس	القيمة	مطلوب	الوصف
DD-API-KEY	<your_api_key>	نعم	مفتاح API Datadog الخاص بك
Content-Type	application/json	نعم	تنسيق الحمولة

نص الطلب

نص الطلب عبارة عن مصفوفة JSON تتكون من كائن سجل واحد أو أكثر. يدعم كل كائن سجل الحقول التالية:

الحقل	النوع	مطلوب	الوصف
message	سلسلة	نعم	نص رسالة السجل
ddsource	سلسلة	موصى به	التقنية التي ينشأ منها السجل، على سبيل المثال، python أو nginx.
ddtags	سلسلة	اختياري	علامات مفصولة بفواصل، على سبيل المثال، env:prod,team:payments.
hostname	سلسلة	اختياري	اسم المضيف الذي أنشأ السجل
service	سلسلة	موصى به	اسم التطبيق أو الخدمة
:::ملاحظة
يجب تضمين حقل message. جميع الحقول الأخرى اختيارية، لكن Datadog توصي بها. يستخدم Datadog الحقول service وddsource وddtags للتصفية والتصنيف ومطابقة مسار البيانات.
:::

مثال على الحمولة

[
  {
    "message": "فشل المعاملة: انتهت مهلة البوابة"،
    "ddsource": "payment-gateway"،
    "ddtags": "env:prod,region:us-east-1"،
    "hostname": "payments-host-01",
    "service": "payment-gateway",
    "timestamp": "2025-11-15T08:30:00Z",
    "transaction_id": "txn_998877",
    "customer_id": "cus_554433",
    "level": "ERROR"
  }
]

ملاحظة

يجب أن يستخدم timestamp تنسيق التوقيت العالمي المنسق (UTC) وفقًا للمنظمة الدولية للتوحيد القياسي (ISO) 8601. يستخدم Datadog هذا التنسيق لمواءمة الخط الزمني في Log Explorer. يقوم Datadog بفهرسة السجلات المرسلة بدون طابع زمني باستخدام وقت الاستلام.

رموز الاستجابة

202 accepted

يعني الرد 202 Accepted أن Datadog قد استلمت الحمولة. لا يحتوي هذا الرد على نص. يظهر السجل في Log Explorer في غضون بضع ثوانٍ.

HTTP/1.1 202 Accepted

400 طلب غير صحيح

تُرجع Datadog هذا الرمز عندما تحتوي الحمولة على أخطاء في التنسيق. الأسباب الشائعة:

• صيغة JSON غير صحيحة.
• الحقل message مفقود.
• الحمولة تتجاوز الحد الأقصى البالغ 5 ميغابايت.

{
  "errors": ["Invalid JSON"]
}

401 غير مصرح به

مفتاح API مفقود أو غير صحيح أو يفتقر إلى أذونات استيعاب السجلات.

{
  "errors": ["Forbidden"]
}

429 عدد الطلبات زائد

تجاوز النظام حد معدل الطلبات. قلل من تكرار الطلبات أو قم بتجميع كائنات السجلات في حمولة مصفوفة واحدة.

مثال Curl

export DD_API_KEY="your_datadog_api_key_here"
export DD_SITE="datadoghq.com"

curl -X POST "https://http-intake.logs.$DD_SITE/api/v2/logs" \
  -H "DD-API-KEY: $DD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
 "message": "فشل المعاملة: انتهت مهلة البوابة"،
 "ddsource": "payment-gateway"،
 "ddtags": "env:prod,region:us-east-1"،
 "hostname": "payments-host-01"،
      "service": "payment-gateway",
 "level": "ERROR",
 "transaction_id": "txn_998877"
    }
  ]'

تجميع أحداث السجلات المتعددة

يمكنك إرسال ما يصل إلى 1,000 إدخال سجل في طلب واحد عن طريق تمرير مصفوفة. توصي Datadog بهذه الطريقة للخدمات ذات الإنتاجية العالية.

[
  {
    "message": "نجح تسجيل دخول المستخدم"،
    "service": "auth-service"،
    "ddsource": "python"،
    "ddtags": "env:prod"،
    "level": "INFO"
  },
  {
    "message": "فشل المعاملة: انتهت مهلة البوابة"،
    "service": "payment-gateway"،
    "ddsource": "python"،
    "ddtags": "env:prod"،
    "level": "ERROR"،
    "transaction_id": "txn_998877"
  }
]

الحدود:

• الحد الأقصى لحجم الحمولة: 5 ميغابايت لكل طلب
• الحد الأقصى لحجم السجل الفردي: 1 ميغابايت
• الحد الأقصى لعدد إدخالات المصفوفة: 1,000 كائن سجل

حالات الاستخدام الشائعة

• استيعاب السجلات من الخدمات الصغيرة دون نشر وكيل Datadog.
• إرسال أحداث JSON منظمة من وظائف بدون خادم مثل Amazon Web Services (AWS) Lambda أو Google Cloud Platform (GCP) Cloud Run.
• بث بيانات القياس عن بُعد من أجهزة إنترنت الأشياء أو خدمات الحافة.
• توجيه الأحداث المُثريّة إلى إدارة المعلومات والأحداث الأمنية (SIEM) أو S3 أو وجهات التنبيه عبر خطوط أنابيب السجلات.
• إرسال السجلات من خطوط أنابيب التكامل المستمر والتسليم المستمر (CI/CD) أو نصوص النشر.

استكشاف الأخطاء وإصلاحها

المشكلة	السبب المحتمل	الحل
401 غير مصرح به	مفتاح API غير صحيح أو مفقود	تحقق من DD_API_KEY في إعدادات المؤسسة → مفاتيح API
400 طلب غير صحيح	JSON غير صحيح	تحقق من صحة البيانات باستخدام jq . payload.json قبل الإرسال
السجل غير موجود في Explorer	مرشح خط الأنابيب يستبعد السجل	امسح المرشحات؛ تحقق من قواعد توجيه الفهرس
الطابع الزمني غير صحيح	تنسيق غير UTC أو غير ISO 8601	استخدم تنسيق "2025-11-15T08:30:00Z"
429 Too Many Requests	تجاوز حد المعدل	تجميع كائنات السجلات في حمولة مصفوفة واحدة

الخطوات التالية

• مرجع واجهة برمجة تطبيقات استيعاب سجلات Datadog
• معالجات مسار السجلات
• توجيه سجلات تطبيقات السحابة باستخدام Datadog و Galileo
• إنشاء خادم Postman وهمي