Partilhar via

Ingerir métricas personalizadas para um recurso do Azure usando a API REST

  • Artigo

Este artigo mostra como enviar métricas personalizadas para recursos do Azure para o repositório de métricas do Azure Monitor por meio da API REST. Quando as métricas estão no Azure Monitor, você pode fazer todas as coisas com elas que faz com métricas padrão. Por exemplo, você pode gerar gráficos e alertas e rotear as métricas para outras ferramentas externas.

Nota

A API REST só permite o envio de métricas personalizadas para recursos do Azure. Para enviar métricas para recursos em outros ambientes ou no local, use o Application Insights.

Enviar solicitações REST para ingerir métricas personalizadas

Quando você envia métricas personalizadas para o Azure Monitor, cada ponto de dados, ou valor, relatado nas métricas deve incluir as seguintes informações.

Autenticação

Para enviar métricas personalizadas para o Azure Monitor, a entidade que envia a métrica precisa de um token válido do Microsoft Entra no cabeçalho Portador da solicitação. As formas suportadas de adquirir um token de portador válido incluem:

  • Identidades gerenciadas para recursos do Azure. Você pode usar uma identidade gerenciada para conceder permissões de recursos para executar determinadas operações. Um exemplo é permitir que um recurso emita métricas sobre si mesmo. Um recurso, ou sua identidade gerenciada, pode receber permissões do Monitoring Metrics Publisher em outro recurso. Com essa permissão, a identidade gerenciada também pode emitir métricas para outros recursos.

  • Entidade de serviço Microsoft Entra. Nesse cenário, um aplicativo ou serviço do Microsoft Entra pode receber permissões para emitir métricas sobre um recurso do Azure. Para autenticar a solicitação, o Azure Monitor valida o token do aplicativo usando chaves públicas do Microsoft Entra. A função existente de Publicador de Métricas de Monitoramento já tem essa permissão. Está disponível no portal do Azure.

    A entidade de serviço, dependendo dos recursos para os quais emite métricas personalizadas, pode receber a função de Publicador de Métricas de Monitoramento no escopo necessário. Exemplos são uma assinatura, grupo de recursos ou recurso específico.

Gorjeta

Quando você solicitar um token do Microsoft Entra para emitir métricas personalizadas, verifique se o público ou recurso para o qual o token é solicitado é https://monitoring.azure.com/. Certifique-se de incluir a barra à direita.

Obter um token de autorização

Depois de criar sua identidade gerenciada ou entidade de serviço e atribuir permissões do Monitoring Metrics Publisher , você pode obter um token de autorização. Ao solicitar um token, especifique resource: https://monitoring.azure.com.

Obtenha um token de autenticação usando qualquer um dos seguintes métodos:

  • CLI
  • API REST
  • SDK

Ao solicitar um token, você deve fornecer um resource parâmetro. O resource parâmetro é a URL do recurso que você deseja acessar.

Os recursos incluem:

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

Obter um token usando uma solicitação REST

Use a seguinte chamada à API REST para obter um token. Essa solicitação usa uma ID do cliente e um segredo do cliente para autenticar a solicitação. A ID do cliente e o segredo do cliente são obtidos quando você registra seu aplicativo com o Microsoft Entra ID. Para obter mais informações, consulte Registrar um aplicativo para solicitar tokens de autorização e trabalhar com APIs

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'

O corpo da resposta aparece no seguinte formato:

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

Salve o token de acesso da resposta para uso nas seguintes solicitações HTTP.

Assunto

A propriedade subject captura para qual ID de recurso do Azure a métrica personalizada é relatada. Essas informações são codificadas na URL da chamada da API. Cada API pode enviar valores de métrica para apenas um único recurso do Azure.

Nota

Não é possível emitir métricas personalizadas em relação à ID de recurso de um grupo de recursos ou assinatura.

País/Região

A propriedade region captura a região do Azure para a qual o recurso para o qual você está emitindo métricas é implantado. As métricas devem ser emitidas para o mesmo ponto de extremidade regional do Azure Monitor que a região onde o recurso é implantado. Por exemplo, métricas personalizadas para uma VM implantada no oeste dos EUA devem ser enviadas para o ponto de extremidade regional do Azure Monitor do WestUS. As informações da região também são codificadas na URL da chamada da API.

Carimbo de Data/Hora

Cada ponto de dados enviado para o Azure Monitor deve ser marcado com um carimbo de data/hora. Esse carimbo de data/hora captura a data e a hora em que o valor da métrica é medido ou coletado. O Azure Monitor aceita dados métricos com carimbos de data/hora de até 20 minutos no passado e 5 minutos no futuro. O carimbo de data/hora deve estar no formato ISO 8601.

Espaço de Nomes

Os namespaces são uma maneira de categorizar ou agrupar métricas semelhantes. Usando namespaces, você pode obter isolamento entre grupos de métricas que podem coletar diferentes insights ou indicadores de desempenho. Por exemplo, você pode ter um namespace chamado contosomemorymetrics que rastreia métricas de uso de memória que traçam o perfil do seu aplicativo. Outro namespace chamado contosoapptransaction pode controlar todas as métricas sobre transações de usuário em seu aplicativo.

Nome

A propriedade name é o nome da métrica que está sendo relatada. Normalmente, o nome é descritivo o suficiente para ajudar a identificar o que é medido. Um exemplo é uma métrica que mede o número de bytes de memória usados em uma VM. Ele pode ter um nome de métrica como Bytes de memória em uso.

Teclas de dimensão

Uma dimensão é um par chave/valor que ajuda a descrever outras características sobre a métrica que está sendo coletada. Usando as outras características, você pode coletar mais informações sobre a métrica, o que permite insights mais profundos.

Por exemplo, a métrica Bytes de memória em uso pode ter uma chave de dimensão chamada Processo que captura quantos bytes de memória cada processo em uma VM consome. Usando essa chave, você pode filtrar a métrica para ver a quantidade de memória que processos específicos usam ou para identificar os cinco principais processos por uso de memória.

As dimensões são opcionais e nem todas as métricas têm dimensões. Uma métrica personalizada pode ter até 10 dimensões.

Valores de dimensão

Quando você está relatando um ponto de dados de métrica, para cada chave de dimensão na métrica relatada, há um valor de dimensão correspondente. Por exemplo, talvez você queira relatar a memória que ContosoApp usa em sua VM:

  • O nome da métrica seria Memory Bytes in Use.
  • A chave da dimensão seria Processo.
  • O valor da dimensão seria ContosoApp.exe.

Ao publicar um valor de métrica, você pode especificar apenas um único valor de dimensão por chave de dimensão. Se você coletar a mesma utilização de memória para vários processos na VM, poderá relatar vários valores de métrica para esse carimbo de data/hora. Cada valor de métrica especificaria um valor de dimensão diferente para a chave de dimensão Processo .

Embora as dimensões sejam opcionais, se uma postagem métrica definir chaves de dimensão, os valores de dimensão correspondentes serão obrigatórios.

Valores de métricas

O Azure Monitor armazena todas as métricas em intervalos de granularidade de 1 minuto. Durante um determinado minuto, uma métrica pode precisar ser amostrada várias vezes. A utilização da CPU é um exemplo. Ou uma métrica pode precisar ser medida para muitos eventos discretos, como latências de transação de entrada.

Para limitar o número de valores brutos que você precisa emitir e pagar no Azure Monitor, pré-agregar e emitir localmente os valores agregados:

  • Min: O valor mínimo observado de todas as amostras e medições durante o minuto.
  • Max: O valor máximo observado de todas as amostras e medições durante o minuto.
  • Soma: A soma de todos os valores observados de todas as amostras e medições durante o minuto.
  • Contagem: O número de amostras e medições tomadas durante o minuto.

Nota

O Azure Monitor não dá suporte à definição de Unidades para uma métrica personalizada.

Por exemplo, se houver quatro transações de entrada em seu aplicativo durante um minuto, as latências medidas resultantes para cada uma podem ser:

Transação 1 Transação 2 Transação 3 Transação 4
7 ms 4 ms 13 ms 16 ms

Em seguida, a publicação de métrica resultante no Azure Monitor seria:

  • MÍN: 4
  • Máx: 16
  • Soma: 40
  • Contagem: 4

Se seu aplicativo não puder pré-agregar localmente e precisar emitir cada amostra ou evento discreto imediatamente após a coleta, você poderá emitir os valores brutos de medida. Por exemplo, cada vez que ocorre uma transação de entrada em seu aplicativo, você publica uma métrica no Azure Monitor com apenas uma única medição. Assim, para uma transação de entrada que levou 12 milissegundos, a publicação métrica seria:

  • MÍN: 12
  • Máx: 12
  • Soma: 12
  • Contagem: 1

Com esse processo, você pode emitir vários valores para a mesma combinação métrica/dimensão durante um determinado minuto. Em seguida, o Azure Monitor pega todos os valores brutos emitidos por um determinado minuto e os agrega.

Exemplo de publicação de métrica personalizada

No exemplo a seguir, crie uma métrica personalizada chamada Memory Bytes in Use sob o namespace métrico Memory Profile para uma máquina virtual. A métrica tem uma única dimensão chamada Processo. Para o carimbo de data/hora, os valores métricos são emitidos para dois processos.

Armazene o JSON a seguir em um arquivo chamado custommetric.json em seu computador local. Atualize o parâmetro de tempo para que fique nos últimos 20 minutos. Não é possível colocar uma métrica na loja com mais de 20 minutos.

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

Envie a seguinte solicitação HTTP POST usando as seguintes variáveis:

  • location: região de implantação do recurso para o qual você está emitindo métricas.

  • resourceId: ID do recurso do Azure contra o qual você está rastreando a métrica.

  • accessToken: O token de autorização adquirido da etapa Obter um token de autorização.

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

Veja suas métricas

  1. Inicie sessão no portal do Azure.

  2. No menu à esquerda, selecione Monitor.

  3. Na página Monitor, selecione Métricas.

    Captura de tela que mostra como selecionar Métricas no portal do Azure.

  4. Altere o período de agregação para Última hora.

  5. Na lista suspensa Escopo, selecione o recurso para o qual você envia a métrica.

  6. Na lista suspensa Metric Namespace, selecione Memory Profile.

  7. Na lista suspensa Métrica, selecione Bytes de memória em uso.

Resolução de Problemas

Se você receber uma mensagem de erro com alguma parte do processo, considere as seguintes informações de solução de problemas:

  • Se você não puder emitir métricas em relação a uma assinatura ou grupo de recursos, ou recurso, verifique se seu aplicativo ou entidade de serviço tem a função de Editor de Métricas de Monitoramento atribuída no Controle de acesso (IAM).
  • Verifique se o número de nomes de dimensão corresponde ao número de valores.
  • Verifique se você está emitindo métricas para o ponto de extremidade regional correto do Azure Monitor. Por exemplo, se o recurso for implantado no oeste dos EUA, você deverá emitir métricas para o ponto de extremidade regional oeste dos EUA.
  • Verifique se o carimbo de data/hora está dentro dos últimos 20 minutos.
  • Verifique se o carimbo de data/hora está no formato ISO 8601.
  • Verifique se o nome da métrica é válido. Por exemplo, não pode conter espaços.

Próximos passos

Saiba mais sobre métricas personalizadas.