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

APLICA-SE A: Todas as camadas de gerenciamento de API

Você pode integrar facilmente o Aplicação Azure Insights com o Gerenciamento de API do Azure. O Aplicação Azure 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.

Note

Num 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 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 espaço de trabalho configurando uma cadeia de conexão (recomendado) ou uma chave de instrumentação.

Warning

Ao usar o nosso gateway auto-hospedado, não garantimos que toda a telemetria seja enviada para o Aplicação Azure Insights, pois depende do buffering em memória do Application Insights.

Prerequisites

  • Crie uma instância API Management do Azure.

  • Crie uma instância do serviço Application Insights. Para criar uma instância utilizando o portal do Azure, consulte recursos do Application Insights baseados em espaços de trabalho.

    Note

    O recurso do Application Insights pode estar numa subscrição diferente ou até num tenant diferente do recurso do API Management.

  • Se você planeja configurar credenciais de identidade gerenciadas para usar com o Application Insights, conclua as seguintes etapas:

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

      • Se habilitar uma identidade gerida atribuída pelo utilizador, anote a ID de 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

Os passos seguintes fornecem uma visão geral deste cenário.

  1. Crie uma ligação entre o Application Insights e a Gestão de APIs.

    Pode criar uma ligação entre o Application Insights e a sua API Management usando o portal Azure, a API REST ou ferramentas Azure relacionadas. O Gerenciamento de API configura um recurso de registrador para a conexão.

    Important

    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, utilize uma cadeia de ligação do Application Insights com a identidade gerida do API Management. 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. Para saber mais, consulte Cadeias de Ligação no Application Insights.

    Note

    Se o seu recurso Application Insights estiver num tenant diferente, crie o logger usando a API REST ou ferramentas relacionadas, conforme mostrado numa secção posterior deste artigo.

  2. Ative o registo do Application Insights para a sua API ou APIs.

    Neste artigo, ativa o registo do Application Insights para a sua API utilizando o portal Azure. O Gerenciamento de API configura um recurso de diagnóstico para a API.

Crie uma ligaçã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.

Note

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.

  1. Vá à sua instância de serviço API Management do Azure no portal Azure.

  2. Em Monitorização, no menu lateral, selecione Insights de Aplicação.

  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.

    • Esta definição verifica regularmente se o endpoint do gateway de Gestão de API está a responder.
    • 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.

Note

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.

Tip

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.

Crie uma ligação usando a API REST, Bicep ou template 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. Pode configurar um registador que utiliza uma cadeia de ligação com credenciais de uma identidade gerida (recomendado) ou um registador que utiliza apenas uma cadeia de ligaçã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 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":"<client-ID>"
    }
  }
}

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 estiver a configurar o logger para um espaço de trabalho, use a funcionalidade Workspace Logger - Criar ou Atualizar da REST API.

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

  1. Vá à sua instância de serviço API Management do Azure no portal Azure.

  2. Selecione APIs>APIs no menu lateral.

  3. Selecione uma API, como Swagger Petstore. Se configurado, selecione uma versão.

    Tip

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

  4. Selecione o separador Definições na barra superior.

  5. Desça até à secção de Registos de Diagnóstico e marque a caixa Ativar . Captura de ecrã da configuração dos Registos de Diagnóstico no portal.

  6. Selecione o registador anexado no menu suspenso Destino.

  7. Introduza 100 em Amostragem (%) e selecione a caixa de verificação Sempre registar erros.

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

    Warning

    Alterar o valor predefinido de Número de bytes de payload a registar0 pode diminuir significativamente o desempenho das suas API.

  9. Selecione Guardar.

  10. Nos bastidores, uma entidade de diagnóstico nomeada applicationinsights é criada no nível da API.

Note

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

Pode especificar registadores em diferentes níveis:

  • Registador de API único
  • Um registrador para todas as APIs

Se especificar ambos:

  • Por padrão, o registrador de API único (nível mais granular) substitui o de todas as APIs.
  • Se os loggers configurados nos dois níveis forem diferentes, e precisares de ambos para receber telemetria (multiplexação), contacta o Suporte da Microsoft. A multiplexação não é suportada se estiveres a usar o mesmo logger (destino Application Insights) ao nível de "Todas as APIs" e ao nível de uma única API. 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 de Telemetria Description
Request Para cada pedido recebido:
  • Pedido de frontend
  • resposta front-end
Dependency Telemetria automática de dependências externas a partir da execução de políticas suportadas, incluindo pedidos encaminhados para um serviço backend.
Exception Para cada solicitação com falha:
  • Falha devido a uma conexão de cliente fechada
  • Foi acionada a seção de erro das políticas de API
  • Tem um código de status HTTP de resposta correspondente a 4xx ou 5xx
Trace Se configurares uma política de rastreamento.
A definição severity na política trace deve ser igual ou maior que a definição verbosity no registo do Application Insights.

Telemetria de dependências externas para políticas suportadas

Depois de configurar e ativar o registo do Application Insights, a API Management recolhe automaticamente telemetria externa de dependências para as seguintes políticas. Não é necessária nenhuma política adicional ou configuração de telemetria:

  • authentication-managed-identity
  • authentication-token
  • azure-openai-semantic-cache-lookup
  • cosmosdb-request-handler
  • forward-request
  • get-authorization-context
  • http-data-source
  • invoke-dapr-binding
  • llm-content-safety
  • llm-semantic-cache-lookup
  • send-request
  • send-one-way-request
  • send-service-bus-message
  • sql-data-source
  • validate-jwt

O Application Insights regista estas chamadas externas como operações subordinadas correlacionadas. Por exemplo, pode ver tentativas de repetição, obtenção de metadados do OpenID Connect por validate-jwt, um envio do Service Bus ou encaminhamento para o back-end enquanto operações relacionadas. Para verificar a telemetria no portal Azure, abra os detalhes de transações de ponta a ponta no seu recurso Application Insights e reveja as operações relacionadas para um pedido.

Atualmente, o rastreamento de dependências é suportado apenas para as políticas da lista anterior.

Note

Para informações sobre o tamanho máximo e número de métricas e eventos por instância do Application Insights, consulte limites 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. A API Management emite métricas personalizadas utilizando políticas como emit-metric e llm-emit-token-metric. A seção a seguir usa a emit-metric política como exemplo.

Note

Métricas personalizadas são uma funcionalidade de pré-visualização do Azure Monitor e estão sujeitas a limitações.

Para emitir métricas personalizadas, complete os seguintes passos de configuração:

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

    1. Aceda à sua instância do Application Insights no portal.
    2. Em Configurar no menu lateral, selecione Utilização e custos estimados.
    3. Selecione Métricas personalizadas (visualização)>Com dimensões.
    4. Selecione OK.

  2. Adicione a propriedade "metrics": true à entidade de diagnóstico applicationInsights que configurar no API Management. Atualmente, tem de adicionar esta propriedade através da API REST Diagnostic - Create or Update do API Management. Por exemplo:

    PUT https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/diagnostics/applicationinsights

{
    [...]
    {
    "properties": {
        "loggerId": "/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/loggers/<application-insights-logger-name>",
        "metrics": true
        [...]
    }
  }
}

  3. Certifique-se de que o registador Application Insights está configurado no âmbito onde 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 emit-metric política num âmbito onde o registo do Application Insights esteja configurado (seja todas as APIs ou uma única API) e esteja ativado 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). No Gerenciamento de API, 5 deles são usados para dimensões padrão, incluindo o seguinte:

  • Region
  • ID do serviço
  • Nome do serviço
  • Tipo de Serviço:

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 5 dimensões personalizadas por política.

  • O número de séries temporais ativas geradas pela política é o produto do número de valores únicos de cada dimensão configurada por namespace. 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.

  • A API Management limita cada dimensão a 100 valores únicos e cada espaço de nomes de métricas a 1.000 séries temporais ativas. Quando qualquer um dos limites é atingido, quaisquer novos valores de dimensão ou série temporal não são registados, e os dados correspondentes da métrica são silenciosamente descartados.

  • 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

Warning

Registar todos os eventos pode ter sérias implicações de desempenho, dependendo da 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 1.000 pedidos por segundo. O Application Insights está concebido para avaliar o desempenho das aplicações através de análise estatística. Não é:

  • Destinado a 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, prevenindo efetivamente uma degradação significativa do desempenho, ao mesmo tempo que mantém os benefícios do registo.

Para melhorar os problemas de desempenho, ignore:

  • Cabeçalhos de solicitações e respostas
  • Registo corporal

Troubleshooting

Abordando a questão do fluxo de dados de telemetria do Gerenciamento de API para o Application Insights:

  • Investigue se existe um recurso Azure Monitor Private Link Scope (AMPLS) ligado dentro da rede virtual onde o recurso de Gestão da API está ligado. 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 Private-Only 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údo relacionado

  • Última atualização a