> ## 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'utilisation
Après avoir [conçu vos événements d'utilisation](/fr/guides/events/design-usage-events), envoyez-les à Metronome. Ce guide décrit quelles données envoyer et les bonnes pratiques pour assurer l'exactitude des événements.
Envoyez des événements d'utilisation à Metronome via
le point de terminaison [/ingest](/api/#operation/ingest-v1) ou en [connectant Metronome
à Segment](/fr/integrations/platform-integrations/segment).
## Structure d'un événement d'utilisation
Un événement d'utilisation est un objet JSON avec les champs suivants :
```jsx theme={null}
{
"transaction_id": string, // (requis) identifiant unique pour cet événement
"customer_id": string, // (requis) à quel client l'événement s'applique
"timestamp": string, // (requis) quand l'événement s'est produit
"event_type": string, // (requis) le type d'événement, comme page_view ou sent_email
"properties": object, // (optionnel) paires clé/valeur avec les détails de l'événement
}
```
### `transaction_id`
Metronome utilise le `transaction_id` pour ignorer les événements en double. Une fois qu'un événement d'utilisation est accepté avec un ID de transaction donné, les événements ultérieurs dans les 34 jours suivants avec le même ID sont traités comme des doublons et ignorés.
### `customer_id`
Le `customer_id` spécifie quel 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'utilisation : un ID de client ou un *alias d'ingestion*. Les alias d'ingestion sont utiles lors de l'envoi d'événements à l'aide d'un identifiant de votre système, tel qu'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'utilisation avec un `customer_id` correspondant à l'un de ces alias peuvent être attribués à l'utilisation 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, telle que `2025-01-23T01:23:45Z`. Lors de l'interrogation des données d'utilisation ou de la production d'une facture, ce champ est utilisé pour sélectionner uniquement les événements qui se sont produits dans une certaine plage de temps. Les horodatages plus de 24 heures dans le futur sont rejetés par l'API.
### `event_type`
L'`event_type` fonctionne avec le mappage `properties` pour décrire les détails de l'événement. Par exemple, un content delivery network (CDN) pourrait générer des événements de type `http_request` avec des propriétés comme `domain` et `bytes_sent` pour prendre en charge la facturation basée sur le transfert de données. Ils pourraient également générer un type d'événement différent, `cache_invalidation`, avec une propriété `number_of_files`. Vous pouvez nommer l'`event_type` selon les besoins, mais pour plus d'informations, consultez comment [concevoir des métriques facturables](/fr/guides/implement-metronome/core-concepts/create-billable-metrics).
### `properties`
Toutes les clés et valeurs dans le mappage `properties` doivent être représentées sous forme de chaînes, même si les valeurs sont souvent numériques. Cela empêche la perte de précision qui se produit souvent dans les systèmes qui utilisent des nombres à virgule flottante. En interne, Metronome utilise des décimales de précision arbitraire pour fournir des résultats de calcul exacts. Encore une fois, nous vous conseillons de partager plus de données ici que vous n'en avez besoin initialement afin de pouvoir les utiliser plus tard avec flexibilité si nécessaire.
## File d'attente et réessai
Si des événements d'utilisation sont perdus en route vers Metronome, vous perdrez des revenus. Si vous envoyez des événements via l'API, vous devez être résilient face aux défaillances telles que des problèmes réseau ou des plantages de processus. Une bonne façon de gagner cette résilience est de placer vos événements d'utilisation dans une file d'attente fiable telle que [Amazon SQS](https://aws.amazon.com/sqs/) ou [RabbitMQ](https://www.rabbitmq.com/), et de faire en sorte qu'un processus tire de cette file d'attente et pousse les événements vers 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 d'autres non. Réessayez toujours un appel échoué à `/ingest` jusqu'à ce que vous receviez un code de statut `200`. Le `transaction_id` unique dans chaque événement empêche le traitement en double, donc les réessais sont toujours sûrs.
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 débit. Dans ce cas, vous devriez faire un backoff et réessayer l'appel après un délai. Si la requête continue d'être limitée en débit, attendez un temps croissant de manière exponentielle entre les réessais.
Évitez les réessais automatiques sur les 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. Mettez plutôt 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 d'attente de messages
Lors de la première intégration avec Metronome, il est utile d'activer la journalisation dans votre file d'attente de messages. Cela vous permet d'auditer exactement quels événements d'utilisation sont envoyés à Metronome. Activez également la journalisation chaque fois que vous apportez une modification à vos événements d'utilisation.
## Essai de résilience à l'ingestion
Pour tester la réponse de votre système à des taux d'erreur élevés de l'API de Metronome, Metronome peut configurer un taux d'échec automatique de votre choix (nous recommandons 20 %). Contactez votre représentant Metronome pour spécifier le % de taux d'échec, quand activer et désactiver le test, et si vous souhaitez l'appliquer à votre instance sandbox ou production.
### Agrégation
Une métrique facturable agrège par défaut sur une seule propriété. Par exemple, si vous êtes un service d'envoi d'e-mails, vous pourriez avoir un événement d'utilisation qui ressemble à :
```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 plus poussée, comme les données totales envoyées (`num_recipients` \* `size`), utilisez les [métriques facturables basées sur SQL](/fr/guides/implement-metronome/core-concepts/billable-metrics-sql-editor).
## Idempotence des événements de heartbeat
Les événements d'utilisation tombent généralement dans l'une des deux catégories : un événement qui se produit lorsqu'un utilisateur effectue une action, ou un « heartbeat » périodique qui mesure l'état actuel — une approche courante dans les services d'infrastructure. Par exemple, un service vendant du calcul pourrait envoyer un heartbeat par nœud à Metronome chaque minute décrivant l'utilisation du CPU et du disque sur ce nœud. Ces événements pourraient être agrégés dans les métriques « minutes CPU » et « minutes gigaoctets ».
Il est important pour les événements de heartbeat de s'assurer que l'utilisation n'est comptabilisée qu'une seule fois. Ceci est réalisé en choisissant un `transaction_id` déterministe pour 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 heartbeat par nœud et par minute, vous pourriez structurer un ID de transaction comme suit :
```
_
```
où `unix_now()` est une fonction qui retourne 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 à granularité 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 également que vous n'avez pas à vous soucier d'envoyer des événements trop souvent. Nous recommandons d'envoyer *deux heartbeats 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'utilisation peuvent provoquer des dysfonctionnements. Les événements d'utilisation 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'utilisation. Nous pouvons vous aider à valider et tester la modification avec
vous pour éviter toute perturbation.
## S'assurer 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 suggérons de vérifier que Metronome n'est pas un bloqueur dans votre chemin de création de clients. Comme Metronome peut faire correspondre les é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 d'abord le client dans votre système — puis de créer l'enregistrement client correspondant dans Metronome de manière asynchrone.