Tutorial: Monitorizar as APIs publicadas

APLICA-SE A: Todas as camadas de gerenciamento de API

Com o Azure Monitor, pode visualizar, consultar, encaminhar, arquivar e tomar medidas relativamente a métricas ou registos provenientes do serviço Gestão de API do Azure. Para obter uma visão geral do Azure Monitor for API Management, consulte Monitor API Management.

Gorjeta

As equipes de API podem usar esse recurso em espaços de trabalho. Os espaços de trabalho fornecem acesso administrativo isolado às APIs e possuem os seus próprios ambientes de execução de API.

Neste tutorial, irá aprender a:

• Ver métricas da API
• Configurar uma regra de alerta
• Ver registos de atividades
• Habilitar e exibir logs de recursos

Nota

O Gerenciamento de API suporta uma variedade de ferramentas adicionais para observar APIs, incluindo análises internas e integração com o Application Insights. Mais informações

Pré-requisitos

• Conhecer a terminologia da Gestão de API do Azure.
• Conclua o guia de início rápido seguinte: Criar uma instância da Gestão de API do Azure.
• Conclua também o tutorial seguinte: Importar e publicar a sua primeira API.

Ver métricas das APIs

O Gerenciamento de API emite métricas a cada minuto, oferecendo visibilidade quase em tempo real do estado e da integridade de suas APIs. A seguir estão as métricas usadas com mais frequência. Para obter uma lista de todas as métricas disponíveis, consulte Métricas.

• Capacidade - ajuda você a tomar decisões sobre upgrade/downgrade de seus serviços de Gerenciamento de API. A métrica é emitida por minuto e reflete a capacidade estimada do gateway no momento do relatório. A métrica varia de 0 a 100 calculada com base em recursos de gateway, como utilização de CPU e memória e outros fatores.

  Gorjeta

  Nas camadas de serviço v2 e nos gateways de espaço de trabalho, o Gerenciamento de API substituiu a métrica de capacidade do gateway por métricas separadas de utilização de CPU e memória. Essas métricas também podem ser usadas para decisões de dimensionamento e solução de problemas. Mais informações

• Solicitações - ajuda você a analisar o tráfego de API que passa pelos serviços de Gerenciamento de API. A métrica é emitida por minuto e informa o número de solicitações de gateway com dimensões. Filtre solicitações por códigos de resposta, local, nome do host e erros.

Nota

A métrica Solicitações não está disponível em espaços de trabalho.

Importante

As seguintes métricas foram desativadas: Total de solicitações de gateway, solicitações de gateway bem-sucedidas, solicitações de gateway não autorizadas, solicitações de gateway com falha, outras solicitações de gateway. Migre para a métrica Solicitações, que fornece funcionalidade muito semelhante.

Para aceder a métricas:

1. No portal do Azure, navegue até sua instância de Gerenciamento de API. Na página Visão geral, na guia Monitor, revise as principais métricas de suas APIs.

2. Para investigar métricas em detalhes, selecione Monitoramento>de métricas no menu à esquerda.

   

   Gorjeta

   Num espaço de trabalho, pode ver métricas de capacidade relacionadas a um gateway desse espaço de trabalho. Navegue até Métricas de monitoramento> no menu esquerdo de um gateway de espaço de trabalho.

3. Na lista suspensa, selecione as métricas em que você está interessado. Por exemplo, Solicitações.

4. O gráfico mostra o número total de chamadas à API. Ajuste o intervalo de tempo para se concentrar em períodos de interesse.

5. Você pode filtrar o gráfico usando as dimensões da métrica Solicitações . Por exemplo, selecione Adicionar filtro, selecione Categoria de código de resposta de back-end, insira 500 como o valor. O gráfico mostra o número de solicitações com falha no back-end da API.

Configurar uma regra de alerta

Você pode receber alertas com base em métricas e registros de atividades. No Azure Monitor, configure uma regra de alerta para executar uma ação quando ela for acionada. As ações comuns incluem:

• Enviar uma notificação por e-mail
• Chamar um webhook
• Invocar uma Aplicação Lógica do Azure

Para configurar uma regra de alerta de exemplo com base em uma métrica de solicitação:

1. No portal do Azure, navegue até sua instância de Gerenciamento de API.

2. Selecione Monitoramento>de alertas no menu à esquerda.

   

3. Selecione + Criar>regra de alerta.

4. Na guia Condição:

   1. Em Nome do sinal, selecione Solicitações.
   2. Em Lógica de alerta, revise ou modifique os valores padrão do alerta. Por exemplo, atualize o Limite estático, que é o número de ocorrências após o qual o alerta deve ser acionado.
   3. Em Dividir por dimensões, em Nome da dimensão, selecione Categoria do Código de Resposta do Gateway.
   4. Em Valores de dimensão, selecione 4xx, para erros de cliente, como solicitações não autorizadas ou inválidas. Se o valor da dimensão não aparecer, selecione Adicionar valor personalizado e insira 4xx.
   5. Em Quando avaliar, aceite as configurações padrão ou selecione outras configurações para definir a frequência de execução da regra. Selecione Seguinte.

   

5. Na guia Ações, selecione ou crie um ou mais grupos de ações para notificar os usuários sobre o alerta e executar uma ação. Por exemplo, crie um novo grupo de ações para enviar um e-mail de notificação para .admin@contoso.com Para obter etapas detalhadas, consulte Criar e gerenciar grupos de ação no portal do Azure.

   

6. Na guia Detalhes de Criar uma regra de alerta, insira um nome e uma descrição da regra de alerta e selecione o nível de gravidade.

7. Opcionalmente, configure as configurações restantes. Em seguida, no separador Rever + criar , selecione Criar.

8. Opcionalmente, teste a regra de alerta usando um cliente HTTP para simular uma solicitação que dispara o alerta. Por exemplo, execute o seguinte comando em um terminal, substituindo o nome do host do Gerenciamento de API pelo nome do host da sua instância de Gerenciamento de API:

   curl GET https://contoso.azure-api.net/non-existent-endpoint HTTP/1.1 
   

   Um alerta é acionado com base no período de avaliação e ele enviará um e-mail para admin@contoso.com.

   Os alertas também aparecem na página Alertas da instância de Gerenciamento de API.

   

Registos de atividade

Os logs de atividades fornecem informações sobre as operações em seus serviços de Gerenciamento de API. Ao utilizar registos de atividades, pode determinar o "quê, quem e quando" de quaisquer operações de escrita (PUT, POST, DELETE) efetuadas nos seus serviços de Gestão de API.

Nota

Os logs de atividades não incluem operações de leitura (GET) ou operações executadas no portal do Azure.

Pode aceder aos registos de atividades no serviço de Gestão de API ou aceder aos registos de todos os recursos do Azure no Azure Monitor.

Para visualizar o registo de atividades:

1. No portal do Azure, navegue até sua instância de Gerenciamento de API.

2. Selecione Registro de atividades.

   

3. Selecione o escopo de filtragem desejado e, em seguida, Aplicar.

Registos do recurso

Os logs de recursos (logs do Azure Monitor) fornecem informações detalhadas sobre operações e erros de Gerenciamento de API que são importantes para fins de auditoria e solução de problemas. Quando habilitados por meio de uma configuração de diagnóstico, os logs coletam informações sobre as solicitações de API recebidas e processadas pelo gateway de Gerenciamento de API.

Nota

A camada Consumo não oferece suporte à coleta de logs de recursos.

Gorjeta

Em instâncias de Gerenciamento de API com espaços de trabalho, os logs federados no serviço de Gerenciamento de API podem ser acessados pela equipe da plataforma de API para monitoramento centralizado de APIs, enquanto as equipes de espaço de trabalho podem acessar os logs específicos das APIs de seus espaços de trabalho. Saiba mais sobre o registo do Azure Monitor com espaços de trabalho

Para configurar uma definição de diagnóstico para a recolha de logs de recursos:

1. No portal do Azure, navegue até sua instância de Gerenciamento de API.

2. No menu à esquerda, em Monitoramento, selecione Configurações de diagnóstico>+ Adicionar configuração de diagnóstico.

   

3. Na página Configuração de diagnóstico , insira ou selecione detalhes para a configuração:

   1. Nome da configuração de diagnóstico: insira um nome descritivo.
   2. Grupos de categorias: opcionalmente, faça uma seleção para o seu cenário.
   3. Em Categorias: Selecione uma ou mais categorias. Por exemplo, selecione Logs relacionados ao ApiManagement Gateway para coletar logs para a maioria das solicitações ao gateway de Gerenciamento de API.
   4. Em Detalhes do destino, selecione uma ou mais opções e especifique detalhes para o destino. Por exemplo, envie logs para um espaço de trabalho do Azure Log Analytics, arquive logs para uma conta de armazenamento ou transmita-os para um hub de eventos. Para obter mais informações, consulte Configurações de diagnóstico no Azure Monitor.
   5. Selecione Guardar.

   Gorjeta

   Se você selecionar um espaço de trabalho do Log Analytics, poderá optar por armazenar os dados em uma tabela específica de recursos (por exemplo, uma tabela ApiManagementGatewayLogs) ou armazenar na tabela geral AzureDiagnostics. Recomendamos que utilize a tabela específica do recurso para destinos de registo que a suportem. Mais informações

4. Depois de configurar os detalhes para o(s) destino(s) do log, selecione Salvar.

Nota

Adicionar um objeto de configuração de diagnóstico pode resultar em uma falha se a propriedade MinApiVersion do seu serviço de Gerenciamento de API estiver definida como qualquer versão de API superior a 2022-09-01-preview.

Nota

Para habilitar as configurações de diagnóstico para espaços de trabalho de Gerenciamento de API, consulte Criar e gerenciar um espaço de trabalho.

Exibir logs e métricas no Azure Log Analytics

Se você habilitar a coleta de logs ou métricas em um espaço de trabalho do Log Analytics, poderá levar alguns minutos para que os dados apareçam no Azure Monitor.

Para visualizar os dados:

1. No portal do Azure, navegue até sua instância de Gerenciamento de API.

2. No menu à esquerda, em Monitoramento, selecione Logs.

3. Execute consultas para exibir os dados. Várias consultas de exemplo são fornecidas ou executam as suas próprias. Por exemplo, a consulta a seguir recupera as 24 horas mais recentes de dados da tabela ApiManagementGatewayLogs:

   ApiManagementGatewayLogs
   | where TimeGenerated > ago(1d) 
   

   

Para obter mais informações sobre como usar logs de recursos para o Gerenciamento de API, consulte:

• Tutorial do Log Analytics.
• Visão geral das consultas de log no Azure Monitor.

Modificar as configurações de log da API

Quando você usa o portal para criar uma configuração de diagnóstico para habilitar a coleta de logs de gateway de gerenciamento de API ou LLM (gateway de IA generativa), o registro em log é habilitado com as configurações padrão. As configurações padrão não incluem detalhes de solicitações ou respostas, como os corpos de solicitação ou de resposta. Você pode ajustar as configurações de log para todas as APIs ou substituí-las para APIs individuais. Por exemplo, ajuste a taxa de amostragem ou o detalhamento dos dados de registo do gateway, ative o registo de mensagens de solicitação ou resposta LLM, ou desative o registo para algumas APIs.

Para obter detalhes sobre as configurações de log, consulte as páginas de referência Diagnóstico - Criar ou Atualizar e Diagnóstico de API - Criar ou Atualizar da API REST.

Para definir as configurações de log para todas as APIs:

1. No menu esquerdo da sua instância de Gerenciamento de API, selecione APIs>>
2. Selecione a guia Configurações na barra superior.
3. Role para baixo até a seção Logs de Diagnóstico e selecione a guia Azure Monitor .
4. Revise as configurações e faça alterações, se necessário. Selecione Guardar.

Para definir as configurações de log para uma API específica:

1. No menu esquerdo da instância de Gerenciamento de API, selecione APIs de APIs> e, em seguida, o nome da API.
2. Selecione a guia Configurações na barra superior.
3. Role para baixo até a seção Logs de Diagnóstico e selecione a guia Azure Monitor .
4. Revise as configurações e faça alterações, se necessário. Selecione Guardar.

Importante

O Gerenciamento de API impõe um limite de 32 KB para o tamanho das entradas de log enviadas ao Azure Monitor. O comportamento quando uma entrada de log excede o limite depende da categoria de log e dos atributos de dados que são registrados:

• Logs do gateway de gestão de API - As cargas úteis de solicitação ou resposta registradas numa entrada de log, caso tenham sido coletadas, podem ter até 8.192 bytes cada. Se o tamanho combinado dos atributos em uma entrada exceder 32 KB, o Gerenciamento de API cortará a entrada removendo todo o corpo e conteúdo de rastreamento.
• Logs de gateway de IA generativa - mensagens de solicitação ou resposta LLM de até 32 KB de tamanho, se coletadas, são enviadas em uma única entrada. Mensagens maiores que 32 KB são divididas e registradas em blocos de 32 KB com números de sequência para reconstrução posterior. As mensagens de solicitação e as mensagens de resposta não podem exceder 2 MB cada.

Próximos passos

Neste tutorial, ficou a saber como:

• Ver métricas da API
• Configurar uma regra de alerta
• Ver registos de atividades
• Habilitar e exibir logs de recursos

Avance para o tutorial seguinte:

Rastrear chamadas