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 scopeopenpipeline:logs:ingestfonctionne aussi (le scopestorage:logs:writeest 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.
- SaaS :
curlpour 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/plainn’accepte qu’un seul événement par requête ;application/jsonaccepte un objet ou un tableau.content: le texte du log. À défaut, l’API cherchemessage,payload,bodyoulog.severity(oustatus,level) devient l’attributloglevel;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.sourceou 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 :

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
- Le code retour de
curlest204(ajoutez-w "%{http_code}\n"pour l’afficher). - 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 - En Managed, ouvrez la visionneuse de logs, filtrez sur l’attribut
log.sourceet vérifiez le niveau et l’horodatage. - Côté ActiveGate, surveillez les
503dans 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.