Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Envoi de journaux à l'aide du point de terminaison HLC (HLC Logs)
Le point de terminaison HLC Logs (`/services/collector/event`) est basé sur le format HTTP Log Collector (HLC).
Si vous utilisez l'authentification par jeton porteur, suivez les étapes de configuration décrites [Configuration de l'authentification par jeton porteur](CWL_HTTP_Endpoints_BearerTokenAuth.md) avant de continuer.
## Modes d'entrée
Chaque événement est un objet JSON avec un `"event"` champ obligatoire. Champs de métadonnées facultatifs : `"time"``"host"`,`"source"`,`"sourcetype"`,,`"index"`.
**Événement unique :**
```
{"event":"Hello world!","time":1486683865.0}
```
**Tableau d'événements JSON :**
```
[
{"event":"msg1","time":1486683865.0},
{"event":"msg2","time":1486683866.0}
]
```
**Événements concaténés/groupés (aucun encapsuleur de tableau) :**
```
{"event":"msg1","time":1486683865.0}{"event":"msg2","time":1486683866.0}
```
## Champ de l'événement (obligatoire)
Ce `"event"` champ est obligatoire. Sa valeur peut être de n'importe quel type JSON :
```
{"event":"a string message"}
{"event":{"message":"structured data","severity":"INFO"}}
{"event":42}
{"event":true}
```
Les objets sans `"event"` champ sont ignorés en silence :
```
{"message":"this is skipped — no event field"}
```
## Champ horaire (facultatif)
Le `"time"` champ est exprimé en secondes d'époque (et non en millisecondes), avec une décimale facultative pour une précision inférieure à la seconde.
| Format | Exemple | Interprété comme |
| --- | --- | --- |
| Float | "time":1486683865.500 | 1486683865500 ms |
| Entier | "time":1486683865 | 1486683865000 ms |
| Chaîne (flottante) | "time":"1486683865.500" | 1486683865500 ms |
| Chaîne (entier) | "time":"1486683865" | 1486683865000 ms |
| Manquant | (aucun champ horaire) | Heure actuelle du serveur |
| Non valide | "time":"invalid" | Heure actuelle du serveur |
## Content-Type
Seul `application/json` est accepté.
## Types de valeurs JSON acceptés
| Type de haut niveau | Comportement |
| --- | --- |
| Objet avec "event" | Acceptée |
| Objet sans "event" | Ignoré |
| Tableau d’objets | Chaque élément est traité individuellement |
| Objets concaténés | Chaque objet est traité individuellement |
| Primitif (chaîne, nombre, booléen, nul) | Ignoré |
## Format du point de terminaison
L'URL du point de terminaison HLC suit le format suivant :
```
https://logs..amazonaws.com/services/collector/event?logGroup=&logStream=[&entityName=&entityEnvironment=]
```
**Paramètres requis :**
+ ``— AWS Région (par exemple`us-east-1`,`eu-west-1`)
+ `logGroup`— Nom du groupe de logs codé en URL
+ `logStream`— Nom du flux de journal codé en URL
**Paramètres facultatifs :**
Vous pouvez éventuellement associer les événements de votre journal à une `Service` entité en incluant les paramètres de requête suivants. Les journaux envoyés via le point de terminaison HLC étant de la télémétrie personnalisée, ils ne sont pas automatiquement associés à une entité. En fournissant ces paramètres, CloudWatch Logs crée une entité `KeyAttributes.Type` définie sur `Service` et l'associe à vos événements de journal. Cela permet à la fonctionnalité **associée CloudWatch à Explore** de corréler ces journaux avec d'autres données de télémétrie (métriques, traces et journaux) du même service, ce qui facilite le dépannage et la surveillance de vos applications sur différents types de signaux. Pour plus d'informations sur les entités et la télémétrie associée, voir [Ajout d'informations connexes à la télémétrie personnalisée](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html).
+ `entityName`— Nom de l'entité de service à associer aux événements du journal. Cette valeur est stockée en tant qu'entité `KeyAttributes.Name` (par exemple, `my-application` ou`api.myservice.com`).
+ `entityEnvironment`— L'environnement dans lequel le service est hébergé ou à quoi il appartient. Cette valeur est stockée en tant qu'entité `KeyAttributes.Environment` (par exemple`production`,`ec2:default`, ou`eks:my-cluster/default`).
## Format des demandes
Envoyez les journaux à l'aide du protocole HTTP POST avec les en-têtes et le corps suivants :
**En-têtes :**
+ `Authorization: Bearer `
+ `Content-Type: application/json`
**Format du boîtier :**
Le corps de la requête doit être au format JSON avec un tableau d'événements :
```
{
"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"
}
]
}
```
**Descriptions des champs :**
+ `time`— Horodatage de l'époque Unix en secondes, avec décimal optionnel pour une précision inférieure à la seconde (facultatif)
+ `event`— Le message du journal ou les données de l'événement (obligatoire)
+ `host`— Nom d'hôte ou identifiant source (facultatif)
+ `source`— Identifiant de la source du journal (facultatif)
Des champs personnalisés supplémentaires peuvent être inclus selon les besoins.
## Exemple de demande
```
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"}'
```
## Bonnes pratiques
### Événements de mise en lots
Pour de meilleures performances et une meilleure efficacité :
+ Batch de plusieurs événements en une seule demande lorsque cela est possible
+ Taille de lot recommandée : 10 à 100 événements par demande
+ Taille maximale de la demande : 1 Mo
### Gestion des erreurs
Implémentez une gestion appropriée des erreurs dans votre application. Codes d'état HTTP courants :
+ `200 OK`— Logs correctement ingérés
+ `400 Bad Request`— Format ou paramètres de demande non valides
+ `401 Unauthorized`— Jeton porteur non valide ou expiré
+ `403 Forbidden`— Autorisations insuffisantes
+ `404 Not Found`— Le groupe de journaux ou le flux n'existe pas
+ `429 Too Many Requests`— Limite de débit dépassée
+ `500 Internal Server Error`— Erreur de service (nouvelle tentative avec retard exponentiel)
## Limitations
+ Taille maximale de l'événement : 256 Ko par événement
+ Taille maximale de la demande : 1 Mo
+ Nombre maximum d'événements par demande : 10 000
+ Les noms des groupes de journaux doivent respecter les conventions de dénomination des CloudWatch journaux
+ L'authentification par jeton porteur doit être activée sur le groupe de journaux si l'authentification par jeton porteur est utilisée.