Passer au contenu principal
Après avoir conçu vos événements d’utilisation, 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 ou en connectant Metronome à Segment.

​
Structure d’un événement d’utilisation

Un événement d’utilisation est un objet JSON avec les champs suivants : 
{
  "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 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.

​
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 ou RabbitMQ, 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 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 à : 
{
  "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.

​
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 : 
<node id>_<floor(unix_now()/60)>
où unix_now() est une fonction qui retourne le nombre de secondes depuis l’époque Unix. 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.