View a markdown version of this page

Inserimento di log tramite endpoint HTTP - CloudWatch Registri Amazon
Comportamento comuneConfronto degli endpoint di ingestione HTTPScelta di un endpoint

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à.

Inserimento di log tramite endpoint HTTP

Amazon CloudWatch Logs fornisce endpoint HTTP che consentono di inviare i log direttamente ai CloudWatch log utilizzando semplici richieste HTTP POST. Questi endpoint supportano sia l'autenticazione SigV4 che quella con token bearer.

Importante

Consigliamo di utilizzare l'autenticazione SigV4 per tutti i carichi di lavoro di produzione in cui è possibile l'integrazione con SDK. AWS SigV4 utilizza credenziali a breve termine e offre la posizione di sicurezza più solida. L'autenticazione con token Bearer (chiave API) è destinata a scenari in cui SigV4 non è fattibile, come i log forwarder di terze parti che non supportano l'integrazione SDK. AWS Per ulteriori informazioni, consulta Alternative alle chiavi di accesso a lungo termine nella Guida per l'utente IAM.

CloudWatch Logs supporta i seguenti endpoint di ingestione HTTP:

Endpoint Path Content-Type Formato
OpenTelemetry Logs /v1/logs application/json o application/x-protobuf JSON OTLP o Protobuf
HLC Logs /services/collector/event application/json Formato HLC
ND-JSON Logs /ingest/bulk application/json o application/x-ndjson JSON delimitato da nuove righe
Structured JSON Logs /ingest/json application/json oggetto o array JSON

Comportamento comune

Tutti gli endpoint di ingestione HTTP condividono il seguente comportamento:

Autenticazione

Tutti gli endpoint supportano sia l'autenticazione SigV4 che quella con token bearer:

  • SigV4 (consigliato): firma con firma standard versione 4. AWS Usa SigV4 ogni volta che l'applicazione o l'infrastruttura supporta l' AWS SDK o può firmare richieste. SigV4 utilizza credenziali a breve termine ed è il metodo di autenticazione più sicuro.

  • Token Bearer: utilizza l'intestazione. Authorization: Bearer <ACWL token>

Gruppo di log e flusso di log

  • Fornito tramite header: x-aws-log-group e x-aws-log-stream

  • I parametri di interrogazione ?logGroup=<name>&logStream=<name> sono supportati anche su tutti gli endpoint tranne OTLP.

  • Non è possibile utilizzare sia i parametri di query che le intestazioni per lo stesso parametro.

  • Sono obbligatori sia il gruppo di log che il flusso di log.

Risposta

  • Successo: HTTP 200 con corpo {}

  • Errori di convalida: HTTP 400

  • Errori di autenticazione: HTTP 401

Confronto degli endpoint di ingestione HTTP

Funzionalità Registri HLC Registri ND-JSON Registri JSON strutturati OpenTelemetry Registri
Path /services/collector/event /ingest/bulk /ingest/json /v1/logs
Content-Type application/json application/json o application/x-ndjson application/json application/json o application/x-protobuf
Campo Timestamp "time"(secondi) "timestamp"(millisecondi) "timestamp"(millisecondi) "timeUnixNano"(nanosecondi)
Campi obbligatori "event" Nessuno Nessuno Struttura OTLP () "resourceLogs"
Risposta parziale di successo No Sì Sì Sì
Supporto per i parametri di interrogazione Sì Sì Sì No (solo intestazioni)
Metadati dell'entità Sì Sì Sì No
Accetta primitive No Sì No No
Analisi basata su linee No Sì No No
Supporto Protobuf No No No Sì
Intestazione Retry-After No No No Sì

Scelta di un endpoint

  • Stai usando il formato HLC? Usa i registri HLC. I tuoi payload HLC esistenti funzionano con modifiche minime.

  • Registri di streaming line-by-line? Usa i registri ND-JSON. Ideale per pipeline di log che emettono un evento per riga. Il più flessibile: accetta qualsiasi tipo di valore JSON.

  • Invio di payload JSON strutturati? Usa log JSON strutturati. Ideale per applicazioni che producono oggetti o array JSON ben formati.

  • Lo stai già utilizzando? OpenTelemetry Usa OpenTelemetry i registri. Accetta il formato OTLP JSON o Protobuf e supporta risposte di successo parziali con semantica dei tentativi.