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 sont 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 inclure 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 produits par pays et par division, avec des métadonnées supplémentaires pour les catégories et les notes de produit.

Avant de commencer

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 détenez pas les 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 points 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 les métriques en gardant l'agrégation à l'esprit. 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 les mesures dans le but de garder à l'esprit les limites de renvoi. 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). Reportez-vous à MetricData. Reportez-vous également à Limites relatives à Monitoring.
  • Assurez-vous que les valeurs d'horodatage sont proches de l'heure actuelle. Pour qu'un point de données puisse être publié, son horodatage doit être proche de l'heure actuelle (moins d'une heure 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 façon que pour toutes les autres mesures stockées par le service Monitoring : visualisation des graphiques dans la console, interrogation des mesures à l'aide de l'interface de ligne de commande ou l'API, et création d'alarmes.
  • Lors de l'extraction de mesures personnalisées, vous pouvez les mettre en correspondance avec un groupe de ressources. Une valeur vide (NULL) pour le groupe de ressources renvoie la donnée de mesure qui n'a pas de groupe de ressources.

Clients de publication de mesure

Pour obtenir des informations sur le développement d'un client de publication de mesure, reportez-vous au guide du développeur. Pour obtenir un exemple de client, reportez-vous à MonitoringMetricPostExample.java.

Pour plus d'autres informations sur l'utilisation de l'API et sur la signature des demandes, reportez-vous à ladocumentation relative aux API REST et aux 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 n'est pas possible dans la console.
  • Remarque

    Contrairement à d'autres commandes Monitoring qui utilisent les adresses telemetry, cette commande requiert une adressetelemetry-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 file://<json_file_path> --endpoint https://telemetry-ingestion.<region>.oraclecloud.com

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

    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 les adresses telemetry, cette opération requiert une adressetelemetry-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
         }
      ]
   }
]