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

Questo articolo illustra come inviare metriche personalizzate per le risorse di Azure all'archivio metriche di Monitoraggio di Azure tramite l'API REST. Quando le metriche si trovano in Monitoraggio di Azure, è possibile eseguire tutte le operazioni eseguite 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 metriche personalizzate a Monitoraggio di Azure, ogni punto dati o valore, segnalato nelle metriche deve includere le informazioni seguenti.

• Token di autenticazione
• Argomento
• Area
• Timestamp:
• Spazio dei nomi
• Nome
• Chiavi delle dimensioni
• Valori delle dimensioni
• Valori delle metriche

Autenticazione

Per inviare metriche personalizzate a Monitoraggio di Azure, l'entità che invia la metrica richiede un token 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. A una risorsa, o alla relativa identità gestita, è possibile concedere le autorizzazioni del server di pubblicazione delle metriche di monitoraggio su un'altra risorsa. Con questa autorizzazione, l'identità gestita può anche generare metriche per altre risorse.

• Entità servizio Microsoft Entra. In questo scenario, un'applicazione o un servizio Microsoft Entra può essere assegnata alle 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 un token Microsoft Entra per generare metriche personalizzate, assicurarsi che il gruppo di destinatari 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 le autorizzazioni del server di pubblicazione delle metriche di monitoraggio, è possibile ottenere un token di autorizzazione usando la richiesta seguente:

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 acquisisce l'ID risorsa di Azure per cui viene segnalata 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.

Area

La proprietà region acquisisce l'area di Azure in cui viene distribuita la risorsa per cui si stanno creando metriche. Le metriche devono essere generate nello stesso endpoint a livello di area di Monitoraggio di Azure dell'area in cui viene distribuita la risorsa. 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. Questo timestamp acquisisce la data e l'ora in cui 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, potresti avere uno spazio dei nomi denominato contosomemorymetrics che tiene traccia delle metriche di utilizzo della memoria che profila l'app. Un altro spazio dei nomi denominato contosoapptransaction potrebbe 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 in 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 relative alla metrica che viene raccolta. Usando le altre caratteristiche, è possibile raccogliere altre informazioni sulla metrica, che consente informazioni più approfondite.

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. Una metrica personalizzata può avere fino a 10 dimensioni.

Valori di dimensione

Quando si segnala un punto dati della metrica, per ogni chiave della dimensione nella metrica segnalata è presente un valore di dimensione corrispondente. Ad esempio, è possibile 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 di metrica, è possibile specificare solo un singolo valore della dimensione per ogni chiave della 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. In alternativa, potrebbe 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, preaggregare localmente e generare i valori aggregati:

• 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 sono presenti quattro transazioni di accesso all'app durante un minuto, le latenze misurate risultanti per ognuna potrebbero 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 sarà quindi:

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

Se l'applicazione non può preaggregare localmente e deve generare ogni campione o evento discreto immediatamente dopo la 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. Pertanto, per una transazione di accesso che ha richiesto 12 millisecondi, la pubblicazione delle metriche sarà:

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

Con questo processo, è possibile generare più valori per la stessa combinazione metrica/dimensione durante un determinato minuto. Monitoraggio di Azure accetta quindi tutti i valori non elaborati generati per un determinato minuto e li aggrega.

Pubblicazione di metrica personalizzata di esempio

Nell'esempio seguente creare una metrica personalizzata denominata Byte di memoria in Usare nel profilo di memoria dello spazio dei nomi delle metriche 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 si tratti degli ultimi 20 minuti. Non è possibile inserire una metrica nell'archivio di più 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 per cui si stanno creando metriche.

• resourceId: ID risorsa della risorsa di Azure in cui si sta monitorando la metrica.

• 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.

   

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 Usa.

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 emettere metriche rispetto a una sottoscrizione o a un gruppo di risorse o a una risorsa, verificare che all'applicazione o all'entità servizio sia assegnato il ruolo server di pubblicazione Metriche di monitoraggio in Controllo di accesso (IAM).
• Verificare che il numero di nomi delle dimensioni corrisponda al numero di valori.
• Verificare di aver creato metriche per l'endpoint 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 sia compreso 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.