Passer au contenu principal
Après avoir conçu vos événements d’usage, envoyez-les à Metronome. Ce guide décrit quelles données envoyer et les bonnes pratiques pour garantir l’exactitude des événements.
INFOEnvoyez les événements d’usage à Metronome via le point de terminaison /ingest ou en connectant Metronome à Segment.

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

Un événement d’usage est un objet JSON avec les champs suivants : 
{  
  "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 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.
  • 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 ou RabbitMQ, 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 4XXSi 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 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 : 
{  
  "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.

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