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'](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles)utente IAM.*
CloudWatch Logs supporta i seguenti endpoint di ingestione HTTP:
| Endpoint | Path | Content-Type | Formato |
| --- | --- | --- | --- |
| [OpenTelemetry Logs](CWL_HTTP_Endpoints_OTLP.md) | /v1/logs | application/json o application/x-protobuf | JSON OTLP o Protobuf |
| [HLC Logs](CWL_HLC_Endpoint.md) | /services/collector/event | application/json | Formato HLC |
| [ND-JSON Logs](CWL_HTTP_Endpoints_NDJSON.md) | /ingest/bulk | application/json o application/x-ndjson | JSON delimitato da nuove righe |
| [Structured JSON Logs](CWL_HTTP_Endpoints_StructuredJSON.md) | /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 `
+ Il token deve essere un token portatore ACWL valido. Per le istruzioni di configurazione, vedere. [Configurazione dell'autenticazione con token al portatore](CWL_HTTP_Endpoints_BearerTokenAuth.md)
+ Richiede le autorizzazioni `logs:PutLogEvents` e `logs:CallWithBearerToken` IAM.
**Gruppo di log e flusso di log**
+ Fornito tramite header: `x-aws-log-group` e `x-aws-log-stream`
+ I parametri di interrogazione `?logGroup=&logStream=` 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`
# Configurazione dell'autenticazione con token al portatore
Prima di poter inviare i log utilizzando l'autenticazione con token bearer con uno qualsiasi degli endpoint di ingestione HTTP, devi:
+ Creare un utente IAM con autorizzazioni Logs CloudWatch
+ Genera credenziali specifiche per il servizio (bearer token)
+ Crea un gruppo di log e un flusso di log
+ Abilita l'autenticazione con token al portatore sul gruppo di log
**Importante**
Consigliamo di utilizzare l'autenticazione SigV4 con credenziali a breve termine per tutti i carichi di lavoro laddove ciò sia possibile. SigV4 offre la posizione di sicurezza più solida. Limita l'uso delle chiavi API (bearer token) agli scenari in cui l'autenticazione a breve termine basata su credenziali non è possibile. Quando sei pronto per incorporare i CloudWatch log in applicazioni con requisiti di sicurezza più elevati, dovresti passare alle credenziali a breve termine. Per ulteriori informazioni, consulta [Alternative alle chiavi di accesso a lungo termine nella Guida](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles) per l'*utente IAM*.
## Opzione 1: avvio rapido a utilizzare la AWS console
La console AWS di gestione offre un flusso di lavoro semplificato per generare chiavi API per l'accesso agli endpoint HTTP.
**Per configurare l'accesso agli endpoint HTTP utilizzando la console**
1. Accedi alla console di AWS gestione.
1. Vai a **CloudWatch**> **Impostazioni** > **Registri.**
1. Nella sezione Chiavi API, scegli **Genera chiave API**.
1. Per **Scadenza della chiave API**, esegui una delle seguenti operazioni:
+ Seleziona una durata di scadenza della chiave API di **1**, **5**, **30**, **90** o **365** giorni.
+ Scegli **Durata personalizzata** per specificare una data di scadenza della chiave API personalizzata.
+ Seleziona **Non scade mai** (scelta non consigliata).
1. Scegli **Genera chiave API**.
La console automaticamente:
+ Crea un nuovo utente IAM con le autorizzazioni appropriate
+ Allega la policy gestita di [CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) (include `logs:PutLogEvents` e `logs:CallWithBearerToken` autorizzazioni)
+ Genera credenziali specifiche del servizio (chiave API)
1. Copia e salva in modo sicuro le credenziali visualizzate:
+ **ID chiave API (ID credenziale** specifico del servizio)
+ **Chiave API segreta (token Bearer**)
**Importante**
Salva immediatamente l'API Key Secret. Non può essere recuperata più tardi. Se la perdi, dovrai generare una nuova chiave API.
1. Crea il gruppo di log e il flusso di log in cui verranno archiviati i log:
```
# Create the log group
aws logs create-log-group \
--log-group-name /aws/hlc-logs/my-application \
--region us-east-1
# Create the log stream
aws logs create-log-stream \
--log-group-name /aws/hlc-logs/my-application \
--log-stream-name application-stream-001 \
--region us-east-1
```
1. Abilita l'autenticazione con token al portatore sul gruppo di log:
```
aws logs put-bearer-token-authentication \
--log-group-identifier /aws/hlc-logs/my-application \
--bearer-token-authentication-enabled \
--region us-east-1
```
Verifica la configurazione:
```
aws logs describe-log-groups \
--log-group-name-prefix /aws/hlc-logs/my-application \
--region us-east-1
```
**Autorizzazioni incluse:** l'utente IAM creato automaticamente avrà le seguenti autorizzazioni:
+ `logs:PutLogEvents`— Invia eventi di registro a Logs CloudWatch
+ `logs:CallWithBearerToken`— Autenticazione utilizzando il token bearer
+ `kms:Describe*`,`kms:GenerateDataKey*`, `kms:Decrypt` — Accedi ai gruppi di log crittografati con KMS (con condizioni limitate al servizio di log)
## Opzione 2: configurazione manuale
Se preferisci un maggiore controllo sulla configurazione IAM o devi personalizzare le autorizzazioni, puoi configurare manualmente l'accesso agli endpoint HTTP.
### Passaggio 1: creare un utente IAM
Crea un utente IAM che verrà utilizzato per l'inserimento dei log:
1. Accedi alla console di AWS gestione e accedi a IAM.
1. Nel riquadro di navigazione a sinistra, seleziona **Users (Utenti)**.
1. Selezionare **Create user (Crea utente)**.
1. Inserisci un nome utente (ad esempio,`cloudwatch-logs-hlc-user`).
1. Scegli **Next (Successivo)**.
1. Allega una delle seguenti politiche IAM:
**Opzione A: utilizza la policy gestita (consigliata)**
Allega la policy gestita di [CloudWatchLogsAPIKeyaccesso](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html).
**Opzione B: creare una politica personalizzata**
Crea e allega la seguente policy IAM:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "LogsAPIs",
"Effect": "Allow",
"Action": [
"logs:CallWithBearerToken",
"logs:PutLogEvents"
],
"Resource": "*"
},
{
"Sid": "KMSAPIs",
"Effect": "Allow",
"Action": [
"kms:Describe*",
"kms:GenerateDataKey*",
"kms:Decrypt"
],
"Condition": {
"StringEquals": {
"kms:ViaService": [
"logs.*.amazonaws.com"
]
}
},
"Resource": "arn:aws:kms:*:*:key/*"
}
]
}
```
1. Scegli **Avanti**, quindi **Crea utente**.
**Nota**
Le autorizzazioni KMS sono necessarie se prevedi di inviare registri a gruppi di log crittografati con KMS. La condizione limita l'accesso KMS alle sole chiavi utilizzate tramite il servizio Logs. CloudWatch
### Fase 2: Generazione di credenziali specifiche per il servizio (chiave API)
Genera la chiave API CloudWatch Logs utilizzando l'API. [CreateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceSpecificCredential.html) Puoi anche usare il comando [create-service-specific-credential](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-service-specific-credential.html)CLI. Per l'età delle credenziali, è possibile specificare un valore compreso tra 1 e 36600 giorni. Se non specifici l’età delle credenziali, la chiave API non scadrà.
Per generare una chiave API con una scadenza di 30 giorni:
```
aws iam create-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com \
--credential-age-days 30
```
La risposta è un [ServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ServiceSpecificCredential.html)oggetto. Il `ServiceCredentialSecret` valore è la tua chiave API CloudWatch Logs (token bearer).
**Importante**
Archivia il valore `ServiceCredentialSecret` in modo sicuro, poiché non potrai recuperarlo in un secondo momento. Se la perdi, dovrai generare una nuova chiave API.
### Fase 3: Creare un gruppo di log e un flusso di log
Crea il gruppo di log e il flusso di log in cui verranno archiviati i log:
```
# Create the log group
aws logs create-log-group \
--log-group-name /aws/hlc-logs/my-application \
--region us-east-1
# Create the log stream
aws logs create-log-stream \
--log-group-name /aws/hlc-logs/my-application \
--log-stream-name application-stream-001 \
--region us-east-1
```
### Passaggio 4: abilitare l'autenticazione con token al portatore
Abilita l'autenticazione con token al portatore nel gruppo di log:
```
aws logs put-bearer-token-authentication \
--log-group-identifier /aws/hlc-logs/my-application \
--bearer-token-authentication-enabled \
--region us-east-1
```
Verifica la configurazione:
```
aws logs describe-log-groups \
--log-group-name-prefix /aws/hlc-logs/my-application \
--region us-east-1
```
## Controlla le autorizzazioni per la generazione e l'utilizzo delle chiavi API CloudWatch Logs
La generazione e l'utilizzo delle chiavi API CloudWatch Logs sono controllati da azioni e chiavi di condizione nei servizi CloudWatch Logs e IAM.
### Controllo della generazione di chiavi API CloudWatch Logs
L'CreateServiceSpecificCredentialazione [iam:](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsidentityandaccessmanagementiam.html#awsidentityandaccessmanagementiam-actions-as-permissions) controlla la generazione di una chiave specifica del servizio (come una chiave API CloudWatch Logs). È possibile questa azione agli utenti IAM come una risorsa per limitare gli utenti per cui è possibile generare una chiave.
Per imporre condizioni all’autorizzazione per l’azione `iam:CreateServiceSpecificCredential`, è possibile utilizzare le chiavi di condizione seguenti:
+ [iam: ServiceSpecificCredentialAgeDays](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — Consente di specificare, nella condizione, il tempo di scadenza della chiave in giorni. Ad esempio, si può utilizzare questa chiave di condizione per consentire solo la creazione di chiavi API che scadono entro 90 giorni.
+ [iam: ServiceSpecificCredentialServiceName](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — Consente di specificare, nella condizione, il nome di un servizio. Ad esempio, è possibile utilizzare questa chiave di condizione per consentire solo la creazione di chiavi API per CloudWatch Logs e non per altri servizi.
### Controllo dell'utilizzo delle chiavi API CloudWatch Logs
L'`logs:CallWithBearerToken`azione controlla l'uso di una chiave API CloudWatch Logs. Per impedire a un'identità di utilizzare le chiavi API CloudWatch Logs, allega una policy che neghi l'`logs:CallWithBearerToken`azione all'utente IAM associato alla chiave.
### Policy di esempio
#### Impedisci a un'identità di generare e utilizzare le chiavi API CloudWatch Logs
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyCWLAPIKeys",
"Effect": "Deny",
"Action": [
"iam:CreateServiceSpecificCredential",
"logs:CallWithBearerToken"
],
"Resource": "*"
}
]
}
```
**avvertimento**
Questa politica impedirà la creazione di credenziali per tutti i AWS servizi che supportano la creazione di credenziali specifiche del servizio. Per ulteriori informazioni, consulta [Credenziali specifiche del servizio per gli utenti IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_service-specific-creds.html).
#### Impedisci a un'identità di utilizzare le chiavi API Logs CloudWatch
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "logs:CallWithBearerToken",
"Resource": "*"
}
]
}
```
#### Consenti la creazione di chiavi CloudWatch Logs solo se scadono entro 90 giorni
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:CreateServiceSpecificCredential",
"Resource": "arn:aws:iam::123456789012:user/username",
"Condition": {
"StringEquals": {
"iam:ServiceSpecificCredentialServiceName": "logs.amazonaws.com"
},
"NumericLessThanEquals": {
"iam:ServiceSpecificCredentialAgeDays": "90"
}
}
}
]
}
```
## Chiavi API rotanti
La rotazione regolare delle chiavi API riduce il rischio di accessi non autorizzati. Ti consigliamo di stabilire un programma di rotazione in linea con le politiche di sicurezza dell'organizzazione.
### Processo di rotazione
Per ruotare una chiave API senza interrompere la consegna dei log, segui questa procedura:
1. Crea una nuova credenziale (secondaria) per l'utente IAM:
```
aws iam create-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com \
--credential-age-days 90
```
1. (Facoltativo) Archivia la nuova credenziale Gestione dei segreti AWS per il recupero sicuro e la rotazione automatica.
1. Importa la nuova credenziale nel portale del fornitore o aggiorna la configurazione dell'applicazione per utilizzare la nuova chiave API.
1. Imposta la credenziale originale su inattiva:
```
aws iam update-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-specific-credential-id ACCA1234EXAMPLE1234 \
--status Inactive
```
1. Verifica che la consegna dei log non sia influenzata dal monitoraggio della `IncomingBytes` metrica relativa al tuo gruppo di log in. CloudWatch Per ulteriori informazioni, consulta [Monitoraggio con CloudWatch metriche](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html).
1. Dopo aver confermato l'avvenuta consegna con la nuova chiave, elimina la credenziale precedente:
```
aws iam delete-service-specific-credential \
--service-specific-credential-id ACCA1234EXAMPLE1234
```
### Monitoraggio della scadenza delle chiavi
Per verificare la data di creazione e lo stato delle chiavi API esistenti, usa il [list-service-specific-credentials](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/list-service-specific-credentials.html)comando:
```
aws iam list-service-specific-credentials \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com
```
La risposta include `CreateDate` e `Status` per ogni credenziale. Utilizza queste informazioni per identificare le chiavi che stanno per scadere o che sono state attive più a lungo di quanto consentito dalla politica di rotazione.
## Risposta a una chiave API compromessa
Se sospetti che una chiave API sia stata compromessa, procedi immediatamente come segue:
1. **Disattiva immediatamente la chiave** per evitare ulteriori utilizzi non autorizzati:
```
aws iam update-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-specific-credential-id ACCA1234EXAMPLE1234 \
--status Inactive
```
1. ** CloudTrail Esamina i log** per determinare l'ambito dell'accesso non autorizzato. Scopri [Registrazione dell'utilizzo delle chiavi API con CloudTrail](#CWL_HTTP_Endpoints_CloudTrail_Logging) come abilitare il controllo dell'utilizzo delle chiavi API.
1. **Crea una chiave sostitutiva** seguendo il processo di rotazione descritto in[Processo di rotazione](#CWL_HTTP_Endpoints_Rotation_Process).
1. **Eliminare la chiave compromessa** dopo aver effettuato la sostituzione:
```
aws iam delete-service-specific-credential \
--service-specific-credential-id ACCA1234EXAMPLE1234
```
1. **Allega una politica di rifiuto** se devi bloccare immediatamente l'accesso a tutti i token portatori per l'utente IAM durante le indagini:
```
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Deny",
"Action": "logs:CallWithBearerToken",
"Resource": "*"
}
}
```
**Nota**
Per eseguire queste azioni tramite l'API, devi autenticarti con AWS le credenziali e non con una CloudWatch chiave API Logs.
Puoi anche utilizzare le seguenti operazioni dell'API IAM per gestire le chiavi compromesse:
+ [ResetServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html)— Reimposta la chiave per generare una nuova password senza eliminare la credenziale. La chiave non deve essere scaduta.
## Le migliori pratiche di sicurezza per le chiavi API
Segui queste best practice per proteggere le tue chiavi API CloudWatch Logs:
+ **Non incorporare mai le chiavi API nel codice sorgente.** Non codificate le chiavi API nel codice dell'applicazione né affidatele a sistemi di controllo della versione. Se una chiave viene salvata accidentalmente in un archivio pubblico, la scansione AWS automatica potrebbe contrassegnarla ed è necessario ruotarla immediatamente.
+ **Usa un gestore di segreti.** Archivia le chiavi API in una soluzione di gestione dei segreti equivalente [Gestione dei segreti AWS](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)o in una soluzione di gestione dei segreti equivalente. Ciò consente il controllo centralizzato degli accessi, la registrazione degli audit e la rotazione automatizzata.
+ **Imposta una scadenza per tutte le chiavi.** Specificate sempre un `--credential-age-days` valore durante la creazione delle chiavi API. Per imporre una durata massima delle chiavi in tutta l'organizzazione, utilizza la chiave di condizione `iam:ServiceSpecificCredentialAgeDays` IAM. Per vedere un esempio, consulta [Consenti la creazione di chiavi CloudWatch Logs solo se scadono entro 90 giorni](#CWL_HTTP_Endpoints_Allow_Expire_90).
+ **Applica le autorizzazioni con privilegi minimi.** Ambita le autorizzazioni dell'utente IAM solo per i gruppi di log e le azioni richieste. Utilizza la policy di [CloudWatchLogsAPIKeyaccesso](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) gestito come punto di partenza e limita ulteriormente se necessario.
+ **Abilita la CloudTrail registrazione.** Verifica l'utilizzo delle chiavi API abilitando gli eventi di CloudTrail dati per`AWS::Logs::LogGroupAuthorization`. Per informazioni, consulta [Registrazione dell'utilizzo delle chiavi API con CloudTrail](#CWL_HTTP_Endpoints_CloudTrail_Logging).
+ **Monitora con IAM Access Analyzer.** Utilizza [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html) per identificare le credenziali non utilizzate e le policy eccessivamente permissive associate agli utenti IAM della tua chiave API.
+ **Ruota i tasti regolarmente.** Stabilite un programma di rotazione e seguite la procedura descritta in[Chiavi API rotanti](#CWL_HTTP_Endpoints_Rotating_Keys).
## Registrazione dell'utilizzo delle chiavi API con CloudTrail
È possibile utilizzare AWS CloudTrail per registrare gli eventi relativi ai dati per l'utilizzo della chiave API CloudWatch Logs. CloudWatch Logs emette eventi di `AWS::Logs::LogGroupAuthorization` dati per `CallWithBearerToken` le chiamate, consentendoti di verificare quando e come le chiavi API vengono utilizzate per inviare i log.
Per abilitare la CloudTrail registrazione per l'utilizzo delle chiavi API CloudWatch Logs:
**Nota**
Il bucket S3 che specifichi per il percorso deve avere una policy sui bucket che CloudTrail consenta di scrivere file di registro al suo interno. Per ulteriori informazioni, consulta la policy sui [bucket di Amazon S3](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/create-s3-bucket-policy-for-cloudtrail.html) per. CloudTrail
1. Crea un percorso:
```
aws cloudtrail create-trail \
--name cloudwatch-logs-api-key-audit \
--s3-bucket-name my-cloudtrail-bucket \
--region us-east-1
```
1. Configura i selettori di eventi avanzati per acquisire gli eventi di autorizzazione dei gruppi di CloudWatch log log:
```
aws cloudtrail put-event-selectors \
--region us-east-1 \
--trail-name cloudwatch-logs-api-key-audit \
--advanced-event-selectors '[{
"Name": "CloudWatch Logs API key authorization events",
"FieldSelectors": [
{ "Field": "eventCategory", "Equals": ["Data"] },
{ "Field": "resources.type", "Equals": ["AWS::Logs::LogGroupAuthorization"] }
]
}]'
```
1. Inizia la registrazione dei percorsi:
```
aws cloudtrail start-logging \
--name cloudwatch-logs-api-key-audit \
--region us-east-1
```
# Invio di log utilizzando l'endpoint OTLP (Logs) OpenTelemetry
L'endpoint OpenTelemetry Logs (`/v1/logs`) accetta i dati di log del OpenTelemetry protocollo (OTLP) con codifica JSON o Protobuf. [Per informazioni dettagliate sull'endpoint OTLP, inclusi configurazione e utilizzo, consulta Inviare metriche e tracce a with. CloudWatch OpenTelemetry](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html)
Se utilizzi l'autenticazione con token al portatore, completa i passaggi di configurazione prima di procedere. [Configurazione dell'autenticazione con token al portatore](CWL_HTTP_Endpoints_BearerTokenAuth.md)
## Formato della richiesta
+ Metodo: `POST`
+ Tipo di contenuto: o `application/json` `application/x-protobuf`
+ Gruppo di log: solo `x-aws-log-group` intestazione (parametro di query non supportato)
+ Flusso di registro: intestazione `x-aws-log-stream`
## Richiesta di esempio
```
curl -X POST "https://logs..amazonaws.com/v1/logs" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/json" \
-H "x-aws-log-group: MyLogGroup" \
-H "x-aws-log-stream: MyLogStream" \
-d '{
"resourceLogs": [
{
"resource": {
"attributes": [
{
"key": "service.name",
"value": { "stringValue": "my-service" }
}
]
},
"scopeLogs": [
{
"scope": {
"name": "my-library",
"version": "1.0.0"
},
"logRecords": [
{
"timeUnixNano": "1741900000000000000",
"severityNumber": 9,
"severityText": "INFO",
"body": {
"stringValue": "User logged in successfully"
},
"attributes": [
{
"key": "user.id",
"value": { "stringValue": "12345" }
}
]
}
]
}
]
}
]
}'
```
## 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}"
}
}
```
Quando la richiesta Content-Type è`application/x-protobuf`, la risposta viene restituita come messaggio `ExportLogsServiceResponse` protobuf serializzato con gli stessi campi.
## Comportamenti specifici di OTLP
I seguenti comportamenti sono specifici dell'endpoint OTLP e non sono presenti negli altri endpoint di ingestione HTTP:
+ **Intestazione Retry-After**: inclusa nelle risposte 503 e 429 per indicare quando il client deve riprovare.
# Invio di registri utilizzando l'endpoint HLC (registri HLC)
L'endpoint HLC Logs () si basa sul formato HTTP Log Collector (HLC`/services/collector/event`).
Se utilizzi l'autenticazione con token bearer, completa i passaggi di configurazione prima di procedere. [Configurazione dell'autenticazione con token al portatore](CWL_HTTP_Endpoints_BearerTokenAuth.md)
## Modalità di input
Ogni evento è un oggetto JSON con un `"event"` campo obbligatorio. Campi di metadati opzionali:`"time"`,,`"host"`,`"source"`,`"sourcetype"`. `"index"`
**Evento singolo:**
```
{"event":"Hello world!","time":1486683865.0}
```
**Matrice di eventi JSON:**
```
[
{"event":"msg1","time":1486683865.0},
{"event":"msg2","time":1486683866.0}
]
```
**Eventi concatenati/in batch (nessun array wrapper):**
```
{"event":"msg1","time":1486683865.0}{"event":"msg2","time":1486683866.0}
```
## Campo evento (obbligatorio)
Il `"event"` campo è obbligatorio. Il suo valore può essere di qualsiasi tipo JSON:
```
{"event":"a string message"}
{"event":{"message":"structured data","severity":"INFO"}}
{"event":42}
{"event":true}
```
Gli oggetti senza `"event"` campo vengono ignorati silenziosamente:
```
{"message":"this is skipped — no event field"}
```
## Campo orario (opzionale)
Il `"time"` campo è in secondi epocali (non in millisecondi), con decimali opzionali per una precisione inferiore al secondo.
| Formato | Esempio | Interpretato come |
| --- | --- | --- |
| Float | "time":1486683865.500 | 1486683865500 ms |
| Numero intero | "time":1486683865 | 1486683865000 ms |
| Stringa (float) | "time":"1486683865.500" | 1486683865500 ms |
| Stringa (numero intero) | "time":"1486683865" | 1486683865000 ms |
| Mancante | (nessun campo temporale) | Ora corrente del server |
| Non valido | "time":"invalid" | Ora corrente del server |
## Content-Type
`application/json`È accettata solo.
## Tipi di valori JSON accettati
| Tipo di primo livello | Comportamento |
| --- | --- |
| Oggetto con "event" | Accettato |
| Oggetto senza "event" | Saltato |
| Matrice di oggetti | Ogni elemento è stato elaborato singolarmente |
| Oggetti concatenati | Ogni oggetto viene elaborato singolarmente |
| Primitiva (stringa, numero, booleano, nullo) | Saltato |
## Formato dell'endpoint
L'URL dell'endpoint HLC segue questo formato:
```
https://logs..amazonaws.com/services/collector/event?logGroup=&logStream=[&entityName=&entityEnvironment=]
```
**Parametri richiesti:**
+ ``— AWS Regione (ad esempio`us-east-1`,`eu-west-1`)
+ `logGroup`— nome del gruppo di log con codifica URL
+ `logStream`— nome del flusso di log con codifica URL
**Parametri opzionali:**
Facoltativamente, è possibile associare gli eventi di registro a un'`Service`entità includendo i seguenti parametri di query. Poiché i log inviati tramite l'endpoint HLC sono telemetria personalizzata, non vengono associati automaticamente a un'entità. Fornendo questi parametri, CloudWatch Logs crea un'entità con `KeyAttributes.Type` set to `Service` e la associa ai tuoi eventi di registro. Ciò consente **alla funzionalità relativa a Explore** di CloudWatch correlare questi log con altri dati di telemetria (metriche, tracce e registri) dello stesso servizio, semplificando la risoluzione dei problemi e il monitoraggio delle applicazioni su diversi tipi di segnale. [Per ulteriori informazioni sulle entità e sulla relativa telemetria, vedere Aggiungere informazioni correlate alla telemetria personalizzata.](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html)
+ `entityName`— Il nome dell'entità di servizio da associare agli eventi del registro. Questo valore viene memorizzato come entità `KeyAttributes.Name` (ad esempio, `my-application` o`api.myservice.com`).
+ `entityEnvironment`— L'ambiente in cui è ospitato il servizio o a cosa appartiene. Questo valore viene memorizzato come entità `KeyAttributes.Environment` (ad esempio`production`,`ec2:default`, o`eks:my-cluster/default`).
## Formato della richiesta
Invia i log utilizzando HTTP POST con le intestazioni e il testo seguenti:
**Intestazioni:**
+ `Authorization: Bearer `
+ `Content-Type: application/json`
**Formato del corpo:**
Il corpo della richiesta deve essere in formato JSON con una serie di eventi:
```
{
"event": [
{
"time": 1730141374.001,
"event": "Application started successfully",
"host": "web-server-1",
"source": "application.log",
"severity": "info"
},
{
"time": 1730141374.457,
"event": "User login successful",
"host": "web-server-1",
"source": "auth.log",
"user": "john.doe"
}
]
}
```
**Descrizioni dei campi:**
+ `time`— Timestamp Unix epoch in secondi, con decimale opzionale per una precisione inferiore al secondo (opzionale)
+ `event`— Il messaggio di registro o i dati dell'evento (obbligatorio)
+ `host`— Nome host o identificatore di origine (opzionale)
+ `source`— Identificatore di origine del registro (opzionale)
Se necessario, è possibile includere campi personalizzati aggiuntivi.
## Richiesta di esempio
```
curl -X POST "https://logs..amazonaws.com/services/collector/event?logGroup=MyLogGroup&logStream=MyStream" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/json" \
-d '{"event":{"message":"User logged in","user_id":"u-123"},"time":1486683865.0,"host":"web-01","source":"auth-service"}'
```
## 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.
# Invio di log utilizzando l'endpoint NDJSON (ND-JSON Logs)
[L'endpoint ND-JSON Logs () accetta i log in formato NDJSON (Newline Delimited JSON). `/ingest/bulk`](https://github.com/ndjson/ndjson-spec) Ogni riga contiene esattamente un valore JSON, separato da caratteri di nuova riga.
Se utilizzi l'autenticazione con token al portatore, completa i passaggi di configurazione indicati prima di procedere. [Configurazione dell'autenticazione con token al portatore](CWL_HTTP_Endpoints_BearerTokenAuth.md)
## Formato della richiesta
Invia un valore JSON per riga, separato da `\n` (LF) o `\r\n` (CRLF). Le righe vuote vengono ignorate silenziosamente.
```
{"timestamp":1771007942000,"message":"event one","level":"INFO"}
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
{"timestamp":1771007944000,"message":"event three","level":"DEBUG"}
```
Entrambi i tipi `application/json` `application/x-ndjson` sono accettati come Content-Type.
## Tipi di valori JSON accettati
In base alle specifiche NDJSON (RFC 8259), qualsiasi valore JSON valido viene accettato su ogni riga.
**Oggetti JSON (i più comuni):**
```
{"timestamp":1771007942000,"message":"User logged in","service":"auth"}
{"timestamp":1771007943000,"error":"Connection timeout","service":"api"}
```
**Matrici JSON (appiattite in singoli eventi):**
```
[{"timestamp":1000,"message":"a"},{"timestamp":2000,"message":"b"}]
```
Questa singola riga produce 2 eventi. Ogni elemento dell'array diventa un evento di registro separato.
**Valori primitivi:**
```
"a plain string log message"
42
true
null
```
Ogni primitiva diventa un evento a sé stante con il timestamp corrente del server.
**Tipi misti:**
```
{"timestamp":1771007942000,"message":"structured event"}
"unstructured string message"
42
{"timestamp":1771007943000,"error":"something failed"}
```
Tutte e 4 le righe sono accettate come eventi validi.
| Contenuto della riga | Comportamento |
| --- | --- |
| Oggetto JSON | Accettato, timestamp estratto se presente |
| Array JSON | Appiattito: ogni elemento diventa un evento separato |
| Matrice vuota [] | Accettato, produce 0 eventi |
| Stringa JSON | Accettato come messaggio di evento |
| Numero JSON | Accettato come messaggio di evento |
| Booleano JSON | Accettato come messaggio di evento |
| JSON nullo | Accettato come messaggio di evento |
| JSON non valido | Ignorato (conteggiato, l'elaborazione continua) |
| Riga vuota | Ignorata (non contata come ignorata) |
## Campo Timestamp
Il `"timestamp"` campo è espresso in millisecondi epocali (non secondi).
| 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 |
| Linea non oggetto | "hello", 42, true | Ora corrente del server |
## Righe non valide
Le righe che non sono JSON valide vengono ignorate e contate silenziosamente. L'elaborazione continua con la riga successiva.
```
{"message":"valid event"}
this is not valid json
{"message":"another valid event"}
```
Risultato: 2 eventi inseriti, 1 ignorato. Restituisce `HTTP 200`.
Se tutte le righe non sono valide, restituisce con. `HTTP 400` `"All events were invalid"`
## Richiesta di esempio
```
curl -X POST "https://logs..amazonaws.com/ingest/bulk?logGroup=MyLogGroup&logStream=MyStream" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/x-ndjson" \
-d '{"timestamp":1771007942000,"message":"User logged in","level":"INFO"}
{"timestamp":1771007943000,"message":"Query took 42ms","level":"DEBUG"}
{"timestamp":1771007944000,"error":"Connection refused","level":"ERROR"}'
```
## 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.
# 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](CWL_HTTP_Endpoints_BearerTokenAuth.md)
## 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 \$1...\$1\$1...\$1 | 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..amazonaws.com/ingest/json?logGroup=MyLogGroup&logStream=MyStream" \
-H "Authorization: Bearer ACWL" \
-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.
## 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.