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

Article
11/05/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 que vous avez affecté les autorisations de l’éditeur de métriques de surveillance, vous pouvez obtenir un jeton d’autorisation. Lors de la demande d’un jeton, spécifiez resource: https://monitoring.azure.com.

Obtenez un jeton d’authentification à l’aide de l’une des méthodes suivantes :

INTERFACE DE LIGNE DE COMMANDE
API REST
Kit SDK

Lors de la demande d’un jeton, vous devez fournir un paramètre resource. Le paramètre resource est l’URL de la ressource que vous souhaitez accéder.

Les ressources incluent :

https://management.azure.com
https://api.loganalytics.io
https://monitoring.azure.com

Obtenir un jeton à l’aide d’une requête REST

Utilisez l’appel d’API REST suivant pour obtenir un jeton. Cette demande utilise un ID client et une clé secrète client pour authentifier la demande. L’ID client et la clé secrète client sont obtenus lorsque vous inscrivez votre application auprès de Microsoft Entra ID. Pour plus d’informations, voir Inscrire une application pour demander des jetons d’autorisation et utiliser des API

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"
}

Obtenir un jeton à l’aide d’Azure CLI

Pour obtenir un jeton à l’aide de l’interface CLI, vous pouvez utiliser la commande suivante

az account get-access-token

Pour plus d’informations, consultez az account get-access-token

Obtenir un jeton à l’aide des Kits de développement logiciel (SDK)

Les exemples de code suivants montrent comment obtenir un jeton à l’aide de :

C#
NodeJS
Python

C#

Le code suivant montre comment obtenir un jeton à l’aide d’Azure. La bibliothèque d’identités nécessite un ID client et une clé secrète client pour authentifier la demande.

var context = new AuthenticationContext("https://login.microsoftonline.com/<tennant ID>");
var clientCredential = new ClientCredential("<your apps client ID>", "<your apps client secret>");
var result = context.AcquireTokenAsync("https://monitoring.azure.com", clientCredential).Result;

Vous pouvez également utiliser la classe DefaultAzureCredential pour obtenir un jeton. Cette méthode utilise les informations d’identification Azure par défaut pour authentifier la demande et ne nécessite pas d’ID client ou de clé secrète client.

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

Vous pouvez également spécifier vos informations d’identification d’identité managée ou de principal de service comme suit :

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

Pour plus d’informations, consultez la classe DefaultAzureCredential

Node.JS

Pour plus d’informations sur l’authentification, utilisez JavaScript et NodeJS, consultez Comment authentifier des applications JavaScript auprès des services Azure à l’aide du Kit de développement logiciel (SDK) Azure pour JavaScript

Le code suivant montre comment obtenir un jeton à l’aide de la classe DefaultAzureCredential. Cette méthode utilise les informations d’identification Azure par défaut pour authentifier la demande et ne nécessite pas d’ID client ou de clé secrète client.

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const accessToken = await credential.getToken("https://management.azure.com/.default");

Vous pouvez également utiliser la classe InteractiveBrowserCredential pour obtenir les informations d’identification. Cette méthode offre une expérience d’authentification basée sur un navigateur pour que les utilisateurs s’authentifient auprès des services Azure.

Pour plus d’informations, consultez la classe DefaultAzureCredential et la classe InteractiveBrowserCredential

Vous pouvez également utiliser la classe ClientSecretCredential pour obtenir un jeton. Cette méthode nécessite un ID client et une clé secrète client pour authentifier la demande.

const { ClientSecretCredential } = require("@azure/identity");
credential = ClientSecretCredential(
    client_id="<client_id>",
    username="<username>",
    password="<password>"
   )
const accessToken = await credential.getToken("https://management.azure.com/.default");

Pour plus d’informations, consultez la classe ClientSecretCredential

Python

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.azure.com/.default')
print(token.token)

Pour plus d’informations, consultez la classe DefaultAzureCredential et la classe InteractiveBrowserCredential

Vous pouvez également utiliser la classe ClientSecretCredential pour obtenir un jeton. Cette méthode nécessite un ID client et une clé secrète client pour authentifier la demande.

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential (
     tenant_id="<tenant id>",
     client_id="<Client id>",
     client_secret="client secret"
    )
token =  credential.get_token("https://management.azure.com/.default")
print(token.token)

Pour plus d’informations, consultez Classe ClientSecretCredential

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 à é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 elle 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.

Partager via