Invio di log utilizzando l'endpoint JSON strutturato (Structured JSON Logs) - CloudWatch Registri Amazon
Formato della richiestaTipi di valori JSON accettatiCampo TimestampRichiesta di esempioRisposteBest practiceLimitazioni

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Invio di log utilizzando l'endpoint JSON strutturato (Structured JSON Logs)

L'endpoint Structured JSON Logs (/ingest/json) accetta lo standard JSON: un singolo oggetto JSON o un array di oggetti JSON. Questo endpoint è progettato per dati di registro strutturati in cui ogni evento è un oggetto JSON.

Se utilizzi l'autenticazione con token al portatore, completa i passaggi di configurazione indicati prima di procedere. Configurazione dell'autenticazione con token al portatore

Formato della richiesta

Solo application/json viene accettato come Content-Type.

Oggetto JSON singolo:

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

Matrice di oggetti JSON:

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

Tipi di valori JSON accettati

Questo endpoint è rigoroso: solo gli oggetti JSON vengono accettati come eventi.

Input Comportamento
Oggetto JSON singolo Accettato come evento unico
Matrice di oggetti JSON Ogni oggetto diventa un evento separato
Matrice vuota [] Accettato, produce 0 eventi
Non è un oggetto nell'array (stringa, numero, ecc.) Saltato
Primitiva di primo livello (,) "hello" 42 Saltato
Oggetti concatenati {...}{...} Solo il primo oggetto è stato analizzato

Esempio: array con tipi misti:

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

Risultato: 2 eventi inseriti (gli oggetti), 2 ignorati (la stringa e il numero).

Campo Timestamp

Il "timestamp" campo è espresso in millisecondi di epoca, come l'endpoint NDJSON.

Formato Esempio Interpretato come
Numerico (millis) "timestamp":1771007942000 1771007942000 ms
Mancante (nessun campo timestamp) Ora corrente del server
Non numerico "timestamp":"invalid" Ora corrente del server

Richiesta di esempio

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

Risposte

Operazione riuscita (tutti gli eventi sono accettati):

HTTP 200 OK
{}

Successo parziale (alcuni eventi rifiutati):

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

Il rejectedLogRecords campo indica il numero totale di eventi rifiutati. Il errorMessage campo contiene una suddivisione con codifica JSON in base al motivo del rifiuto:

  • tooOldLogEventCount— Eventi con timestamp precedenti al periodo di conservazione

  • tooNewLogEventCount— Eventi con timestamp troppo lontani nel futuro

  • expiredLogEventCount— Eventi scaduti durante l'elaborazione

Best practice

Eventi di raggruppamento

Per prestazioni ed efficienza migliori:

  • Batch di più eventi in un'unica richiesta, quando possibile

  • Dimensione del batch consigliata: 10—100 eventi per richiesta

  • Dimensione massima della richiesta: 1 MB

Gestione degli errori

Implementa una corretta gestione degli errori nell'applicazione. Codici di stato HTTP comuni:

  • 200 OK— Registri inseriti con successo

  • 400 Bad Request— Formato o parametri di richiesta non validi

  • 401 Unauthorized— Token al portatore non valido o scaduto

  • 403 Forbidden— Autorizzazioni insufficienti

  • 404 Not Found— Il gruppo o lo stream di log non esiste

  • 429 Too Many Requests— Limite di velocità superato

  • 500 Internal Server Error— Errore di servizio (nuovo tentativo con backoff esponenziale)

Limitazioni

  • Dimensione massima dell'evento: 256 KB per evento

  • Dimensione massima della richiesta: 1 MB

  • Numero massimo di eventi per richiesta: 10.000

  • I nomi dei gruppi di log devono seguire le convenzioni di denominazione CloudWatch dei log

  • L'autenticazione con token portatore deve essere abilitata nel gruppo di log se viene utilizzata l'autenticazione con token portatore.