Log ingestion API Dynatrace : envoyer, transférer et enrichir vos logs

Log ingestion API Dynatrace : envoyez vos logs en JSON ou texte, enrichissez-les, passez par ActiveGate ou un Collector et gérez les erreurs sans perte.
Log ingestion API Dynatrace : envoyer, transférer et enrichir vos logs

Un job batch nocturne échoue, mais ses logs restent sur une VM sans OneAgent. Le lendemain, personne ne sait pourquoi le rapport n’est pas parti. Pour ces sources orphelines (scripts, appliances, conteneurs tiers, fonctions éphémères), la Log ingestion API de Dynatrace reçoit des logs en JSON ou en texte par une simple requête HTTP, et un forwarder peut s’en charger à votre place.

Objectif : envoyer un premier log avec curl, structurer et enrichir les événements, choisir une voie de forwarding (ActiveGate, OpenTelemetry Collector, Fluent Bit) et gérer correctement les erreurs. Le contenu vaut pour Dynatrace SaaS et Dynatrace Managed : l’endpoint et quelques options diffèrent, signalés au fil du texte.

Pour un tour d’horizon du traitement des logs une fois ingérés, voir le module de formation sur les logs et OpenPipeline.

Trois façons d’envoyer des logs sans OneAgent

  • Log ingestion API (Log Monitoring API v2) : un endpoint REST qui accepte du JSON, des JSON lines ou du texte brut. Idéal pour un script, une intégration maison ou un shipper qui sait parler HTTP.
  • API OTLP : les logs au format OpenTelemetry, en OTLP/HTTP protobuf, le plus souvent via un OpenTelemetry Collector.
  • Shippers existants : la documentation cite l’OpenTelemetry Collector, Fluent Bit, Fluentd et Logstash, qui s’appuient sur l’une de ces deux API.

Ce guide se concentre sur la première voie, puis montre comment un forwarder prend le relais.

Prérequis

  • Un token d’accès classique avec le scope logs.ingest. En SaaS, un platform token ou un client OAuth avec le scope openpipeline:logs:ingest fonctionne aussi (le scope storage:logs:write est marqué legacy).
  • L’URL de l’endpoint :
    • SaaS : https://<env-id>.live.dynatrace.com/api/v2/logs/ingest ;
    • Managed : https://<votre-domaine>/e/<env-id>/api/v2/logs/ingest ;
    • ActiveGate d’environnement (SaaS ou Managed) : https://<activegate>:9999/e/<env-id>/api/v2/logs/ingest.
  • curl pour le test, et un accès réseau sortant en 443 (ou 9999 vers l’ActiveGate).

Un doute sur les scopes ou un 401 persistant ? La méthode est dans le dépannage d’un token d’API Dynatrace.

Utiliser la Log ingestion API pas à pas

Étape 1 : envoyer un premier log

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

Une réponse 204 sans corps signifie que tout a été accepté. Les points qui comptent :

  • Content-Type : déclarez le type exact et l’encodage UTF-8. text/plain n’accepte qu’un seul événement par requête ; application/json accepte un objet ou un tableau.
  • content : le texte du log. À défaut, l’API cherche message, payload, body ou log.
  • severity (ou status, level) devient l’attribut loglevel ; timestamp (ou @timestamp, time…) fixe l’horodatage, en UTC si aucun fuseau n’est indiqué. Sans horodatage reconnu, l’heure courante est utilisée.

Étape 2 : envoyer des lots en JSON lines

Pour un fichier déjà au format un-objet-par-ligne, inutile de construire un tableau. Utilisez l’un des types JSON lines acceptés (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

En SaaS, respectez les limites documentées par requête : 10 Mo de charge utile et 50 000 enregistrements au plus. Les événements dont l’horodatage est antérieur de plus de 24 heures sont rejetés : 400 si tous le sont, 200 avec un message si une partie seulement l’est.

Étape 3 : enrichir les logs à l’envoi

Un log sans contexte coûte cher en diagnostic. Trois leviers, du plus simple au plus central :

  • Attributs dans l’événement : service.name, service.namespace, log.source ou des clés métier. Ce sont eux qui permettront de filtrer et de rattacher le log à un service.
  • En-tête X-Dynatrace-Attr : des paires clé-valeur séparées par &, ajoutées à chaque enregistrement de la requête. Pratique pour un forwarder qui ne sait pas modifier les événements :
    -H "X-Dynatrace-Attr: deployment.environment=prod&team=finance"
  • OpenPipeline (SaaS) : parsing, extraction de champs et masquage côté Dynatrace, sans toucher aux sources. Avec OpenPipeline, l’API conserve les types JSON des attributs (version SaaS ou ActiveGate 1.295 et plus) ; sinon toutes les valeurs deviennent des chaînes. Le masquage est détaillé dans OpenPipeline et les données sensibles.

En SaaS uniquement, le paramètre structure (raw ou flattened) choisit comment les objets JSON imbriqués deviennent des attributs.

Étape 4 : confier l’envoi à un forwarder

Via un ActiveGate d’environnement. Le module Log analytics collector y est activé par défaut. L’ActiveGate reçoit les requêtes, les met en file sur disque et les transmet par lots. La file se règle dans custom.properties :

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

La taille par défaut est de 300 Mo. Si la file sature, l’API renvoie 503 Usable space limit reached ; augmentez disk_queue_max_size_mb si l’erreur persiste.

Via l’OpenTelemetry Collector. Le Collector lit les fichiers de logs avec le receiver file_log et les exporte en OTLP vers /api/v2/otlp/v1/logs. Le dépôt de la distribution Dynatrace du Collector (licence Apache 2.0) fournit un exemple pour les pods Kubernetes :

Extrait du fichier k8s_pod_logs.yaml du dépôt dynatrace-otel-collector : receiver file_log sur /var/log/pods, exporteur otlp_http avec en-tête Api-Token et pipeline logs

Dans les versions récentes du Collector, filelog s’appelle file_log et otlphttp devient otlp_http ; les anciens noms restent acceptés comme alias dépréciés.

Via Fluent Bit. Sur Kubernetes, c’est souvent le choix le plus léger : le pas-à-pas est dans Fluent Bit vers Dynatrace.

Gérer les erreurs de la Log ingestion API

Code Signification Action
204 Tout est ingéré Rien
200 Ingestion partielle (événements invalides) Lire le corps de la réponse
400 Entrée invalide Corriger la charge utile, ne pas réessayer
402 Licence ou budget DPS épuisé Voir le contrat
404 Aucun ActiveGate avec le module Log analytics collector Vérifier l’ActiveGate
413 Charge utile trop grosse Réduire la taille des lots
429, 502, 503, 504 Surcharge ou passerelle indisponible Réessayer avec un backoff exponentiel

La documentation impose aux clients de réessayer sur les erreurs marquées comme réessayables, avec un backoff exponentiel. Un script qui ignore un 429 perd des logs en silence ; pour détecter ce genre de trou, voir la surveillance de l’ingestion des logs.

Comment vérifier que ça fonctionne

  1. Le code retour de curl est 204 (ajoutez -w "%{http_code}\n" pour l’afficher).
  2. En SaaS, dans un Notebook :
    fetch logs, from: now() - 30m
    | filter service.name == "export-comptable"
    | fields timestamp, loglevel, content, log.source, service.namespace
    | sort timestamp desc
  3. En Managed, ouvrez la visionneuse de logs, filtrez sur l’attribut log.source et vérifiez le niveau et l’horodatage.
  4. Côté ActiveGate, surveillez les 503 dans les journaux du forwarder : ils signalent une file saturée.

Bonnes pratiques

  • Toujours un horodatage source : l’heure de réception fausse l’analyse après une coupure réseau.
  • Des lots, pas un appel par ligne : JSON lines et lots de quelques centaines d’événements réduisent la charge et les 429.
  • Un token par source, limité à logs.ingest, pour révoquer sans tout casser.
  • Des attributs stables (service.name, environnement, équipe) dès l’envoi, plutôt qu’un parsing a posteriori.
  • Un backoff exponentiel dans chaque client maison, testé en simulant un 503.

Questions fréquentes

Faut-il préférer la Log ingestion API ou OTLP ?

Pour un script ou un outil qui produit du JSON, l’API de logs est la plus simple. Si vous avez déjà un Collector ou des applications instrumentées avec OpenTelemetry, OTLP garde la corrélation avec les traces (voir les logs OpenTelemetry et le trace_id).

L’API fonctionne-t-elle sur Dynatrace Managed ?

Oui, à l’adresse https://<votre-domaine>/e/<env-id>/api/v2/logs/ingest ou via un ActiveGate sur le port 9999, avec un token logs.ingest. Les options OpenPipeline et le paramètre structure relèvent de SaaS.

Pourquoi des événements disparaissent-ils avec un code 200 ?

Le 200 signale une ingestion partielle : certains événements étaient invalides, par exemple trop anciens. Le corps de la réponse indique combien ont été rejetés.

Conclusion

La Log ingestion API comble les angles morts laissés par OneAgent : une requête HTTP, un token logs.ingest, et vos logs rejoignent les autres signaux. Structurez les événements dès l’envoi, confiez le transport à un ActiveGate, un Collector ou Fluent Bit dès que le volume grandit, et traitez les erreurs réessayables. Vous réduisez ainsi les trous de couverture et le temps de diagnostic.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de Dynatrace LLC. Endpoints, scopes et limites évoluent : vérifiez-les dans la documentation officielle de l’API.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

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

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

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

OpenTelemetry Collector Contrib : quels composants choisir pour la production

Related Posts