Envío de registros mediante el punto final de Structured JSON (Structured JSON Logs) - Amazon CloudWatch Logs
Formato de las solicitudesTipos de valores JSON aceptadosCampo de fecha y horaEjemplo de solicitudRespuestasPrácticas recomendadasLimitaciones

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Envío de registros mediante el punto final de Structured JSON (Structured JSON Logs)

El punto final de Structured JSON Logs (/ingest/json) acepta JSON estándar, ya sea un único objeto JSON o una matriz de objetos JSON. Este punto final está diseñado para datos de registro estructurados en los que cada evento es un objeto JSON.

Si utiliza la autenticación por token de portador, complete los pasos de configuración Configuración de la autenticación por token de portador antes de continuar.

Formato de las solicitudes

Solo application/json se acepta como tipo de contenido.

Objeto JSON único:

{"timestamp":1771007942000,"message":"single event","level":"INFO"}

Matriz de objetos JSON:

[
  {"timestamp":1771007942000,"message":"event one","level":"INFO"},
  {"timestamp":1771007943000,"message":"event two","level":"ERROR"}
]

Tipos de valores JSON aceptados

Este punto final es estricto: solo los objetos JSON se aceptan como eventos.

Input Comportamiento
Objeto JSON único Se acepta como un solo evento
Matriz de objetos JSON Cada objeto se convierte en un evento independiente
Matriz vacía [] Aceptado, produce 0 eventos
No es un objeto en la matriz (cadena, número, etc.) Omitido
Primitiva de nivel superior ("hello",) 42 Omitido
Objetos concatenados {...}{...} Solo se analizó el primer objeto

Ejemplo: matriz con tipos mixtos:

[
  {"timestamp":1771007942000,"message":"valid object"},
  "just a string",
  42,
  {"timestamp":1771007943000,"message":"another valid object"}
]

Resultado: 2 eventos ingeridos (los objetos) y 2 omitidos (la cadena y el número).

Campo de fecha y hora

El "timestamp" campo está expresado en milisegundos de época, igual que el punto final NDJSON.

Formato Ejemplo Interpretado como
Numérico (milis) "timestamp":1771007942000 1771007942000 ms
Missing (Ausente) (sin campo de marca de tiempo) Hora actual del servidor
No numérico "timestamp":"invalid" Hora actual del servidor

Ejemplo de solicitud

curl -X POST "https://logs.<region>.amazonaws.com/ingest/json?logGroup=MyLogGroup&logStream=MyStream" \
  -H "Authorization: Bearer ACWL<token>" \
  -H "Content-Type: application/json" \
  -d '[{"timestamp":1771007942000,"message":"User logged in","user_id":"u-123"},{"timestamp":1771007943000,"message":"Order placed","order_id":"o-456"}]'

Respuestas

Éxito (se aceptan todos los eventos):

HTTP 200 OK
{}

Éxito parcial (algunos eventos rechazados):

{
  "partialSuccess": {
    "rejectedLogRecords": 5,
    "errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
  }
}

El rejectedLogRecords campo es el número total de eventos rechazados. El errorMessage campo contiene un desglose codificado en JSON por motivo de rechazo:

  • tooOldLogEventCount— Eventos con marcas de tiempo anteriores al período de retención

  • tooNewLogEventCount— Eventos con marcas de tiempo demasiado lejanas en el futuro

  • expiredLogEventCount— Eventos que caducaron durante el procesamiento

Prácticas recomendadas

Agrupación de eventos por lotes

Para un mejor rendimiento y eficiencia:

  • Batch varios eventos en una sola solicitud cuando sea posible

  • Tamaño de lote recomendado: de 10 a 100 eventos por solicitud

  • Tamaño máximo de la solicitud: 1 MB

Gestión de errores

Implemente una gestión de errores adecuada en su aplicación. Códigos de estado HTTP comunes:

  • 200 OK— Los registros se ingirieron correctamente

  • 400 Bad Request— Formato o parámetros de solicitud no válidos

  • 401 Unauthorized— Token de portador no válido o caducado

  • 403 Forbidden— Permisos insuficientes

  • 404 Not Found— El grupo de registros o la transmisión no existen

  • 429 Too Many Requests— Se ha superado el límite de velocidad

  • 500 Internal Server Error— Error de servicio (reintento con un retraso exponencial)

Limitaciones

  • Tamaño máximo del evento: 256 KB por evento

  • Tamaño máximo de solicitud: 1 MB

  • Número máximo de eventos por solicitud: 10 000

  • Los nombres de los grupos de registros deben seguir las convenciones CloudWatch de nomenclatura de los registros

  • La autenticación por token de portador debe estar habilitada en el grupo de registros si se utiliza la autenticación por token de portador.