Ingérer des métriques personnalisées pour une ressource Azure à l’aide de l’API REST

Article
01/08/2024

Cet article explique comment envoyer des métriques personnalisées pour les ressources Azure au magasin de métriques Azure Monitor via l’API REST. Quand les métriques se trouvent dans Azure Monitor, vous pouvez les utiliser de la même façon que des métriques standard. Par exemple, vous pouvez générer des graphiques et des alertes et acheminer les métriques vers d’autres outils externes.

Notes

L’API REST autorise uniquement l’envoi de métriques personnalisées pour les ressources Azure. Pour envoyer des métriques pour des ressources dans d’autres environnements ou au niveau local, utilisez Application Insights.

Envoyer des requêtes REST pour ingérer des métriques personnalisées

Lorsque vous envoyez des métriques personnalisées à Azure Monitor, chaque point de données ou valeur rapporté dans les métriques doit inclure les informations suivantes.

jeton d’authentification
Objet
Région
Timestamp
Espace de noms
Nom
Clés de dimension
Valeurs de dimension
Valeurs de métrique

Authentification

Pour soumettre des métriques personnalisées à Azure Monitor, l’entité qui soumet la métrique doit disposer d’un jeton Microsoft Entra valide, figurant dans l’en-tête porteur de la requête. Les moyens d’acquérir un jeton du porteur valide incluent :

Identités managées pour les ressources Azure. Vous pouvez utiliser une identité managée pour accorder aux ressources des autorisations d’effectuer certaines opérations. Il peut s’agir, par exemple, d’autoriser une ressource à générer des métriques à propos d’elle-même. Une ressource, ou son identité managée, peut recevoir des autorisations Publication des métriques de surveillance pour une autre ressource. Grâce à cette autorisation, l’identité managée peut également émettre des métriques pour d’autres ressources.
Principal de service Microsoft Entra. Dans ce scénario, une application (ou service) Microsoft Entra peut se voir accorder les autorisations nécessaires pour générer des métriques concernant une ressource Azure. Pour authentifier la requête, Azure Monitor valide le jeton d’application à l’aide de clés publiques Microsoft Entra. Le rôle Surveillance de l’éditeur de métriques dispose déjà de cette autorisation. Cette autorisation est disponible dans le portail Azure.

En fonction des ressources pour lesquelles il émettra des métriques personnalisées, le principal de service peut se voir accorder le rôle Surveillance de l’éditeur de métriques selon la portée nécessaire. Il peut s’agir d’un abonnement, d’un groupe de ressources ou d’une ressource.

Conseil

Lorsque vous demandez à un jeton Microsoft Entra d’émettre des métriques personnalisées, vérifiez que l’audience ou la ressource pour laquelle le jeton est demandé est https://monitoring.azure.com/. Veillez à inclure la barre oblique de fin.

Obtenir un jeton d’autorisation

Une fois que vous avez créé votre identité managée ou votre principal de service et affecté l’éditeur de métriques de surveillance autorisations, vous pouvez obtenir un jeton d’autorisation à l’aide de la demande suivante :

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

Le corps de la réponse apparaît au format suivant :

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

Enregistrez le jeton d’accès à partir de la réponse pour l’utiliser dans les requêtes HTTP suivantes.

Objet

La propriété d’objet capture l’ID de ressource Azure pour lequel la métrique personnalisée est rapportée. Cette information est codée dans l’URL de l’appel d’API. Chaque API peut soumettre des valeurs de métrique pour une seule ressource Azure.

Notes

Vous ne pouvez pas générer de métriques personnalisées pour l’ID de ressource d’un abonnement ou d’un groupe de ressources.

Région

La propriété de région capture la région Azure dans laquelle est déployée la ressource pour laquelle vous émettez des métriques. Les métriques doivent être émises vers le point de terminaison régional Azure Monitor correspondant à la région dans laquelle la ressource est déployée. Par exemple, les métriques personnalisées concernant une machine virtuelle déployée dans la région USA Ouest doivent être envoyées au point de terminaison Azure Monitor régional WestUS. Les informations de région sont également codées dans l’URL de l’appel d’API.

Horodateur

Chaque point de données envoyé à Azure Monitor doit être marqué par un timestamp. Ce timestamp capture la date et l’heure auxquelles la valeur de métrique a été mesurée ou collectée. Azure Monitor accepte les données métriques dont les horodatages ne datent pas de plus de 20 minutes et ne dépassent pas les 5 minutes à venir. Le timestamp doit être au format ISO 8601.

Espace de noms

Les espaces de noms offrent un moyen de grouper ou classer par catégorie des métriques similaires. Les espaces de noms permettent d’isoler les groupes de métriques collectant différents insights ou indicateurs de performances. On peut avoir par exemple un espace de noms nommé contosomemorymetrics qui effectue le suivi des métriques d’utilisation de la mémoire caractéristiques de l’application. Un autre espace de noms appelé contosoapptransaction pourrait effectuer le suivi de toutes les métriques relatives aux transactions utilisateur de l’application.

Nom

La propriété de nom correspond au nom de la métrique rapportée. Généralement, le nom est suffisamment descriptif pour identifier ce qui est mesuré. Par exemple, il peut s’agir d’une métrique qui mesure le nombre d’octets de mémoire utilisés sur une machine virtuelle. Le nom de cette métrique pourrait être Memory Bytes In Use (Octets de mémoire en cours d’utilisation).

Clés de dimension

Une dimension est une paire clé-valeur simplifiant la description des autres caractéristiques sur la métrique collectée. Ces autres caractéristiques permettent de collecter plus d’informations sur la métrique, offrant des insights plus approfondis.

Par exemple, la métrique Memory Bytes In Use peut disposer d’une clé de dimension nommée Process, qui capture le nombre d’octets de mémoire consommés par chaque processus sur une machine virtuelle. Cette clé vous permet de filtrer les résultats de cette métrique pour connaître la quantité de mémoire utilisée par certains processus ou pour identifier les cinq processus utilisant le plus de mémoire.

Les dimensions sont facultatives ; certaines métriques n’ont pas de dimensions. Une métrique personnalisée peut avoir jusqu'à 10 dimensions.

Valeurs de dimension

Lorsque vous rapportez un point de données de métrique, chaque clé de dimension de la métrique rapportée est associée à une valeur de dimension. Par exemple, vous pouvez rapporter la mémoire utilisée par ContosoApp sur votre machine virtuelle :

Le nom de la métrique sera Memory Bytes In Use.
La clé de dimension sera Process.
La valeur de dimension sera ContosoApp.exe.

Lorsque vous publiez une valeur de métrique, vous ne pouvez spécifier qu’une seule valeur de dimension par clé de dimension. Si vous collectez une même utilisation de la mémoire pour plusieurs processus sur la machine virtuelle, vous pouvez rapporter plusieurs valeurs de métrique pour cet horodatage. Chaque valeur de métrique spécifiera une valeur de dimension différente pour la clé de dimension Process.

Bien que les dimensions soient facultatives, si une publication de métriques définit des clés de dimension, les valeurs de dimension correspondantes sont obligatoires.

Valeurs de métrique

Azure Monitor stocke toutes les métriques à intervalles réguliers (avec une granularité d’une minute). Au cours d’une minute donnée, une métrique peut devoir être échantillonnée plusieurs fois. C’est le cas, par exemple, avec l’utilisation du processeur. Il se peut également qu’une métrique doive être mesurée pour de nombreux événements discrets, tels que les latences de transaction de connexion.

Pour limiter le nombre de valeurs brutes que vous devez émettre et payer dans Azure Monitor, pré-agrégez les valeurs localement et émettez les valeurs agrégées :

Min : valeur minimale observée parmi tous les échantillons et mesures au cours d’une minute donnée.
Max : valeur maximale observée parmi tous les échantillons et mesures au cours d’une minute donnée.
Sum : somme de toutes les valeurs observées parmi tous les échantillons et mesures au cours d’une minute donnée.
Nombre : nombre d’échantillons et de mesures relevés au cours d’une minute donnée.

Remarque

Azure Monitor ne prend pas en charge la définition des unités pour une métrique personnalisée.

Par exemple, si quatre transactions de connexion à votre application ont été effectuées pendant une minute, les latences mesurées pour chacune d’elles sont :

Transaction 1	Transaction 2	Transaction 3	Transaction 4
7 ms	4 ms	13 ms	16 ms

La publication des métriques dans Azure Monitor se présentera comme suit :

Min : 4
Max : 16
Somme : 40
Nombre : 4

Si votre application ne peut pas préagréger les valeurs localement et doit émettre chaque événement ou échantillon discret immédiatement après collecte, vous pouvez émettre les valeurs de mesure brutes. Par exemple, à chaque exécution d’une transaction de connexion à votre application, vous publiez une métrique dans Azure Monitor avec une seule mesure. Par conséquent, pour une transaction de connexion qui a duré 12 millisecondes, la publication de métrique se présentera ainsi :

Min : 12
Max : 12
Somme : 12
Nombre : 1

Ce processus vous permet d’émettre plusieurs valeurs pour la même combinaison métrique-dimension au cours d’une minute donnée. Azure Monitor prend ensuite toutes les valeurs brutes émises pour une minute donnée et les agrège.

Exemple de publication de métrique personnalisée

Dans l’exemple suivant, créez une métrique personnalisée appelée octets de mémoire en cours d’utilisation sous l’espace de noms de métrique profil de mémoire pour une machine virtuelle. La métrique a une seule dimension appelée Process. Pour le timestamp, les valeurs de métrique sont émises pour deux processus.

Stockez le code JSON suivant dans un fichier appelé custommetric.json sur votre ordinateur local. Mettez à jour le paramètre time pour qu’il se situe dans les 20 dernières minutes. Vous ne pouvez pas envoyer une métrique datant de plus de 20 minutes au magasin.

{
    "time": "2024-01-07T11:25:20-7:00",
    "data": {

      "baseData": {

        "metric": "Memory Bytes in Use",
        "namespace": "Memory Profile",
        "dimNames": [
          "Process"
        ],
        "series": [
          {
            "dimValues": [
              "ContosoApp.exe"
            ],
            "min": 10,
            "max": 89,
            "sum": 190,
            "count": 4
          },
          {
            "dimValues": [
              "SalesApp.exe"
            ],
            "min": 10,
            "max": 23,
            "sum": 86,
            "count": 4
          }
        ]
      }
    }
  }

Envoyez la requête HTTP POST suivante en utilisant les variables suivantes :

location: région de déploiement de la ressource pour laquelle vous émettez des métriques.
resourceId: ID de ressource de la ressource Azure sur laquelle vous suivez la métrique.

accessToken: jeton d’autorisation acquis à partir du Obtenir un jeton d’autorisation étape.

curl -X POST 'https://<location>/.monitoring.azure.com<resourceId>/metrics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <accessToken>' \
-d @custommetric.json

Afficher vos métriques

Connectez-vous au portail Azure.
Dans le menu de gauche, sélectionnez Surveiller.
Sur la page Surveiller, sélectionnez Métriques.
Remplacez la période d’agrégation par Dernière heure.
Dans la liste déroulante Étendue, sélectionnez la ressource pour laquelle vous envoyez la métrique.
Dans la liste déroulante Espace de noms des métriques, sélectionnez Profil de mémoire.
Dans la liste déroulante Metric , sélectionnez Octets de mémoire utilisés.

Dépannage

Si vous recevez un message d’erreur lors du processus, tenez compte des informations de dépannage suivantes :

Si vous ne pouvez pas émettre de métriques pour un abonnement, un groupe de ressources ou une ressource, vérifiez que le rôle Éditeur de métriques de monitoring est attribué à votre application ou principal de service dans Contrôle d’accès (IAM).
Vérifiez que le nombre de noms de dimension correspond au nombre de valeurs.
Vérifiez que vous émettez des métriques vers le point de terminaison régional Azure Monitor approprié. Par exemple, si votre ressource est déployée dans la région USA Ouest, vous devez émettre des métriques au point de terminaison régional USA Ouest.
Vérifiez que l’horodatage se trouve dans les 20 dernières minutes.
Vérifiez que l’horodatage est au format ISO 8601.
Vérifiez que le nom de la métrique est valide. Par exemple, il ne peut pas contenir d’espaces.

Étapes suivantes

En savoir plus sur les métriques personnalisées.