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

  • Artigo

Esse artigo mostra como enviar métricas personalizadas de recursos do Azure para o armazenamento de métricas do Azure Monitor por meio da API REST. Quando as métricas estiverem no Azure Monitor, você poderá fazer com elas tudo o que faz com as métricas padrão. Por exemplo, é possível gerar gráficos e alertas e encaminhar as métricas para outras ferramentas externas.

Observação

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

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

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

Autenticação

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

  • Identidades gerenciadas para recursos do Azure. Você pode usar uma identidade gerenciada para dar permissões aos 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 de 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 do 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 de aplicativo usando chaves públicas do Microsoft Entra. A função existente do Monitoring Metrics Publisher já tem essa permissão. Ele está disponível no portal do Azure.

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

Dica

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

Use um token de autorização

Depois de criar sua identidade gerenciada ou entidade de serviço e atribuir permissões de Monitoring Metrics Publisher, você poderá obter um token de autorização usando a seguinte solicitação:

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 solicitações HTTP a seguir.

Assunto

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

Observação

Você não pode emitir métricas personalizadas contra o ID do recurso de um grupo de recursos ou assinatura.

Região

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

Timestamp

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

Namespace

Namespaces são uma maneira de categorizar ou agrupar métricas semelhantes. Ao usar 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 monitora as métricas de uso de memória que formam o perfil do seu aplicativo. Outro namespace, chamado contosoapptransaction, pode rastrear todas as métricas sobre transações do usuário em seu aplicativo.

Nome

É o nome da métrica que está sendo relatada. Normalmente, o nome é descritivo para ajudar a identificar o que está sendo medido. Um exemplo é uma métrica que mede o número de bytes de memória usados em uma VM. Pode ter um nome de métrica como Memory Bytes In Use.

Chaves 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 Memory Bytes In Use pode ter uma chave de dimensão chamada Process que captura quantos bytes de memória cada processo em uma VM consome. Usando essa chave, você pode filtrar a métrica para ver quantos processos específicos de memória usam ou para identificar os cinco principais processos pelo uso da 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é dez dimensões.

Valores de dimensão

Ao relatar um ponto de dados de métrica, para cada chave de dimensão na métrica que está sendo relatada, há um valor de dimensão correspondente. Por exemplo, você pode querer relatar a memória usada pelo ContosoApp em sua VM:

  • O nome da métrica seria Bytes de Memória em Uso.
  • A chave de dimensão seria processo.
  • O valor da dimensão seria ContosoApp.exe .

Ao publicar um valor de métrica, você pode especificar apenas um 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 registro de data e hora. Cada valor de métrica especificaria um valor de dimensão diferente para a chave de dimensão Process.

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

Valores métricos

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

Para limitar o número de valores brutos que você precisa emitir e pagar no Azure Monitor, faça uma pré-agregação local dos valores e emita os valores agregados:

  • Mín.: O valor mínimo observado de todas as amostras e medições durante o minuto.
  • Máx: O valor máximo observado de todas as amostras e medições durante o minuto.
  • Sum: A soma de todos os valores observados de todas as amostras e medições durante o minuto.
  • Contar: o número de amostras e medições feitas durante o minuto.

Observação

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

Por exemplo, se há quatro transações de conexão em seu aplicativo durante um minuto, as latências medidas resultantes para cada um podem ser:

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

Assim, a publicação de métrica resultante para o Azure Monitor seria:

  • Mín.: 4
  • Máx.: 16
  • Soma: 40
  • Contagem: 4

Se o seu aplicativo não é capaz de pré-agregar localmente e precisa emitir cada exemplo ou evento separado imediatamente após a coleta, você pode emitir os valores de medida brutos. Por exemplo, toda vez que uma transação de login ocorre no seu aplicativo, você publica uma métrica no Monitor do Azure com apenas uma única medida. Portanto, para uma transação de login que levou 12 milissegundos, a publicação de 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 de métrica e dimensão durante determinado minuto. O Azure Monitor pega todos os valores brutos emitidos por determinado minuto e os agrega.

Publicação de métrica personalizada de exemplo

No exemplo a seguir, crie uma métrica personalizada chamada Memory Bytes in Use no namespace da métrica Memory Profile para uma máquina virtual. A métrica tem uma única dimensão chamada Process. Para o carimbo de data/hora, os valores de métrica 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 esteja dentro dos últimos 20 minutos. Não é possível colocar no repositório uma métrica 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á acompanhando a métrica.

  • accessToken: O token de autorização adquirido na 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

Exibir as métricas

  1. Entre no portal do Azure.

  2. No menu à esquerda, selecione Monitor.

  3. Sobre o Monitor página, selecione métricas.

    Screenshot that shows how to select Metrics in the Azure portal.

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

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

  6. Na lista suspensa Namespace de Métrica, selecione Perfil de Memória.

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

Solução de problemas

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

  • Se não for possível emitir métricas para uma assinatura, grupo de recursos ou recurso, verifique se o aplicativo ou a entidade de serviço tem a função de Editor de métricas de monitoramento atribuída em Controle de acesso (IAM).
  • Verifique se o número de nomes de dimensão corresponde ao número de valores.
  • Verifique se está a emitir métricas para o ponto de extremidade regional correto do Azure Monitor. Por exemplo, se o seu recurso for implantado no oeste dos EUA, você deverá emitir métricas para o ponto de extremidade regional do oeste dos EUA.
  • Verifique se o carimbo de data/hora está nos ú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óximas etapas

Saiba mais sobre métricas personalizadas.