Analyser et consulter l'utilisation des compteursVersion bêta privée

Découvrez comment interroger et analyser les données d'utilisation des compteurs.

Utilisez Meter Usage Analytics pour effectuer des requêtes et analyser les données d’utilisation des compteurs de vos clients. Cela vous permet de créer des dashboards personnalisés, de générer des rapports et de déterminer des modèles de consommation sur l’ensemble de vos compteurs.

Interroger les données d’utilisation

L’API Meter Usage Analytics renvoie des données d’utilisation agrégées pour un client au cours d’un intervalle de temps spécifié. Vous pouvez rechercher des données par période, filtrer par dimensions de compteur et effectuer des requêtes sur plusieurs compteurs simultanément.

Récupérer l’utilisation pour un seul dispositif de mesure

Récupérez les données d’utilisation d’un client et d’un dispositif de mesure spécifiques sur une période donnée :

Récupérez l’utilisation d’un dispositif de mesure filtré et regroupé par dimension

Interrogez les données d’utilisation filtrées par niveau premium et regroupées par modèle :

Récupérez l’utilisation sur plusieurs mètres

Interrogez l’utilisation sur plusieurs compteurs avec différents filtres et groupes :

Créez des dashboards d’utilisation

Vous pouvez utiliser les données de l’API pour créer des visualisations, telles que des graphiques empilés qui montrent l’utilisation dans différentes dimensions. L’exemple suivant montre comment structurer les données d’un graphique qui montre l’utilisation de l’API par modèle :

Voici un exemple de réponse à cette requête :

Afficher la réponse

{
  "data": [
    {
      "bucket_start_time": 1735689600,
      "bucket_end_time": 1735776000,
      "bucket_value": 1500,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "bucket_start_time": 1735689600,
      "bucket_end_time": 1735776000,
      "bucket_value": 800,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-3.5-turbo"
      }
    },
    {
      "bucket_start_time": 1735776000,
      "bucket_end_time": 1735862400,
      "bucket_value": 2100,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "bucket_start_time": 1735776000,
      "bucket_end_time": 1735862400,
      "bucket_value": 950,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-3.5-turbo"
      }
    }
  ]
}

Utilisez cet exemple de code pour extraire des données de l’API dans votre back-end et les afficher aux utilisateurs sous la forme d’un diagramme à barres empilé dans votre front-end.

Votre back-end

// Step 1: Extract the data from the Stripe API response
const data = stripeApiResponse.data;

// Step 2: Create a dictionary to store the processed data
const processedData = {};

// Step 3: Iterate through the data and organize it by date and model
data.forEach(point => {
  const date = new Date(point.bucket_start_time * 1000).toISOString().split('T')[0];
  const model = point.dimensions.model;
  const value = point.bucket_value;

  if (!processedData[date]) {
    processedData[date] = {};
  }

  processedData[date][model] = value;
});

// Step 4: Create a list of unique models and sort them
const models = [...new Set(data.map(point => point.dimensions.model))].sort();

// Step 5: Prepare the data for charting
const chartData = [];
Object.keys(processedData).sort().forEach(date => {
  const dataPoint = { date };
  let cumulativeValue = 0;

  models.forEach(model => {
    const value = processedData[date][model] || 0;
    dataPoint[`${model}_start`] = cumulativeValue;
    cumulativeValue += value;
    dataPoint[`${model}_end`] = cumulativeValue;
    dataPoint[model] = value; // For simple stacked charts
  });

  chartData.push(dataPoint);
});

// Return chart data for front end chart library usage
return chartData;

Votre front-end

// Step 1: Fetch usage chart data from your back end
const chartData = await fetch('/api/customer_usage/:customer_id').then(r => r.json());

// Step 2: Extract unique models from the chart data
const models = Object.keys(chartData[0]).filter(key =>
  key !== 'date' && !key.endsWith('_start') && !key.endsWith('_end')
);

// Step 3: Use the chart data to create your stacked bar chart
// Example using D3 or Recharts:
createStackedChart({
  data: chartData.map(point => ({
    date: point.date,
    'gpt-4': point['gpt-4'] || 0,
    'gpt-3.5-turbo': point['gpt-3.5-turbo'] || 0
  })),
  stackKeys: models,
  xKey: 'date',
  title: 'Daily API Usage by Model'
});

Limites de débit

L’API Meter Usage Analytics a sa propre limite d’appels de 100 requêtes par seconde et par compte, qui est distincte des limites d’appels globales de l’API Stripe. Si vous dépassez cette limite, l’API renvoie un code d’état 429 Too Many Request.

Bonnes pratiques

Gérez l’actualisation des données

Les données d’utilisation peuvent présenter un léger retard. Vous pouvez utiliser le champ data_refreshed_at dans la réponse pour comprendre l’actualisation des données. Tenez également compte de cette latence lorsque vous créez des dashboards ou des alertes en temps réel.

Personnaliser vos requêtes

Suivez ces bonnes pratiques :

Utilisez les valeurs value_grouping_window appropriées pour équilibrer la granularité avec les performances.
Appliquez dimension_filters pour réduire le volume de données lorsque vous n’avez besoin que de segments spécifiques.
Interrogez plusieurs compteurs dans une même requête lors de l’analyse des habitudes d’utilisation associées.

Limites de dimension des données

Pour éviter des réponses trop longues, les limites suivantes s’appliquent par mètre :

Un maximum de 2 dimension_group_by_keys
Un maximum de 10 dimension_filters
Un maximum de 3 tenant_filters

Gérer les erreurs

L’API renvoie des codes d’état HTTP standard et des réponses d’erreur structurées :

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_time_range",
    "message": "Param start_time should not be greater than end_time"
  }
}