Compartilhar via

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.

Observação

Num espaço de trabalho de Gerenciamento de API, um proprietário do espaço de trabalho pode integrar de forma independente o Application Insights e ativar o registo 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 workspace configurando uma cadeia de conexão (recomendado) ou uma chave de instrumentação.

Aviso

Ao usar o nosso gateway auto-hospedado, não garantimos que todos os dados telemétricos serão enviados por push para o Azure Application Insights, uma vez que ele depende do Buffer na memória do Application Insights.

Pré-requisitos

Visão geral do cenário

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

  1. 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 agente para a conexão.

    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 segurança aprimorada, recomendamos usar uma cadeia de conexão do Application Insights com uma identidade gerenciada do Gerenciamento de API. Para configurar a cadeia de conexão com credenciais de identidade gerenciada, 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.

    Observação

    Se o recurso do Application Insights estiver em um locatário diferente, você deverá criar o agente usando a API REST ou ferramentas relacionadas, conforme mostrado em uma seção posterior deste artigo.

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

Observação

Sempre que possível, a Microsoft recomenda usar a cadeia de conexão com credenciais de identidade gerenciadas para segurança aprimorada. Para configurar essas credenciais, use a API REST ou ferramentas relacionadas, conforme mostrado em uma seção posterior deste artigo.

  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 modelo Bicep ou o ARM para criar um agente do Application Insights para a sua instância do Gerenciamento de API. Você pode configurar um agente que usa a cadeia de conexão com credenciais de identidade gerenciadas (recomendado) ou um agente que usa apenas uma cadeia de conexão.

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 pelo sistema

Use a Gerenciamento de API Logger - Criar ou Atualizar 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 a Gerenciamento de API Logger - Criar ou Atualizar 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>"
    }
  }
}

Agente somente 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 Gerenciamento de API Logger - Criar ou Atualizar REST API com o seguinte corpo de solicitação.

Se você estiver configurando o criador de logs para um espaço de trabalho, use a API REST Workspace Logger - Criar ou Atualizar.

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

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>APIs no menu à esquerda.

  3. Selecione uma API, como Swagger Petstore. 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.
    Captura de tela da configuração de Logs de Diagnóstico no portal.

  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 políticas como emit-metric e azure-openai-emit-token-metric. A seção a seguir usa a política emit-metric como exemplo.

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 em uma política de Gerenciamento de API, como emit-metric ou azure-openai-emit-token-metric:

  • Você pode configurar no máximo 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 foram configuradas na política e cada dimensão tinha 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érie temporal ativo regional.

Saiba mais sobre limitações de design e considerações para métricas personalizadas no Azure Monitor.

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.

Conteúdo relacionado