Como integrar a Gestão de API do Azure com o Azure Application Insights
APLICA-SE A: Todas as camadas de gerenciamento de API
Você pode integrar facilmente o Azure Application Insights com o Gerenciamento de API do Azure. O Azure Application Insights é um serviço extensível para programadores Web que criam e gerem aplicações em várias plataformas. Neste guia, você irá:
- Percorra a integração do Application Insights ao Gerenciamento de API.
- Aprenda estratégias para reduzir o impacto no desempenho em sua instância de serviço de Gerenciamento de API.
Nota
Em um espaço de trabalho de Gerenciamento de API, um proprietário de espaço de trabalho pode integrar independentemente o Application Insights e habilitar o log do Application Insights para as APIs do espaço de trabalho. A orientação geral para integrar um espaço de trabalho com o Application Insights é semelhante à orientação para uma instância de Gerenciamento de API; no entanto, a configuração tem como escopo apenas o espaço de trabalho. Atualmente, você deve integrar o Application Insights em um espaço de trabalho configurando uma cadeia de conexão (recomendado) ou uma chave de instrumentação.
Aviso
Ao usar nosso gateway auto-hospedado, não garantimos que toda a telemetria será enviada por push para o Azure Application Insights, pois depende do buffer na memória do Application Insights.
Pré-requisitos
Você precisa de uma instância de Gerenciamento de API do Azure. Crie um primeiro.
Para usar o Application Insights, crie uma instância do serviço Application Insights. Para criar uma instância usando o portal do Azure, consulte Recursos do Application Insights baseados em espaço de trabalho.
Nota
O recurso do Application Insights pode estar em uma assinatura diferente ou até mesmo em um locatário diferente do recurso de Gerenciamento de API.
Se você planeja configurar credenciais de identidade gerenciadas para usar com o Application Insights, conclua as seguintes etapas:
Habilite uma identidade gerenciada atribuída pelo sistema ou pelo usuário para o Gerenciamento de API.
- Se você habilitar uma identidade gerenciada atribuída pelo usuário, anote a ID do Cliente da identidade.
Atribua a identidade à função Monitoring Metrics Publisher , com escopo para o recurso Application Insights. Para atribuir a função, use o portal do Azure ou outras ferramentas do Azure.
Descrição geral do cenário
A seguir estão as etapas de alto nível para esse cenário.
Primeiro, crie uma conexão entre o Application Insights e o Gerenciamento de API
Você pode criar uma conexão entre o Application Insights e seu Gerenciamento de API usando o portal do Azure, a API REST ou as ferramentas relacionadas do Azure. O Gerenciamento de API configura um recurso de registrador para a conexão.
Importante
Atualmente, no portal, o Gerenciamento de API só oferece suporte a conexões com o Application Insights usando uma chave de instrumentação do Application Insights. Para maior segurança, recomendamos o uso de uma cadeia de conexão do Application Insights com uma identidade gerenciada pelo Gerenciamento de API. Para configurar a cadeia de conexão com credenciais de identidade gerenciadas, use a API REST ou ferramentas relacionadas, conforme mostrado em uma seção posterior deste artigo. Saiba mais sobre as cadeias de conexão do Application Insights.
Nota
Se o recurso do Application Insights estiver em um locatário diferente, você deverá criar o registrador usando a API REST ou ferramentas relacionadas, conforme mostrado em uma seção posterior deste artigo.
Em segundo lugar, habilite o log do Application Insights para sua API ou APIs.
Neste artigo, você habilita o log do Application Insights para sua API usando o portal do Azure. O Gerenciamento de API configura um recurso de diagnóstico para a API.
Criar uma conexão usando o portal do Azure
Siga estas etapas para usar o portal do Azure para criar uma conexão entre o Application Insights e o Gerenciamento de API.
Nota
Sempre que possível, a Microsoft recomenda o uso de cadeia de conexão com credenciais de identidade gerenciadas para maior segurança. Para configurar essas credenciais, use a API REST ou ferramentas relacionadas, conforme mostrado em uma seção posterior deste artigo.
Navegue até sua instância de serviço de Gerenciamento de API do Azure no portal do Azure.
Selecione Application Insights no menu à esquerda.
Selecione + Adicionar.
Selecione a instância do Application Insights criada anteriormente e forneça uma breve descrição.
Para habilitar o monitoramento de disponibilidade de sua instância de Gerenciamento de API no Application Insights, marque a caixa de seleção Adicionar monitor de disponibilidade.
- Essa configuração valida regularmente se o ponto de extremidade do gateway de Gerenciamento de API está respondendo.
- Os resultados aparecem no painel Disponibilidade da instância do Application Insights.
Selecione Criar.
Verifique se o novo registrador do Application Insights agora aparece na lista.
Nota
Nos bastidores, uma entidade logger é criada em sua instância de Gerenciamento de API, contendo a chave de instrumentação da instância do Application Insights.
Gorjeta
Se você precisar atualizar a chave de instrumentação configurada no registrador do Application Insights, selecione a linha do registrador na lista (não o nome do registrador). Insira a chave de instrumentação e selecione Salvar.
Criar uma conexão usando o modelo REST API, Bíceps ou ARM
Siga estas etapas para usar o modelo de API REST, Bíceps ou ARM para criar um registrador do Application Insights para sua instância de Gerenciamento de API. Você pode configurar um registrador que usa cadeia de conexão com credenciais de identidade gerenciadas (recomendado) ou um registrador que usa apenas uma cadeia de conexão.
Logger com cadeia de conexão com credenciais de identidade gerenciadas (recomendado)
Consulte os pré-requisitos para usar uma identidade gerenciada do Gerenciamento de API.
A cadeia de conexão do Application Insights aparece na seção Visão geral do recurso do Application Insights.
Cadeia de conexão com identidade gerenciada atribuída ao sistema
Use o API Management Logger - Create or Update REST API com o seguinte corpo de solicitação.
{
"properties": {
"loggerType": "applicationInsights",
"description": "Application Insights logger with system-assigned managed identity",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
"identityClientId":"SystemAssigned"
}
}
}
Cadeia de conexão com identidade gerenciada atribuída pelo usuário
Use o API Management Logger - Create or Update REST API com o seguinte corpo de solicitação.
{
"properties": {
"loggerType": "applicationInsights",
"description": "Application Insights logger with user-assigned managed identity",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
"identityClientId":"<ClientID>"
}
}
}
Logger apenas com credenciais de cadeia de conexão
A cadeia de conexão do Application Insights aparece na seção Visão geral do recurso do Application Insights.
Use o API Management Logger - Create or Update REST API com o seguinte corpo de solicitação.
Se você estiver configurando o registrador para um espaço de trabalho, use o Registrador de espaço de trabalho - Criar ou atualizar a API REST.
{
"properties": {
"loggerType": "applicationInsights",
"description": "Application Insights logger with connection string",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
}
}
}
Habilite o registro em log do Application Insights para sua API
Use as etapas a seguir para habilitar o log do Application Insights para uma API. Você também pode habilitar o log do Application Insights para todas as APIs.
Navegue até sua instância de serviço de Gerenciamento de API do Azure no portal do Azure.
Selecione APIs> APIs no menu à esquerda.
Selecione uma API, como Swagger Petstore. Se configurado, selecione uma versão.
Gorjeta
Para habilitar o registro em log para todas as APIs, selecione Todas as APIs.
Vá para a guia Configurações na barra superior.
Role para baixo até a seção Logs de diagnóstico .
Marque a caixa Ativar .
Selecione o registador anexado no menu pendente Destino .
Insira 100 como Amostragem (%) e marque a caixa de seleção Sempre registrar erros.
Deixe o resto das configurações como estão. Para obter detalhes sobre as configurações, consulte Referência de configurações de logs de diagnóstico.
Aviso
Substituir o número padrão de bytes de carga pelo valor de log 0 pode diminuir significativamente o desempenho de suas APIs.
Selecione Guardar.
Nos bastidores, uma entidade de diagnóstico nomeada
applicationinsightsé criada no nível da API.
Nota
As solicitações são bem-sucedidas quando o Gerenciamento de API envia toda a resposta para o cliente.
Loggers para uma única API ou todas as APIs
Você pode especificar registradores em diferentes níveis:
- Registador de API único
- Um registrador para todas as APIs
Especificando ambos:
- Por padrão, o registrador de API único (nível mais granular) substitui o de todas as APIs.
- Se os registradores configurados nos dois níveis forem diferentes e você precisar de ambos os registradores para receber telemetria (multiplexação), entre em contato com o Suporte da Microsoft. Observe que a multiplexação não é suportada se você estiver usando o mesmo registrador (destino do Application Insights) no nível "Todas as APIs" e no nível de API única. Para que a multiplexação funcione corretamente, você deve configurar diferentes registradores no nível "Todas as APIs" e API individual e solicitar assistência do suporte da Microsoft para habilitar a multiplexação para seu serviço.
Que dados são adicionados ao Application Insights
O Application Insights recebe:
| Item Telemetria | Description |
|---|---|
| Pedir | Para cada pedido recebido:
|
| Dependência | Para cada solicitação encaminhada para um serviço de back-end:
|
| Exceção | Para cada solicitação com falha:
|
| Rastreio | Se você configurar uma política de rastreamento . A severity configuração na trace política deve ser igual ou maior do que a verbosity configuração no log do Application Insights. |
Nota
Consulte Limites do Application Insights para obter informações sobre o tamanho máximo e o número de métricas e eventos por instância do Application Insights.
Emitir métricas personalizadas
Você pode emitir métricas personalizadas para o Application Insights a partir de sua instância de Gerenciamento de API. O Gerenciamento de API emite métricas personalizadas usando políticas como emit-metric e azure-openai-emit-token-metric. A seção a seguir usa a emit-metric política como exemplo.
Nota
As métricas personalizadas são um recurso de visualização do Azure Monitor e estão sujeitas a limitações.
Para emitir métricas personalizadas, execute as seguintes etapas de configuração.
Habilite métricas personalizadas (visualização) com dimensões personalizadas em sua instância do Application Insights.
- Navegue até sua instância do Application Insights no portal.
- No menu à esquerda, selecione Uso e custos estimados.
- Selecione Métricas personalizadas (visualização)>Com dimensões.
- Selecione OK.
Adicione a
"metrics": truepropriedade àapplicationInsightsentidade de diagnóstico configurada no Gerenciamento de API. Atualmente, você deve adicionar essa propriedade usando o API Management Diagnostic - Create or Update REST API. Por exemplo:PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/diagnostics/applicationinsights { [...] { "properties": { "loggerId": "/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/loggers/{ApplicationInsightsLoggerName}", "metrics": true [...] } }Certifique-se de que o registrador do Application Insights esteja configurado no escopo que você pretende emitir métricas personalizadas (todas as APIs ou uma única API). Para obter mais informações, consulte Habilitar o log do Application Insights para sua API, anteriormente neste artigo.
Configure a política em um escopo em que o log do Application Insights esteja configurado (todas as APIs ou uma única API) e esteja habilitado
emit-metricpara métricas personalizadas. Para obter detalhes sobre a política, consulte a referência daemit-metricpolítica.
Limites para métricas personalizadas
O Azure Monitor impõe limites de uso para métricas personalizadas que podem afetar sua capacidade de emitir métricas do Gerenciamento de API. Por exemplo, o Azure Monitor atualmente define um limite de 10 chaves de dimensão por métrica e um limite de 50.000 séries temporais ativas totais por região em uma assinatura (dentro de um período de 12 horas).
Esses limites têm as seguintes implicações para configurar métricas personalizadas em uma política de Gerenciamento de API, como emit-metric ou azure-openai-emit-token-metric:
Você pode configurar um máximo de 10 dimensões personalizadas por política.
O número de séries temporais ativas geradas pela política dentro de um período de 12 horas é o produto do número de valores exclusivos de cada dimensão configurada durante o período. Por exemplo, se três dimensões personalizadas fossem configuradas na política e cada dimensão tivesse 10 valores possíveis dentro do período, a política contribuiria com 1.000 (10 x 10 x 10) séries temporais ativas.
Se você configurar a política em várias instâncias de Gerenciamento de API que estão na mesma região em uma assinatura, todas as instâncias poderão contribuir para o limite de séries temporais ativas regionais.
Saiba mais sobre limitações de design e considerações para métricas personalizadas no Azure Monitor.
Implicações no desempenho e amostragem de registos
Aviso
Registar todos os eventos pode ter graves implicações no desempenho, consoante a taxa de pedidos recebidos.
Com base em testes de carga internos, a ativação da funcionalidade de registo provocou uma redução de 40%-50% no débito quando a taxa de pedidos excedeu os 1000 pedidos por segundo. O Application Insights está concebido para avaliar o desempenho das aplicações através de análise estatística. Não está:
- Preparado para ser um sistema de auditoria.
- Preparado para registar cada pedido individual de APIs de volume elevado.
Você pode manipular o número de solicitações registradas ajustando a configuração Amostragem. Um valor de 100% significa que todos os pedidos são registados, enquanto 0% não reflete qualquer registo.
A Amostragem ajuda a reduzir o volume de telemetria, o que impede efetivamente uma degradação do desempenho significativa e mantém os benefícios do registo.
Para melhorar os problemas de desempenho, ignore:
- Cabeçalhos de pedidos e respostas.
- Registos de corpo.
Vídeo
Resolução de Problemas
Abordando a questão do fluxo de dados de telemetria do Gerenciamento de API para o Application Insights:
- Investigue se existe um recurso vinculado do Azure Monitor Private Link Scope (AMPLS) na VNet onde o recurso de Gerenciamento de API está conectado. Os recursos AMPLS têm um escopo global em todas as assinaturas e são responsáveis por gerenciar a consulta e a ingestão de dados para todos os recursos do Azure Monitor. É possível que o AMPLS tenha sido configurado com um modo de acesso somente privado especificamente para ingestão de dados. Nesses casos, inclua o recurso Application Insights e seu recurso Log Analytics associado no AMPLS. Depois que essa adição for feita, os dados do Gerenciamento de API serão ingeridos com êxito no recurso do Application Insights, resolvendo o problema de transmissão de dados de telemetria.
Conteúdos relacionados
- Saiba mais sobre o Azure Application Insights.
- Considere o registro em log com os Hubs de Eventos do Azure.
- Saiba mais sobre como visualizar dados do Application Insights usando o Azure Managed Grafana