Condividi tramite

Inserire metriche personalizzate per una risorsa di Azure usando l'API REST

  • Articolo

Questo articolo illustra come inviare metriche personalizzate per le risorse di Azure nell'archivio delle metriche di Monitoraggio di Azure usando l'API REST. Quando le metriche sono in Monitoraggio di Azure, è possibile eseguire tutte le operazioni eseguibili con le metriche standard. Ad esempio, è possibile generare grafici e avvisi e instradare le metriche ad altri strumenti esterni.

Nota

L'API REST consente solo l'invio delle metriche personalizzate per le risorse di Azure. Per inviare metriche per le risorse in altri ambienti o in locale, usare Application Insights.

Inviare richieste REST per inserire metriche personalizzate

Quando si inviano le metriche personalizzate a Monitoraggio di Azure, ogni punto dati (o valore) segnalato nelle metriche deve includere le informazioni seguenti.

Autenticazione

Per inviare le metriche personalizzate a Monitoraggio di Azure, l'entità a cui inviare la metrica deve avere un token di Microsoft Entra valido nell'intestazione Bearer della richiesta. I modi supportati per acquisire un token di connessione valido includono:

  • Identità gestite per le risorse di Azure. È possibile usare un'identità gestita per concedere alle risorse le autorizzazioni per eseguire determinate operazioni. Ad esempio può consentire a una risorsa di generare metriche su se stessa. Una risorsa o la relativa identità gestita possono ricevere autorizzazioni di Autore delle metriche di monitoraggio su di un'altra risorsa. Con questa autorizzazione, l'identità gestita può anche generare metriche per altre risorse.

  • Entità servizio di Microsoft Entra. In questo scenario a un'applicazione o servizio di Microsoft Entra possono essere concesse autorizzazioni per generare metriche su una risorsa di Azure. Per autenticare la richiesta, Monitoraggio di Azure convalida il token dell'applicazione usando le chiavi pubbliche di Microsoft Entra. Il ruolo di autore delle metriche di monitoraggio dispone già di tale autorizzazione. È disponibile nel portale di Azure.

    All'entità servizio, in base alle risorse per cui genera le metriche personalizzate, può essere assegnato il ruolo di autore delle metriche di monitoraggio nell'ambito richiesto. Esempi possono essere una sottoscrizione, un gruppo di risorse o una risorsa specifica.

Suggerimento

Quando si richiede che un token di Microsoft Entra generi metriche personalizzate, assicurarsi che il destinatario o la risorsa per cui è richiesto il token sia https://monitoring.azure.com/. Assicurarsi di includere la barra finale.

Ottenere un token di autorizzazione

Dopo aver creato l'identità gestita o l'entità servizio e aver assegnato autorizzazioni di tipo Autore delle metriche di monitoraggio, è possibile ottenere un token di autorizzazione. Quando si richiede un token, specificare resource: https://monitoring.azure.com.

Ottenere un token di autenticazione usando uno dei metodi seguenti:

  • CLI
  • REST API
  • SDK

Quando si richiede un token, è necessario specificare un parametro resource. Il parametro resource è l'URL della risorsa a cui si vuole accedere.

Le risorse includono:

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

Ottenere un token usando una richiesta REST

Usare la chiamata API REST seguente per ottenere un token. Questa richiesta usa un ID client e un segreto client per autenticare la richiesta. L'ID client e il segreto client vengono ottenuti quando si registra l'applicazione con Microsoft Entra ID. Per altre informazioni, vedere Registrare un'app per richiedere token di autorizzazione e usare le 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'

Il corpo della risposta viene visualizzato nel formato seguente:

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

Salvare il token di accesso dalla risposta da usare nelle richieste HTTP seguenti.

Oggetto

La proprietà subject consente di acquisire l'ID risorsa di Azure per cui viene indicata la metrica personalizzata. Queste informazioni vengono codificate nell'URL della chiamata API. Ogni API può inviare i valori delle metriche solo per una singola risorsa di Azure.

Nota

Non è possibile generare metriche personalizzate in base all'ID risorsa di un gruppo di risorse o di una sottoscrizione.

Paese

La proprietà region acquisisce l'area di Azure in cui viene distribuita la risorsa per cui si stanno creando metriche. Le metriche devono essere inviate allo stesso endpoint a livello di area di Monitoraggio di Azure dell'area in cui la risorsa è distribuita. Per una macchina virtuale distribuita negli Stati Uniti occidentali, ad esempio, le metriche personalizzate devono essere inviate all'endpoint di Monitoraggio di Azure in tale area. Le informazioni sulle aree sono codificate anche nell'URL della chiamata API.

Timestamp:

Ogni punto dati inviato a Monitoraggio di Azure deve essere contrassegnato con un timestamp. Il timestamp consente di acquisire la data e l'ora in corrispondenza delle quali il valore della metrica viene misurato o raccolto. Monitoraggio di Azure accetta i dati di metrica con valori di timestamp non superiori a 20 minuti precedenti e 5 minuti successivi. Il timestamp deve essere in formato ISO 8601.

Spazio dei nomi

Gli spazi dei nomi consentono di classificare o raggruppare metriche simili. Usando gli spazi dei nomi, è possibile isolare i gruppi di metriche per cui possono essere raccolte informazioni dettagliate o indicatori di prestazioni diversi. È ad esempio possibile che sia disponibile uno spazio dei nomi denominato contosomemorymetrics che tiene traccia delle metriche di utilizzo della memoria che profilano l'applicazione. Un altro spazio dei nomi denominato contosoapptransaction può tenere traccia di tutte le metriche relative alle transazioni utente nell'applicazione.

Nome

La proprietà name è il nome della metrica segnalata. In genere, il nome è sufficientemente descrittivo per aiutare a identificare l'elemento misurato. Un esempio è una metrica che misura il numero di byte di memoria usati su una macchina virtuale. Potrebbe avere un nome di metrica come ad esempio Byte di memoria In uso.

Chiavi di dimensione

Una dimensione è una coppia chiave/valore che consente di descrivere altre caratteristiche sulla metrica raccolta. Usando altre caratteristiche, è possibile raccogliere altri dati sulla metrica, così da ottenere informazioni più dettagliate.

Alla metrica Byte di memoria in uso, ad esempio, può essere associata una chiave di dimensione denominata Processo che acquisisce il numero di byte di memoria usati da ogni processo in una macchina virtuale. Usando tale chiave, è possibile filtrare la metrica per visualizzare la quantità di memoria usata da processi specifici o per identificare i primi 5 processi per uso della memoria.

Le dimensioni sono facoltative e non tutte le metriche hanno dimensioni. A una metrica personalizzata possono essere associate fino a 10 dimensioni.

Valori di dimensione

Quando si segnala un punto dati delle metriche, per ogni chiave di dimensione per la metrica segnalata è presente un valore di dimensione corrispondente. Ad esempio, è possibile che si voglia segnalare la memoria usata da ContosoApp nella macchina virtuale:

  • Il nome della metrica è Byte di memoria in uso.
  • La chiave di dimensione è Processo.
  • Il valore di dimensione è ContosoApp.exe.

Quando si pubblica un valore della metrica, è possibile specificare solo un unico valore di dimensione per chiave di dimensione. Se si raccoglie la stessa metrica di uso della memoria per più processi nella macchina virtuale, è possibile indicare più valori di metrica per tale timestamp. Ogni valore della metrica specifica un valore di dimensione diverso per la chiave di dimensione Processo.

Anche se le dimensioni sono facoltative, se un post metrica definisce le chiavi della dimensione, i valori delle dimensioni corrispondenti sono obbligatori.

Valori delle metriche

Monitoraggio di Azure archivia tutte le metriche a intervalli di granularità di 1 minuto. Durante un determinato minuto potrebbe essere necessario campionare più volte una metrica. Un esempio è l'utilizzo della CPU. Potrebbe anche essere necessario misurare una metrica per molti eventi discreti, ad esempio latenze delle transazioni di accesso.

Per limitare il numero di valori non elaborati che è necessario generare e pagare in Monitoraggio di Azure, pre-aggregare in locale e generare i valori aggregati in locale:

  • Min: valore minimo valore osservato da tutti i campioni e da tutte le osservazioni durante il minuto.
  • Max: valore massimo osservato da tutti i campioni e da tutte le osservazioni durante il minuto.
  • Somma: somma di tutti i valori osservati da tutti i campioni e da tutte le misurazioni durante il minuto.
  • Numero: numero di campioni/misurazioni acquisiti durante il minuto.

Nota

Monitoraggio di Azure non supporta la definizione di Unità per una metrica personalizzata.

Ad esempio, se durante un minuto si sono verificate quattro transazioni di accesso all'app le latenze risultanti misurate per ognuna possono essere:

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

La pubblicazione delle metriche risultante in Monitoraggio di Azure è quindi:

  • Min: 4
  • Max: 16
  • Somma: 40
  • Numero: 4

Se l'applicazione non è in grado di eseguire una pre-aggregazione in locale e deve generare ogni campione o evento discreto immediatamente al momento della raccolta, è possibile generare i valori di misura non elaborati. Ogni volta che per l'app si verifica una transazione di accesso, ad esempio, si pubblica una metrica di Monitoraggio di Azure con una singola unità di misura. Per una transazione di accesso di 12 millisecondi la pubblicazione delle metriche sarebbe quindi:

  • Min: 12
  • Max: 12
  • Somma: 12
  • Numero: 1

Con questo processo, è possibile generare più valori per la stessa combinazione di dimensione e metrica durante un determinato minuto. Monitoraggio di Azure acquisisce quindi tutti i valori non elaborati generati per un determinato minuto e ne esegue l'aggregazione.

Pubblicazione di metrica personalizzata di esempio

Nell'esempio seguente si crea una metrica personalizzata denominata Byte di memoria in uso nello spazio dei nomi delle metriche Profilo di memoria per una macchina virtuale. Alla metrica è associata una singola dimensione denominata Processo. Per il timestamp, i valori delle metriche vengono generati per due processi.

Archiviare il codice JSON seguente in un file denominato custommetric.json nel computer locale. Aggiornare il parametro time in modo che rientri negli ultimi 20 minuti. Non è possibile inserire nell'archivio una metrica più vecchia di 20 minuti.

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

Inviare la richiesta HTTP POST seguente usando le variabili seguenti:

  • location: area di distribuzione della risorsa di cui si stanno generando le metriche.

  • resourceId: ID della risorsa di Azure di cui si stanno rilevando le metriche.

  • accessToken: token di autorizzazione acquisito dal passaggio Ottenere un token di autorizzazione.

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

Visualizzare le metriche

  1. Accedere al portale di Azure.

  2. Scegliere Monitoraggio dal menu a sinistra.

  3. Nella pagina Monitoraggio selezionare Metriche.

    Screenshot che mostra come selezionare Metriche nel portale di Azure.

  4. Modificare il periodo di aggregazione in Ultima ora.

  5. Nell'elenco a discesa Ambito selezionare la risorsa per cui si invia la metrica.

  6. Nell'elenco a discesa Spazio dei nomi delle metriche selezionare Profilo di memoria.

  7. Nell'elenco a discesa Metrica selezionare Byte di memoria in uso.

Risoluzione dei problemi

Se si riceve un messaggio di errore con una parte del processo, prendere in considerazione le seguenti informazioni sulla risoluzione dei problemi:

  • Se non è possibile generare metriche rispetto a una sottoscrizione o a un gruppo di risorse o a una risorsa, verificare che all'applicazione o all'entità servizio sia stato assegnato il ruolo Autore delle metriche di monitoraggio in Controllo di accesso (IAM).
  • Verificare che il numero di nomi delle dimensioni corrisponda al numero di valori.
  • Verificare di aver generato metriche per l'endpoint a livello di area di Monitoraggio di Azure corretto. Ad esempio, se la risorsa viene distribuita negli Stati Uniti occidentali, è necessario generare metriche nell'endpoint dell'area Stati Uniti occidentali.
  • Verificare che il timestamp rientri negli ultimi 20 minuti.
  • Verificare che il timestamp sia in formato ISO 8601.
  • Verificare che il nome della metrica sia valido. Ad esempio, non può contenere spazi.

Passaggi successivi

Altre informazioni sulle metriche personalizzate.