API de ingesta de logs de Dynatrace: enviar, reenviar y enriquecer tus logs

API de ingesta de logs de Dynatrace: envía tus logs en JSON o texto, enriquécelos, pasa por ActiveGate o un Collector y gestiona los errores sin pérdidas.
Log ingestion API Dynatrace : envoyer, transférer et enrichir vos logs

Un job batch nocturno falla, pero sus logs se quedan en una VM sin OneAgent. Al día siguiente, nadie sabe por qué no salió el informe. Para estas fuentes huérfanas (scripts, appliances, contenedores de terceros, funciones efímeras), la API de ingesta de logs de Dynatrace (Log ingestion API) recibe logs en JSON o en texto mediante una simple petición HTTP, y un forwarder puede encargarse de ello por ti.

Objetivo: enviar un primer log con curl, estructurar y enriquecer los eventos, elegir una vía de reenvío (ActiveGate, OpenTelemetry Collector, Fluent Bit) y gestionar correctamente los errores. El contenido vale para Dynatrace SaaS y Dynatrace Managed: el endpoint y algunas opciones difieren, y se señalan a lo largo del texto.

Para un repaso del tratamiento de los logs una vez ingeridos, consulta el módulo de formación sobre logs y OpenPipeline.

Tres formas de enviar logs sin OneAgent

  • Log ingestion API (Log Monitoring API v2): un endpoint REST que acepta JSON, JSON lines o texto plano. Ideal para un script, una integración propia o un shipper que sepa hablar HTTP.
  • API OTLP: los logs en formato OpenTelemetry, en OTLP/HTTP protobuf, normalmente a través de un OpenTelemetry Collector.
  • Shippers existentes: la documentación cita OpenTelemetry Collector, Fluent Bit, Fluentd y Logstash, que se apoyan en una de estas dos API.

Esta guía se centra en la primera vía y muestra después cómo toma el relevo un forwarder.

Requisitos previos

  • Un token de acceso clásico con el scope logs.ingest. En SaaS, un platform token o un cliente OAuth con el scope openpipeline:logs:ingest también funciona (el scope storage:logs:write está marcado como legacy).
  • La URL del endpoint:
    • SaaS: https://<env-id>.live.dynatrace.com/api/v2/logs/ingest;
    • Managed: https://<tu-dominio>/e/<env-id>/api/v2/logs/ingest;
    • ActiveGate de entorno (SaaS o Managed): https://<activegate>:9999/e/<env-id>/api/v2/logs/ingest.
  • curl para la prueba y acceso de red saliente por el 443 (o el 9999 hacia el ActiveGate).

¿Dudas sobre los scopes o un 401 persistente? El método está en la resolución de problemas de un token de API de Dynatrace.

Usar la API de ingesta de logs paso a paso

Paso 1: enviar un primer 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"
    }
  ]'

Una respuesta 204 sin cuerpo significa que todo se ha aceptado. Los puntos que importan:

  • Content-Type: declara el tipo exacto y la codificación UTF-8. text/plain solo acepta un evento por petición; application/json acepta un objeto o un array.
  • content: el texto del log. Si falta, la API busca message, payload, body o log.
  • severity (o status, level) se convierte en el atributo loglevel; timestamp (o @timestamp, time…) fija la marca de tiempo, en UTC si no se indica zona horaria. Sin una marca de tiempo reconocida, se usa la hora actual.

Paso 2: enviar lotes en JSON lines

Para un archivo que ya tiene el formato un-objeto-por-línea, no hace falta construir un array. Usa uno de los tipos JSON lines admitidos (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, respeta los límites documentados por petición: 10 MB de carga útil y 50 000 registros como máximo. Los eventos cuya marca de tiempo es anterior en más de 24 horas se rechazan: 400 si lo son todos, 200 con un mensaje si solo lo es una parte.

Paso 3: enriquecer los logs al enviarlos

Un log sin contexto sale caro en el diagnóstico. Tres palancas, de la más sencilla a la más central:

  • Atributos en el evento: service.name, service.namespace, log.source o claves de negocio. Son los que permitirán filtrar y asociar el log a un servicio.
  • Cabecera X-Dynatrace-Attr: pares clave-valor separados por &, añadidos a cada registro de la petición. Práctica para un forwarder que no sabe modificar los eventos:
    -H "X-Dynatrace-Attr: deployment.environment=prod&team=finance"
  • OpenPipeline (SaaS): parsing, extracción de campos y enmascaramiento en el lado de Dynatrace, sin tocar las fuentes. Con OpenPipeline, la API conserva los tipos JSON de los atributos (versión SaaS o ActiveGate 1.295 y posteriores); si no, todos los valores se convierten en cadenas. El enmascaramiento se detalla en OpenPipeline y los datos sensibles.

Solo en SaaS, el parámetro structure (raw o flattened) elige cómo los objetos JSON anidados se convierten en atributos.

Paso 4: confiar el envío a un forwarder

A través de un ActiveGate de entorno. El módulo Log analytics collector está activado ahí por defecto. El ActiveGate recibe las peticiones, las pone en una cola en disco y las transmite por lotes. La cola se ajusta en custom.properties:

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

El tamaño por defecto es de 300 MB. Si la cola se satura, la API devuelve 503 Usable space limit reached; aumenta disk_queue_max_size_mb si el error persiste.

A través del OpenTelemetry Collector. El Collector lee los archivos de logs con el receiver file_log y los exporta en OTLP hacia /api/v2/otlp/v1/logs. El repositorio de la distribución de Dynatrace del Collector (licencia Apache 2.0) ofrece un ejemplo para pods de Kubernetes:

Extracto del archivo k8s_pod_logs.yaml del repositorio dynatrace-otel-collector: receiver file_log sobre /var/log/pods, exportador otlp_http con cabecera Api-Token y pipeline de logs

En las versiones recientes del Collector, filelog se llama file_log y otlphttp pasa a ser otlp_http; los nombres antiguos se siguen aceptando como alias obsoletos.

A través de Fluent Bit. En Kubernetes, suele ser la opción más ligera: el paso a paso está en Fluent Bit hacia Dynatrace.

Gestionar los errores de la API de ingesta de logs

Código Significado Acción
204 Todo ingerido Nada
200 Ingesta parcial (eventos no válidos) Leer el cuerpo de la respuesta
400 Entrada no válida Corregir la carga útil, no reintentar
402 Licencia o presupuesto DPS agotado Consultar el contrato
404 Ningún ActiveGate con el módulo Log analytics collector Comprobar el ActiveGate
413 Carga útil demasiado grande Reducir el tamaño de los lotes
429, 502, 503, 504 Sobrecarga o pasarela no disponible Reintentar con backoff exponencial

La documentación obliga a los clientes a reintentar ante los errores marcados como reintentables, con un backoff exponencial. Un script que ignora un 429 pierde logs en silencio; para detectar este tipo de hueco, consulta la monitorización de la ingesta de logs.

Cómo comprobar que funciona

  1. El código de retorno de curl es 204 (añade -w "%{http_code}\n" para mostrarlo).
  2. En SaaS, en 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, abre el visor de logs, filtra por el atributo log.source y comprueba el nivel y la marca de tiempo.
  4. En el lado del ActiveGate, vigila los 503 en los registros del forwarder: señalan una cola saturada.

Buenas prácticas

  • Siempre una marca de tiempo de origen: la hora de recepción falsea el análisis tras un corte de red.
  • Lotes, no una llamada por línea: JSON lines y lotes de unos cientos de eventos reducen la carga y los 429.
  • Un token por fuente, limitado a logs.ingest, para revocar sin romperlo todo.
  • Atributos estables (service.name, entorno, equipo) desde el envío, en lugar de un parsing a posteriori.
  • Un backoff exponencial en cada cliente propio, probado simulando un 503.

Preguntas frecuentes

¿Hay que preferir la Log ingestion API o OTLP?

Para un script o una herramienta que produce JSON, la API de logs es lo más sencillo. Si ya tienes un Collector o aplicaciones instrumentadas con OpenTelemetry, OTLP mantiene la correlación con las trazas (consulta los logs de OpenTelemetry y el trace_id).

¿Funciona la API en Dynatrace Managed?

Sí, en la dirección https://<tu-dominio>/e/<env-id>/api/v2/logs/ingest o a través de un ActiveGate en el puerto 9999, con un token logs.ingest. Las opciones de OpenPipeline y el parámetro structure son propios de SaaS.

¿Por qué desaparecen eventos con un código 200?

El 200 señala una ingesta parcial: algunos eventos eran no válidos, por ejemplo demasiado antiguos. El cuerpo de la respuesta indica cuántos se han rechazado.

Conclusión

La API de ingesta de logs cubre los puntos ciegos que deja OneAgent: una petición HTTP, un token logs.ingest y tus logs se unen al resto de señales. Estructura los eventos desde el envío, confía el transporte a un ActiveGate, un Collector o Fluent Bit en cuanto el volumen crezca y trata los errores reintentables. Así reduces los huecos de cobertura y el tiempo de diagnóstico.

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Los endpoints, los scopes y los límites evolucionan: compruébalos en la documentación oficial de la API.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

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

Enriquecimiento de metadatos Kubernetes en Dynatrace: namespaceSelector, reglas y anotaciones

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

OpenTelemetry Collector Contrib: qué componentes elegir para producción

Related Posts