Tutorial: Monitorar APIs publicadas

APLICA-SE A: todas as camadas do Gerenciamento de API

Com o Azure Monitor, é possível visualizar, consultar, rotear, arquivar e realizar ações nas métricas ou nos logs do serviço de Gerenciamento de API do Azure. Para ter uma visão geral do Azure Monitor para o Gerenciamento de API, confira Gerenciamento de API do Monitor.

Dica

As equipes de API podem usar esse recurso nos workspaces. Os workspaces fornecem acesso administrativo isolado às APIs e aos respectivos ambientes de runtime de API.

Neste tutorial, você aprenderá a:

• Exibir métricas da API
• Configurar uma regra de alerta
• Exibir logs de atividade
• Habilitar e ver logs de recursos

Observação

O Gerenciamento de API dá suporte a uma variedade de ferramentas adicionais para observar APIs, incluindo análise interna e integração com o Application Insights. Saiba mais

Pré-requisitos

• Conheça a terminologia do Gerenciamento de API do Azure.
• Conclua o seguinte guia de início rápido: Criar uma instância do Gerenciamento de API do Azure.
• Além disso, conclua o seguinte tutorial: Importar e publicar sua primeira API.

Exibir métricas das APIs

O Gerenciamento de API emite métricas a cada minuto. Assim você vê quase em tempo real o estado e a integridade das suas APIs. Veja abaixo as métricas usadas com mais frequência. Para ver uma lista de todas as métricas disponíveis, confira Métricas.

• Capacidade – Ajuda a tomar decisões relacionadas a upgrade/downgrade do serviços do Gerenciamento de API. A métrica é emitida por minuto e reflete a capacidade estimada do gateway no momento da emissão dos relatórios. A métrica varia de 0 a 100 e é calculada com base em recursos do gateway, como utilização da CPU e da memória e outros fatores.

  Dica

  Nas camadas de serviço v2 e em 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. Saiba mais

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

Observação

A métrica de 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 de Solicitações, que oferece funcionalidade semelhante.

Para acessar as métricas:

1. No portal do Azure, navegue até a instância do Gerenciamento de API. Na página Visão geral, na guia Monitorar, analise as principais métricas das APIs.

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

   

   Dica

   Em um espaço de trabalho, você pode exibir métricas de capacidade com escopo para um gateway de espaço de trabalho. Navegue até Métricas>Monitorar no menu à esquerda 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 nos períodos de interesse.

5. O gráfico pode ser filtrado usando as dimensões da métrica Solicitações. Por exemplo, selecione Adicionar filtro, selecione Categoria de Código de Resposta do Back-end e insira 500 como valor. O gráfico mostra o número de solicitações que falharam no back-end da API.

Configurar uma regra de alerta

É possível receber alertas com base em métricas e logs de atividades. No Azure Monitor, configure uma regra de alerta para executar uma ação quando ela for disparada. As ações comuns incluem:

• Enviar uma notificação por email
• Chamar um webhook
• Invocar um aplicativo lógico do Azure

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

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

2. Selecione Monitoramento>Alertas no menu à esquerda.

   

3. Clique em + Criar>Regra de Alerta.

4. Na guia Condições:

   1. Em Nome do sinal, selecione Solicitações.
   2. Em Lógica de alerta, analise ou modifique os valores padrão do alerta. Por exemplo, atualize o Limite estático, que é o número de ocorrências após as quais o alerta deve ser disparado.
   3. Em Dividir por dimensões, em Nome da dimensão, selecione Categoria de 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 com que a regra é executada. Selecione Avançar.

   

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 grupo de ações para enviar um email de notificação a admin@contoso.com. Para obter as etapas detalhadas, confira Criar e gerenciar grupos de ações 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 severidade.

7. Opcionalmente, defina as configurações restantes. Na guia Examinar + 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 será disparado com base no período de avaliação e ele enviará um email para admin@contoso.com.

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

   

Logs de atividades

Os logs de atividades fornecem insights sobre as operações que foram realizadas em seus serviços de Gerenciamento de API. Usando logs de atividades, é possível determinar “o que, quem e quando” para quaisquer operações de gravação (PUT, POST, DELETE) realizadas em seus serviços de Gerenciamento de API.

Observação

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

É possível acessar os logs de atividades em seu serviço de Gerenciamento de API ou acessar logs de todos os seus recursos do Azure no Azure Monitor.

Para ver o log de atividades:

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

2. Selecione Log de atividades.

   

3. Selecione o escopo de filtragem desejado e clique em Aplicar.

Logs de recursos

Os logs de recursos (logs do Azure Monitor) fornecem informações avançadas sobre as operações e os erros do 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 que são recebidas e processadas pelo gateway do Gerenciamento de API.

Observação

A camada de Consumo não tem suporte para a coleta de logs de recursos.

Dica

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

Para definir uma configuração de diagnóstico para coleta de logs de recursos:

1. No portal do Azure, navegue até a instância do 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 seu cenário.
   3. Em Categorias: selecione uma ou mais categorias. Por exemplo, selecione Logs relacionados ao ApiManagement Gateway para coletar logs das principais solicitações ao gateway de Gerenciamento de API.
   4. Em Detalhes de destino, selecione uma ou mais opções e especifique detalhes para o destino. Por exemplo, envie logs para um workspace 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 as configurações de diagnóstico no Azure Monitor.
   5. Clique em Salvar.

   Dica

   Se você selecionar um workspace do Log Analytics, poderá optar por armazenar os dados em uma tabela específica do recurso (por exemplo, uma tabela ApiManagementGatewayLogs) ou armazenar na tabela geral do AzureDiagnostics. É recomendável usar a tabela específica do recurso para destinos de log que dão suporte a ela. Saiba mais

4. Depois de configurar os detalhes do destino ou dos destinos do log, selecione Salvar.

Observação

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

Observação

Para habilitar as configurações de diagnóstico para workspaces de Gerenciamento de API, consulte Criar e gerenciar um workspace.

Exibir os logs e as métricas no Log Analytics do Azure

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

Para ver os dados:

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

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

3. Execute consultas para ver os dados. Existem várias consultas de exemplo. Você também pode executar as suas. Por exemplo, a seguinte consulta recupera as 24 horas mais recentes de dados da tabela ApiManagementGatewayLogs:

   ApiManagementGatewayLogs
   | where TimeGenerated > ago(1d) 
   

   

Para saber mais sobre como usar logs de recursos do Gerenciamento de API, confira:

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

Modificar as configurações de registro em log da API

Quando você usa o portal para criar uma configuração de diagnóstico para habilitar a coleta de logs do gateway do Gerenciamento de API ou do gateway de IA generativa (LLM), 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 corpos de solicitação ou resposta. Você pode ajustar as configurações de registro em log de todas as APIs ou substituí-las em APIs individuais. Por exemplo, ajuste a taxa de amostragem ou a verbosidade dos dados de log do gateway, habilite o registro de mensagens relativas a solicitações ou respostas LLM, ou desabilite o registro para determinadas APIs.

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

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

1. No menu à esquerda da sua instância de Gerenciamento de API, selecione APIs>APIs>Todas as APIs.
2. Acesse 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. Examine as configurações e faça alterações, se necessário. Clique em Salvar.

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

1. No menu à esquerda da sua instância de Gerenciamento de API, selecione APIs>APIs e depois o nome da API.
2. Acesse 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. Examine as configurações e faça alterações, se necessário. Clique em Salvar.

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 registrados:

• Logs de gateway do Gerenciamento de API: conteúdos de solicitação ou resposta registrados em uma entrada de log, se coletados, podem ter até 8.192 bytes cada. Se o tamanho combinado dos atributos em uma entrada exceder 32 KB, o Gerenciamento de API reduzirá a entrada removendo todo o conteúdo do corpo e do rastreamento.
• Logs de gateway de IA generativa: mensagens de solicitação ou resposta de LLM com até 32 KB de tamanho, se coletadas, serão enviadas em uma única entrada. Mensagens maiores que 32 KB são divididas e registradas em partes de 32 KB com números de sequência para reconstrução posterior. Mensagens de solicitação e mensagens de resposta não podem exceder 2 MB cada.

Próximas etapas

Neste tutorial, você aprendeu a:

• Exibir métricas da API
• Configurar uma regra de alerta
• Exibir logs de atividade
• Habilitar e ver logs de recursos

Prosseguir para o próximo tutorial:

Rastrear chamadas