Libreria client di Monitoraggio di Azure Query Metrics per JavaScript - versione 1.0.0

La libreria client delle metriche di query di Monitoraggio di Azure viene usata per eseguire query di sola lettura sulla piattaforma dati delle metriche di Monitoraggio di Azure:

Metriche : raccoglie i dati numerici dalle risorse monitorate in un database di serie temporali. Le metriche sono valori numerici che vengono raccolti a intervalli regolari e che descrivono un aspetto di un sistema in un determinato momento. Le metriche sono leggere e in grado di supportare scenari quasi in tempo reale, il che le rende utili per gli avvisi e il rilevamento rapido dei problemi.

Migrazione dall'advisory @azure/monitor-query⚠️

Consulta la Guida alla migrazione per istruzioni dettagliate su come aggiornare il codice dell'applicazione dal pacchetto originale @azure/monitor-query alla @azure/monitor-query-metrics libreria.

Risorse:

Come iniziare

Ambienti supportati

Versioni LTS di Node.js
Ultime versioni di Safari, Chrome, Microsoft Edge e Firefox

Per ulteriori informazioni, consulta la nostra politica di supporto.

Prerequisiti

Una sottoscrizione di Azure
Un'implementazione di TokenCredential, come un tipo di credenziale della libreria Azure Identity .
Per eseguire query sulle metriche, è necessaria una risorsa di Azure di qualsiasi tipo (account di archiviazione, Key Vault, Cosmos DB e così via).

Installare il pacchetto

Installare la libreria client Query Metrics di Monitoraggio di Azure per JavaScript con npm:

npm install --save @azure/monitor-query-metrics

Creare il client

Per eseguire query sulle metriche è necessario un client autenticato. Per eseguire l'autenticazione, nell'esempio seguente viene usato DefaultAzureCredential dal pacchetto @azure/identity .

import { DefaultAzureCredential } from "@azure/identity";
import { MetricsClient } from "@azure/monitor-query-metrics";

const credential = new DefaultAzureCredential();

// Create a MetricsClient
const endpoint = " https://<endpoint>.monitor.azure.com/";
const metricsClient = new MetricsClient(endpoint, credential);

Configurare il client per il cloud sovrano di Azure

Per impostazione predefinita, i client della libreria sono configurati per l'uso del cloud pubblico di Azure. Per usare invece un cloud sovrano, fornire il valore corretto dell'endpoint e del gruppo di destinatari durante la creazione di un'istanza di un client. Per esempio:

import { DefaultAzureCredential } from "@azure/identity";
import { MetricsClient } from "@azure/monitor-query-metrics";

const credential = new DefaultAzureCredential();

// Create a MetricsClient
const endpoint = " https://<endpoint>.monitor.azure.cn/";
const metricsClient = new MetricsClient(endpoint, credential, {
  audience: "https://monitor.azure.cn/.default",
});

Esecuzione della query

Per esempi di query sulle metriche, vedere la sezione Esempi .

Concetti chiave

Struttura dei dati delle metriche

Ogni set di valori metrici è una serie temporale con le caratteristiche seguenti:

Ora in cui è stato raccolto il valore
La risorsa associata al valore
Spazio dei nomi che funge da categoria per la metrica
Nome della metrica
Valore stesso
Alcune metriche hanno più dimensioni, come descritto in Metriche multidimensionali. Le metriche personalizzate possono avere fino a 10 dimensioni.

Esempi

Query sulle metriche
- Gestire la risposta alle query sulle metriche

Query sulle metriche

Per eseguire query sulle metriche per una o più risorse di Azure, utilizzare il queryResources metodo di MetricsClient. Questo metodo richiede un endpoint a livello di area durante la creazione del client. Ad esempio: https://westus3.metrics.monitor.azure.com.

Ogni risorsa di Azure deve risiedere in:

La stessa area dell'endpoint specificato durante la creazione del client.
La stessa sottoscrizione di Azure.

Gli ID risorsa devono essere quelli delle risorse per le quali vengono eseguite query sulle metriche. Normalmente è del formato /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Per trovare l'ID/URI della risorsa:

Passare alla pagina della risorsa nel portale di Azure.
Selezionare il collegamento Visualizzazione JSON nella sezione Panoramica .
Copiare il valore nella casella di testo ID risorsa nella parte superiore della visualizzazione JSON.

Inoltre:

L'utente deve essere autorizzato a leggere i dati di monitoraggio a livello di sottoscrizione di Azure. Ad esempio, il ruolo Lettore monitoraggio nella sottoscrizione su cui eseguire query.
È necessario specificare lo spazio dei nomi delle metriche contenente le metriche su cui eseguire query. Per un elenco degli spazi dei nomi delle metriche, vedere Metriche supportate e categorie di log per tipo di risorsa.

import { DefaultAzureCredential } from "@azure/identity";
import { MetricsClient } from "@azure/monitor-query-metrics";

const resourceIds = [
  "/subscriptions/0000000-0000-000-0000-000000/resourceGroups/test/providers/Microsoft.OperationalInsights/workspaces/test-logs",
  "/subscriptions/0000000-0000-000-0000-000000/resourceGroups/test/providers/Microsoft.OperationalInsights/workspaces/test-logs2",
];
const metricsNamespace = "Microsoft.OperationalInsights/workspaces";
const metricNames = ["Heartbeat"];
const endpoint = "https://westus3.metrics.monitor.azure.com";

const credential = new DefaultAzureCredential();
const metricsClient = new MetricsClient(endpoint, credential);

const result = await metricsClient.queryResources(resourceIds, metricNames, metricsNamespace, {
  aggregation: "Count",
});

console.log(`Retrieved metrics for ${result.length} resources`);
for (const resource of result) {
  console.log(`Resource: ${resource.resourceId}`);
  console.log(`Metrics: ${resource.metrics.length}`);
}

Gestire la risposta alle query sulle metriche

L'API di query delle metriche restituisce un elenco di MetricsQueryResult oggetti. L'oggetto MetricsQueryResult contiene proprietà quali un elenco di Metricoggetti tipizzati, granularity, namespace, e timespan. È possibile accedere all'elenco Metric degli oggetti utilizzando la metrics proprietà. Ogni Metric oggetto in questo elenco contiene un elenco di TimeSeriesElement oggetti. Ogni TimeSeriesElement oggetto contiene data e metadatavalues proprietà. In forma visiva, la gerarchia degli oggetti della risposta è simile alla struttura seguente:

MetricsQueryResult
|---granularity
|---timespan
|---cost
|---namespace
|---resourceRegion
|---metrics (list of `Metric` objects)
    |---id
    |---type
    |---name
    |---unit
    |---timeseries (list of `TimeSeriesElement` objects)
        |---metadatavalues
        |---data (list of data points)

Nota: Ognuno MetricsQueryResult viene restituito nello stesso ordine della risorsa corrispondente nel resourceIds parametro. Se vengono eseguite query su più metriche diverse, le metriche vengono restituite nell'ordine in cui sono metricNames state inviate.

Esempio di gestione della risposta:

import { DefaultAzureCredential } from "@azure/identity";
import { MetricsClient, Durations } from "@azure/monitor-query-metrics";

const resourceIds = [
  "/subscriptions/0000000-0000-000-0000-000000/resourceGroups/test/providers/Microsoft.OperationalInsights/workspaces/test-logs",
];
const metricsNamespace = "Microsoft.OperationalInsights/workspaces";
const metricNames = ["Heartbeat"];
const endpoint = "https://westus3.metrics.monitor.azure.com";

const credential = new DefaultAzureCredential();
const metricsClient = new MetricsClient(endpoint, credential);

const endTime = new Date();
const startTime = new Date(endTime.getTime() - 60 * 60 * 1000); // 1 hour ago

const result = await metricsClient.queryResources(resourceIds, metricNames, metricsNamespace, {
  aggregation: "Count,Average", // Multiple aggregations
  startTime: startTime,
  endTime: endTime,
  interval: Durations.fiveMinutes,
  top: 10, // Limit results
  orderBy: "count desc", // Sort by count descending
  filter: "Computer eq '*'", // Filter criteria
});

console.log(`Retrieved ${result.length} resources with advanced filtering`);
for (const resource of result) {
  for (const metric of resource.metrics) {
    console.log(`Metric: ${metric.name}`);
    console.log(`Time series count: ${metric.timeseries.length}`);
  }
}

Per un inventario delle metriche e delle dimensioni disponibili per ogni tipo di risorsa di Azure, vedere Metriche supportate con Monitoraggio di Azure.

Risoluzione dei problemi

Per diagnosticare vari scenari di errore, vedere la guida alla risoluzione dei problemi.

Passaggi successivi

Per altre informazioni su Monitoraggio di Azure, vedere la documentazione del servizio Monitoraggio di Azure.

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

I test di questo modulo sono una combinazione di test live e unit test, che richiedono la presenza di un'istanza di Monitoraggio di Azure. Per eseguire i test, è necessario eseguire:

rush update
rush build -t @azure/monitor-query-metrics
cd into sdk/monitor/monitor-query-metrics
Copia il sample.env file in .env
Aprire il .env file in un editor e inserire i valori.
npm run test.

Per maggiori dettagli, consulta la nostra cartella dei test .

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-08-13