Importer des événements à l'aide de l'API d'importation de logs de Datadog

Utilisez l’interface de programmation d’application (API) d’ingestion de logs de Datadog pour envoyer des événements de log au format JSON directement dans Datadog Log Management. Vous pouvez ingérer des logs provenant d’applications cloud, de microservices ou de tout système générant des données de télémétrie. Une fois les logs ingérés, ils sont disponibles dans Log Explorer en quelques secondes. Vous pouvez les traiter, les acheminer et les archiver à l’aide des Log Pipelines.

Ce point de terminaison prend en charge l'ingestion en temps réel et à haut débit de charges utiles JSON structurées et semi-structurées.

Actions prises en charge par cette API

Envoyez des logs directement depuis des applications cloud sans installer l'agent Datadog.
Appliquer des processeurs de pipeline, tels que le parseur Grok, le remappeur et le processeur de recherche, aux données entrantes.
Acheminer les journaux vers des index, des archives ou des destinations d'alerte en fonction de leur contenu.
Réduisez les coûts d'indexation en associant ce point de terminaison à des règles d'échantillonnage et de filtrage.

Remarque

Pour plus d'informations sur la gestion des identifiants, consultez la page API Datadog et clés d'application.

Avant de commencer

Assurez-vous d'avoir :

Une clé API Datadog disposant des autorisations nécessaires pour l'ingestion des journaux. Vous la trouverez dans Paramètres de l'organisation → Clés API.
L'adresse de votre site Datadog. Cette adresse varie selon la région :

Région Adresse du site
États-Unis (Est) datadoghq.com
US3 (ouest) us3.datadoghq.com
US5 (centre) us5.datadoghq.com
UE (Europe) datadoghq.eu
AP1 (Japon) ap1.datadoghq.com
AP2 (Australie) ap2.datadoghq.com
curl ou Postman doit être installé.
Données de journal au format JSON.

Région	Adresse du site
États-Unis (Est)	`datadoghq.com`
US3 (ouest)	`us3.datadoghq.com`
US5 (centre)	`us5.datadoghq.com`
UE (Europe)	`datadoghq.eu`
AP1 (Japon)	`ap1.datadoghq.com`
AP2 (Australie)	`ap2.datadoghq.com`

Présentation du pipeline

Mermaid (schéma/image)
Mermaid (code)
ASCII

Pipeline d'ingestion des logs Datadog

flowchart LR
    A[Application cloud<br/>ou microservice] -->|POST /api/v2/logs| B[API d'ingestion de logs Datadog<br/>]
    B --> C[Pipeline de logs<br/>• Analyseur Grok<br/>• Remappeur<br/>• Processeur de recherche]
    C --> D[Moteur de routage<br/>• Filtres<br/>• Index<br/>• Règles d'échantillonnage]
    D --> E{{Destinations<br/>Explorateur de logs · S3 · SIEM · Alertes}}

ASCII diagram
[Application cloud ]    POST /api/v2/logs     [API d'ingestion ]
 [ou microservice   ]   --------------------> [de logs Datadog ]
                                                       |
                                                       v
                                               [Pipeline de logs]
                                              (Grok, Remappeur,
                                                  Recherche)
                                                       |
                                                       v
                                               [Moteur de routage]
                                                (Filtres, Index,
                                                      Règles)
                                                       |
                                                       v
                                                  { Destinations }
                                                 (Explorateur, S3,
                                                  SIEM, Alertes)

Point de terminaison d'ingestion

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

Remplacez {dd_site} par l'adresse du site correspondant à votre région, par exemple datadoghq.com ou ap2.datadoghq.com.

En-têtes de requête

En-tête	Valeur	Obligatoire	Description
`DD-API-KEY`	`<your_api_key>`	Oui	Votre clé API Datadog
`Content-Type`	`application/json`	Oui	Format de la charge utile
`Content-Encoding`	`gzip`	Facultatif	Format de données utiles compressées (recommandé pour les lots volumineux)

Corps de la requête

Le corps de la requête est un tableau JSON contenant un ou plusieurs objets de journal. Chaque objet de journal comporte les champs suivants :

Champ	Type	Obligatoire	Description
`message`	string	Oui	Le corps du message de journalisation
`ddsource`	string	Recommandé	La technologie à l'origine du fichier journal, par exemple `python` ou `nginx`.
`ddtags`	string	Facultatif	Des balises séparées par des virgules, par exemple : `env:prod,team:payments`.
`hostname`	string	Facultatif	Le nom de l'hôte à l'origine du fichier journal
`service`	string	Recommandé	Le nom de l'application ou du service

Remarque

Vous devez inclure le champ message. Tous les autres champs sont facultatifs, mais Datadog recommande de les renseigner. Datadog utilise les champs service, ddsource et ddtags pour le filtrage, la facettisation et la correspondance avec les pipelines.

Exemple de charge utile

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"
  }
]

Remarque

L’horodatage (timestamp) doit respecter le format ISO 8601 (Organisation internationale de normalisation) correspondant au temps universel coordonné (UTC). Datadog utilise ce format pour l’alignement des chronologies dans Log Explorer. Datadog indexe les logs envoyés sans horodatage en utilisant l’heure d’ingestion.

Exemple avec 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"
    }
  ]'

Codes de réponse

Code	Status	Description
`202`	Accepted	Données acceptées et mises en file d'attente pour l'indexation
`400`	Bad request	Erreur de mise en forme ou de validation
`401` / `403`	Unauthorized / Forbidden	Clé API manquante (`401`) ou clé non valide / autorisations insuffisantes (`403`)
`413`	Payload too large	La taille des données dépasse 5 Mo sans compression (50 Mo avec gzip)
`429`	Too many requests	Limite de débit d'ingestion dépassée

202 acceptés

Une réponse « 202 Accepted » confirme que Datadog a bien reçu la charge utile. Le corps de cette réponse est vide. Les événements de journalisation apparaissent dans Log Explorer en quelques secondes.

Response: 202 Accepted
HTTP/1.1 202 Accepted

400 requête incorrecte

Datadog renvoie ce code lorsqu'une charge utile présente des erreurs de formatage ou de validation :

Syntaxe JSON incorrecte ou caractères non échappés.
Le champ obligatoire « message » est manquant.
La charge utile non compressée dépasse la limite de 5 Mo.

Response: 400 Bad Request
{
  "errors": ["Invalid JSON"]
}

401 « non autorisé » et 403 « interdit »

Datadog renvoie le code d'erreur 401 Unauthorized si l'en-tête DD-API-KEY est manquant. Datadog renvoie le code d'erreur 403 Forbidden si la clé API n'est pas valide ou ne dispose pas des autorisations nécessaires pour l'ingestion des logs :

Response: 403 Forbidden
{
  "errors": ["Forbidden"]
}

413 : charge utile trop volumineuse

Datadog renvoie ce code lorsque la charge utile de la requête dépasse la limite de taille maximale : 5 Mo pour les données JSON non compressées ou 50 Mo pour les données compressées au format gzip.

Response: 413 Payload Too Large
{
  "errors": ["Payload too large"]
}

429 : trop de requêtes

Le client a dépassé la limite de fréquence des requêtes. Réduisez la fréquence des requêtes ou regroupez les objets de journalisation dans une charge utile de type tableau.

Regroupement de plusieurs événements de journalisation

Vous pouvez envoyer jusqu'à 1 000 entrées de journal en une seule requête en transmettant un tableau. Datadog recommande cette approche pour les services à haut débit.

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"
  }
]

Limites :

Taille maximale de la charge utile : 5 Mo par requête non compressée (50 Mo lorsqu'elle est compressée avec gzip)
Taille maximale d'un fichier journal : 1 Mo
Nombre maximal d'entrées dans le tableau : 1 000 objets de journal

Cas d'utilisation courants

Importation des journaux provenant de microservices sans déployer l'agent Datadog.
Envoi d'événements JSON structurés à partir de fonctions sans serveur telles qu'Amazon Web Services (AWS) Lambda ou Google Cloud Run.
Diffusion en continu de données télémétriques provenant d'appareils IoT ou de services en périphérie.
Acheminement des événements enrichis vers un système de gestion des informations et des événements de sécurité (SIEM), vers S3 ou vers des destinations d'alerte via des pipelines de journaux.
Envoi des journaux provenant des pipelines d'intégration continue et de livraison continue (CI/CD) ou des scripts de déploiement.

Dépannage

Problème	Probable cause	Solution
`401 Unauthorized`	Clé API incorrecte ou manquante	Vérifiez la valeur de `DD_API_KEY` dans Paramètres de l'organisation → Clés API
`400 Bad Request`	JSON mal formé	Vérifiez le contenu à l'aide de la commande `jq . payload.json` avant l'envoi
Journal non disponible dans l'Explorateur	Filtre de pipeline excluant les journaux	Effacer les filtres ; vérifier les règles de routage de l'index
L'horodatage est incorrect	Format non UTC ou non conforme à la norme ISO 8601	Utilisez le format « 2025-11-15T08:30:00Z ».
`429 Too Many Requests`	Limite de requêtes dépassée	Batch log objects into a single array payload

Actions prises en charge par cette API​

Avant de commencer​

Présentation du pipeline​

Point de terminaison d'ingestion​

En-têtes de requête​

Corps de la requête​

Exemple de charge utile​

Exemple avec cURL​

Codes de réponse​

202 acceptés​

400 requête incorrecte​

401 « non autorisé » et 403 « interdit »​

413 : charge utile trop volumineuse​

429 : trop de requêtes​

Regroupement de plusieurs événements de journalisation​

Cas d'utilisation courants​

Dépannage​

Prochaines étapes​

Actions prises en charge par cette API

Avant de commencer

Présentation du pipeline

Point de terminaison d'ingestion

En-têtes de requête

Corps de la requête

Exemple de charge utile

Exemple avec cURL

Codes de réponse

202 acceptés

400 requête incorrecte

401 « non autorisé » et 403 « interdit »

413 : charge utile trop volumineuse

429 : trop de requêtes

Regroupement de plusieurs événements de journalisation

Cas d'utilisation courants

Dépannage

Prochaines étapes