Biblioteca de cliente do Azure Monitor Query Metrics para JavaScript - versão 1.0.0

A biblioteca de cliente de Métricas de Consulta do Azure Monitor é usada para executar consultas somente leitura na plataforma de dados de métricas do Azure Monitor:

Métricas - Coleta dados numéricos de recursos monitorados em um banco de dados de séries temporais. As métricas são valores numéricos que são coletados em intervalos regulares e descrevem algum aspeto de um sistema em um determinado momento. As métricas são leves e capazes de suportar cenários quase em tempo real, tornando-as úteis para alertas e deteção rápida de problemas.

Migrando de @azure/monitor-query advisory ⚠️

Confira o Guia de Migração para obter instruções detalhadas sobre como atualizar o código do aplicativo do pacote original @azure/monitor-query para a @azure/monitor-query-metrics biblioteca.

Recursos:

Como Começar

Ambientes suportados

Versões LTS do Node.js
Versões mais recentes do Safari, Chrome, Microsoft Edge e Firefox

Para mais informações, consulte a nossa política de suporte.

Pré-requisitos

Uma assinatura do Azure
Uma implementação de TokenCredential, como um tipo de credencial da biblioteca Azure Identity do .
Para consultar Métricas, você precisa de um recurso do Azure de qualquer tipo (Conta de Armazenamento, Cofre de Chaves, Cosmos DB, etc.).

Instale o pacote

Instale a biblioteca de cliente Azure Monitor Query Metrics para JavaScript com npm:

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

Criar o cliente

Um cliente autenticado é necessário para consultar Métricas. Para autenticar, o exemplo a seguir usa DefaultAzureCredential do pacote @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);

Configurar o cliente para a nuvem soberana do Azure

Por padrão, os clientes da biblioteca são configurados para usar a Nuvem Pública do Azure. Para usar uma nuvem soberana em vez disso, forneça o valor correto de ponto de extremidade e audiência ao instanciar um cliente. Por exemplo:

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",
});

Executar a consulta

Para obter exemplos de consultas de métricas, consulte a seção Exemplos .

Conceitos-chave

Estrutura de dados de métricas

Cada conjunto de valores métricos é uma série temporal com as seguintes características:

O momento em que o valor foi recolhido
O recurso associado ao valor
Um namespace que atua como uma categoria para a métrica
Um nome de métrica
O valor em si
Algumas métricas têm várias dimensões, conforme descrito em métricas multidimensionais. As métricas personalizadas podem ter até 10 dimensões.

Exemplos

Consulta de métricas
- Manipular a resposta da consulta de métricas

Consulta de métricas

Para consultar métricas para um ou mais recursos do Azure, use o queryResources método de MetricsClient. Esse método requer um ponto de extremidade regional ao criar o cliente. Por exemplo, https://westus3.metrics.monitor.azure.com.

Cada recurso do Azure deve residir em:

A mesma região que o ponto de extremidade especificado ao criar o cliente.
A mesma assinatura do Azure.

As IDs de recurso devem ser as dos recursos para os quais as métricas estão sendo consultadas. Normalmente é do formato /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Para localizar o ID/URI do recurso:

Navegue até a página do seu recurso no portal do Azure.
Selecione o link Visualização JSON na seção Visão geral .
Copie o valor na caixa de texto ID do recurso na parte superior do modo de exibição JSON.

Além disso:

O usuário deve estar autorizado a ler dados de monitoramento no nível de assinatura do Azure. Por exemplo, a função Leitor de monitoramento na assinatura a ser consultada.
O namespace de métrica que contém as métricas a serem consultadas deve ser fornecido. Para obter uma lista de namespaces de métrica, consulte Métricas suportadas e categorias de log por tipo de recurso.

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}`);
}

Manipular a resposta da consulta de métricas

A API de consulta de métricas retorna uma lista de MetricsQueryResult objetos. O MetricsQueryResult objeto contém propriedades como uma lista de Metricobjetos -typed, granularity, namespacee timespan. A Metric lista de objetos pode ser acessada usando a metrics propriedade. Cada Metric objeto nesta lista contém uma lista de TimeSeriesElement objetos. Cada TimeSeriesElement objeto contém data e metadatavalues propriedades. Na forma visual, a hierarquia de objetos da resposta é semelhante à seguinte estrutura:

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)

Observação: Cada MetricsQueryResult um é retornado na mesma ordem que o recurso correspondente no resourceIds parâmetro. Se várias métricas diferentes forem consultadas, as métricas serão retornadas na ordem do metricNames envio.

Exemplo de manipulação da resposta:

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}`);
  }
}

Para obter um inventário de métricas e dimensões disponíveis para cada tipo de recurso do Azure, consulte Métricas suportadas com o Azure Monitor.

Solução de problemas

Para diagnosticar vários cenários de falha, consulte o guia de solução de problemas.

Próximos passos

Para saber mais sobre o Azure Monitor, consulte a documentação do serviço Azure Monitor.

Contribuir

Se você quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Os testes deste módulo são uma mistura de testes ao vivo e de unidade, que exigem que você tenha uma instância do Azure Monitor. Para executar os testes, você precisará executar:

rush update
rush build -t @azure/monitor-query-metrics
cd into sdk/monitor/monitor-query-metrics
Copie o sample.env ficheiro para .env
Abra o .env arquivo em um editor e preencha os valores.
npm run test.

Para mais detalhes, consulte a nossa pasta de testes .

Feedback

Esta página foi útil?

Last updated on 2025-08-13