Como integrar a Gestão de API do Azure com o Azure Application Insights

  • Artigo

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.

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 uma identidade gerenciada para o Gerenciamento de API usar com o Application Insights, precisará concluir as seguintes etapas:

    1. Habilite uma identidade gerenciada atribuída pelo sistema ou pelo usuário para o Gerenciamento de API em sua instância de Gerenciamento de API.

      • Se você habilitar uma identidade gerenciada atribuída pelo usuário, anote a ID do Cliente da identidade.

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

  1. Primeiro, você cria 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.

    Nota

    Se o recurso do Application Insights estiver em um locatário diferente, você deverá criar o registrador usando a API REST.

    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 usar uma cadeia de conexão do Application Insights ou uma identidade gerenciada pelo Gerenciamento de API, use o modelo API REST, Bíceps ou ARM para criar o registrador. Saiba mais sobre as cadeias de conexão do Application Insights.

  2. Em segundo lugar, você habilita 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.

  1. Navegue até sua instância de serviço de Gerenciamento de API do Azure no portal do Azure.

  2. Selecione Application Insights no menu à esquerda.

  3. Selecione + Adicionar.
    Captura de ecrã que mostra onde adicionar uma nova ligação

  4. Selecione a instância do Application Insights criada anteriormente e forneça uma breve descrição.

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

  6. Selecione Criar.

  7. Verifique se o novo registrador do Application Insights agora aparece na lista.

    Captura de tela que mostra onde exibir o registrador do Application Insights recém-criado.

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 REST API, Bíceps ou ARM para criar uma conexão entre o Application Insights e o Gerenciamento de API. Você pode configurar um registrador que usa uma cadeia de conexão, identidade gerenciada atribuída ao sistema ou identidade gerenciada atribuída pelo usuário.

Logger 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 a API REST de Gerenciamento de API com o seguinte corpo de solicitação.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new logger with connection string",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
    }
  }
}

Logger com credenciais de identidade gerenciadas atribuídas pelo sistema

Consulte os pré-requisitos para usar uma identidade gerenciada do Gerenciamento de API.

Use a API REST de Gerenciamento de API com o seguinte corpo de solicitação.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new logger with system-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"SystemAssigned"
    }
  }
}

Logger com credenciais de identidade gerenciadas atribuídas pelo usuário

Consulte os pré-requisitos para usar uma identidade gerenciada do Gerenciamento de API.

Use a API REST de Gerenciamento de API com o seguinte corpo de solicitação.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new logger with user-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"<ClientID>"
    }
  }
}

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.

  1. Navegue até sua instância de serviço de Gerenciamento de API do Azure no portal do Azure.

  2. Selecione APIs no menu à esquerda.

  3. Clique na sua API, neste caso Demo Conference API. Se configurado, selecione uma versão.

    Gorjeta

    Para habilitar o registro em log para todas as APIs, selecione Todas as APIs.

  4. Vá para a guia Configurações na barra superior.

  5. Role para baixo até a seção Logs de diagnóstico .
    Registador do App Insights

  6. Marque a caixa Ativar .

  7. Selecione o registador anexado no menu pendente Destino .

  8. Insira 100 como Amostragem (%) e marque a caixa de seleção Sempre registrar erros.

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

  10. Selecione Guardar.

  11. 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:
  • Pedido de frontend
  • resposta frontend
Dependência Para cada solicitação encaminhada para um serviço de back-end:
  • solicitação de back-end
  • resposta de back-end
Exceção Para cada solicitação com falha:
  • Falha devido a uma conexão de cliente fechada
  • Acionada uma seção de erro das políticas de API
  • Tem um código de status HTTP de resposta correspondente a 4xx ou 5xx
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 a política de métricas de emissão.

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.

  1. Habilite métricas personalizadas (visualização) com dimensões personalizadas em sua instância do Application Insights.

    1. Navegue até sua instância do Application Insights no portal.
    2. No menu à esquerda, selecione Uso e custos estimados.
    3. Selecione Métricas personalizadas (visualização)>Com dimensões.
    4. Selecione OK.

  2. Adicione a "metrics": true propriedade à applicationInsights entidade 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
        [...]
    }
}

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

  4. 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-metric para métricas personalizadas. Para obter detalhes sobre a política, consulte a referência da emit-metric polí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 no Gerenciamento de API:

  • Você pode configurar um máximo de 10 dimensões personalizadas por emit-metric política.

  • O número de séries temporais ativas geradas pela emit-metric 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 emit-metric política contribuiria com 1.000 (10 x 10 x 10) séries temporais ativas.

  • Se você configurar a emit-metric 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.

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.

Próximos passos