Documentation Oracle Cloud Infrastructure

Publication de mesures personnalisées à l'aide de l'API

Publiez des mesures personnalisées dans le service Monitoring.

Conseil

Les configurations d'agent constituent un autre moyen de publier des mesures personnalisées dans Monitoring. Avec les configurations d'agent, l'API n'est pas nécessairement requise pour publier des mesures personnalisées. Vous pouvez désormais utiliser des configurations d'agent pour ingérer des données de mesure dans des mesures personnalisées. Par exemple, exposez les mesures d'une machine virtuelle à l'aide d'une adresse HTTP au format Prometheus.

Une mesure personnalisée est une mesure que vous concevez pour collecter et analyser des données.

Par exemple, créez une mesure productOrder (dans un espace de noms de mesure, mymetricsnamespace) pour suivre les commandes de produit par pays et par division, avec des métadonnées supplémentaires pour les catégories de produit et les notes.

Avant le début

Stratégies IAM : pour publier des mesures personnalisées, vous devez disposer du type d'accès requis dans une stratégie écrite par un administrateur. Cette exigence s'applique que vous utilisiez l'API REST avec un kit SDK, l'interface de ligne de commande ou un autre outil. Si vous obtenez un message indiquant que vous ne disposez pas des droits d'accès ou des autorisations nécessaires, contactez l'administrateur. Vous ne disposez peut-être pas du type d'accès requis dans le compartiment en cours.

Administrateurs : pour obtenir un exemple de stratégie, reportez-vous à Publication de mesures personnalisées (sécurisation de Monitoring).

Remarques

Lors de la définition de mesures personnalisées, tenez compte des éléments suivants :

  • Pour l'espace de noms de mesure, n'utilisez pas de préfixe réservé (oci_ ou oracle_).
  • Assurez-vous que les mesures personnalisées ne dépassent pas les limites. Par exemple, notez la plage valide de dimensions et le nombre maximal de flux de données pour les mesures personnalisées. Reportez-vous à PostMetricData.
  • Définissez des mesures en gardant à l'esprit l'agrégation. Bien que les mesures personnalisées puissent être publiées toutes les secondes (fréquence minimale d'une seconde), l'intervalle d'agrégation minimal est d'une minute.
  • Définissez des mesures en gardant à l'esprit les limites de retour. Les informations sur les limites concernant les données renvoyées incluent la valeur maximale de 100 000 points de données et les valeurs maximales de plage (déterminées par la résolution, associée à l'intervalle). Voir MetricData. Reportez-vous également à Limites relatives à la surveillance.
  • Assurez-vous que les valeurs d'horodatage sont proches de l'heure actuelle. Pour qu'un point de données soit publié, son horodatage doit être proche de l'heure actuelle (moins de deux heures dans le passé et moins de 10 minutes dans le futur). Reportez-vous à PostMetricData.
  • Après avoir publié des mesures personnalisées, vous pouvez y accéder de la même manière que pour toutes les autres mesures stockées par le service Monitoring : Visualiser les graphiques dans la console, interroger les mesures à l'aide de l'interface de ligne de commande ou de l'API et créer des alarmes.
  • Lors de l'extraction de mesures personnalisées, vous pouvez correspondre à un groupe de ressources. Une valeur vide (NULL) pour le groupe de ressources renvoie des données de mesure qui n'ont pas de groupe de ressources.

Clients de publication de mesure

Pour plus d'informations sur le développement d'un client de publication de mesures, reportez-vous au Guide du développeur. Pour un exemple de client, reportez-vous à MonitoringMetricPostExample.java.

Pour plus d'informations sur l'utilisation de l'API et la signature des demandes, reportez-vous à la documentation relative à l'API REST et à Informations d'identification de sécurité. Pour plus d'informations sur les kits SDK, reportez-vous à Kits SDK et interface de ligne de commande.

  • Cette tâche ne peut pas être effectuée dans la console.
  • Remarque

    Contrairement à d'autres commandes Monitoring qui utilisent des adresses telemetry, cette commande requiert une adresse telemetry-ingestion.

    Utilisez la commande oci monitoring metric-data post, le paramètre --endpoint et les paramètres requis pour publier des mesures personnalisées :

    oci monitoring metric-data post --metric-data <json_file_path> --endpoint https://telemetry-ingestion.<region>.oraclecloud.com

    Pour obtenir la liste complète des paramètres et des valeurs des commandes d'interface de ligne de commande, reportez-vous à Référence de ligne de commande pour Monitoring.

    Exemple de fichier JSON pour une demande

    L'exemple de fichier JSON inclut les éléments suivants.

    • Espace de noms de mesure : mymetricsnamespace
    • Nom de mesure : productOrder
    • Dimension Product
    • Dimension Country
    • Groupe de ressources : DivisionX, DivisionY
    • Métadonnées supplémentaires pour la catégorie et la remarque
    [
  {
    "compartmentId": "$compartmentId",
    "datapoints": [
      {
        "count": 10,
        "timestamp": "2023-01-08T04:18:01+00:00",
        "value": 5.0
      },
      {
        "count": 3,
        "timestamp": "2023-01-08T05:11:01+00:00",
        "value": 10.0
      }
    ],
    "dimensions": {
      "product": "ball",
      "country": "NL"
    },
    "metadata": {
      "category": "toys",
      "note": "national holiday"
    },
    "name": "productOrder",
    "namespace": "mymetricsnamespace",
    "resourceGroup": "divisionX"
  },
  {
    "compartmentId": "$compartmentId",
    "datapoints": [
      {
        "count": 7,
        "timestamp": "2023-01-08T03:22:01+00:00",
        "value": 3.0
      },
      {
        "count": 11,
        "timestamp": "2023-01-08T05:08:03+00:00",
        "value": 2
      }
    ],
    "dimensions": {
      "product": "The Road to Nowhere",
      "country": "FR"
    },
    "metadata": {
      "category": "books",
      "note": "start second semester"
    },
    "name": "productOrder",
    "namespace": "mymetricsnamespace",
    "resourceGroup": "divisionY"
  }
]
    Exemple de réponse
    {
  "data": {
    "failed-metrics": [],
    "failed-metrics-count": 0
  }
}
  • Remarque

    Contrairement à d'autres opérations Monitoring qui utilisent des adresses telemetry, cette opération requiert une adresse telemetry-ingestion.

    Exécutez l'opération PostMetricData pour publier des mesures personnalisées.

    Exemple de demande en batch

    Cet exemple présente une demande particulière contenant des points de données pour les mesures de deux espaces de noms de mesure . 

    [
   {
      "namespace":"myFirstNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "resourceGroup":"myFirstResourceGroup",
      "name":"successRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.exampleuniqueID",
         "appName":"myAppA"
      },
      "metadata":{
         "unit":"percent",
         "displayName":"MyAppA Success Rate"
      },
      "datapoints":[
         {
            "timestamp":"2023-01-10T22:19:20Z",
            "value":83.0
         },
         {
            "timestamp":"2023-01-10T22:19:40Z",
            "value":90.1
         }
      ]
   },
   {
      "namespace":"myFirstNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "resourceGroup":"mySecondResourceGroup",
      "name":"successRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.differentuniqId",
         "appName":"myAppA"
      },
      "metadata":{
         "unit":"percent",
         "displayName":"MyAppA Success Rate"
      },
      "datapoints":[
         {
            "timestamp":"2023-01-10T22:19:10Z",
            "value":100.0
         },
         {
            "timestamp":"2023-01-10T22:19:30Z",
            "value":100.0
         }
      ]
   },
   {
      "namespace":"mySecondNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "name":"deliveryRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.exampleuniqueID",
         "appName":"myAppB"
      },
      "metadata":{
         "unit":"bytes",
         "displayName":"MyAppB Delivery Rate"
      },
      "datapoints":[
         {
            "timestamp":"2023-01-10T22:19:00Z",
            "value":87.0,
            "count":60
         },
         {
            "timestamp":"2023-01-10T22:19:00Z",
            "value":96.0,
            "count":30
         }
      ]
   }
]