Como configurar Azure App Insights para seu aplicativo de código

Azure Application Insights é um serviço de telemetria e monitoramento que ajuda você a coletar e analisar a telemetria detalhada de seus aplicativos. Ao integrá-lo a aplicativos de código Power Apps, você pode capturar métricas como o desempenho de carga de sessão e resumos de solicitações de rede. Essa integração oferece uma visibilidade mais profunda de como seu aplicativo se comporta em condições reais. Para obter mais informações, consulte a visão geral de observabilidade do Application Insights OpenTelemetry.

Azure Application Insights complementa Power Platform Monitor fornecendo logs granulares e eventos personalizados. No entanto, ele só captura a telemetria depois que o aplicativo é carregado com êxito. Falhas de inicialização - incluindo problemas causados por arquivos bloqueados ou inicialização com falha - não aparecem aqui e aparecem apenas no Monitor.

Pré-requisitos

• Uma assinatura Azure.
• Um recurso do Application Insights criado no Azure portal.
• A cadeia de conexão ou a chave de instrumentação do recurso do App Insights.

Steps

Use as etapas a seguir para provisionar o Application Insights, instalar a biblioteca de clientes do Power Apps para aplicativos de código, conectar a telemetria em seu aplicativo de código do Power Apps e verificar dados em Azure. Este guia curto orienta você pela configuração de ponta a ponta para que você possa começar a capturar o desempenho e as métricas de rede rapidamente.

1. Criar um recurso do Application Insights

   • Entre no Azure portal.
   • Acesse o Application Insights e crie um novo recurso.
   • Copie o Connection String ou Instrumentation Key da visão geral do recurso.

2. Instalar o SDK do Application Insights

   Adicione o pacote npm ao projeto do aplicativo de código.

   npm install @microsoft/applicationinsights-web 
   

3. Inicializar Application Insights

   Adicione a lógica para inicializar o Application Insights:

   
   import { ApplicationInsights } from '@microsoft/applicationinsights-web'; 
   
   const initializeAppInsights = () => { 
   const appInsights = new ApplicationInsights({ 
    config: { 
     connectionString: 'InstrumentationKey=<YOUR_KEY>;IngestionEndpoint=<YOUR_ENDPOINT>' 
    } 
   }); 
   appInsights.loadAppInsights(); 
   appInsights.trackPageView(); // Optional: Tracks page view 
   return appInsights; 
   }; 
   
   

   Observação

   As variáveis de ambiente ainda não têm suporte para aplicativos de código. Para gerenciar chaves de instrumentação por ambiente, armazene valores no Dataverse (por exemplo, uma tabela de configurações) ou use getContext() para detectar o ambiente e selecionar a connection string apropriada das constantes do aplicativo.

4. Configurar o logger

   Forneça um logger para que a plataforma possa encaminhar métricas de sessão e rede para seu sistema de monitoramento. A plataforma chama a logMetric função com métricas como sessionLoadSummary e networkLoadSummary. Você só deve chamar essa função uma vez.

   import { setConfig } from '@microsoft/power-apps/app' 
   import type { IConfig } from '@microsoft/power-apps/app' 
   
   setConfig({ 
   logger: {   
      logMetric: (value: Metric) => {   
         appInsights.trackEvent(   
         {   
            name: value.type, 
         }, 
            value.data   
         );   
      }   
   } 
   }); 
   

   Diretrizes adicionais

   • logMetric tipo: Defina-o como (value: Metric) => void para clareza.

   • Interface de Logger:

     interface ILogger { 
     logMetric?: (value: Metric) => void; 
     } 
     

   Você pode importar ILogger de: @microsoft/power-apps.

   import type { ILogger } from '@microsoft/power-apps/telemetry' 
   

   Observação

   Este é apenas um exemplo. Você deve implementar logMetric para que as métricas sejam enviadas para sua ferramenta de monitoramento de escolha, não necessariamente o App Insights. A plataforma simplesmente fornece conteúdos de métrica. Sua implementação determina como eles são tratados.

5. Configurar CSP (Política de Segurança de Conteúdo)

   Se a CSP (Política de Segurança de Conteúdo) estiver habilitada em seu ambiente, o envio de eventos de telemetria para o Application Insights poderá ser bloqueado. Você precisa adicionar os endpoints do App Insights às configurações de CSP do seu ambiente.

   Identificar as fontes necessárias

   1. Abra seu aplicativo com o Application Insights configurado.

   2. Abra o navegador DevTools fazendo um dos seguintes procedimentos:

      • Pressione F12
      • Pressione Ctrl+Shift+I
      • Clique com o botão direito do mouse no aplicativo e selecione Inspecionar

   3. Vá para a guia Console.

   4. Desmarque o console e selecione Erros somente na lista suspensa. Essa etapa não é necessária, mas facilita a identificação dos erros relevantes.

      

   5. Procure erros com a mensagem: Connecting to 'https:...' violates the following Content Security Policy directive.

      

   6. Observe as URLs mostradas nessas mensagens de erro. Essas URLs são as fontes que você precisa adicionar à configuração do CSP.

   Adicionar fontes às configurações do CSP

   1. Acesse o centro de administração da Power Platform..

   2. Siga as instruções em Configurar a Política de Segurança de Conteúdo para adicionar as fontes que você identificou nas etapas anteriores à lista de permissões.connect-src Veja o exemplo na seção a seguir.

      

   3. Aguarde até que as configurações sejam aplicadas. As alterações de CSP podem levar vários minutos para serem propagadas.

   Dica

   Depois de atualizar as configurações do CSP, atualize seu aplicativo e verifique o console novamente para verificar se as violações do CSP foram resolvidas e se a telemetria está sendo enviada com êxito.

6. Exibir logs no portal do Azure

   • Abra seu recurso do Application Insights.
   • Vá até Monitoramento > Logs.
   • Consulte a customEvents tabela para ver resumos de sessão e solicitações de rede.

   A biblioteca de clientes Power Apps para aplicativos de código atualmente fornece dois tipos de métrica internos:

   type SessionLoadSummaryMetricData = { 
   successfulAppLaunch: boolean; 
   appLoadResult: 'optimal' | 'other'; 
   appLoadNonOptimalReason: 'interactionRequired' | 'throttled' | 'screenNavigatedAway' | 'other'; 
   timeToAppInteractive: number; 
   } 
   
   type NetworkRequestMetricData = { 
   url: string; 
   method:  string; 
   duration: number; 
   statusCode: number; 
   responseSize: number; 
   } 
   

7. (Opcional) Registrar eventos personalizados

   Você pode registrar mais telemetria (além das métricas padrão) chamando as próprias APIs da ferramenta de monitoramento nos pontos desejados em seu aplicativo. Para cenários mais avançados, consulte a documentação oficial do Application Insights para obter diretrizes. Evite registrar dados confidenciais ou desnecessários e sempre siga as diretrizes de conformidade da sua organização.

Exemplos de consultas

Para ajudá-lo a começar analisando seus dados de telemetria, as consultas de exemplo a seguir usam o Azure Application Insights Analytics (Linguagem de Consulta Kusto).

Desempenho aberto do aplicativo

Esta consulta mostra as métricas de desempenho abertas do aplicativo por dia. Use essa consulta para avaliar as tendências de desempenho ao longo do tempo ou depois de fazer alterações. Utilize o 75º percentil do campo timeToAppInteractive para evitar ruídos causados por valores extremos.

customEvents 
| where name == "sessionLoadSummary" 
| extend cd = parse_json(customDimensions) 
| extend cm = parse_json(customMeasurements)  
| extend timeToAppInteractive = todouble(cm["timeToAppInteractive"]) 
| extend successfulAppLaunch = tobool(cd.successfulAppLaunch) 
| where successfulAppLaunch == true 
| summarize percentile(timeToAppInteractive, 75)  
by bin(timestamp, 1d)  
| render timechart 

Desempenho da solicitação de rede por URL

Essa consulta analisa eventos personalizados networkRequest no Application Insights. Ele extrai a URL e a duração da telemetria. Em seguida, resume as contagens diárias e os tempos de resposta do 75º percentil por URL. Ele visualiza os resultados como um gráfico de série temporal.

customEvents 
| where name == "networkRequest" 
| extend cd = parse_json(customDimensions) 
| extend url = tostring(cd.url) 
| extend cm = parse_json(customMeasurements) 
| extend duration = todouble(cm.duration) 
| summarize  
count(), percentile(duration, 75) by url, bin(timestamp, 1d) 
| render timechart