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