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 scopeopenpipeline:logs:ingesttambién funciona (el scopestorage:logs:writeestá 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.
- SaaS:
curlpara 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/plainsolo acepta un evento por petición;application/jsonacepta un objeto o un array.content: el texto del log. Si falta, la API buscamessage,payload,bodyolog.severity(ostatus,level) se convierte en el atributologlevel;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.sourceo 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:

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
- El código de retorno de
curles204(añade-w "%{http_code}\n"para mostrarlo). - 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 - En Managed, abre el visor de logs, filtra por el atributo
log.sourcey comprueba el nivel y la marca de tiempo. - En el lado del ActiveGate, vigila los
503en 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.