Partilhar via

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

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.

Observação

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 ao Azure Monitor, a entidade que envia a métrica precisa de um token válido do Microsoft Entra no cabeçalho Bearer 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 principal 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.

Sugestão

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

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 utilizando um dos seguintes métodos:

  • CLI
  • API REST
  • SDK

Ao solicitar um token, é necessário fornecer um parâmetro resource. O parâmetro resource é o URL do recurso que você deseja aceder.

Recursos incluem:

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

Obtenha um token usando uma solicitação REST

Utilize a seguinte chamada de API REST para obter um token. Esta solicitação utiliza uma identificação de cliente e um segredo de cliente para autenticar a solicitação. O ID do cliente e o segredo do cliente são obtidos quando você regista a sua aplicação com o Microsoft Entra ID. Para mais informações, consulte Registar uma Aplicação 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 de sujeito captura o ID de recurso do Azure para o qual 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.

Observação

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

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 na mesma 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 desta região. As informações da região também são codificadas na URL da chamada da API.

Data e Hora

Cada ponto de dados enviado para o Azure Monitor deve ser marcado com um carimbo de data/hora. Este carimbo temporal captura a data e a hora em que o valor da métrica é medido ou coletado. O Azure Monitor aceita dados métricos com timestamps de até 20 minutos no passado e até 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

Ao relatar um dado métrico, para cada chave de dimensão na métrica reportada, 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 for coletada a mesma utilização de memória para vários processos na VM, poderão ser relatados vários valores de métricas para esse carimbo de data/hora. Cada valor de métrica especificaria um valor de dimensão diferente para a chave de dimensão do 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.

Observação

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:

  • min: 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. Entre 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.

Soluçã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.

Próximos passos

Saiba mais sobre métricas personalizadas.

  • Last updated on