Como integrar o Gerenciamento de API do Azure ao Azure Application Insights

  • Artigo

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

Você pode facilmente integrar o Azure Application Insights com o Gerenciamento de API do Azure. O Azure Application Insights é um serviço extensível para desenvolvedores da Web que criam e gerenciam aplicativos em várias plataformas. Neste guia, você vai:

  • Percorrer as etapa da integração do Application Insights ao Gerenciamento de API.
  • Aprender estratégias para reduzir o impacto no desempenho em sua instância de serviço do Gerenciamento de API.

Pré-requisitos

Visão geral do cenário

Veja a seguir as etapas de alto nível para esse cenário.

  1. Para começar, 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 agente para a conexão.

    Observação

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

    Importante

    Atualmente, no portal, o Gerenciamento de API dá suporte apenas 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 do Gerenciamento de API, use a API REST, o Bicep ou o modelo do ARM para criar o agente. Saiba mais sobre as cadeias de conexão do Application Insights.

  2. Em seguida, habilite o registro em log do Application Insights para sua API ou APIs.

    Neste artigo, você habilitará o registro em 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é a instância de serviço do Gerenciamento de API do Azure no portal do Azure.

  2. Selecione Application Insights no menu à esquerda.

  3. Selecione + Adicionar.
    Captura de tela que mostra em que local adicionar uma conexão

  4. Selecione a instância do Application Insights que você criou antes e forneça uma descrição resumida.

  5. Para permitir o monitoramento de disponibilidade da 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 são exibidos no painel Disponibilidade da instância do Application Insights.

  6. Selecione Criar.

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

    Captura de tela que mostra em que local exibir o agente do Application Insights que acaba de ser criado.

Observação

Nos bastidores, uma entidade de agente é criada na sua instância do Gerenciamento de API, contendo a chave de instrumentação da instância do Application Insights.

Dica

Se você precisar atualizar a chave de instrumentação configurada no agente do Application Insights, selecione a linha do agente na lista (não o nome do agente). Insira a chave de instrumentação e selecione Salvar.

Criar uma conexão usando a API REST, o Bicep ou o modelo do ARM

Siga estas etapas para usar a API REST, o Bicep ou o modelo do ARM para criar uma conexão entre o Application Insights e o Gerenciamento de API. Você pode configurar um agente que usa uma cadeia de conexão, uma identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário.

Agente 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 do Gerenciamento de API com o corpo da solicitação a seguir.

{
  "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/;..."    
    }
  }
}

Agente com credenciais de identidade gerenciada atribuídas pelo sistema

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

Use a API REST do Gerenciamento de API com o corpo da solicitação a seguir.

{
  "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"
    }
  }
}

Agente com credenciais de identidade gerenciada atribuídas pelo usuário

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

Use a API REST do Gerenciamento de API com o corpo da solicitação a seguir.

{
  "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>"
    }
  }
}

Habilitar o log do Application Insights para sua API

Use as etapas a seguir para habilitar o registro em log do Application Insights para uma API. Você também pode habilitar o registro em log do Application Insights para todas as APIs.

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

  2. Selecione APIs no menu à esquerda.

  3. Clique na API, nesse caso a API de Conferência de Demonstração. Se configurado, selecione uma versão.

    Dica

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

  4. Acesse a guia Configurações na barra superior.

  5. Role para baixo até a seção Logs de Diagnóstico.
    Agente do Application Insights

  6. Marque a caixa Habilitar.

  7. Selecione o agente anexado na lista suspensa Destino.

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

  9. Deixe o restante das configurações como estão. Para obter detalhes sobre as configurações, confira Referência de configurações dos logs de diagnóstico.

    Aviso

    Substituir o valor padrão Número de bytes de conteúdo a registrar0 pode diminuir significativamente o desempenho das suas APIs.

  10. Selecione Salvar.

  11. Nos bastidores, uma entidade Diagnóstico chamada applicationinsights é criada no nível da API.

Observação

As solicitações são bem-sucedidas depois que o Gerenciamento de API envia a resposta inteira ao cliente.

Agentes para uma só API ou todas as APIs

Você pode especificar os agentes em diferentes níveis:

  • Agente para uma só API
  • Um agente para todas as APIs

Ao especificar ambos:

  • Por padrão, o único registrador de API (nível mais granular) substitui o de todas as APIs.
  • Se os agentes configurados nos dois níveis forem diferentes e você precisar que ambos os agentes recebam telemetria (multiplexação), entre em contato com Suporte da Microsoft. Observe que não há suporte para multiplexação se você estiver usando o mesmo agente (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 agentes diferentes no nível de API individual e de "Todas as APIs" e solicitar assistência do suporte da Microsoft para habilitar a multiplexação para seu serviço.

Quais dados são adicionados ao Application Insights

O Application Insights recebe:

Item de telemetria Descrição
Solicitação Para cada solicitação de entrada:
  • solicitação de front-end
  • resposta de front-end
Dependência Para cada solicitação encaminhada a um serviço de back-end:
  • solicitação de back-end
  • resposta de back-end
Exceção Para cada solicitação com falha:
  • Falhou porque uma conexão de cliente foi fechada
  • Disparou uma seção em erro das políticas de API
  • Tem um código de status HTTP de resposta correspondente a 4xx ou 5xx
Trace Se você configurar uma política de rastreamento.
A configuração severity na política trace deve ser igual ou maior que a configuração verbosity no registro em log do Application Insights.

Observação

Confira Limites do Application Insights para obter informações sobre o tamanho e o número máximos 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 da sua instância de Gerenciamento de API. O Gerenciamento de API emite métricas personalizadas usando a política emit-metric.

Observação

As métricas personalizadas são uma versão prévia do recurso do Azure Monitor e estão sujeitas a limitações.

Para emitir métricas personalizadas, execute as etapas da configuração a seguir.

  1. Habilite as métricas personalizadas (Versão prévia) com as dimensões personalizadas na 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 (Versão prévia)>com dimensões.
    4. Selecione OK.

  2. Adicione a propriedade "metrics": true à entidade de diagnóstico applicationInsights configurada no Gerenciamento de API. Atualmente, você precisa adicionar essa propriedade usando o Gerenciamento de API Diagnóstico - Criar ou Atualizar a API REST. 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. Confirme se o agente do Application Insights está configurado no escopo que você pretende emitir as métricas personalizadas (todas as APIs ou uma única API). Para obter mais informações, confira Habilitar o registro em log do Application Insights para sua API, anteriormente neste artigo.

  4. Configure a política emit-metric em um escopo no qual o registro em log do Application Insights esteja configurado (todas as APIs ou uma única API) e habilitado para métricas personalizadas. Para obter detalhes sobre a política, confira a referência de política emit-metric.

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 de 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 no máximo 10 dimensões personalizadas por política emit-metric.

  • O número de séries temporais ativas geradas pela política emit-metric 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 foram configuradas na política e cada dimensão tinha 10 valores possíveis dentro do período, a política emit-metric contribuiria com 1.000 (10 x 10 x 10) séries temporais ativas.

  • Se você configurar a política emit-metric 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érie temporal ativo regional.

Implicações no desempenho e amostragem de log

Aviso

O registro de todos os eventos pode ter sérias implicações no desempenho, dependendo da taxa de solicitações recebidas.

Com base nos testes de carga internos, a habilitação do recurso de registro em log causou uma redução de 40% a 50% na taxa de transferência quando a taxa de solicitação excedeu 1.000 solicitações por segundo. O Application Insights foi projetado para avaliar desempenhos do aplicativo usando análise estatística. Ele não é:

  • Destinado a ser um sistema de auditoria.
  • Adequado para registrar em log cada solicitação individual para APIs de alto volume.

Você pode manipular o número de solicitações registradas em log, ajustando a configuração Amostragem. Um valor de 100% significa que todas as solicitações são registradas, enquanto 0% reflete que não há nenhum registro.

Amostragem ajuda a reduzir o volume de telemetria, evitando efetivamente a degradação significativa do desempenho, enquanto continua carregando os benefícios do registro em log.

Para melhorar os problemas de desempenho, ignore:

  • Cabeçalhos de solicitação e resposta.
  • Registro em log do corpo.

Vídeo

Solução de problemas

Resolver o problema de fluxo de dados de telemetria do Gerenciamento de API para o Application Insights:

  • Investigue se existe um recurso de Escopo de Link Privado (AMPLS) do Azure Monitor vinculado na VNet à qual o recurso de Gerenciamento de API está conectado. Os recursos do AMPLS têm um escopo global entre as assinaturas e são responsáveis por gerenciar a consulta e a ingestão de dados em 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 o recurso Log Analytics associado no AMPLS. Quando essa adição for feita, os dados do Gerenciamento de API serão ingeridos com sucesso no recurso Application Insights, resolvendo o problema de transmissão de dados de telemetria.

Próximas etapas