Importar eventos con la API de importación de registros de Datadog

Utiliza la interfaz de programación de aplicaciones (API) de ingesta de registros de Datadog para enviar eventos de registro en formato JSON directamente a Datadog Log Management. Puedes ingestar registros de aplicaciones en la nube, microservicios o cualquier sistema que genere telemetría. Una vez ingestados, los registros estarán disponibles en Log Explorer en cuestión de segundos. Puede procesarlos, redirigirlos y archivarlos mediante Log Pipelines.

Este punto final admite la ingesta en tiempo real y de alto rendimiento de cargas útiles JSON estructuradas y semiestructuradas.

Acciones compatibles con esta API

Envía registros directamente desde aplicaciones en la nube sin necesidad de instalar el agente de Datadog.
Aplica procesadores de canalización, como el analizador Grok, el remapador y el procesador de consulta, a los datos entrantes.
Dirige los registros a índices, archivos o destinos de alertas en función de su contenido.
Reduzca el coste de indexación combinando este punto final con reglas de muestreo y filtrado.

nota

Para obtener más información sobre la gestión de credenciales, consulta API de Datadog y claves de aplicación.

Antes de empezar

Asegúrate de tener:

Una clave API de Datadog con permisos para la ingesta de registros. La encontrarás en Configuración de la organización → Claves API.
Tu dirección del sitio de Datadog. Esta dirección varía según la región:

Región Dirección del sitio web
EE. UU. (este) datadoghq.com
US3 (oeste) us3.datadoghq.com
US5 (central) us5.datadoghq.com
UE (Europa) datadoghq.eu
AP1 (Japón) ap1.datadoghq.com
AP2 (Australia) ap2.datadoghq.com
Tener instalado curl o Postman.
Datos de registro en formato JSON.

Región	Dirección del sitio web
EE. UU. (este)	`datadoghq.com`
US3 (oeste)	`us3.datadoghq.com`
US5 (central)	`us5.datadoghq.com`
UE (Europa)	`datadoghq.eu`
AP1 (Japón)	`ap1.datadoghq.com`
AP2 (Australia)	`ap2.datadoghq.com`

Resumen de la cartera de proyectos

Mermaid (imagen)
Mermaid (código)
ASCII

Canal de ingestión de registros de Datadog

flowchart LR
    A[Aplicación en la nube<br/>o microservicio] -->|ENVIAR /api/v2/logs| B[API de ingesta de registros Datadog<br/>]
    B --> C[Canalización de registros<br/>• Analizador Grok<br/>• Remapper<br/>• Procesador de consultas]
    C --> D[Motor de enrutamiento<br/>• Filtros<br/>• Índices<br/>• Reglas de muestreo]
    D --> E{{Destinos<br/>Explorador de registros · S3 · SIEM · Alertas}}

ASCII diagram
[Aplicación en la nube]   ENVIAR /api/v2/logs   [API de ingesta de]
 [o microservicio     ]   --------------------> [registros Datadog]
                                                       |
                                                       v
                                               [Canaliz. de logs]
                                              (Grok, Remapper,
                                                  Consulta)
                                                       |
                                                       v
                                              [Motor enrutamiento]
                                                (Filtros, Índices,
                                                      Reglas)
                                                       |
                                                       v
                                                  { Destinos }
                                                (Explorador, S3,
                                                 SIEM, Alertas)

Punto final de ingesta

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

Sustituye {dd_site} por la dirección del sitio de tu región; por ejemplo, datadoghq.com o ap2.datadoghq.com.

Encabezados de solicitud

Encabezado	Valor	Obligatorio	Descripción
`DD-API-KEY`	`<your_api_key>`	Sí	Tu clave API de Datadog
`Content-Type`	`application/json`	Sí	Formato de la carga útil
`Content-Encoding`	`gzip`	Opcional	Formato de carga útil comprimida (recomendado para lotes de gran volumen)

Cuerpo de la solicitud

El cuerpo de la solicitud es una matriz JSON compuesta por uno o varios objetos de registro. Cada objeto de registro incluye los siguientes campos:

Campo	Tipo	Obligatorio	Descripción
`message`	string	Sí	El cuerpo del mensaje de registro
`ddsource`	string	Recomendado	La tecnología de la que procede el registro, por ejemplo, `python` o `nginx`.
`ddtags`	string	Opcional	Etiquetas separadas por comas, por ejemplo, `env:prod,team:payments`.
`hostname`	string	Opcional	El nombre del servidor que generó el registro
`service`	string	Recomendado	El nombre de la aplicación o del servicio

nota

Debes incluir el campo message. El resto de campos son opcionales, aunque Datadog recomienda incluirlos. Datadog utiliza service, ddsource y ddtags para el filtrado, la faceta y la coincidencia de canalizaciones.

Ejemplo de carga útil

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

nota

La «marca de tiempo» debe seguir el formato 8601 de la Organización Internacional de Normalización (ISO) para el Tiempo Universal Coordinado (UTC). Datadog utiliza este formato para alinear las líneas de tiempo en Log Explorer. Datadog indexa los registros enviados sin marca de tiempo utilizando la hora de ingesta.

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

Códigos de respuesta

Code	Status	Descripción
`202`	Accepted	Carga útil aceptada y puesta en cola para su indexación
`400`	Bad request	Error de formato o de validación
`401` / `403`	Unauthorized / Forbidden	Falta la clave API (`401`) o la clave no es válida / permisos insuficientes (`403`)
`413`	Payload too large	El tamaño de la carga útil supera los 5 MB sin comprimir (50 MB con gzip)
`429`	Too many requests	Se ha superado el límite de velocidad de ingestión

202 aceptados

Una respuesta «202 Accepted» confirma que Datadog ha recibido la carga útil. Esta respuesta tiene un cuerpo vacío. Los eventos de registro aparecen en Log Explorer en unos segundos.

Response: 202 Accepted
HTTP/1.1 202 Accepted

400 Solicitud no válida

Datadog devuelve este código cuando una carga útil presenta errores de formato o de validación:

Sintaxis JSON incorrecta o caracteres sin escapar.
Falta el campo obligatorio message.
La carga útil sin comprimir supera el límite de 5 MB.

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

401 «Acceso no autorizado» y 403 «Prohibido»

Datadog devuelve el código de estado 401 No autorizado si falta el encabezado DD-API-KEY. Datadog devuelve el código de estado 403 Prohibido si la clave de API no es válida o carece de permisos para la ingesta de registros:

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

413: la carga útil es demasiado grande

Datadog devuelve este código cuando el contenido de la solicitud supera el límite de tamaño máximo: 5 MB para JSON sin comprimir o 50 MB para datos comprimidos con gzip.

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

429: demasiadas solicitudes

El cliente ha superado el límite de frecuencia de solicitudes. Reduce la frecuencia de las solicitudes o agrupa los objetos de registro en una carga útil de tipo matriz.

Agrupación de varios eventos de registro

Puedes enviar hasta 1.000 entradas de registro en una sola solicitud pasando una matriz. Datadog recomienda este método para servicios de alto rendimiento.

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

Límites:

Tamaño máximo de la carga útil: 5 MB por solicitud sin comprimir (50 MB si se comprime con gzip)
Tamaño máximo de cada registro: 1 MB
Número máximo de entradas en la matriz: 1.000 objetos de registro

Casos de uso habituales

Recopilar registros de microservicios sin implementar el agente de Datadog.
Envío de eventos JSON estructurados desde funciones sin servidor, como Amazon Web Services (AWS) Lambda o Google Cloud Run.
Transmisión en tiempo real de datos de telemetría procedentes de dispositivos IoT o servicios periféricos.
Envío de eventos enriquecidos a sistemas de gestión de información y eventos de seguridad (SIEM), S3 o destinos de alertas a través de Log Pipelines.
Envío de registros procedentes de los procesos de integración continua y entrega continua (CI/CD) o de scripts de implementación.

Solución de problemas

Tema	Causa probable	Solución
`401 Unauthorized`	Clave API incorrecta o ausente	Comprueba `DD_API_KEY` en Configuración de la organización → Claves API
`400 Bad Request`	JSON malformado	Comprueba que sea correcto con `jq . payload.json` antes de enviarlo
Registro no realizado en Explorer	Filtro de canalización que excluye los troncos	Borrar filtros; comprobar las reglas de enrutamiento del índice
La marca de tiempo no está en orden	Formato distinto de UTC o de ISO 8601	Utiliza el formato `"2025-11-15T08:30:00Z"`.
`429 Too Many Requests`	Se ha superado el límite de solicitudes	Batch log objects into a single array payload

Acciones compatibles con esta API​

Antes de empezar​

Resumen de la cartera de proyectos​

Punto final de ingesta​

Encabezados de solicitud​

Cuerpo de la solicitud​

Ejemplo de carga útil​

Ejemplo de cURL​

Códigos de respuesta​

202 aceptados​

400 Solicitud no válida​

401 «Acceso no autorizado» y 403 «Prohibido»​

413: la carga útil es demasiado grande​

429: demasiadas solicitudes​

Agrupación de varios eventos de registro​

Casos de uso habituales​

Solución de problemas​

Próximos pasos​

Acciones compatibles con esta API

Antes de empezar

Resumen de la cartera de proyectos

Punto final de ingesta

Encabezados de solicitud

Cuerpo de la solicitud

Ejemplo de carga útil

Ejemplo de cURL

Códigos de respuesta

202 aceptados

400 Solicitud no válida

401 «Acceso no autorizado» y 403 «Prohibido»

413: la carga útil es demasiado grande

429: demasiadas solicitudes

Agrupación de varios eventos de registro

Casos de uso habituales

Solución de problemas

Próximos pasos