استيعاب الأحداث باستخدام واجهة برمجة تطبيقات استيعاب السجلات (Log Ingestion API) من Datadog

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

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

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

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

ملاحظة

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

قبل أن تبدأ

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

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

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

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

• يجب أن يكون برنامج curl أو Postman مثبتًا.

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

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

Mermaid (صورة/image)

Mermaid (كود/code)

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

ASCII diagram

[تطبيق سحابي]      إرسال /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	نعم	تنسيق الحمولة
Content-Encoding	gzip	اختياري	تنسيق الحمولة المضغوطة (موصى به للدفعات ذات الحجم الكبير)

نص الطلب

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

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

ملاحظة

يجب عليك تضمين الحقل message. جميع الحقول الأخرى اختيارية، لكن Datadog توصي باستخدامها. تستخدم Datadog الحقول service وddsource وddtags لأغراض التصفية والتصنيف ومطابقة مسارات البيانات.

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

Payload: single log

[
  {
    "message": "Transaction failed: Gateway timeout",
    "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"
  }
]

ملاحظة

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

مثال على cURL

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": "Transaction failed: Gateway timeout",
      "ddsource": "payment-gateway",
      "ddtags": "env:prod,region:us-east-1",
      "hostname": "payments-host-01",
      "service": "payment-gateway",
      "level": "ERROR",
      "transaction_id": "txn_998877"
    }
  ]'

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

Code	Status	الوصف
202	Accepted	تم قبول الحمولة ووضعها في قائمة الانتظار للفهرسة
400	Bad request	خطأ في التنسيق أو التحقق من الصحة
401 / 403	Unauthorized / Forbidden	مفتاح API مفقود (401) أو مفتاح غير صالح / أذونات غير كافية (403)
413	Payload too large	تتجاوز الحمولة 5 ميغابايت دون ضغط (50 ميغابايت بتنسيق gzip)
429	Too many requests	تم تجاوز الحد الأقصى لمعدل الاستهلاك

تم قبول 202

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

Response: 202 Accepted

HTTP/1.1 202 Accepted

400 طلب غير صحيح

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

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

Response: 400 Bad Request

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

401 غير مصرح به و403 ممنوع

تُرجع Datadog الرمز 401 Unauthorized في حالة عدم وجود رأس DD-API-KEY. وتُرجع Datadog الرمز 403 Forbidden إذا كان مفتاح واجهة برمجة التطبيقات (API) غير صالح أو يفتقر إلى أذونات استيعاب السجلات:

Response: 403 Forbidden

{
  "errors": ["Forbidden"]
}

413 الحمولة أكبر من المسموح به

تُرجع Datadog هذا الرمز عندما تتجاوز حمولة الطلب الحد الأقصى للحجم: 5 ميغابايت لملفات JSON غير المضغوطة أو 50 ميغابايت للبيانات المضغوطة بواسطة gzip.

Response: 413 Payload Too Large

{
  "errors": ["Payload too large"]
}

429 طلبًا أكثر من اللازم

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

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

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

Payload: batched logs

[
  {
    "message": "User login succeeded",
    "service": "auth-service",
    "ddsource": "python",
    "ddtags": "env:prod",
    "level": "INFO"
  },
  {
    "message": "Transaction failed: Gateway timeout",
    "service": "payment-gateway",
    "ddsource": "python",
    "ddtags": "env:prod",
    "level": "ERROR",
    "transaction_id": "txn_998877"
  }
]

القيود:

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

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

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

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

الموضوع	سبب محتمل	الحل
401 Unauthorized	مفتاح API غير صحيح أو مفقود	تحقق من DD_API_KEY في إعدادات المؤسسة → مفاتيح API
400 Bad Request	تنسيق JSON غير صحيح	تحقق من صحة البيانات باستخدام jq . payload.json قبل الإرسال
السجل غير موجود في مستكشف الملفات	مرشح خط الأنابيب باستثناء جذع الشجرة	مسح عوامل التصفية؛ التحقق من قواعد توجيه الفهرس
الطابع الزمني غير صحيح	تنسيق غير متوافق مع التوقيت العالمي المنسق (UTC) أو مع معيار ISO 8601	استخدم التنسيق "2025-11-15T08:30:00Z".
429 Too Many Requests	تم تجاوز الحد الأقصى لعدد الطلبات	Batch log objects into a single array payload

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

• توجيه سجلات تطبيق السحابة إلى مسار معالجة
• إنشاء خادم وهمي باستخدام Postman
• نظرة عامة على قابلية المراقبة المتوازية
• تدفقات الأحداث وخطوط أنابيب القابلية للمراقبة
• دليل واجهة برمجة تطبيقات استيعاب السجلات في Datadog
• معالجات خط أنابيب السجلات