> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metronome.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Envoyer des événements d’usage
Après avoir [conçu vos événements d’usage](/fr/guides/events/design-usage-events), envoyez-les à Metronome. Ce guide décrit quelles données envoyer et les bonnes pratiques pour garantir l’exactitude des événements.
**INFO**
Envoyez les événements d’usage à Metronome via le point de terminaison [/ingest](/fr/api-reference/usage/ingest-events) ou en [connectant Metronome à Segment](/fr/integrations/platform-integrations/segment).
## Structure d’un événement d’usage
Un événement d’usage est un objet JSON avec les champs suivants :
```json theme={null}
{
"transaction_id": "string", // (required) unique identifier for this event
"customer_id": "string", // (required) which customer the event applies to
"timestamp": "string", // (required) when the event happened
"event_type": "string", // (required) the kind of event, such as page_view or sent_email
"properties": {}, // (optional) key/value pairs with event details
}
```
* **transaction\_id**
Metronome utilise le `transaction_id` pour ignorer les événements en double. Une fois qu’un événement d’usage est accepté avec un ID de transaction donné, les événements ultérieurs dans les 34 jours suivants ayant le même ID sont traités comme des doublons et ignorés.
* **customer\_id**
Le `customer_id` spécifie lequel de vos clients est responsable de toute facturation associée à l’événement. Il existe deux façons d’identifier un client Metronome dans les événements d’usage : un ID client ou un *alias d’ingestion*. Les alias d’ingestion sont utiles lors de l’envoi d’événements avec un identifiant de votre système, comme une adresse e-mail ou un numéro de compte.
Chaque client dans Metronome peut avoir plusieurs alias d’ingestion, et les événements d’usage avec un `customer_id` correspondant à l’un de ces alias peuvent être attribués à l’usage de ce client.
* **timestamp**
Le `timestamp` doit être une chaîne [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) avec une année à 4 chiffres, comme `2025-01-23T01:23:45Z`. Lors de la requête de données d’usage ou de la production d’une facture, ce champ est utilisé pour sélectionner uniquement les événements qui se sont produits dans une plage de temps donnée. Les horodatages à plus de 24 heures dans le futur sont rejetés par l’API.
* **event\_type**
Le `event_type` fonctionne avec la carte `properties` pour décrire les détails de l’événement. Par exemple, un réseau de distribution de contenu (CDN) peut générer des événements de type `http_request` avec des propriétés telles que `domain` et `bytes_sent` pour prendre en charge la facturation basée sur le transfert de données. Il peut également générer un autre type d’événement, `cache_invalidation`, avec une propriété `number_of_files`. Vous pouvez nommer le `event_type` comme nécessaire, mais pour plus d’informations, voyez comment [concevoir des métriques facturables](/fr/guides/implement-metronome/core-concepts/create-billable-metrics/).
* **properties**
Toutes les clés et valeurs dans la carte `properties` doivent être représentées sous forme de chaînes, même si les valeurs sont souvent numériques. Cela évite la perte de précision qui se produit souvent dans les systèmes utilisant des nombres à virgule flottante. En interne, Metronome utilise des décimales à précision arbitraire pour fournir des résultats exacts. Encore une fois, nous vous conseillons de partager davantage de données ici que vous n’en aurez peut-être besoin initialement, afin de pouvoir les exploiter avec flexibilité plus tard, si nécessaire.
## Mise en file d’attente et nouvelles tentatives
Si les événements d’usage sont perdus en chemin vers Metronome, vous perdrez des revenus. Si vous envoyez des événements via l’API, vous devez être résilient aux pannes telles que les problèmes réseau ou les pannes de processus. Une bonne façon d’obtenir cette résilience est de placer vos événements d’usage sur une file d’attente fiable telle qu’[Amazon SQS](https://aws.amazon.com/sqs/) ou [RabbitMQ](https://www.rabbitmq.com/), et d’avoir un processus qui tire de cette file et pousse les événements à Metronome.
Si votre appel au point de terminaison `/ingest` de Metronome échoue avec une erreur réseau ou un code de statut HTTP `5xx`, certains de vos événements peuvent avoir été ingérés, mais pas d’autres. Réessayez toujours un appel échoué à `/ingest` jusqu’à ce que vous receviez un code de statut `200`. L’`transaction_id` unique de chaque événement empêche le traitement en double, donc les nouvelles tentatives sont toujours sûres.
Si votre appel au point de terminaison `/ingest` de Metronome échoue avec un code de statut HTTP `429`, vous avez dépassé l’une de nos limites de taux. Dans ce cas, vous devez ralentir et réessayer l’appel après un délai. Si la requête continue d’être limitée, attendez un temps croissant exponentiellement entre les nouvelles tentatives.
**ÉVITEZ LES RELANCES AUTOMATIQUES SUR 4XX**
Si un appel à `/ingest` échoue avec un code de statut HTTP `4xx` (autre que `429`), cela indique un problème avec la charge utile. **Ne réessayez pas** automatiquement un tel appel. Au lieu de cela, mettez l’événement de côté dans une [file d’attente de lettres mortes](https://en.wikipedia.org/wiki/Dead_letter_queue) et déclenchez une alarme afin de pouvoir enquêter sur l’échec et résoudre le problème.
## Journalisation de la file de messages
Lors de l’intégration initiale à Metronome, il est utile d’activer la journalisation dans votre file de messages. Cela vous permet d’auditer exactement quels événements d’usage sont envoyés à Metronome. Activez également la journalisation chaque fois que vous apportez une modification à vos événements d’usage.
## Résilience d’ingestion en mode essai
Pour tester la réponse de votre système à des taux d’erreur élevés provenant de l’API Metronome, Metronome peut configurer un taux d’échec automatique de votre choix (nous recommandons 20 %). Contactez votre représentant Metronome pour spécifier le pourcentage de taux d’échec, quand activer et désactiver le test, et si vous souhaitez l’appliquer à votre sandbox ou à votre instance de production.
### Agrégation
Une métrique facturable s’agrège sur une seule propriété par défaut. Par exemple, si vous êtes un service d’envoi d’e-mails, vous pouvez avoir un événement d’usage qui ressemble à ceci :
```json theme={null}
{
"event_type": "email_sent",
"properties": {
"num_recipients": "8",
"size": "1000"
},
// ...
}
```
Déjà, cet événement permet de facturer les clients en fonction du nombre d’e-mails envoyés ou de la taille maximale d’un e-mail. Pour une agrégation supplémentaire, comme le total des données envoyées (`num_recipients` \* `size`), utilisez des [métriques facturables basées sur SQL](/fr/guides/implement-metronome/core-concepts/billable-metrics-sql-editor/).
## Idempotence des événements de battement de cœur
Les événements d’usage tombent généralement dans l’une des deux catégories suivantes : un événement qui se produit lorsqu’un utilisateur effectue une action, ou un « battement de cœur » périodique qui mesure l’état actuel — une approche courante dans les services d’infrastructure. Par exemple, un service vendant du calcul peut envoyer un battement de cœur par nœud à Metronome chaque minute décrivant l’utilisation du processeur et du disque sur ce nœud. Ces événements peuvent être agrégés en métriques telles que « minutes CPU » et « minutes gigaoctets ».
Il est important pour les événements de battement de cœur de s’assurer que l’usage n’est compté qu’une seule fois. Cela se fait en choisissant un `transaction_id` déterministe afin que les événements en double aient le même ID. Metronome garantit qu’un seul événement avec un `transaction_id` donné est traité.
Dans l’exemple d’un battement de cœur par nœud et par minute, vous pouvez structurer un ID de transaction comme suit :
```bash theme={null}
_
```
où `unix_now()` est une fonction qui renvoie le nombre de secondes depuis l’[époque Unix](https://en.wikipedia.org/wiki/Unix_time). En incluant à la fois l’ID du nœud et un horodatage à la granularité de la minute dans l’ID de transaction, il est garanti que les événements en double provenant du même nœud dans la même minute sont ignorés.
Utiliser ce type de `transaction_id` signifie que vous n’avez pas à vous soucier d’envoyer des événements trop souvent. Nous recommandons d’envoyer *deux battements de cœur ou plus* par période de mesure. Les doublons sont ignorés en toute sécurité, et en utilisant cette approche, vous diminuez le risque de manquer une période de mesure en raison d’une imprécision du minuteur ou d’un retard temporaire.
**LES MODIFICATIONS APPORTÉES AUX ÉVÉNEMENTS D’USAGE PEUVENT CAUSER DES RUPTURES**
Les événements d’usage sont conçus pour cibler des métriques facturables très spécifiques, donc si la structure des données change, cela pourrait empêcher l’enregistrement correct des métriques en aval. Il est préférable de travailler avec votre représentant Metronome chaque fois que vous ajustez la structure de vos événements d’usage. Nous pouvons aider à valider et tester le changement avec vous pour éviter toute perturbation.
## Assurez-vous que Metronome ne bloque pas les chemins critiques
Metronome a été expressément conçu pour être utilisé en toute sécurité dans les parties les plus critiques de votre application. Conformément aux bonnes pratiques de disponibilité, nous vous suggérons de vérifier que Metronome n’est pas un bloqueur dans votre chemin de création de client. Étant donné que Metronome peut faire correspondre des événements envoyés à tout moment avant ou après la création du client à l’aide d’alias d’ingestion, nous recommandons de créer le client dans votre système en premier — puis de créer l’enregistrement client correspondant dans Metronome de manière asynchrone.