Monitore aplicativos .NET e Node.js com o Application Insights (API clássica)

O SDK do Serviço de Trabalho não faz nenhuma coleta de telemetria por si só. Em vez disso, ele traz outros coletores automáticos do Application Insights, como DependencyCollector, PerfCounterCollector e ApplicationInsightsLoggingProvider. Este SDK expõe métodos de extensão em `IServiceCollection` para habilitar e configurar a recolha de telemetria.

A biblioteca de cliente Node.js pode monitorar automaticamente solicitações HTTP de entrada e saída, exceções e algumas métricas do sistema. A partir da versão 0.20, a biblioteca do cliente também pode monitorar alguns pacotes comuns de terceiros, como MongoDB, MySQL e Redis.

Todos os eventos relacionados com pedidos HTTP de entrada são correlacionados para resolução de problemas mais rápida.

Você pode usar a API TelemetryClient para instrumentar e monitorar manualmente mais aspetos do seu aplicativo e sistema. A API TelemetryClient está descrita em mais detalhe posteriormente neste artigo.

Pré-requisitos

Criar um aplicativo Web básico

Se você ainda não tiver um aplicativo Web em funcionamento, poderá usar as orientações a seguir para criar um.

ASP.NET

1. Abra o Visual Studio.
2. Selecione Criar um novo projeto.
3. Escolha ASP.NET Aplicativo Web (.NET Framework) com C# e selecione Avançar.
4. Insira um nome de projeto e selecione Criar.
5. Escolha MVC e, em seguida, selecione Criar.

ASP.NET Core

1. Abra o Visual Studio.
2. Selecione Criar um novo projeto.
3. Escolha ASP.NET Core Web App (Razor Pages) com C# e selecione Next.
4. Insira um nome de projeto e selecione Criar.
5. Escolha uma estrutura (LTS ou STS) e, em seguida, selecione Criar.

Adicionar o Application Insights automaticamente (Visual Studio)

Esta seção orienta você pela adição automática do Application Insights a um aplicativo Web baseado em modelo.

ASP.NET

De dentro do seu projeto de aplicativo Web ASP.NET no Visual Studio:

1. Selecione Projeto>Adicionar Telemetria do Application Insights>Application Insights SDK (local)>Próximo>Concluir>Fechar.

2. Abra o arquivo ApplicationInsights.config .

3. Antes da tag de fechamento </ApplicationInsights> , adicione uma linha que contenha a cadeia de conexão para o recurso do Application Insights. Encontre sua cadeia de conexão no painel de visão geral do recurso do Application Insights recém-criado.

   <ConnectionString>Copy connection string from Application Insights Resource Overview</ConnectionString>
   

4. Selecione Project>> Em seguida, atualize cada Microsoft.ApplicationInsights pacote NuGet para a versão estável mais recente.

5. Execute seu aplicativo selecionando IIS Express. Um aplicativo ASP.NET básico é aberto. À medida que você navega pelas páginas do site, a telemetria é enviada para o Application Insights.

ASP.NET Core

De dentro do seu projeto de aplicativo Web ASP.NET no Visual Studio:

1. Vá para Project>Add Application Insights Telemetry.

2. Selecione Azure Application Insights>Next.

3. Escolha sua assinatura e a instância do Application Insights. Ou você pode criar uma nova instância com Create new. Selecione Avançar.

4. Adicione ou confirme sua cadeia de conexão do Application Insights. Ele deve ser pré-preenchido com base na sua seleção na etapa anterior. Selecione Concluir.

5. Depois de adicionar o Application Insights ao seu projeto, verifique se você está usando a versão estável mais recente do SDK. Vá para Project>Manage NuGet Packages>Microsoft.ApplicationInsights.AspNetCore. Se precisar, selecione Atualizar.

   

Adicionar o Application Insights manualmente (sem Visual Studio)

Esta seção orienta você pela adição manual do Application Insights a um aplicativo Web baseado em modelo.

ASP.NET

1. Adicione os seguintes pacotes NuGet e suas dependências ao seu projeto:

   • Microsoft.ApplicationInsights.WindowsServer
   • Microsoft.ApplicationInsights.Web
   • Microsoft.AspNet.TelemetryCorrelation

2. Em alguns casos, o arquivo ApplicationInsights.config é criado para você automaticamente. Se o ficheiro já estiver presente, avance para o passo 4.

   Crie você mesmo, se estiver faltando. No diretório raiz de um aplicativo ASP.NET, crie um novo arquivo chamado ApplicationInsights.config.

3. Copie a seguinte configuração XML para o arquivo recém-criado:

   
   
   Expandir para visualizar a configuração

   <?xml version="1.0" encoding="utf-8"?>
   <ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
     <TelemetryInitializers>
       <Add Type="Microsoft.ApplicationInsights.DependencyCollector.HttpDependenciesParsingTelemetryInitializer, Microsoft.AI.DependencyCollector" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AzureRoleEnvironmentTelemetryInitializer, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.BuildInfoConfigComponentVersionTelemetryInitializer, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.Web.WebTestTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.SyntheticUserAgentTelemetryInitializer, Microsoft.AI.Web">
         <!-- Extended list of bots:
               search|spider|crawl|Bot|Monitor|BrowserMob|BingPreview|PagePeeker|WebThumb|URL2PNG|ZooShot|GomezA|Google SketchUp|Read Later|KTXN|KHTE|Keynote|Pingdom|AlwaysOn|zao|borg|oegp|silk|Xenu|zeal|NING|htdig|lycos|slurp|teoma|voila|yahoo|Sogou|CiBra|Nutch|Java|JNLP|Daumoa|Genieo|ichiro|larbin|pompos|Scrapy|snappy|speedy|vortex|favicon|indexer|Riddler|scooter|scraper|scrubby|WhatWeb|WinHTTP|voyager|archiver|Icarus6j|mogimogi|Netvibes|altavista|charlotte|findlinks|Retreiver|TLSProber|WordPress|wsr-agent|http client|Python-urllib|AppEngine-Google|semanticdiscovery|facebookexternalhit|web/snippet|Google-HTTP-Java-Client-->
         <Filters>search|spider|crawl|Bot|Monitor|AlwaysOn</Filters>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.ClientIpHeaderTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AzureAppServiceRoleNameFromHostNameHeaderInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.OperationNameTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.OperationCorrelationTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.UserTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AuthenticatedUserIdTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AccountIdTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.SessionTelemetryInitializer, Microsoft.AI.Web" />
     </TelemetryInitializers>
     <TelemetryModules>
       <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
         <ExcludeComponentCorrelationHttpHeadersOnDomains>
           <!-- 
           Requests to the following hostnames will not be modified by adding correlation headers.
           Add entries here to exclude additional hostnames.
           NOTE: this configuration will be lost upon NuGet upgrade.
           -->
           <Add>core.windows.net</Add>
           <Add>core.chinacloudapi.cn</Add>
           <Add>core.cloudapi.de</Add>
           <Add>core.usgovcloudapi.net</Add>
         </ExcludeComponentCorrelationHttpHeadersOnDomains>
         <IncludeDiagnosticSourceActivities>
           <Add>Microsoft.Azure.EventHubs</Add>
           <Add>Azure.Messaging.ServiceBus</Add>
         </IncludeDiagnosticSourceActivities>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector">
         <!--
         Use the following syntax here to collect additional performance counters:
   
         <Counters>
           <Add PerformanceCounter="\Process(??APP_WIN32_PROC??)\Handle Count" ReportAs="Process handle count" />
           ...
         </Counters>
   
         PerformanceCounter must be either \CategoryName(InstanceName)\CounterName or \CategoryName\CounterName
   
         NOTE: performance counters configuration will be lost upon NuGet upgrade.
   
         The following placeholders are supported as InstanceName:
           ??APP_WIN32_PROC?? - instance name of the application process for Win32 counters.
           ??APP_W3SVC_PROC?? - instance name of the application IIS worker process for IIS/ASP.NET counters.
           ??APP_CLR_PROC?? - instance name of the application CLR process for .NET counters.
         -->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse.QuickPulseTelemetryModule, Microsoft.AI.PerfCounterCollector" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AppServicesHeartbeatTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AzureInstanceMetadataTelemetryModule, Microsoft.AI.WindowsServer">
         <!--
         Remove individual fields collected here by adding them to the ApplicationInsighs.HeartbeatProvider
         with the following syntax:
   
         <Add Type="Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule, Microsoft.ApplicationInsights">
           <ExcludedHeartbeatProperties>
             <Add>osType</Add>
             <Add>location</Add>
             <Add>name</Add>
             <Add>offer</Add>
             <Add>platformFaultDomain</Add>
             <Add>platformUpdateDomain</Add>
             <Add>publisher</Add>
             <Add>sku</Add>
             <Add>version</Add>
             <Add>vmId</Add>
             <Add>vmSize</Add>
             <Add>subscriptionId</Add>
             <Add>resourceGroupName</Add>
             <Add>placementGroupId</Add>
             <Add>tags</Add>
             <Add>vmScaleSetName</Add>
           </ExcludedHeartbeatProperties>
         </Add>
   
         NOTE: exclusions will be lost upon upgrade.
         -->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule, Microsoft.AI.WindowsServer">
         <!--</Add>
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.FirstChanceExceptionStatisticsTelemetryModule, Microsoft.AI.WindowsServer">-->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule, Microsoft.AI.Web">
         <Handlers>
           <!-- 
           Add entries here to filter out additional handlers:
   
           NOTE: handler configuration will be lost upon NuGet upgrade.
           -->
           <Add>Microsoft.VisualStudio.Web.PageInspector.Runtime.Tracing.RequestDataHttpHandler</Add>
           <Add>System.Web.StaticFileHandler</Add>
           <Add>System.Web.Handlers.AssemblyResourceLoader</Add>
           <Add>System.Web.Optimization.BundleHandler</Add>
           <Add>System.Web.Script.Services.ScriptHandlerFactory</Add>
           <Add>System.Web.Handlers.TraceHandler</Add>
           <Add>System.Web.Services.Discovery.DiscoveryRequestHandler</Add>
           <Add>System.Web.HttpDebugHandler</Add>
         </Handlers>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AspNetDiagnosticTelemetryModule, Microsoft.AI.Web" />
     </TelemetryModules>
     <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
     <TelemetrySinks>
       <Add Name="default">
         <TelemetryProcessors>
           <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse.QuickPulseTelemetryProcessor, Microsoft.AI.PerfCounterCollector" />
           <Add Type="Microsoft.ApplicationInsights.Extensibility.AutocollectedMetricsExtractor, Microsoft.ApplicationInsights" />
           <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
             <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
             <ExcludedTypes>Event</ExcludedTypes>
           </Add>
           <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
             <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
             <IncludedTypes>Event</IncludedTypes>
           </Add>
           <!--
             Adjust the include and exclude examples to specify the desired semicolon-delimited types. (Dependency, Event, Exception, PageView, Request, Trace)
           -->
         </TelemetryProcessors>
         <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel" />
       </Add>
     </TelemetrySinks>
     <!-- 
       Learn more about Application Insights configuration with ApplicationInsights.config here:
       http://go.microsoft.com/fwlink/?LinkID=513840
     -->
     <ConnectionString>Copy the connection string from your Application Insights resource</ConnectionString>
   </ApplicationInsights>
   

4. Adicione a cadeia de conexão, o que pode ser feito de duas maneiras:

   • (Recomendado) Defina a cadeia de conexão na configuração.

     Antes da tag de fechamento </ApplicationInsights> em ApplicationInsights.config, adicione a cadeia de conexão para seu recurso do Application Insights. Você pode encontrar sua cadeia de conexão no painel de visão geral do recurso do Application Insights recém-criado.

     <ConnectionString>Copy the connection string from your Application Insights resource</ConnectionString>
     

   • Defina a cadeia de conexão no código.

     Forneça uma cadeia de conexão em sua classe program.cs .

     var configuration = new TelemetryConfiguration
     {
         ConnectionString = "Copy the connection string from your Application Insights resource"
     };
     

5. No mesmo nível do seu projeto que o arquivo ApplicationInsights.config , crie uma pasta chamada ErrorHandler com um novo arquivo C# chamado AiHandleErrorAttribute.cs. O conteúdo do arquivo tem esta aparência:

   using System;
   using System.Web.Mvc;
   using Microsoft.ApplicationInsights;
   
   namespace WebApplication10.ErrorHandler //namespace will vary based on your project name
   {
       [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)] 
       public class AiHandleErrorAttribute : HandleErrorAttribute
       {
           public override void OnException(ExceptionContext filterContext)
           {
               if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
               {
                   //If customError is Off, then AI HTTPModule will report the exception
                   if (filterContext.HttpContext.IsCustomErrorEnabled)
                   {   
                       var ai = new TelemetryClient();
                       ai.TrackException(filterContext.Exception);
                   } 
               }
               base.OnException(filterContext);
           }
       }
   }
   

6. Na pasta App_Start, abra o arquivo FilterConfig.cs e altere-o para corresponder ao exemplo:

   using System.Web;
   using System.Web.Mvc;
   
   namespace WebApplication10 //Namespace will vary based on project name
   {
       public class FilterConfig
       {
           public static void RegisterGlobalFilters(GlobalFilterCollection filters)
           {
               filters.Add(new ErrorHandler.AiHandleErrorAttribute());
           }
       }
   }
   

7. Se Web.config já estiver atualizado, ignore esta etapa. Caso contrário, atualize o arquivo da seguinte maneira:

   
   
   Expandir para visualizar a configuração

   <?xml version="1.0" encoding="utf-8"?>
   <!--
     For more information on how to configure your ASP.NET application, please visit
     https://go.microsoft.com/fwlink/?LinkId=301880
     -->
   <configuration>
     <appSettings>
       <add key="webpages:Version" value="3.0.0.0" />
       <add key="webpages:Enabled" value="false" />
       <add key="ClientValidationEnabled" value="true" />
       <add key="UnobtrusiveJavaScriptEnabled" value="true" />
     </appSettings>
     <system.web>
       <compilation debug="true" targetFramework="4.7.2" />
       <httpRuntime targetFramework="4.7.2" />
       <!-- Code added for Application Insights start -->
       <httpModules>
         <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" />
         <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" />
       </httpModules>
       <!-- Code added for Application Insights end -->
     </system.web>
     <runtime>
       <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
         <dependentAssembly>
           <assemblyIdentity name="Antlr3.Runtime" publicKeyToken="eb42632606e9261f" />
           <bindingRedirect oldVersion="0.0.0.0-3.5.0.2" newVersion="3.5.0.2" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" />
           <bindingRedirect oldVersion="0.0.0.0-12.0.0.0" newVersion="12.0.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.Optimization" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-1.1.0.0" newVersion="1.1.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="WebGrease" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="0.0.0.0-1.6.5135.21930" newVersion="1.6.5135.21930" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.Helpers" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.WebPages" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-5.2.7.0" newVersion="5.2.7.0" />
         </dependentAssembly>
         <!-- Code added for Application Insights start -->
         <dependentAssembly>
           <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
           <bindingRedirect oldVersion="0.0.0.0-4.0.1.1" newVersion="4.0.1.1" />
         </dependentAssembly>
         <!-- Code added for Application Insights end -->
       </assemblyBinding>
     </runtime>
     <system.codedom>
       <compilers>
         <compiler language="c#;cs;csharp" extension=".cs" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.CSharpCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=2.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:1659;1699;1701" />
         <compiler language="vb;vbs;visualbasic;vbscript" extension=".vb" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.VBCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=2.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:41008 /define:_MYTYPE=\&quot;Web\&quot; /optionInfer+" />
       </compilers>
     </system.codedom>
     <system.webServer>
       <validation validateIntegratedModeConfiguration="false" />
       <!-- Code added for Application Insights start -->
       <modules>
         <remove name="TelemetryCorrelationHttpModule" />
         <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" preCondition="managedHandler" />
         <remove name="ApplicationInsightsWebTracking" />
         <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" preCondition="managedHandler" />
       </modules>
       <!-- Code added for Application Insights end -->
     </system.webServer>
   </configuration>
   

Neste ponto, você configurou com êxito o monitoramento de aplicativos do lado do servidor. Se você executar seu aplicativo Web, verá a telemetria começar a aparecer no Application Insights.

ASP.NET Core

1. Instale o pacote NuGet do Application Insights SDK para ASP.NET Core.

   Recomendamos que você sempre use a versão estável mais recente. Encontre as notas de versão completas do SDK no repositório GitHub de código aberto.

   O exemplo de código a seguir mostra as alterações a serem adicionadas ao arquivo .csproj do seu projeto:

   <ItemGroup>
       <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
   </ItemGroup>
   

2. Adicione AddApplicationInsightsTelemetry() à sua classe program.cs .

   Adicione builder.Services.AddApplicationInsightsTelemetry(); após o WebApplication.CreateBuilder() método, como neste exemplo:

   // This method gets called by the runtime. Use this method to add services to the container.
   var builder = WebApplication.CreateBuilder(args);
   
   // The following line enables Application Insights telemetry collection.
   builder.Services.AddApplicationInsightsTelemetry();
   
   // This code adds other services for your application.
   builder.Services.AddMvc();
   
   var app = builder.Build();
   

3. Adicione a cadeia de conexão, o que pode ser feito de três maneiras:

   • (Recomendado) Defina a cadeia de conexão na configuração.

     Defina a cadeia de conexão em appsettings.json e verifique se o arquivo de configuração é copiado para a pasta raiz do aplicativo durante a publicação.

     {
         "Logging": {
             "LogLevel": {
                 "Default": "Information",
                 "Microsoft.AspNetCore": "Warning"
             }
         },
         "AllowedHosts": "*",
         "ApplicationInsights": {
             "ConnectionString": "<YOUR-CONNECTION-STRING>"
         }
     }
     

   • Defina a APPLICATIONINSIGHTS_CONNECTION_STRING cadeia de conexão na variável de ambiente ou ApplicationInsights:ConnectionString no arquivo de configuração JSON.

     Por exemplo:

     • SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
     • SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
     • Normalmente, APPLICATIONINSIGHTS_CONNECTION_STRING é usado em aplicativos Web. Ele também pode ser usado em todos os lugares onde este SDK é suportado.

     Observação

     Uma cadeia de conexão especificada no código ganha sobre a variável APPLICATIONINSIGHTS_CONNECTION_STRINGde ambiente , que ganha sobre outras opções.

   • Defina a cadeia de conexão no código.

     Forneça uma cadeia de conexão como parte do ApplicationInsightsServiceOptions argumento para AddApplicationInsightsTelemetry em sua classe program.cs .

Segredos de usuário e outros provedores de configuração

Se quiser armazenar a cadeia de conexão em ASP.NET segredos de usuário principais ou recuperá-la de outro provedor de configuração, você pode usar a sobrecarga com um Microsoft.Extensions.Configuration.IConfiguration parâmetro. Um parâmetro de exemplo é services.AddApplicationInsightsTelemetry(Configuration);.

Na Microsoft.ApplicationInsights.AspNetCore versão 2.15.0 e posterior, a chamada services.AddApplicationInsightsTelemetry() lê automaticamente a cadeia de conexão do Microsoft.Extensions.Configuration.IConfiguration aplicativo. Não há necessidade de fornecer IConfigurationexplicitamente .

Se IConfiguration a configuração for carregada de vários provedores, priorizará services.AddApplicationInsightsTelemetry a configuração de appsettings.json, independentemente da ordem em que os provedores forem adicionados. Use o método services.AddApplicationInsightsTelemetry(IConfiguration) para ler a configuração de IConfiguration sem esse tratamento preferencial para appsettings.json.

Serviço ao Trabalhador

Nesta secção

• Usar o SDK do Application Insights para o Worker Service
• Aplicativo .NET Core Worker Service
• ASP.NET Core tarefas em segundo plano com serviços hosteados
• Aplicativo de console do .NET Core/.NET Framework

Usar o SDK do Application Insights para o Serviço do Trabalhador

1. Instale o pacote Microsoft.ApplicationInsights.WorkerService no aplicativo.

   O trecho a seguir mostra as alterações que devem ser adicionadas ao arquivo .csproj do seu projeto:

       <ItemGroup>
           <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
       </ItemGroup>
   

2. Configure a cadeia de conexão na APPLICATIONINSIGHTS_CONNECTION_STRING variável de ambiente ou na configuração (appsettings.json).

   

3. Recupere uma ILogger instância ou TelemetryClient instância do contêiner DI (Injeção de Dependência) chamando serviceProvider.GetRequiredService<TelemetryClient>(); ou usando a Injeção do Construtor. Esta etapa aciona a configuração de módulos de TelemetryConfiguration e de autocoleta.

As instruções específicas para cada tipo de aplicação são descritas nas secções seguintes.

Aplicativo .NET Core Worker Service

O exemplo completo é compartilhado no site do NuGet.

1. Baixe e instale o SDK do .NET.

2. Crie um novo projeto do Serviço de Trabalho usando um novo modelo de projeto do Visual Studio ou a linha dotnet new workerde comando.

3. Adicione o pacote Microsoft.ApplicationInsights.WorkerService ao aplicativo.

4. Adicione services.AddApplicationInsightsTelemetryWorkerService(); ao CreateHostBuilder() método em sua Program.cs classe, como neste exemplo:

       public static IHostBuilder CreateHostBuilder(string[] args) =>
           Host.CreateDefaultBuilder(args)
               .ConfigureServices((hostContext, services) =>
               {
                   services.AddHostedService<Worker>();
                   services.AddApplicationInsightsTelemetryWorkerService();
               });
   

5. Modifique o seu Worker.cs de acordo com o exemplo a seguir:

       using Microsoft.ApplicationInsights;
       using Microsoft.ApplicationInsights.DataContracts;
   
       public class Worker : BackgroundService
       {
           private readonly ILogger<Worker> _logger;
           private TelemetryClient _telemetryClient;
           private static HttpClient _httpClient = new HttpClient();
   
           public Worker(ILogger<Worker> logger, TelemetryClient tc)
           {
               _logger = logger;
               _telemetryClient = tc;
           }
   
           protected override async Task ExecuteAsync(CancellationToken stoppingToken)
           {
               while (!stoppingToken.IsCancellationRequested)
               {
                   _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
   
                   using (_telemetryClient.StartOperation<RequestTelemetry>("operation"))
                   {
                       _logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                       _logger.LogInformation("Calling bing.com");
                       var res = await _httpClient.GetAsync("https://bing.com");
                       _logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                       _telemetryClient.TrackEvent("Bing call event completed");
                   }
   
                   await Task.Delay(1000, stoppingToken);
               }
           }
       }
   

6. Defina a cadeia de conexão.

   

   Observação

   Recomendamos que você especifique a cadeia de conexão na configuração. O exemplo de código a seguir mostra como especificar uma cadeia de conexão no appsettings.json. Certifique-se de que appsettings.json é copiado para a pasta raiz do aplicativo durante a publicação.

       {
           "ApplicationInsights":
           {
               "ConnectionString" : "<YOUR-CONNECTION-STRING>"
           },
           "Logging":
           {
               "LogLevel":
               {
                   "Default": "Warning"
               }
           }
       }
   

Como alternativa, especifique a cadeia de conexão na APPLICATIONINSIGHTS_CONNECTION_STRING variável de ambiente.

Normalmente, APPLICATIONINSIGHTS_CONNECTION_STRING especifica a cadeia de conexão para aplicações implantadas em aplicações Web como tarefas Web.

ASP.NET Principais tarefas em segundo plano com serviços hospedados

Este documento descreve como criar tarefas em segundo plano em um aplicativo ASP.NET Core.

O exemplo completo é compartilhado nesta página do GitHub.

1. Instale o pacote Microsoft.ApplicationInsights.WorkerService no aplicativo.

2. Adicione services.AddApplicationInsightsTelemetryWorkerService(); ao ConfigureServices() método, como neste exemplo:

       public static async Task Main(string[] args)
       {
           var host = new HostBuilder()
               .ConfigureAppConfiguration((hostContext, config) =>
               {
                   config.AddJsonFile("appsettings.json", optional: true);
               })
               .ConfigureServices((hostContext, services) =>
               {
                   services.AddLogging();
                   services.AddHostedService<TimedHostedService>();
   
                   // connection string is read automatically from appsettings.json
                   services.AddApplicationInsightsTelemetryWorkerService();
               })
               .UseConsoleLifetime()
               .Build();
   
           using (host)
           {
               // Start the host
               await host.StartAsync();
   
               // Wait for the host to shutdown
               await host.WaitForShutdownAsync();
           }
       }
   

   O código a seguir é para TimedHostedService, onde reside a lógica da tarefa em segundo plano:

       using Microsoft.ApplicationInsights;
       using Microsoft.ApplicationInsights.DataContracts;
   
       public class TimedHostedService : IHostedService, IDisposable
       {
           private readonly ILogger _logger;
           private Timer _timer;
           private TelemetryClient _telemetryClient;
           private static HttpClient httpClient = new HttpClient();
   
           public TimedHostedService(ILogger<TimedHostedService> logger, TelemetryClient tc)
           {
               _logger = logger;
               this._telemetryClient = tc;
           }
   
           public Task StartAsync(CancellationToken cancellationToken)
           {
               _logger.LogInformation("Timed Background Service is starting.");
   
               _timer = new Timer(DoWork, null, TimeSpan.Zero,
                   TimeSpan.FromSeconds(1));
   
               return Task.CompletedTask;
           }
   
           private void DoWork(object state)
           {
               _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
   
               using (_telemetryClient.StartOperation<RequestTelemetry>("operation"))
               {
                   _logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                   _logger.LogInformation("Calling bing.com");
                   var res = httpClient.GetAsync("https://bing.com").GetAwaiter().GetResult();
                   _logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                   _telemetryClient.TrackEvent("Bing call event completed");
               }
           }
       }
   

3. Defina a cadeia de conexão. Use o mesmo appsettings.json do exemplo anterior do .NET Worker Service.

Aplicativo de console do .NET Core/.NET Framework

Como mencionado no início deste artigo, o novo pacote pode ser usado para habilitar a telemetria do Application Insights até mesmo de um aplicativo de console comum. Este pacote destina-se netstandard2.0, para que possa ser usado em aplicativos de console no .NET Core ou superior e .NET Framework ou superior.

O exemplo completo é compartilhado nesta página do GitHub.

1. Instale o pacote Microsoft.ApplicationInsights.WorkerService no aplicativo.

2. Modifique Program.cs conforme mostrado no exemplo a seguir:

       using Microsoft.ApplicationInsights;
       using Microsoft.ApplicationInsights.DataContracts;
       using Microsoft.ApplicationInsights.WorkerService;
       using Microsoft.Extensions.DependencyInjection;
       using Microsoft.Extensions.Logging;
       using System;
       using System.Net.Http;
       using System.Threading.Tasks;
   
       namespace WorkerSDKOnConsole
       {
           class Program
           {
               static async Task Main(string[] args)
               {
                   // Create the DI container.
                   IServiceCollection services = new ServiceCollection();
   
                   // Being a regular console app, there is no appsettings.json or configuration providers enabled by default.
                   // Hence connection string and any changes to default logging level must be specified here.
                   services.AddLogging(loggingBuilder => loggingBuilder.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("Category", LogLevel.Information));
                   services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = "<YOUR-CONNECTION-STRING>");
   
                   // To pass a connection string
                   // - aiserviceoptions must be created
                   // - set connectionstring on it
                   // - pass it to AddApplicationInsightsTelemetryWorkerService()
   
                   // Build ServiceProvider.
                   IServiceProvider serviceProvider = services.BuildServiceProvider();
   
                   // Obtain logger instance from DI.
                   ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();
   
                   // Obtain TelemetryClient instance from DI, for additional manual tracking or to flush.
                   var telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();
   
                   var httpClient = new HttpClient();
   
                   while (true) // This app runs indefinitely. Replace with actual application termination logic.
                   {
                       logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
   
                       // Replace with a name which makes sense for this operation.
                       using (telemetryClient.StartOperation<RequestTelemetry>("operation"))
                       {
                           logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                           logger.LogInformation("Calling bing.com");                    
                           var res = await httpClient.GetAsync("https://bing.com");
                           logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                           telemetryClient.TrackEvent("Bing call event completed");
                       }
   
                       await Task.Delay(1000);
                   }
   
                   // Explicitly call Flush() followed by sleep is required in console apps.
                   // This is to ensure that even if application terminates, telemetry is sent to the back-end.
                   telemetryClient.Flush();
                   Task.Delay(5000).Wait();
               }
           }
       }
   

Este aplicativo de console também usa o mesmo padrão TelemetryConfiguration. Ele pode ser personalizado da mesma forma que os exemplos nas seções anteriores.

Pré-requisitos

Configurar a biblioteca de cliente Node.js

Inclua o SDK em seu aplicativo para que ele possa coletar dados.

1. Copie a cadeia de conexão do seu novo recurso. O Application Insights usa a cadeia de conexão para mapear dados para seu recurso do Azure. Antes que o SDK possa usar sua cadeia de conexão, você deve especificar a cadeia de conexão em uma variável de ambiente ou em seu código.

   

2. Adicione a biblioteca de cliente Node.js às dependências do seu aplicativo via package.json. Na pasta raiz da aplicação, execute:

   npm install applicationinsights --save
   

   Observação

   Se você estiver usando o TypeScript, não instale pacotes de "digitação" separados. Este pacote NPM contém digitações internas.

3. Carregue explicitamente a biblioteca no seu código. Como o SDK injeta instrumentação em muitas outras bibliotecas, carregue a biblioteca o mais cedo possível, antes mesmo de outras declarações require.

   let appInsights = require('applicationinsights');
   

4. Você também pode fornecer uma cadeia de conexão através da variável APPLICATIONINSIGHTS_CONNECTION_STRINGde ambiente , em vez de passá-la manualmente para setup() ou new appInsights.TelemetryClient(). Essa prática permite manter as cadeias de conexão fora do código-fonte confirmado e especificar cadeias de conexão diferentes para ambientes diferentes. Para configurar manualmente, chame appInsights.setup('[your connection string]');.

   Para obter mais opções de configuração, consulte as seções a seguir.

   Pode definir appInsights.defaultClient.config.disableAppInsights = true para experimentar o SDK sem enviar telemetria.

5. Comece a coletar e enviar dados automaticamente ligando para appInsights.start();.

Utilização básica

Para uma coleção pré-configurada de solicitações HTTP, eventos populares de bibliotecas de terceiros, exceções não tratadas e métricas do sistema:

let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

Carregue a biblioteca require("applicationinsights") do Application Insights o mais cedo possível em seus scripts antes de carregar outros pacotes. Esta etapa é necessária para que a biblioteca do Application Insights possa preparar pacotes posteriores para rastreamento. Se você encontrar conflitos com outras bibliotecas que fazem uma preparação semelhante, tente carregar a biblioteca do Application Insights posteriormente.

Devido à maneira como o JavaScript lida com retornos de chamada, é necessário mais trabalho para rastrear uma solicitação em dependências externas e retornos de chamada posteriores. Por padrão, esse rastreamento extra está habilitado. Desative-o chamando setAutoDependencyCorrelation(false) conforme descrito na seção de configuração do SDK.

Migrar de versões anteriores à 0.22

Há alterações significativas entre as versões anteriores à versão 0.22 e posteriores. Essas alterações foram projetadas para trazer consistência com outros SDKs do Application Insights e permitir extensibilidade futura.

Em geral, você pode migrar com as seguintes ações:

• Substitua as referências a appInsights.client por appInsights.defaultClient.
• Substitua as referências a appInsights.getClient() por new appInsights.TelemetryClient().
• Substitua todos os argumentos para métodos client.track* por um único objeto contendo propriedades nomeadas como argumentos. Consulte a dica de tipo interna do IDE ou TelemetryTypes para obter o objeto excetuado para cada tipo de telemetria.

Se você acessar as funções de configuração do SDK sem encadeá-las ao appInsights.setup(), agora poderá encontrar essas funções em appInsights.Configurations. Um exemplo é appInsights.Configuration.setAutoCollectDependencies(true). Analise as alterações na configuração padrão na próxima seção.

ASP.NET & ASP.NET Núcleo

Execute seu aplicativo e faça solicitações para ele. A telemetria agora deve fluir para o Application Insights. O SDK do Application Insights coleta automaticamente as solicitações da Web de entrada para seu aplicativo, juntamente com a telemetria a seguir.

Serviço ao Trabalhador

Execute seu aplicativo. Os trabalhadores de todos os exemplos anteriores fazem uma chamada HTTP a cada segundo para bing.com e também emitem poucos logs usando ILogger. Essas linhas são encapsuladas dentro da StartOperation invocação de TelemetryClient, que é usada para criar uma operação. Neste exemplo, RequestTelemetry é chamado de "operação".

O Application Insights coleta esses logs ILogger, com uma severidade de Aviso ou superior por padrão, e dependências. Eles estão correlacionados RequestTelemetry com uma relação entre pais e filhos. A correlação também funciona através dos limites do processo/rede. Por exemplo, se a chamada foi feita para outro componente monitorado, ela também está correlacionada a esse pai.

Esta operação personalizada de RequestTelemetry pode ser vista como equivalente a um pedido web de entrada num aplicativo web típico. Não é necessário usar uma operação, mas ela se encaixa melhor com o modelo de dados de correlação do Application Insights. RequestTelemetry atua como a operação pai e cada telemetria gerada dentro da iteração do trabalhador é tratada como logicamente pertencente à mesma operação.

Essa abordagem também garante que a telemetria gerada, tanto automática quanto manual, tenha o mesmo operation_id. Como a amostragem é baseada no operation_id, o algoritmo de amostragem mantém ou descarta toda a telemetria de uma única iteração.

O SDK reúne automaticamente a telemetria sobre o tempo de execução do Node.js e alguns módulos comuns de terceiros. Utilize a sua aplicação para gerar alguns destes dados.

Em seguida, no portal do Azure, aceda ao recurso do Application Insights que criou anteriormente. Na Linha cronológica geral, procure os seus primeiros pontos de dados. Para ver dados mais detalhadas, selecione diferentes componentes nos gráficos.

Para exibir a topologia descoberta para seu aplicativo, você pode usar o Mapa de Aplicativos.

Sem dados

Como o SDK envia dados em lotes para envio, pode haver um atraso antes que os itens apareçam no portal. Se não vir dados no seu recurso, experimente algumas das correções a seguir.

• Continue a utilizar a aplicação. Realize mais ações para gerar mais telemetria.
• Selecione Atualizar na visualização de recursos do portal. Os gráficos atualizam-se periodicamente por si próprios, mas atualizá-los manualmente força-os a fazer a atualização de imediato.
• Confirme que as portas de saída necessárias estão abertas.
• Utilize a Pesquisa para procurar eventos específicos.
• Veja as FAQ.

Nesta secção

• Métricas em tempo real
• Vestígios (logs)
• Rastreio distribuído
• Dependências
• Exceções
• Métricas personalizadas
• Operações personalizadas
• Contadores
• Coleção de instantâneos

Métricas em tempo real

As métricas em tempo real podem ser usadas para verificar rapidamente se o monitoramento de aplicativos com o Application Insights está configurado corretamente. A telemetria pode levar alguns minutos para aparecer no portal do Azure, mas o painel de métricas ao vivo mostra o uso da CPU do processo em execução quase em tempo real. Ele também pode mostrar outras telemetrias, como solicitações, dependências e rastreamentos.

Habilite métricas ao vivo usando código para qualquer aplicativo .NET

ASP.NET

Para configurar manualmente as métricas em tempo real:

1. Instale o pacote NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

2. O código de aplicativo de console de exemplo a seguir mostra a configuração de métricas ao vivo:

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
using System;
using System.Threading.Tasks;

namespace LiveMetricsDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create a TelemetryConfiguration instance.
            TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
            config.ConnectionString = "<YOUR-CONNECTION-STRING>";
            QuickPulseTelemetryProcessor quickPulseProcessor = null;
            config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
                .Use((next) =>
                {
                    quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
                    return quickPulseProcessor;
                })
                .Build();

            var quickPulseModule = new QuickPulseTelemetryModule();

            // Secure the control channel.
            // This is optional, but recommended.
            quickPulseModule.AuthenticationApiKey = "<YOUR-API-KEY>";
            quickPulseModule.Initialize(config);
            quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

            // Create a TelemetryClient instance. It is important
            // to use the same TelemetryConfiguration here as the one
            // used to set up live metrics.
            TelemetryClient client = new TelemetryClient(config);

            // This sample runs indefinitely. Replace with actual application logic.
            while (true)
            {
                // Send dependency and request telemetry.
                // These will be shown in live metrics.
                // CPU/Memory Performance counter is also shown
                // automatically without any additional steps.
                client.TrackDependency("My dependency", "target", "http://sample",
                    DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
                client.TrackRequest("My Request", DateTimeOffset.Now,
                    TimeSpan.FromMilliseconds(230), "200", true);
                Task.Delay(1000).Wait();
            }
        }
    }
}

ASP.NET Core

Para configurar manualmente as métricas em tempo real:

1. Instale o pacote NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

2. O código de aplicativo de console de exemplo a seguir mostra a configuração de métricas ao vivo:

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.ConnectionString = "<YOUR-CONNECTION-STRING>";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "<YOUR-API-KEY>";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

O exemplo anterior é para um aplicativo de console, mas o mesmo código pode ser usado em qualquer aplicativo .NET.

Serviço ao Trabalhador

Os logs emitidos via ILogger com a gravidade de Aviso ou superior são capturados automaticamente. Para alterar este comportamento, substitua explicitamente a configuração de registo para o fornecedor ApplicationInsights, conforme mostrado no código seguinte. A configuração a seguir permite que o Application Insights capture todos os Information logs e logs mais severos.

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

É importante observar que o exemplo a seguir não faz com que o provedor do Application Insights capture Information logs. Não o captura porque o SDK adiciona um filtro de log padrão que instrui ApplicationInsights a capturar apenas logs Warning e logs mais severos. O Application Insights requer uma substituição explícita.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Para obter mais informações, siga os documentos do ILogger para personalizar quais níveis de log são capturados pelo Application Insights.

Vestígios (logs)

Esta seção explica como enviar logs de rastreamento de diagnóstico de aplicativos ASP.NET ou ASP.NET Core para o Application Insights e, em seguida, explorar/pesquisar esses logs no portal.

Você pode usar logs de rastreamento para identificar rastreamentos associados a cada solicitação de usuário e correlacioná-los com outros eventos e relatórios de exceções.

Application Insights captura logs de ASP.NET Core e de outros aplicativos .NET utilizando o ILogger, e de ASP.NET clássico (.NET Framework) através do SDK e adaptadores clássicos.

Instalar o registo na sua aplicação

ASP.NET

Escolha uma abordagem de registo de logs para emitir logs de diagnóstico que o Application Insights possa coletar.

Para aplicativos ASP.NET clássicos que usam o rastreamento System.Diagnostics , configure um Application Insights TraceListener na configuração.

Adicionar um ouvinte a web.config ou app.config:

<configuration>
  <system.diagnostics>
    <trace>
      <listeners>
        <add name="myAppInsightsListener"
             type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

Configurar o Application Insights para recolher logs

Opção 1: Adicione o Application Insights ao seu projeto, caso ainda não o tenha feito. Ao adicionar o Application Insights no Visual Studio, há uma opção para incluir o coletor de log.

Opção 2: Clique com o botão direito do mouse em seu projeto no Gerenciador de Soluções para Configurar o Application Insights. Selecione a opção Configurar coleta de rastreamento .

ASP.NET Core

O SDK do Application Insights para ASP.NET Core já coleta logs do ILogger por padrão. Se você usar o SDK, normalmente não precisará também chamar builder.Logging.AddApplicationInsights() e pode ignorar as seguintes instruções de instalação do ILogger.

Se precisar apenas do reencaminhamento de logs e não da pilha completa de telemetria, poderá usar o pacote do fornecedor Microsoft.Extensions.Logging.ApplicationInsights para capturar logs.

Instalação manual

Use esse método se o tipo de projeto não for suportado pelo instalador do Application Insights (por exemplo, alguns cenários de desktop/console) ou se preferir o controle explícito no nível do pacote.

1. No Gerenciador de Soluções, clique com o botão direito do mouse em seu projeto e selecione Gerenciar Pacotes NuGet.

2. Pesquise por Application Insights.

3. Selecione um dos seguintes pacotes:

   • ILogger: Microsoft.Extensions.Logging.ApplicationInsights
   • System.Diagnostics: Microsoft.ApplicationInsights.TraceListener
   • log4net: Microsoft.ApplicationInsights.Log4NetAppender
   • NLog: Microsoft.ApplicationInsights.NLogTarget
   • Microsoft.ApplicationInsights.EventSourceListener
   • Microsoft.ApplicationInsights.DiagnosticSourceListener
   • Banner Microsoft.ApplicationInsights.EtwCollector

O pacote NuGet instala os assemblies necessários e modifica o web.config ou app.config, se aplicável.

Instruções de instalação:

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Logging.AddApplicationInsights(
        configureTelemetryConfiguration: (config) => 
            config.ConnectionString = builder.Configuration.GetConnectionString("APPLICATIONINSIGHTS_CONNECTION_STRING"),
            configureApplicationInsightsLoggerOptions: (options) => { }
    );

builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("your-category", LogLevel.Trace);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

System.Diagnostics.Trace.TraceWarning("Slow response - database01");

    logger.Warn("Slow response - database01");

    <Add Type="Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule, Microsoft.ApplicationInsights.EtwCollector">
      <Sources>
        <Add ProviderName="MyCompanyEventSourceName" Level="Verbose" />
      </Sources>
    </Add>

Use a API de rastreamento diretamente

Você pode chamar a API de rastreamento do Application Insights diretamente. Os adaptadores de log usam essa API. Por exemplo:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow response - database01");

Uma vantagem de TrackTrace é que se podem colocar dados relativamente longos na mensagem. Por exemplo, você pode codificar dados POST lá.

Você também pode adicionar um nível de gravidade à sua mensagem. E, como outra telemetria, podes adicionar valores de propriedade para ajudar a filtrar ou procurar diferentes conjuntos de rastos. Por exemplo:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow database response",
                            SeverityLevel.Warning,
                            new Dictionary<string, string> { { "database", "db.ID" } });

Agora pode facilmente filtrar em Pesquisa todas as mensagens de um determinado nível de gravidade que estejam relacionadas com uma base de dados específica.

Aplicação de consola

Para adicionar o log do Application Insights aos aplicativos de console, primeiro instale os seguintes pacotes NuGet:

• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.Extensions.DependencyInjection

O exemplo a seguir usa o Microsoft.Extensions.Logging.ApplicationInsights pacote e demonstra o comportamento padrão para um aplicativo de console. O Microsoft.Extensions.Logging.ApplicationInsights pacote deve ser usado em um aplicativo de console ou sempre que você quiser uma implementação mínima do Application Insights sem o conjunto completo de recursos, como métricas, rastreamento distribuído, amostragem e inicializadores de telemetria.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

using var channel = new InMemoryChannel();

try
{
    IServiceCollection services = new ServiceCollection();
    services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);
    services.AddLogging(builder =>
    {
        // Only Application Insights is registered as a logger provider
        builder.AddApplicationInsights(
            configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",
            configureApplicationInsightsLoggerOptions: (options) => { }
        );
    });

    IServiceProvider serviceProvider = services.BuildServiceProvider();
    ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

    logger.LogInformation("Logger is working...");
}
finally
{
    // Explicitly call Flush() followed by Delay, as required in console apps.
    // This ensures that even if the application terminates, telemetry is sent to the back end.
    channel.Flush();

    await Task.Delay(TimeSpan.FromMilliseconds(1000));
}

Para obter mais informações, consulte Qual tipo de telemetria do Application Insights é produzido a partir de logs ILogger? Onde posso ver os logs do ILogger no Application Insights?.

Escopos de registro em log

ApplicationInsightsLoggingProvider Suporta escopos de log, que são habilitados por padrão.

Se o escopo for do tipo IReadOnlyCollection<KeyValuePair<string,object>>, cada par chave/valor na coleção será adicionado à telemetria do Application Insights como propriedades personalizadas. No exemplo a seguir, os logs são capturados como TraceTelemetry e têm ("MyKey", "MyValue") em propriedades.

using (_logger.BeginScope(new Dictionary<string, object> { ["MyKey"] = "MyValue" }))
{
    _logger.LogError("An example of an Error level message");
}

Se qualquer outro tipo for usado como escopo, ele será armazenado sob a propriedade Scope na telemetria do Application Insights. No exemplo a seguir, TraceTelemetry tem uma propriedade chamada Scope que contém o escopo.

using (_logger.BeginScope("hello scope"))
{
    _logger.LogError("An example of an Error level message");
}

Encontre os seus registos

Execute seu aplicativo no modo de depuração ou implante-o ao vivo.

Explorar na Pesquisa

No painel de visão geral da sua aplicação no portal Application Insights, selecione Pesquisar onde pode:

• Filtre em rastreamentos de log ou em itens com propriedades específicas.
• Inspecione um item específico em detalhes.
• Encontre outros dados de log do sistema relacionados à mesma solicitação do usuário (tem o mesmo ID de operação).
• Salve a configuração de uma página como favorita.

Explorar nos logs do Azure Monitor

Os logs do ILogger aparecem como telemetria de rastreamento (tabela traces no Application Insights e AppTraces no Log Analytics).

Exemplo

No portal do Azure, vá para Application Insights e execute:

traces
| where severityLevel >= 2 // 2=Warning, 1=Information, 0=Verbose
| take 50

Rastreio distribuído

As arquiteturas modernas de nuvem e microsserviços permitiram serviços simples e implantáveis de forma independente que reduzem custos e, ao mesmo tempo, aumentam a disponibilidade e a taxa de transferência. No entanto, torna mais difícil compreender e depurar os sistemas em geral. O rastreamento distribuído resolve este problema fornecendo um perfil de desempenho que funciona como pilhas de chamadas funcionais para arquiteturas de nuvem e microsserviços.

O Azure Monitor fornece duas experiências para consumir dados de rastreamento distribuídos: a exibição de diagnóstico de transação para uma única transação/solicitação e a exibição de mapa do aplicativo para mostrar como os sistemas interagem.

O Application Insights pode monitorar cada componente separadamente e detetar qual componente é responsável por falhas ou degradação do desempenho usando a correlação de telemetria distribuída. Este artigo explica o modelo de dados, técnicas de propagação de contexto, protocolos e implementação de táticas de correlação em diferentes linguagens e plataformas usadas pelo Application Insights.

Ative o rastreamento distribuído através do Application Insights por meio de autoinstrumentação ou SDKs.

Os agentes e SDKs do Application Insights para .NET, .NET Core, Java, Node.jse JavaScript suportam rastreamento distribuído nativamente.

Com o SDK adequado do Application Insights instalado e configurado, as informações de rastreamento são coletadas automaticamente para estruturas, bibliotecas e tecnologias populares pelos autocolectores de dependências do SDK. A lista completa de tecnologias suportadas está disponível na documentação de coleta automática de dependência.

Qualquer tecnologia também pode ser rastreada manualmente com uma chamada para TrackDependency no TelemetryClient.

Modelo de dados para correlação de telemetria

O Application Insights define um modelo de dados para correlação de telemetria distribuída. Para associar a telemetria a uma operação lógica, cada item de telemetria tem um campo de contexto chamado operation_Id. Cada item de telemetria no rastreamento distribuído compartilha esse identificador. Portanto, mesmo que você perca a telemetria de uma única camada, ainda poderá associar a telemetria relatada por outros componentes.

Uma operação lógica distribuída normalmente consiste em um conjunto de operações menores que são solicitações processadas por um dos componentes. A telemetria de solicitação define essas operações. Cada item de telemetria de solicitação tem seu próprio id que o identifica de forma única e global. E todos os itens de telemetria (como rastreamentos e exceções) associados à solicitação devem definir o valor de operation_parentId para o valor de id da solicitação.

A telemetria de dependência representa cada operação de saída, como uma chamada HTTP para outro componente. Ele também define o seu próprio id que é globalmente único. A telemetria de solicitação, iniciada por esta chamada de dependência, usa este id como seu operation_parentId.

Você pode criar uma exibição da operação lógica distribuída usando operation_Id, operation_parentIde request.id com dependency.id. Esses campos também definem a ordem de causalidade das chamadas de telemetria.

Em um ambiente de microsserviços, os rastreamentos de componentes podem ir para diferentes itens de armazenamento. Cada componente pode ter sua própria cadeia de conexão no Application Insights. Para obter telemetria para a operação lógica, o Application Insights consulta dados de cada item de armazenamento.

Quando o número de itens de armazenamento é grande, você precisa de uma dica sobre onde procurar em seguida. O modelo de dados do Application Insights define dois campos para resolver esse problema: request.source e dependency.target. O primeiro campo identifica o componente que iniciou a solicitação de dependência. O segundo campo identifica qual componente retornou a resposta da chamada de dependência.

Para obter informações sobre como consultar várias instâncias diferentes, consulte Consultar dados em espaços de trabalho, aplicativos e recursos do Log Analytics no Azure Monitor.

Example

Vejamos um exemplo. Um aplicativo chamado Stock Prices mostra o preço de mercado atual de uma ação usando uma API externa chamada Stock. O aplicativo Preços de Ações tem uma página chamada Página de Estoque que o navegador da Web do cliente abre usando GET /Home/Stock. O aplicativo consulta a API de estoque usando a chamada GET /api/stock/valueHTTP .

Você pode analisar a telemetria resultante executando uma consulta:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

Nos resultados, todos os itens de telemetria compartilham a raiz operation_Id. Quando uma chamada Ajax é feita a partir da página, um novo ID exclusivo (qJSXU) é atribuído à telemetria de dependência e o ID do pageView é usado como operation_ParentId. Em seguida, a solicitação do servidor usa o ID do Ajax como operation_ParentId.

Quando a chamada GET /api/stock/value é feita para um serviço externo, você precisa saber a identidade desse servidor para poder definir o dependency.target campo adequadamente. Quando o serviço externo não oferece suporte ao monitoramento, target é definido como o nome do host do serviço. Um exemplo é stock-prices-api.com. Mas se o serviço se identificar retornando um cabeçalho HTTP predefinido, target conterá a identidade do serviço que permite que o Application Insights crie um rastreamento distribuído consultando a telemetria desse serviço.

Cabeçalhos de correlação usando W3C TraceContext

O Application Insights está em transição para o W3C Trace-Context, que define:

• traceparent: Carrega o ID de operação globalmente exclusivo e o identificador exclusivo da chamada.
• tracestate: Carrega o contexto de rastreio específico do sistema.

A versão mais recente do SDK do Application Insights suporta o protocolo Trace-Context, mas talvez seja necessário optar por ele. (A manutenção da compatibilidade retroativa com o protocolo de correlação anterior suportado pelo SDK do Application Insights é assegurada.)

O protocolo HTTP de correlação, também chamado de Request-Id, está sendo preterido. Este protocolo define dois cabeçalhos:

• Request-Id: Carrega o ID globalmente exclusivo da chamada.
• Correlation-Context: Carrega a coleção de pares nome-valor das propriedades de rastreamento distribuído.

O Application Insights também define a extensão para o protocolo HTTP de correlação. Ele usa Request-Context pares nome-valor para propagar a coleção de propriedades usadas pelo chamador ou destinatário imediato. O SDK do Application Insights usa esse cabeçalho para definir os dependency.target campos e request.source .

Os modelos de dados do W3C Trace-Context e Application Insights são mapeados da seguinte maneira:

Para obter mais informações, consulte Modelo de dados de telemetria do Application Insights.

Habilite o suporte ao rastreamento distribuído do W3C

O rastreamento distribuído baseado em TraceContext do W3C é habilitado por padrão em todos os SDKs recentes do .NET Framework/.NET Core, juntamente com a compatibilidade com versões anteriores do protocolo herdado Request-Id .

Correlação de telemetria

A correlação é tratada por padrão ao integrar um aplicativo. Não são necessárias ações especiais.

O runtime do .NET oferece capacidades para operações distribuídas com a ajuda de Activity e DiagnosticSource

O SDK do .NET do Application Insights usa DiagnosticSource e Activity para coletar e correlacionar telemetria.

Dependências

Dependências rastreadas automaticamente

Os SDKs do Application Insights para .NET e .NET Core são fornecidos com DependencyTrackingTelemetryModuleo , que é um módulo de telemetria que coleta automaticamente dependências. O módulo DependencyTrackingTelemetryModule é fornecido como o pacote NuGet Microsoft.ApplicationInsights.DependencyCollector e trazido automaticamente quando você usa o Microsoft.ApplicationInsights.Web pacote NuGet ou o Microsoft.ApplicationInsights.AspNetCore pacote NuGet.

Atualmente, DependencyTrackingTelemetryModule rastreia as seguintes dependências automaticamente:

Se a dependência não for recolhida automaticamente, pode rastreá-la manualmente com uma chamada de monitorização de dependência.

Para obter mais informações sobre como funciona o controle de dependência, consulte Controle de dependência no Application Insights.

Configurar o controlo automático de dependências em aplicações de consola

Para controlar automaticamente as dependências dos aplicativos de console .NET, instale o pacote Microsoft.ApplicationInsights.DependencyCollector NuGet e inicialize DependencyTrackingTelemetryModule:

    DependencyTrackingTelemetryModule depModule = new DependencyTrackingTelemetryModule();
    depModule.Initialize(TelemetryConfiguration.Active);

Rastreando dependências manualmente

Os seguintes exemplos de dependências, que não são coletadas automaticamente, exigem rastreamento manual:

• O Azure Cosmos DB é automaticamente rastreado apenas quando se utiliza HTTP/HTTPS. O modo TCP não é capturado automaticamente pelo Application Insights para versões do SDK anteriores ao 2.22.0-Beta1.
• Redis

Para essas dependências não coletadas automaticamente pelo SDK, você pode rastreá-las manualmente usando a API TrackDependency usada pelos módulos de coleta automática padrão.

Exemplo

Se você criar seu código com um assembly que você mesmo não escreveu, você pode cronometrar todas as chamadas para ele. Este cenário permitir-lhe-ia descobrir qual a sua contribuição para os seus tempos de resposta.

Para que esses dados sejam exibidos nos gráficos de dependência no Application Insights, envie-os usando TrackDependency:

    var startTime = DateTime.UtcNow;
    var timer = System.Diagnostics.Stopwatch.StartNew();
    try
    {
        // making dependency call
        success = dependency.Call();
    }
    finally
    {
        timer.Stop();
        telemetryClient.TrackDependency("myDependencyType", "myDependencyCall", "myDependencyData", startTime, timer.Elapsed, success);
    }

Como alternativa, TelemetryClient fornece os métodos de extensão StartOperation e StopOperation, que podem ser usados para controlar manualmente as dependências conforme mostrado em Rastreamento de dependências de saída.

Desativando o módulo de controle de dependência padrão

Para obter mais informações, consulte Módulos de telemetria.

Acompanhamento SQL avançado para obter consulta SQL completa

Para chamadas SQL, o nome do servidor e do banco de dados é sempre coletado e armazenado como o nome do arquivo DependencyTelemetry. Outro campo, chamado dados, pode conter o texto completo da consulta SQL.

ASP.NET

Para aplicações ASP.NET, o texto completo da consulta SQL é coletado através da instrumentação de código byte, que requer o uso do motor de instrumentação ou do pacote NuGet Microsoft.Data.SqlClient, em vez da biblioteca System.Data.SqlClient. As etapas específicas da plataforma para habilitar a coleção completa de Consultas SQL são descritas na tabela a seguir.

Além das etapas específicas da plataforma anteriores, você também deve optar explicitamente por habilitar a coleta de comandos SQL modificando o ApplicationInsights.config arquivo com o seguinte código:

<TelemetryModules>
  <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
    <EnableSqlCommandTextInstrumentation>true</EnableSqlCommandTextInstrumentation>
  </Add>

ASP.NET Core

Para aplicativos ASP.NET Core, é necessário optar pela coleção SQL Text usando:

services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module. EnableSqlCommandTextInstrumentation = true; });

Nos casos anteriores, a maneira correta de validar que o mecanismo de instrumentação está instalado corretamente é validando que a versão SDK do coletado DependencyTelemetry é rddp. O uso de ou rdddsd indica que as dependências são coletadas por meio rddf de retornos DiagnosticSource de EventSource chamada, portanto, a consulta SQL completa não é capturada.

Exceptions

Exceções em aplicativos Web podem ser relatadas com o Application Insights. Você pode correlacionar solicitações com falha com exceções e outros eventos no cliente e no servidor para que possa diagnosticar rapidamente as causas. Nesta seção, você aprenderá a configurar relatórios de exceções, relatar exceções explicitamente, diagnosticar falhas e muito mais.

Configurar o relatório de exceções

Você pode configurar o Application Insights para relatar exceções que ocorrem no servidor ou no cliente. Dependendo da plataforma da qual seu aplicativo depende, você precisa da extensão ou SDK apropriado.

Server-side

Para que as exceções sejam relatadas do seu aplicativo do lado do servidor, considere os seguintes cenários:

• Adicione a extensão do Application Insights para aplicativos Web do Azure.
• Adicione a Extensão de Monitoramento de Aplicativo para VMs do Azure e a escala da máquina virtual do Azure define aplicativos hospedados no IIS.
• Adicione o SDK do Application Insights ao código do seu aplicativo, execute o Application Insights Agent para servidores Web IIS ou habilite o agente Java para aplicativos Web Java.

Lado do cliente

O JavaScript SDK fornece a capacidade de relatórios do lado do cliente de exceções que ocorrem em navegadores da Web. Para configurar relatórios de exceção no cliente, consulte Application Insights para páginas da Web.

Estruturas de aplicação

Com algumas estruturas de aplicativos, mais configuração é necessária. Considere as seguintes tecnologias:

• Formulários Web
• MVC
• API Web 1.*
• API Web 2.*
• WCF

Diagnosticar falhas e exceções

portal do Azure

O Application Insights vem com uma experiência de gerenciamento de desempenho de aplicativos selecionada para ajudá-lo a diagnosticar falhas em seus aplicativos monitorados.

Para obter instruções detalhadas, consulte Investigar falhas, desempenho e transações com o Application Insights.

Visual Studio

1. Abra a solução de aplicativo no Visual Studio. Execute o aplicativo, no servidor ou na máquina de desenvolvimento, usando F5. Recrie a exceção.

2. Abra a janela de telemetria Pesquisa do Application Insights no Visual Studio. Durante a depuração, selecione a caixa suspensa Application Insights .

3. Selecione um relatório de exceção para mostrar seu rastreamento de pilha. Para abrir o arquivo de código relevante, selecione uma referência de linha no rastreamento de pilha.

   Se o CodeLens estiver habilitado, você verá dados sobre as exceções:

   

Rastreamento personalizado e dados de log

Para obter dados de diagnóstico específicos para seu aplicativo, você pode inserir código para enviar seus próprios dados de telemetria. Seus dados personalizados de telemetria ou log são exibidos na pesquisa de diagnóstico ao lado da solicitação, da visualização de página e de outros dados coletados automaticamente.

Usando o Microsoft.VisualStudio.ApplicationInsights.TelemetryClient, você tem várias APIs disponíveis:

• TelemetryClient.TrackEvent é normalmente usado para monitorar padrões de uso, mas os dados enviados também aparecem em Eventos personalizados na pesquisa de diagnóstico. Os eventos são nomeados e podem carregar propriedades de cadeia de caracteres e métricas numéricas nas quais você pode filtrar suas pesquisas de diagnóstico.
• TelemetryClient.TrackTrace permite enviar dados mais longos, como informações POST.
• TelemetryClient.TrackException envia detalhes de exceção, como rastreamentos de pilha para o Application Insights.

Para ver esses eventos, no menu à esquerda, abra Pesquisar. Selecione o menu suspenso Tipos de evento e escolha Evento personalizado, Rastreamento ou Exceção.

Ver pedido de dados POST

Os detalhes da solicitação não incluem os dados enviados para seu aplicativo em uma chamada POST. Para que estes dados sejam comunicados:

• Adicione o SDK do Application Insights ao código do seu aplicativo.
• Insira o código em seu aplicativo para chamar Microsoft.ApplicationInsights.TrackTrace(). Envie os dados POST no parâmetro message. Há um limite para o tamanho permitido, então você deve tentar enviar apenas os dados essenciais.
• Ao investigar uma solicitação com falha, localize os rastreamentos associados.

Capturar exceções e dados de diagnóstico relacionados

Por padrão, nem todas as exceções que causam falhas em seu aplicativo aparecem no portal. Se você usar o SDK JavaScript em suas páginas da Web, verá exceções do navegador. No entanto, a maioria das exceções do lado do servidor são intercetadas pelo IIS, portanto, você precisa adicionar algum código para capturá-las e relatá-las.

É possível:

• Registre exceções explicitamente inserindo código em manipuladores de exceção para relatar as exceções.
• Capture exceções automaticamente configurando sua estrutura ASP.NET. Os aditamentos necessários são diferentes para diferentes tipos de quadros.

Comunicar exceções explicitamente

A maneira mais simples de relatar é inserir uma chamada para trackException() em um manipulador de exceções.

C#

var telemetry = new TelemetryClient();

try
{
    // ...
}
catch (Exception ex)
{
    var properties = new Dictionary<string, string>
    {
        ["Game"] = currentGame.Name
    };

    var measurements = new Dictionary<string, double>
    {
        ["Users"] = currentGame.Users.Count
    };

    // Send the exception telemetry:
    telemetry.TrackException(ex, properties, measurements);
}

JavaScript

try
{
    // ...
}
catch (ex)
{
    appInsights.trackException(ex, "handler loc",
    {
        Game: currentGame.Name,
        State: currentGame.State.ToString()
    });
}

Os parâmetros de propriedades e medidas são opcionais, mas são úteis para filtrar e adicionar informações extras. Por exemplo, se tiver uma aplicação que possa executar vários jogos, poderá encontrar os relatórios de exceção relacionados com um jogo específico. Você pode adicionar quantos itens quiser a cada dicionário.

Exceções do navegador

A maioria das exceções do navegador são relatadas.

Se sua página da Web incluir arquivos de script de redes de distribuição de conteúdo ou outros domínios, verifique se a marca de script tem o atributo crossorigin="anonymous" e se o servidor envia cabeçalhos CORS. Esse comportamento permite que você obtenha um rastreamento de pilha e detalhes para exceções JavaScript não tratadas desses recursos.

Reutilize seu cliente de telemetria

Com a Injeção de Dependência (DI) no .NET, o SDK do .NET apropriado e a configuração correta do Application Insights for DI, você pode exigir o TelemetryClient parâmetro as a constructor.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

    public ExampleController(TelemetryClient telemetryClient)
    {
        _telemetryClient = telemetryClient;
    }
}

No exemplo anterior, o TelemetryClient é injetado ExampleController na classe.

Formulários Web

Para formulários da Web, o módulo HTTP é capaz de coletar as exceções quando não há redirecionamentos configurados com CustomErrors. No entanto, quando você tiver redirecionamentos ativos, adicione as seguintes linhas à Application_Error função no Global.asax.cs.

void Application_Error(object sender, EventArgs e)
{
    if (HttpContext.Current.IsCustomErrorEnabled &&
        Server.GetLastError () != null)
    {
        _telemetryClient.TrackException(Server.GetLastError());
    }
}

No exemplo anterior, o _telemetryClient é uma variável de escopo de classe do tipo TelemetryClient.

MVC

A partir do Application Insights Web SDK versão 2.6 (beta 3 e posterior), o Application Insights coleta automaticamente exceções não tratadas lançadas nos métodos de controladores MVC 5+. Se você adicionou anteriormente um manipulador personalizado para controlar essas exceções, poderá removê-lo para evitar o rastreamento duplo de exceções.

Há vários cenários em que um filtro de exceção não pode lidar corretamente com erros quando exceções são lançadas:

• De construtores de controladores
• De manipuladores de mensagens
• Durante o encaminhamento
• Durante a serialização do conteúdo de resposta
• Durante o arranque da aplicação
• Em tarefas em segundo plano

Todas as exceções tratadas pelo aplicativo ainda precisam ser rastreadas manualmente. Exceções não tratadas originadas de controladores normalmente resultam em uma resposta 500 "Erro interno do servidor". Se essa resposta for construída manualmente como resultado de uma exceção manipulada, ou nenhuma exceção, ela será rastreada na telemetria de solicitação correspondente com ResultCode 500. No entanto, o SDK do Application Insights não consegue controlar uma exceção correspondente.

Suporte a versões anteriores

Se você usar o MVC 4 (e anterior) do Application Insights Web SDK 2.5 (e anterior), consulte os exemplos a seguir para controlar exceções.

using System;
using System.Web.Mvc;
using Microsoft.ApplicationInsights;

namespace MVC2App.Controllers
{
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)]
    public class AiHandleErrorAttribute : HandleErrorAttribute
    {
        public override void OnException(ExceptionContext filterContext)
        {
            if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
            {
                //The attribute should track exceptions only when CustomErrors setting is On
                //if CustomErrors is Off, exceptions will be caught by AI HTTP Module
                if (filterContext.HttpContext.IsCustomErrorEnabled)
                {   //Or reuse instance (recommended!). See note above.
                    var ai = new TelemetryClient();
                    ai.TrackException(filterContext.Exception);
                }
            }
            base.OnException(filterContext);
        }
    }
}

    namespace MVC2App.Controllers
    {
        [AiHandleError]
        public class HomeController : Controller
        {
            // Omitted for brevity
        }
    }

public class MyMvcApplication : System.Web.HttpApplication
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        filters.Add(new AiHandleErrorAttribute());
    }
}

public class FilterConfig
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        // Default replaced with the override to track unhandled exceptions
        filters.Add(new AiHandleErrorAttribute());
    }
}

Web API

A partir do SDK da Web do Application Insights versão 2.6 (beta 3 e posterior), o Application Insights coleta exceções não tratadas lançadas nos métodos do controlador automaticamente para a API Web 2+. Se você adicionou anteriormente um manipulador personalizado para controlar essas exceções, conforme descrito nos exemplos a seguir, poderá removê-lo para evitar o controle duplo de exceções.

Há vários casos que os filtros de exceção não podem lidar. Por exemplo:

• Exceções lançadas de construtores de controlador.
• Exceções lançadas de manipuladores de mensagens.
• Exceções lançadas durante o roteamento.
• Exceções lançadas durante a serialização do conteúdo de resposta.
• Exceção lançada durante a inicialização do aplicativo.
• Exceção lançada em tarefas em segundo plano.

Todas as exceções tratadas pelo aplicativo ainda precisam ser rastreadas manualmente. Exceções não tratadas originadas de controladores normalmente resultam em uma resposta 500 "Erro interno do servidor". Se essa resposta for construída manualmente como resultado de uma exceção manipulada, ou nenhuma exceção, ela será rastreada em uma telemetria de solicitação correspondente com ResultCode 500. No entanto, o SDK do Application Insights não pode rastrear uma exceção correspondente.

Suporte a versões anteriores

Se você usar a API Web 1 (e anteriores) do Application Insights Web SDK 2.5 (e anteriores), consulte os exemplos a seguir para controlar exceções.

using System.Web.Http.Filters;
using Microsoft.ApplicationInsights;

namespace WebAPI.App_Start
{
    public class AiExceptionFilterAttribute : ExceptionFilterAttribute
    {
    public override void OnException(HttpActionExecutedContext actionExecutedContext)
    {
        if (actionExecutedContext != null && actionExecutedContext.Exception != null)
        {  //Or reuse instance (recommended!). See note above.
            var ai = new TelemetryClient();
            ai.TrackException(actionExecutedContext.Exception);
        }
        base.OnException(actionExecutedContext);
    }
    }
}

using System.Web.Http;
using WebApi1.x.App_Start;

namespace WebApi1.x
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });
    
            // ...
            config.EnableSystemDiagnosticsTracing();
    
            // Capture exceptions for Application Insights:
            config.Filters.Add(new AiExceptionFilterAttribute());
        }
    }
}

using System.Web.Http.ExceptionHandling;
using Microsoft.ApplicationInsights;

namespace ProductsAppPureWebAPI.App_Start
{
    public class AiExceptionLogger : ExceptionLogger
    {
        public override void Log(ExceptionLoggerContext context)
        {
            if (context != null && context.Exception != null)
            {
                //or reuse instance (recommended!). see note above
                var ai = new TelemetryClient();
                ai.TrackException(context.Exception);
            }
            base.Log(context);
        }
    }
}

using System.Web.Http;
using System.Web.Http.ExceptionHandling;
using ProductsAppPureWebAPI.App_Start;

namespace WebApi2WithMVC
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API configuration and services
    
            // Web API routes
            config.MapHttpAttributeRoutes();
    
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });

            config.Services.Add(typeof(IExceptionLogger), new AiExceptionLogger());
        }
    }
}

WCF

Adicione uma classe que estenda Attribute e implemente IErrorHandler e IServiceBehavior.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.ServiceModel.Description;
    using System.ServiceModel.Dispatcher;
    using System.Web;
    using Microsoft.ApplicationInsights;

    namespace WcfService4.ErrorHandling
    {
      public class AiLogExceptionAttribute : Attribute, IErrorHandler, IServiceBehavior
      {
        public void AddBindingParameters(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase,
            System.Collections.ObjectModel.Collection<ServiceEndpoint> endpoints,
            System.ServiceModel.Channels.BindingParameterCollection bindingParameters)
        {
        }

        public void ApplyDispatchBehavior(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
            foreach (ChannelDispatcher disp in serviceHostBase.ChannelDispatchers)
            {
                disp.ErrorHandlers.Add(this);
            }
        }

        public void Validate(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
        }

        bool IErrorHandler.HandleError(Exception error)
        {//or reuse instance (recommended!). see note above
            var ai = new TelemetryClient();

            ai.TrackException(error);
            return false;
        }

        void IErrorHandler.ProvideFault(Exception error,
            System.ServiceModel.Channels.MessageVersion version,
            ref System.ServiceModel.Channels.Message fault)
        {
        }
      }
    }

Adicione o atributo às implementações de serviço:

namespace WcfService4
{
    [AiLogException]
    public class Service1 : IService1
    {
        // Omitted for brevity
    }
}

Exemplo

Contadores de desempenho de exceção

Se você instalou o Azure Monitor Application Insights Agent em seu servidor, poderá obter um gráfico da taxa de exceções medida pelo .NET. As exceções do .NET manipuladas e não tratadas estão incluídas.

Abra uma guia do explorador de métricas e adicione um novo gráfico. Em Contadores de Desempenho, selecione Taxa de exceção.

O .NET Framework calcula a taxa contando o número de exceções em um intervalo e dividindo pelo comprimento do intervalo.

Essa contagem é diferente da contagem de exceções calculada pelos relatórios de contagem TrackException do portal do Application Insights. Os intervalos de amostragem são diferentes e o SDK não envia TrackException relatórios para todas as exceções tratadas e não tratadas.

Coleta de métricas personalizadas

Os SDKs .NET e .NET Core do Azure Monitor Application Insights têm dois métodos diferentes de coleta de métricas personalizadas:

• O TrackMetric() método, que carece de preagregação.
• O GetMetric() método, que tem pré-agregação.

Recomendamos o uso da agregação, portantoTrackMetric(), não é mais o método preferido de coleta de métricas personalizadas. Este artigo orienta você sobre o uso do GetMetric() método e alguns dos fundamentos por trás de como ele funciona.

Introdução ao GetMetric

Para nossos exemplos, vamos usar um aplicativo de serviço de trabalho .NET Core 3.1 básico. Se você quiser replicar o ambiente de teste usado com esses exemplos, siga as etapas 1 a 6 em Aplicativo .NET Core Worker Service. Estas etapas adicionam o Application Insights a um modelo de projeto de serviço de trabalho básico. Os conceitos se aplicam a qualquer aplicativo geral em que o SDK possa ser usado, incluindo aplicativos Web e aplicativos de console.

Enviar métricas

Substitua o conteúdo do arquivo worker.cs pelo seguinte código:

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.ApplicationInsights;

namespace WorkerService3
{
    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;
        private TelemetryClient _telemetryClient;

        public Worker(ILogger<Worker> logger, TelemetryClient tc)
        {
            _logger = logger;
            _telemetryClient = tc;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {   // The following line demonstrates usages of GetMetric API.
            // Here "computersSold", a custom metric name, is being tracked with a value of 42 every second.
            while (!stoppingToken.IsCancellationRequested)
            {
                _telemetryClient.GetMetric("ComputersSold").TrackValue(42);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(1000, stoppingToken);
            }
        }
    }
}

Quando você executa o código de exemplo, você vê o while loop repetidamente em execução sem telemetria sendo enviada na janela de saída do Visual Studio. Um único item de telemetria é enviado em torno da marca de 60 segundos, que em nosso teste se parece com:

Application Insights Telemetry: {"name":"Microsoft.ApplicationInsights.Dev.00000000-0000-0000-0000-000000000000.Metric", "time":"2019-12-28T00:54:19.0000000Z",
"ikey":"00000000-0000-0000-0000-000000000000",
"tags":{"ai.application.ver":"1.0.0.0",
"ai.cloud.roleInstance":"Test-Computer-Name",
"ai.internal.sdkVersion":"m-agg2c:2.12.0-21496",
"ai.internal.nodeName":"Test-Computer-Name"},
"data":{"baseType":"MetricData",
"baseData":{"ver":2,"metrics":[{"name":"ComputersSold",
"kind":"Aggregation",
"value":1722,
"count":41,
"min":42,
"max":42,
"stdDev":0}],
"properties":{"_MS.AggregationIntervalMs":"42000",
"DeveloperMode":"true"}}}}

Este único item de telemetria representa um agregado de 41 medições métricas distintas. Como estávamos enviando o mesmo valor repetidamente, temos um desvio padrão (stDev) com 0 valores máximos (max) e mínimos (min) idênticos. A value propriedade representa uma soma de todos os valores individuais que foram agregados.

Se examinarmos nosso recurso do Application Insights na experiência de Logs (Analytics), o item de telemetria individual se parecerá com a captura de tela a seguir.

Você também pode acessar sua telemetria métrica personalizada na seção Métricas do portal como uma métrica baseada em log e personalizada. A captura de tela a seguir é um exemplo de uma métrica baseada em log.

Referência de métrica de cache para uso de alta taxa de transferência

Os valores métricos podem ser observados com frequência em alguns casos. Por exemplo, um serviço de alta taxa de transferência que processa 500 solicitações por segundo pode querer emitir 20 métricas de telemetria para cada solicitação. O resultado significa rastrear 10.000 valores por segundo. Nesses cenários de alta taxa de transferência, os usuários podem precisar ajudar o SDK evitando algumas pesquisas.

Por exemplo, o exemplo anterior realizou uma pesquisa de um identificador para a métrica ComputersSold e, em seguida, rastreou um valor observado de 42. Em vez disso, o identificador pode ser armazenado em cache para várias invocações de faixa:

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is where the cache is stored to handle faster lookup
            Metric computersSold = _telemetryClient.GetMetric("ComputersSold");
            while (!stoppingToken.IsCancellationRequested)
            {

                computersSold.TrackValue(42);

                computersSold.TrackValue(142);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

Além de armazenar em cache o identificador de métrica, o exemplo anterior também foi reduzido Task.Delay para 50 milissegundos para que o loop fosse executado com mais frequência. O resultado são 772 TrackValue() invocações.

Métricas multidimensionais

Os exemplos na seção anterior mostram métricas de dimensão zero. As métricas também podem ser multidimensionais. Atualmente suportamos até 10 dimensões.

Aqui está um exemplo de como criar uma métrica unidimensional:

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is an example of a metric with a single dimension.
            // FormFactor is the name of the dimension.
            Metric computersSold= _telemetryClient.GetMetric("ComputersSold", "FormFactor");

            while (!stoppingToken.IsCancellationRequested)
            {
                // The number of arguments (dimension values)
                // must match the number of dimensions specified while GetMetric.
                // Laptop, Tablet, etc are values for the dimension "FormFactor"
                computersSold.TrackValue(42, "Laptop");
                computersSold.TrackValue(20, "Tablet");
                computersSold.TrackValue(126, "Desktop");


                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

A execução do código de exemplo por pelo menos 60 segundos resulta no envio de três itens de telemetria distintos para o Azure. Cada item representa a agregação de um dos três fatores forma. Como antes, você pode examinar mais detalhadamente na visualização Logs (Analytics ).

No explorador de métricas:

Observe que você não pode dividir a métrica pela nova dimensão personalizada ou exibir sua dimensão personalizada com a visualização de métricas.

Por padrão, as métricas multidimensionais no explorador de métricas não são ativadas nos recursos do Application Insights.

Habilite métricas multidimensionais

Para habilitar métricas multidimensionais para um recurso do Application Insights, selecione Uso e custos> estimadosMétricas> personalizadasHabilitar alertas sobre dimensões> métricas personalizadasOK. Para obter mais informações, consulte Dimensões e agregação de métricas personalizadas.

Depois de fazer essa alteração e enviar uma nova telemetria multidimensional, você pode selecionar Aplicar divisão.

Visualize suas agregações métricas para cada FormFactor dimensão.

Use MetricIdentifier quando houver mais de três dimensões

Atualmente, 10 dimensões são suportadas. A utilização de mais de três dimensões requer a utilização de MetricIdentifier:

// Add "using Microsoft.ApplicationInsights.Metrics;" to use MetricIdentifier
// MetricIdentifier id = new MetricIdentifier("[metricNamespace]","[metricId],"[dim1]","[dim2]","[dim3]","[dim4]","[dim5]");
MetricIdentifier id = new MetricIdentifier("CustomMetricNamespace","ComputerSold", "FormFactor", "GraphicsCard", "MemorySpeed", "BatteryCapacity", "StorageCapacity");
Metric computersSold = _telemetryClient.GetMetric(id);
computersSold.TrackValue(110,"Laptop", "Nvidia", "DDR4", "39Wh", "1TB");

Configuração métrica personalizada

Se quiser alterar a configuração da métrica, você deve fazer alterações no local onde a métrica é inicializada.

Nomes de dimensões especiais

As métricas não usam o contexto de telemetria do TelemetryClient usado para acessá-las. Usar nomes de dimensões especiais disponíveis como constantes na MetricDimensionNames classe é a melhor solução alternativa para essa limitação.

As agregações métricas enviadas pela métrica a seguir Special Operation Request Sizenão estão Context.Operation.Name definidas como Special Operation. O TrackMetric() método ou qualquer outro TrackXXX() método foi OperationName definido corretamente como Special Operation.

        //...
        TelemetryClient specialClient;
        private static int GetCurrentRequestSize()
        {
            // Do stuff
            return 1100;
        }
        int requestSize = GetCurrentRequestSize()

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                //...
                specialClient.Context.Operation.Name = "Special Operation";
                specialClient.GetMetric("Special Operation Request Size").TrackValue(requestSize);
                //...
            }
                   
        }

Nessa circunstância, use os nomes de dimensão especiais listados na MetricDimensionNames classe para especificar os TelemetryContext valores.

Por exemplo, quando a métrica agregada resultante da próxima instrução é enviada para o ponto de extremidade na nuvem do Application Insights, seu Context.Operation.Name campo de dados é definido como Special Operation:

_telemetryClient.GetMetric("Request Size", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation");

O valor desta dimensão especial é copiado e TelemetryContext não é usado como uma dimensão normal . Se você quiser também manter uma dimensão de operação para exploração métrica normal, precisará criar uma dimensão separada para essa finalidade:

_telemetryClient.GetMetric("Request Size", "Operation Name", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation", "Special Operation");

Dimensionamento e limite de séries cronológicas

Para evitar que o subsistema de telemetria use acidentalmente seus recursos, você pode controlar o número máximo de séries de dados por métrica. Os limites padrão não são mais de 1.000 séries de dados totais por métrica e não mais de 100 valores diferentes por dimensão.

No contexto da limitação de dimensões e séries temporais, usamos Metric.TrackValue(..) para garantir que os limites sejam observados. Se os limites já foram atingidos, Metric.TrackValue(..) retorna False e o valor não é rastreado. Caso contrário, ele retornará True. Esse comportamento é útil se os dados de uma métrica se originarem da entrada do usuário.

O MetricConfiguration construtor usa algumas opções sobre como gerenciar séries diferentes dentro da respetiva métrica e um objeto de uma implementação IMetricSeriesConfiguration de classe que especifica o comportamento de agregação para cada série individual da métrica:

var metConfig = new MetricConfiguration(seriesCountLimit: 100, valuesPerDimensionLimit:2,
                new MetricSeriesConfigurationForMeasurement(restrictToUInt32Values: false));

Metric computersSold = _telemetryClient.GetMetric("ComputersSold", "Dimension1", "Dimension2", metConfig);

// Start tracking.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value1");
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value2");

// The following call gives 3rd unique value for dimension2, which is above the limit of 2.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3");
// The above call doesn't track the metric, and returns false.

• seriesCountLimit é o número máximo de séries temporais de dados que uma métrica pode conter. Quando esse limite é atingido, as chamadas para TrackValue() isso normalmente resultariam em um retorno falsede nova série.
• valuesPerDimensionLimit limita o número de valores distintos por dimensão de forma semelhante.
• restrictToUInt32Values Determina se apenas valores inteiros não negativos devem ou não ser rastreados.

Eis um exemplo de como enviar uma mensagem para saber se os limites máximos são excedidos:

if (! computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3"))
{
// Add "using Microsoft.ApplicationInsights.DataContract;" to use SeverityLevel.Error
_telemetryClient.TrackTrace("Metric value not tracked as value of one of the dimension exceeded the cap. Revisit the dimensions to ensure they are within the limits",
SeverityLevel.Error);
}

Acompanhamento de operações personalizadas

Os SDKs do Application Insights rastreiam automaticamente solicitações HTTP de entrada e chamadas para serviços dependentes, como solicitações HTTP e consultas SQL. O rastreamento e a correlação de solicitações e dependências oferecem visibilidade sobre a capacidade de resposta e a confiabilidade de todo o aplicativo em todos os microsserviços que combinam esse aplicativo.

Há uma classe de padrões de aplicativos que não podem ser suportados genericamente. O monitoramento adequado de tais padrões requer instrumentação manual de código. Esta seção aborda alguns padrões que podem exigir instrumentação manual, como processamento de fila personalizado e execução de tarefas em segundo plano de longa execução.

Esta seção fornece orientação sobre como controlar operações personalizadas com o SDK do Application Insights.

Visão geral

Uma operação é uma parte lógica do trabalho executado por um aplicativo. Ele tem um nome, hora de início, duração, resultado e um contexto de execução como nome de usuário, propriedades e resultado. Se a operação A foi iniciada pela operação B, então a operação B é definida como pai para A. Uma operação pode ter apenas um dos pais, mas pode ter muitas operações filhas. Para obter mais informações sobre operações e correlação de telemetria, consulte Correlação de telemetria do Application Insights.

No SDK do Application Insights .NET, a operação é descrita pela classe abstrata OperationTelemetry e seus descendentes RequestTelemetry e DependencyTelemetry.

Acompanhamento de operações de entrada

O SDK da Web do Application Insights coleta automaticamente solicitações HTTP para aplicativos ASP.NET executados em um pipeline do IIS e todos os aplicativos ASP.NET Core. Existem soluções suportadas pela comunidade para outras plataformas e estruturas. Se o aplicativo não for suportado por nenhuma das soluções padrão ou suportadas pela comunidade, você poderá instrumentá-lo manualmente.

Outro exemplo que requer acompanhamento personalizado é o trabalhador que recebe itens da fila. Para algumas filas, a chamada para adicionar uma mensagem a essa fila é rastreada como uma dependência. A operação de alto nível que descreve o processamento de mensagens não é coletada automaticamente.

Vamos ver como essas operações poderiam ser rastreadas.

Em um alto nível, a tarefa é criar RequestTelemetry e definir propriedades conhecidas. Depois que a operação for concluída, você rastreia a telemetria. O exemplo a seguir demonstra essa tarefa.

Solicitação HTTP no aplicativo auto-hospedado Owin

Neste exemplo, o contexto de rastreamento é propagado de acordo com o protocolo HTTP para correlação. Você deve esperar receber cabeçalhos descritos lá.

public class ApplicationInsightsMiddleware : OwinMiddleware
{
    // You may create a new TelemetryConfiguration instance, reuse one you already have,
    // or fetch the instance created by Application Insights SDK.
    private readonly TelemetryConfiguration telemetryConfiguration = TelemetryConfiguration.CreateDefault();
    private readonly TelemetryClient telemetryClient = new TelemetryClient(telemetryConfiguration);
    
    public ApplicationInsightsMiddleware(OwinMiddleware next) : base(next) {}

    public override async Task Invoke(IOwinContext context)
    {
        // Let's create and start RequestTelemetry.
        var requestTelemetry = new RequestTelemetry
        {
            Name = $"{context.Request.Method} {context.Request.Uri.GetLeftPart(UriPartial.Path)}"
        };

        // If there is a Request-Id received from the upstream service, set the telemetry context accordingly.
        if (context.Request.Headers.ContainsKey("Request-Id"))
        {
            var requestId = context.Request.Headers.Get("Request-Id");
            // Get the operation ID from the Request-Id (if you follow the HTTP Protocol for Correlation).
            requestTelemetry.Context.Operation.Id = GetOperationId(requestId);
            requestTelemetry.Context.Operation.ParentId = requestId;
        }

        // StartOperation is a helper method that allows correlation of 
        // current operations with nested operations/telemetry
        // and initializes start time and duration on telemetry items.
        var operation = telemetryClient.StartOperation(requestTelemetry);

        // Process the request.
        try
        {
            await Next.Invoke(context);
        }
        catch (Exception e)
        {
            requestTelemetry.Success = false;
            requestTelemetry.ResponseCode;
            telemetryClient.TrackException(e);
            throw;
        }
        finally
        {
            // Update status code and success as appropriate.
            if (context.Response != null)
            {
                requestTelemetry.ResponseCode = context.Response.StatusCode.ToString();
                requestTelemetry.Success = context.Response.StatusCode >= 200 && context.Response.StatusCode <= 299;
            }
            else
            {
                requestTelemetry.Success = false;
            }

            // Now it's time to stop the operation (and track telemetry).
            telemetryClient.StopOperation(operation);
        }
    }
    
    public static string GetOperationId(string id)
    {
        // Returns the root ID from the '|' to the first '.' if any.
        int rootEnd = id.IndexOf('.');
        if (rootEnd < 0)
            rootEnd = id.Length;

        int rootStart = id[0] == '|' ? 1 : 0;
        return id.Substring(rootStart, rootEnd - rootStart);
    }
}

O protocolo HTTP para correlação também declara o Correlation-Context cabeçalho. É omitido aqui por simplicidade.

Instrumentação de fila

O Contexto de Rastreamento do W3C e o Protocolo HTTP para Correlação passam detalhes de correlação com solicitações HTTP, mas cada protocolo de fila precisa definir como os mesmos detalhes são passados ao longo da mensagem de fila. Alguns protocolos de fila, como o AMQP, permitem a passagem de mais metadados. Outros protocolos, como a Fila de Armazenamento do Azure, exigem que o contexto seja codificado na carga útil da mensagem.

Fila do Service Bus

Para obter informações de rastreamento, consulte Rastreamento distribuído e correlação por meio de mensagens do Barramento de Serviço do Azure.

Fila de armazenamento do Azure

O exemplo a seguir mostra como controlar as operações de fila do Armazenamento do Azure e correlacionar a telemetria entre o produtor, o consumidor e o Armazenamento do Azure.

A fila de armazenamento tem uma API HTTP. Todas as chamadas para a fila são rastreadas pelo Application Insights Dependency Collector para solicitações HTTP. Ele é configurado por padrão em aplicativos ASP.NET e ASP.NET Core. Com outros tipos de aplicativos, consulte a documentação de aplicativos de console.

Você também pode querer correlacionar o ID da operação do Application Insights com o ID da solicitação de armazenamento. Para obter informações sobre como definir e obter um cliente de solicitação de armazenamento e uma ID de solicitação de servidor, consulte Monitorar, diagnosticar e solucionar problemas do Armazenamento do Azure.

Enfileiramento

Como as filas de armazenamento suportam a API HTTP, todas as operações com a fila são rastreadas automaticamente pelo Application Insights. Em muitos casos, esta instrumentação deve ser suficiente. Para correlacionar rastreamentos do lado do consumidor com rastreamentos do produtor, você deve passar algum contexto de correlação de forma semelhante à forma como fazemos isso no Protocolo HTTP para Correlação.

Este exemplo mostra como controlar a Enqueue operação. É possível:

• Correlacione novas tentativas (se houver): todas elas têm um pai comum que é a Enqueue operação. Caso contrário, eles serão rastreados como filhos da solicitação recebida. Se houver várias solicitações lógicas para a fila, pode ser difícil encontrar qual chamada resultou em tentativas.
• Correlacione os logs de armazenamento (se e quando necessário): eles estão correlacionados com a telemetria do Application Insights.

A Enqueue operação é filha de uma operação pai. Um exemplo é uma solicitação HTTP de entrada. A chamada de dependência HTTP é filha da Enqueue operação e neta da solicitação de entrada.

public async Task Enqueue(CloudQueue queue, string message)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("enqueue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Enqueue " + queue.Name;

    // MessagePayload represents your custom message and also serializes correlation identifiers into payload.
    // For example, if you choose to pass payload serialized to JSON, it might look like
    // {'RootId' : 'some-id', 'ParentId' : '|some-id.1.2.3.', 'message' : 'your message to process'}
    var jsonPayload = JsonConvert.SerializeObject(new MessagePayload
    {
        RootId = operation.Telemetry.Context.Operation.Id,
        ParentId = operation.Telemetry.Id,
        Payload = message
    });
    
    CloudQueueMessage queueMessage = new CloudQueueMessage(jsonPayload);

    // Add operation.Telemetry.Id to the OperationContext to correlate Storage logs and Application Insights telemetry.
    OperationContext context = new OperationContext { ClientRequestID = operation.Telemetry.Id};

    try
    {
        await queue.AddMessageAsync(queueMessage, null, null, new QueueRequestOptions(), context);
    }
    catch (StorageException e)
    {
        operation.Telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.Telemetry.Success = false;
        operation.Telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}  

Para reduzir a quantidade de telemetria que seu aplicativo relata ou se você não quiser acompanhar a Enqueue operação por outros motivos, use a Activity API diretamente:

• Crie (e inicie) um novo Activity em vez de iniciar a operação do Application Insights. Você não precisa atribuir nenhuma propriedade nele, exceto o nome da operação.
• Serialize yourActivity.Id na carga útil da mensagem em vez de operation.Telemetry.Id. Você também pode usar Activity.Current.Id.

Retirar fila

Da mesma forma que Enqueue, uma solicitação HTTP real para a fila de armazenamento é rastreada automaticamente pelo Application Insights. A Enqueue operação presumivelmente acontece no contexto pai, como um contexto de solicitação de entrada. Os SDKs do Application Insights correlacionam automaticamente essa operação, e sua parte HTTP, com a solicitação pai e outra telemetria relatada no mesmo escopo.

A Dequeue operação é complicada. O SDK do Application Insights rastreia automaticamente as solicitações HTTP. Mas não sabe o contexto da correlação até que a mensagem seja analisada. Não é possível correlacionar a solicitação HTTP para obter a mensagem com o resto da telemetria, especialmente quando mais de uma mensagem é recebida.

public async Task<MessagePayload> Dequeue(CloudQueue queue)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("dequeue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Dequeue " + queue.Name;

    try
    {
        var message = await queue.GetMessageAsync();
    }
    catch (StorageException e)
    {
        operation.telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.telemetry.Success = false;
        operation.telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }

    return null;
}

Processo

No exemplo a seguir, uma mensagem de entrada é rastreada de maneira semelhante a uma solicitação HTTP de entrada:

public async Task Process(MessagePayload message)
{
    // After the message is dequeued from the queue, create RequestTelemetry to track its processing.
    RequestTelemetry requestTelemetry = new RequestTelemetry { Name = "process " + queueName };
    
    // It might also make sense to get the name from the message.
    requestTelemetry.Context.Operation.Id = message.RootId;
    requestTelemetry.Context.Operation.ParentId = message.ParentId;

    var operation = telemetryClient.StartOperation(requestTelemetry);

    try
    {
        await ProcessMessage();
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        throw;
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

Da mesma forma, outras operações de fila podem ser instrumentadas. Uma operação de visualização deve ser instrumentada de forma semelhante a uma operação de retirada de fila. Não é necessário instrumentar operações de gerenciamento de filas. O Application Insights rastreia operações como HTTP e, na maioria dos casos, é suficiente.

Ao instrumentar a exclusão de mensagens, certifique-se de definir os identificadores de operação (correlação). Como alternativa, você pode usar a Activity API. Em seguida, você não precisa definir identificadores de operação nos itens de telemetria porque o SDK do Application Insights faz isso por você:

• Crie um novo Activity depois de ter um item da fila.
• Use Activity.SetParentId(message.ParentId) para correlacionar logs de consumidores e produtores.
• Inicie o Activityarquivo .
• Rastreie operações de dequeue, processe e delete usando Start/StopOperation auxiliares. Faça isso a partir do mesmo fluxo de controle assíncrono (contexto de execução). Desta forma, eles são correlacionados corretamente.
• Pare o Activityarquivo .
• Use Start/StopOperation ou chame Track a telemetria manualmente.

Tipos de dependência

O Application Insights usa o tipo de dependência para personalizar experiências de interface do usuário. Para filas, ele reconhece os seguintes tipos que melhoram a experiência de diagnóstico de DependencyTelemetrytransações:

• Azure queue para filas de Armazenamento do Azure
• Azure Event Hubs para Hubs de Eventos do Azure
• Azure Service Bus para o Barramento de Serviço do Azure

Processamento em lotes

Com algumas filas, você pode retirar várias mensagens da fila com uma solicitação. O processamento dessas mensagens é presumivelmente independente e pertence às diferentes operações lógicas. Não é possível correlacionar a Dequeue operação a uma mensagem específica que está sendo processada.

Cada mensagem deve ser processada em seu próprio fluxo de controle assíncrono. Para obter mais informações, consulte a seção Controle de dependências de saída .

Tarefas em segundo plano de longa execução

Alguns aplicativos iniciam operações de longa duração que podem ser causadas por solicitações do usuário. Do ponto de vista do traçado/instrumentação, não é diferente da instrumentação de solicitação ou dependência:

async Task BackgroundTask()
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>(taskName);
    operation.Telemetry.Type = "Background";
    try
    {
        int progress = 0;
        while (progress < 100)
        {
            // Process the task.
            telemetryClient.TrackTrace($"done {progress++}%");
        }
        // Update status code and success as appropriate.
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        // Update status code and success as appropriate.
        throw;
    }
    finally
    {
        telemetryClient.StopOperation(operation);
    }
}

Neste exemplo, telemetryClient.StartOperation cria DependencyTelemetry e preenche o contexto de correlação. Digamos que você tenha uma operação pai que foi criada por solicitações de entrada que agendaram a operação. Desde que BackgroundTask seja iniciado no mesmo fluxo de controle assíncrono de uma solicitação de entrada, ele está correlacionado com essa operação pai. BackgroundTask e todos os itens de telemetria aninhados são automaticamente correlacionados com a solicitação que a causou, mesmo após o término da solicitação.

Quando a tarefa começa a partir do thread em segundo plano que não tem nenhuma operação (Activity) associada a ela, BackgroundTask não tem nenhum pai. No entanto, ele pode ter operações aninhadas. Todos os itens de telemetria relatados da tarefa são correlacionados com o DependencyTelemetry criado em BackgroundTask.

Rastreamento de dependências de saída

Você pode rastrear seu próprio tipo de dependência ou uma operação que não é suportada pelo Application Insights.

O Enqueue método na fila do Service Bus ou na fila de armazenamento pode servir como exemplos para esse rastreamento personalizado.

A abordagem geral para o rastreamento de dependência personalizada é:

• Chame o método (extensão) que preenche as propriedades necessárias para correlação TelemetryClient.StartOperation e algumas outras propriedades, como início, carimbo DependencyTelemetry de data/hora e duração.
• Defina outras propriedades personalizadas no DependencyTelemetry, como o nome e qualquer outro contexto necessário.
• Faça uma chamada de dependência e aguarde.
• Pare a operação quando StopOperation ela terminar.
• Lidar com exceções.

public async Task RunMyTaskAsync()
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>("task 1"))
    {
        try 
        {
            var myTask = await StartMyTaskAsync();
            // Update status code and success as appropriate.
        }
        catch(...) 
        {
            // Update status code and success as appropriate.
        }
    }
}

Eliminar uma operação faz com que a operação pare, pelo que poderá fazê-lo em vez de chamar StopOperation.

Processamento e rastreamento de operações paralelas

A chamada StopOperation apenas interrompe a operação que foi iniciada. Se a operação em execução atual não corresponder àquela que você deseja parar, StopOperation não fará nada. Essa situação pode acontecer se você iniciar várias operações em paralelo no mesmo contexto de execução.

var firstOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 1");
var firstTask = RunMyTaskAsync();

var secondOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 2");
var secondTask = RunMyTaskAsync();

await firstTask;

// FAILURE!!! This will do nothing and will not report telemetry for the first operation
// as currently secondOperation is active.
telemetryClient.StopOperation(firstOperation); 

await secondTask;

Certifique-se de sempre chamar StartOperation e processar a operação no mesmo método assíncrono para isolar as operações em execução em paralelo. Se a operação for síncrona (ou não assíncrona), envolva o processo e acompanhe com Task.Run.

public void RunMyTask(string name)
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>(name))
    {
        Process();
        // Update status code and success as appropriate.
    }
}

public async Task RunAllTasks()
{
    var task1 = Task.Run(() => RunMyTask("task 1"));
    var task2 = Task.Run(() => RunMyTask("task 2"));
    
    await Task.WhenAll(task1, task2);
}

Operações do ApplicationInsights vs. System.Diagnostics.Activity

System.Diagnostics.Activity representa o contexto de rastreamento distribuído e é usado por estruturas e bibliotecas para criar e propagar contexto dentro e fora do processo e correlacionar itens de telemetria. Activity funciona em conjunto com System.Diagnostics.DiagnosticSource o mecanismo de notificação entre a estrutura/biblioteca para notificar eventos interessantes, como solicitações e exceções recebidas ou enviadas.

As atividades são funcionalidades principais no Application Insights. A dependência automática e a coleta de solicitações dependem muito deles, juntamente com DiagnosticSource os eventos. Se você criou Activity em seu aplicativo, isso não resultaria na criação da telemetria do Application Insights. O Application Insights precisa receber DiagnosticSource eventos e conhecer os nomes de eventos e cargas úteis para traduzir Activity em telemetria.

Cada operação do Application Insights (solicitação ou dependência) envolve Activityo . Quando StartOperation é chamado, cria-se Activity por baixo. StartOperation é a maneira recomendada de rastrear telemetrias de solicitação ou dependência manualmente e garantir que tudo esteja correlacionado.

Counters

O Application Insights oferece suporte a contadores de desempenho e contadores de eventos. Este guia fornece uma visão geral de ambos, incluindo sua finalidade, configuração e uso em aplicativos .NET.

Contadores de desempenho

O Windows fornece vários contadores de desempenho, como aqueles usados para coletar estatísticas de uso do processador, da memória e do disco. Você também pode definir seus próprios contadores de desempenho.

Seu aplicativo oferece suporte à coleta de contadores de desempenho se for executado no Internet Information Server (IIS) em um host local ou em uma máquina virtual com acesso administrativo. Os aplicativos executados como Aplicativos Web do Azure não podem acessar diretamente os contadores de desempenho, mas o Application Insights coleta um subconjunto de contadores disponíveis.

Pré-requisitos

Conceda permissão à conta de serviço do pool de aplicativos para monitorar contadores de desempenho adicionando-a ao grupo Usuários do Monitor de Desempenho .

net localgroup "Performance Monitor Users" /add "IIS APPPOOL\NameOfYourPool"

Ver contadores

O painel Métricas mostra o conjunto padrão de contadores de desempenho.

ASP.NET

Contadores padrão para ASP.NET aplicativos Web:

• % Processo\Tempo do processador
• % Processo\Tempo do processador normalizado
• Memória\Bytes disponíveis
• ASP.NET pedidos/seg
• Exceções CLR (Common Language Runtime) do .NET lançadas/s
• ASP.NET AplicaçõesSolicitar Tempo de Execução
• Processo\Bytes privados
• Processar\Bytes de dados de E/S/s
• ASP.NET Aplicativos\Solicitações na fila de aplicativos
• Processador(_Total)\% Tempo do processador

ASP.NET Core

Contadores padrão para aplicativos Web ASP.NET Core:

• % Processo\Tempo do processador
• % Processo\Tempo do processador normalizado
• Memória\Bytes disponíveis
• Processo\Bytes privados
• Processar\Bytes de dados de E/S/s
• Processador(_Total)\% Tempo do processador

Adicionar contadores

Se o contador de desempenho desejado não estiver incluído na lista de métricas, você poderá adicioná-lo.

ASP.NET

Opção 1: Configuração no ApplicationInsights.config

1. Descubra quais contadores estão disponíveis em seu servidor usando este comando do PowerShell no servidor local:

   Get-Counter -ListSet *
   

   Para obter mais informações, consulte Get-Counter.

2. Abra ApplicationInsights.config.

   Se você adicionou o Application Insights ao seu aplicativo durante o desenvolvimento:

   1. Edite ApplicationInsights.config no seu projeto.
   2. Reimplante-o em seus servidores.

3. Edite a diretiva do coletor de desempenho:

   
       <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector">
         <Counters>
           <Add PerformanceCounter="\Objects\Processes"/>
           <Add PerformanceCounter="\Sales(photo)\# Items Sold" ReportAs="Photo sales"/>
         </Counters>
       </Add>
   

Você captura contadores padrão e contadores que você mesmo implementa. \Objects\Processes é um exemplo de um contador padrão que está disponível em todos os sistemas Windows. \Sales(photo)\# Items Sold é um exemplo de um contador personalizado que pode ser implementado em um serviço Web.

O formato é \Category(instance)\Counter, ou para categorias que não têm instâncias, apenas \Category\Counter.

O ReportAs parâmetro é necessário para nomes de contadores que não correspondem ao [a-zA-Z()/-_ \.]+.

Se você especificar uma instância, ela se tornará uma dimensão CounterInstanceName da métrica relatada.

Opção 2: Configuração no código

Consulte a secção seguinte.

ASP.NET Core

Configure PerformanceCollectorModule após o WebApplication.CreateBuilder() método em Program.cs:

using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures PerformanceCollectorModule.

builder.Services.ConfigureTelemetryModule<PerformanceCollectorModule>((module, o) =>
    {
        // The application process name could be "dotnet" for ASP.NET Core self-hosted applications.
        module.Counters.Add(new PerformanceCounterCollectionRequest(@"\Process([replace-with-application-process-name])\Page Faults/sec", "DotnetPageFaultsPerfSec"));
    });

var app = builder.Build();

Coletar contadores de desempenho em código para aplicativos Web ASP.NET ou aplicativos de console .NET/.NET Core

Para coletar contadores de desempenho do sistema e enviá-los para o Application Insights, você pode adaptar o seguinte trecho:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Process([replace-with-application-process-name])\Page Faults/sec", "PageFaultsPerfSec"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

Ou você pode fazer a mesma coisa com métricas personalizadas que você criou:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Sales(photo)\# Items Sold", "Photo sales"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

Contadores de desempenho para aplicativos executados em Aplicativos Web do Azure e contêineres do Windows no Serviço de Aplicativo do Azure

Os aplicativos ASP.NET e ASP.NET Core implantados nos Aplicativos Web do Azure são executados em um ambiente de área restrita especial. Os aplicativos implantados no Serviço de Aplicativo do Azure podem utilizar um contêiner do Windows ou ser hospedados em um ambiente de área restrita. Se o aplicativo for implantado em um contêiner do Windows, todos os contadores de desempenho padrão estarão disponíveis na imagem do contêiner.

O ambiente de área restrita não permite acesso direto aos contadores de desempenho do sistema. No entanto, um subconjunto limitado de contadores é exposto como variáveis de ambiente, conforme descrito em Contadores de Perf expostos como variáveis de ambiente. Apenas um subconjunto de contadores está disponível neste ambiente. Para obter a lista completa, consulte Contadores Perf expostos como variáveis de ambiente.

O SDK do Application Insights para ASP.NET e ASP.NET Core deteta se o código é implantado em um aplicativo Web ou em um contêiner que não seja do Windows. A deteção determina se ele coleta contadores de desempenho em um ambiente de área restrita ou utiliza o mecanismo de coleta padrão quando hospedado em um contêiner do Windows ou máquina virtual.

Consultas do Log Analytics para contadores de desempenho

Você pode pesquisar e exibir relatórios do contador de desempenho no Log Analytics.

O esquema performanceCounters expõe o categorycounter , nome e instance nome de cada contador de desempenho. Na telemetria de cada aplicativo, você vê apenas os contadores desse aplicativo. Por exemplo, para ver quais contadores estão disponíveis:

performanceCounters | summarize count(), avg(value) by category, instance, counter

Aqui, Instance refere-se à instância do contador de desempenho, não à função ou à instância da máquina do servidor. O nome da instância do contador de desempenho normalmente segmenta os contadores, como o tempo do processador, pelo nome do processo ou aplicativo.

Para obter um gráfico de memória disponível durante o período recente:

performanceCounters | where counter == "Available Bytes" | summarize avg(value), min(value) by bin(timestamp, 1h) | render timechart

Como outras telemetrias, performanceCounters também tem uma coluna cloud_RoleInstance que indica a identidade da instância do servidor host na qual seu aplicativo está sendo executado. Por exemplo, para comparar o desempenho do seu aplicativo nas diferentes máquinas:

performanceCounters | where counter == "% Processor Time" and instance == "SendMetrics" | summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1d)

Perguntas frequentes sobre contadores de desempenho

Para rever as perguntas frequentes (FAQ), consulte Perguntas frequentes sobre contadores de desempenho.

Contadores de eventos

EventCounter é o mecanismo .NET/.NET Core para publicar e consumir contadores ou estatísticas. Os EventCounters são suportados em todas as plataformas de SO - Windows, Linux e macOS. Ele pode ser pensado como um equivalente multiplataforma para PerformanceCounters que só são suportados em sistemas Windows.

Embora os usuários possam publicar quaisquer contadores de eventos personalizados para atender às suas necessidades, o .NET publica um conjunto desses contadores por padrão. Este documento percorre as etapas necessárias para coletar e exibir contadores de eventos (definidos pelo sistema ou pelo usuário) no Azure Application Insights.

Usando o Application Insights para coletar EventCounters

O Application Insights oferece suporte à coleta EventCounters com seu EventCounterCollectionModule, que faz parte do recém-lançado pacote NuGet Microsoft.ApplicationInsights.EventCounterCollector. EventCounterCollectionModule é ativado automaticamente ao usar AspNetCore ou WorkerService. EventCounterCollectionModule Recolhe contadores com uma frequência de recolha não configurável de 60 segundos. Não há permissões especiais necessárias para coletar EventCounters. Para aplicativos ASP.NET Core, você também deseja adicionar o pacote Microsoft.ApplicationInsights.AspNetCore .

dotnet add package Microsoft.ApplicationInsights.EventCounterCollector
dotnet add package Microsoft.ApplicationInsights.AspNetCore

Contadores padrão coletados

A partir da versão 2.15.0 do AspNetCore SDK ou do WorkerService SDK, nenhum contador é coletado por padrão. O módulo em si está ativado, para que os usuários possam adicionar os contadores desejados para coletá-los.

Para obter uma lista de contadores conhecidos publicados pelo .NET Runtime, consulte Documento Contadores disponíveis .

Personalização de contadores a serem coletados

O exemplo a seguir mostra como adicionar/remover contadores. Essa personalização seria feita como parte da configuração do serviço de aplicativo depois que a coleta de telemetria do Application Insights fosse habilitada usando um ou AddApplicationInsightsTelemetry()AddApplicationInsightsWorkerService(). A seguir está um exemplo de código de um aplicativo ASP.NET Core. Para outros tipos de aplicativos, consulte Configurar módulos de telemetria.

using Microsoft.ApplicationInsights.Extensibility.EventCounterCollector;
using Microsoft.Extensions.DependencyInjection;

builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>(
        (module, o) =>
        {
            // Removes all default counters, if any.
            module.Counters.Clear();

            // Adds a user defined counter "MyCounter" from EventSource named "MyEventSource"
            module.Counters.Add(
                new EventCounterCollectionRequest("MyEventSource", "MyCounter"));

            // Adds the system counter "gen-0-size" from "System.Runtime"
            module.Counters.Add(
                new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        }
    );

Desativando o módulo de coleta EventCounter

EventCounterCollectionModule pode ser desativado usando ApplicationInsightsServiceOptions.

O exemplo a seguir usa o ASP.NET Core SDK.

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

Uma abordagem semelhante também pode ser usada para o SDK do Serviço de Trabalho, mas o namespace deve ser alterado conforme mostrado no exemplo a seguir.

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

Consultas do Log Analytics para contadores de eventos

Você pode pesquisar e exibir relatórios do contador de eventos no Log Analytics, na tabela customMetrics .

Por exemplo, execute a seguinte consulta para ver quais contadores são coletados e estão disponíveis para consulta:

customMetrics | summarize avg(value) by name

Para obter um gráfico de um contador específico (por exemplo: ThreadPool Completed Work Item Count) durante o período recente, execute a seguinte consulta.

customMetrics 
| where name contains "System.Runtime|ThreadPool Completed Work Item Count"
| where timestamp >= ago(1h)
| summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1m)
| render timechart

Como outras telemetrias, customMetrics também tem uma coluna cloud_RoleInstance que indica a identidade da instância do servidor host na qual seu aplicativo está sendo executado. A consulta anterior mostra o valor do contador por instância e pode ser usada para comparar o desempenho de diferentes instâncias do servidor.

Perguntas frequentes sobre contadores de eventos

Para rever as perguntas mais frequentes (FAQ), consulte Perguntas frequentes sobre contadores de eventos.

Coleção de instantâneos

Para saber como configurar a coleta de instantâneos para aplicativos ASP.NET e ASP.NET Core, consulte Habilitar o depurador de instantâneo para aplicativos .NET no Azure Service Fabric, Serviços de Nuvem e Máquinas Virtuais.

Nesta secção

• Métricas em tempo real
• Rastreio distribuído
• Métricas estendidas
• TelemetryClient API

Métricas em tempo real

Para habilitar o envio de métricas em tempo real do seu aplicativo para o Azure, use setSendLiveMetrics(true). Atualmente, a filtragem de métricas em tempo real no portal não é suportada.

Rastreio distribuído

As arquiteturas modernas de nuvem e microsserviços permitiram serviços simples e implantáveis de forma independente que reduzem custos e, ao mesmo tempo, aumentam a disponibilidade e a taxa de transferência. No entanto, torna mais difícil compreender e depurar os sistemas em geral. O rastreamento distribuído resolve este problema fornecendo um perfil de desempenho que funciona como pilhas de chamadas funcionais para arquiteturas de nuvem e microsserviços.

O Azure Monitor fornece duas experiências para consumir dados de rastreamento distribuídos: a exibição de diagnóstico de transação para uma única transação/solicitação e a exibição de mapa do aplicativo para mostrar como os sistemas interagem.

O Application Insights pode monitorar cada componente separadamente e detetar qual componente é responsável por falhas ou degradação do desempenho usando a correlação de telemetria distribuída. Este artigo explica o modelo de dados, técnicas de propagação de contexto, protocolos e implementação de táticas de correlação em diferentes linguagens e plataformas usadas pelo Application Insights.

Ative o rastreamento distribuído através do Application Insights por meio de autoinstrumentação ou SDKs.

Os agentes e SDKs do Application Insights para .NET, .NET Core, Java, Node.jse JavaScript suportam rastreamento distribuído nativamente.

Com o SDK adequado do Application Insights instalado e configurado, as informações de rastreamento são coletadas automaticamente para estruturas, bibliotecas e tecnologias populares pelos autocolectores de dependências do SDK. A lista completa de tecnologias suportadas está disponível na documentação de coleta automática de dependência.

Qualquer tecnologia também pode ser rastreada manualmente com uma chamada para TrackDependency no TelemetryClient.

Modelo de dados para correlação de telemetria

O Application Insights define um modelo de dados para correlação de telemetria distribuída. Para associar a telemetria a uma operação lógica, cada item de telemetria tem um campo de contexto chamado operation_Id. Cada item de telemetria no rastreamento distribuído compartilha esse identificador. Portanto, mesmo que você perca a telemetria de uma única camada, ainda poderá associar a telemetria relatada por outros componentes.

Uma operação lógica distribuída normalmente consiste em um conjunto de operações menores que são solicitações processadas por um dos componentes. A telemetria de solicitação define essas operações. Cada item de telemetria de solicitação tem seu próprio id que o identifica de forma única e global. E todos os itens de telemetria (como rastreamentos e exceções) associados à solicitação devem definir o valor de operation_parentId para o valor de id da solicitação.

A telemetria de dependência representa cada operação de saída, como uma chamada HTTP para outro componente. Ele também define o seu próprio id que é globalmente único. A telemetria de solicitação, iniciada por esta chamada de dependência, usa este id como seu operation_parentId.

Você pode criar uma exibição da operação lógica distribuída usando operation_Id, operation_parentIde request.id com dependency.id. Esses campos também definem a ordem de causalidade das chamadas de telemetria.

Em um ambiente de microsserviços, os rastreamentos de componentes podem ir para diferentes itens de armazenamento. Cada componente pode ter sua própria cadeia de conexão no Application Insights. Para obter telemetria para a operação lógica, o Application Insights consulta dados de cada item de armazenamento.

Quando o número de itens de armazenamento é grande, você precisa de uma dica sobre onde procurar em seguida. O modelo de dados do Application Insights define dois campos para resolver esse problema: request.source e dependency.target. O primeiro campo identifica o componente que iniciou a solicitação de dependência. O segundo campo identifica qual componente retornou a resposta da chamada de dependência.

Para obter informações sobre como consultar várias instâncias diferentes, consulte Consultar dados em espaços de trabalho, aplicativos e recursos do Log Analytics no Azure Monitor.

Example

Vejamos um exemplo. Um aplicativo chamado Stock Prices mostra o preço de mercado atual de uma ação usando uma API externa chamada Stock. O aplicativo Preços de Ações tem uma página chamada Página de Estoque que o navegador da Web do cliente abre usando GET /Home/Stock. O aplicativo consulta a API de estoque usando a chamada GET /api/stock/valueHTTP .

Você pode analisar a telemetria resultante executando uma consulta:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

Nos resultados, todos os itens de telemetria compartilham a raiz operation_Id. Quando uma chamada Ajax é feita a partir da página, um novo ID exclusivo (qJSXU) é atribuído à telemetria de dependência e o ID do pageView é usado como operation_ParentId. Em seguida, a solicitação do servidor usa o ID do Ajax como operation_ParentId.

Quando a chamada GET /api/stock/value é feita para um serviço externo, você precisa saber a identidade desse servidor para poder definir o dependency.target campo adequadamente. Quando o serviço externo não oferece suporte ao monitoramento, target é definido como o nome do host do serviço. Um exemplo é stock-prices-api.com. Mas se o serviço se identificar retornando um cabeçalho HTTP predefinido, target conterá a identidade do serviço que permite que o Application Insights crie um rastreamento distribuído consultando a telemetria desse serviço.

Cabeçalhos de correlação usando W3C TraceContext

O Application Insights está em transição para o W3C Trace-Context, que define:

• traceparent: Carrega o ID de operação globalmente exclusivo e o identificador exclusivo da chamada.
• tracestate: Carrega o contexto de rastreio específico do sistema.

A versão mais recente do SDK do Application Insights suporta o protocolo Trace-Context, mas talvez seja necessário optar por ele. (A manutenção da compatibilidade retroativa com o protocolo de correlação anterior suportado pelo SDK do Application Insights é assegurada.)

O protocolo HTTP de correlação, também chamado de Request-Id, está sendo preterido. Este protocolo define dois cabeçalhos:

• Request-Id: Carrega o ID globalmente exclusivo da chamada.
• Correlation-Context: Carrega a coleção de pares nome-valor das propriedades de rastreamento distribuído.

O Application Insights também define a extensão para o protocolo HTTP de correlação. Ele usa Request-Context pares nome-valor para propagar a coleção de propriedades usadas pelo chamador ou destinatário imediato. O SDK do Application Insights usa esse cabeçalho para definir os dependency.target campos e request.source .

Os modelos de dados do W3C Trace-Context e Application Insights são mapeados da seguinte maneira:

Para obter mais informações, consulte Modelo de dados de telemetria do Application Insights.

Habilite o suporte ao rastreamento distribuído do W3C

Por padrão, o SDK envia cabeçalhos compreendidos por outros aplicativos ou serviços instrumentados com um SDK do Application Insights. Você pode habilitar o envio e o recebimento de cabeçalhos W3C Trace Context, além dos cabeçalhos de IA existentes. Dessa forma, você não quebrará a correlação com nenhum dos seus serviços legados existentes.

Habilitar cabeçalhos W3C permite que seu aplicativo se correlacione com outros serviços não instrumentados com o Application Insights, mas que adotam esse padrão W3C.

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

Métricas estendidas

Para habilitar o envio de métricas nativas estendidas do seu aplicativo para o Azure, instale o pacote de métricas nativas separado. O SDK é carregado automaticamente quando é instalado e começa a coletar Node.js métricas nativas.

npm install applicationinsights-native-metrics

Atualmente, o pacote de métricas nativo realiza a coleta automática do tempo de CPU dedicado à coleta de lixo, dos ciclos do loop de eventos e do uso da memória heap.

• Coleta de lixo: A quantidade de tempo de CPU gasto em cada tipo de coleta de lixo e quantas ocorrências de cada tipo.
• Laço de eventos: quantos ticks ocorreram e quanto tempo de CPU foi gasto no total.
• Heap vs. nonheap: Quanto da utilização de memória da sua aplicação está no heap ou no non-heap.

API TelemetryClient

Para obter uma descrição completa da API TelemetryClient, veja Application Insights API for custom events and metrics (API do Application Insights para eventos e métricas personalizadas).

Você pode acompanhar qualquer solicitação, evento, métrica ou exceção usando a biblioteca de cliente do Application Insights para Node.js. O exemplo de código seguinte demonstra algumas das APIs que pode utilizar:

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

Monitorizar as suas dependências

Utilize o código abaixo para fazer o acompanhamento das suas dependências:

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

Um utilitário de exemplo para usar trackMetric e medir quanto tempo demora o agendamento no loop de eventos.

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

Adicionar propriedades personalizadas a todos os eventos

Utilize o código abaixo para adicionar uma propriedade personalizada a todos os eventos:

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

Monitorizar pedidos HTTP GET

Use o código a seguir para rastrear manualmente as solicitações HTTP GET:

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

Como alternativa, você pode rastrear solicitações usando o trackNodeHttpRequest método:

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

Monitorizar o tempo de arranque do servidor

Utilize o código abaixo para fazer o acompanhamento do tempo de arranque do servidor:

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

Rubor

Por padrão, a telemetria é armazenada em buffer por 15 segundos antes de ser enviada ao servidor de ingestão. Se o seu aplicativo tiver uma vida útil curta, como uma ferramenta CLI, pode ser necessário liberar manualmente a telemetria em buffer quando o aplicativo for encerrado usando appInsights.defaultClient.flush().

Se o SDK detetar que seu aplicativo está falhando, ele chamará flush para você usando appInsights.defaultClient.flush({ isAppCrashing: true }). Com a opção flush isAppCrashing, presume-se que a sua aplicação está num estado anormal e não é adequada para enviar telemetria. Em vez disso, o SDK salva toda a telemetria em buffer no armazenamento persistente e permite que seu aplicativo seja encerrado. Quando seu aplicativo é iniciado novamente, ele tenta enviar qualquer telemetria que foi salva no armazenamento persistente.

Nesta secção

• Telemetria de filtro e pré-processo
• Inicializadores de telemetria
• Processador de telemetria
• Amostragem
• Enriqueça dados através de HTTP

Filtrar e pré-processar telemetria

Você pode escrever código para filtrar, modificar ou enriquecer sua telemetria antes que ela seja enviada do SDK. O processamento inclui dados enviados dos módulos padrão de telemetria, como a recolha de pedidos HTTP e a recolha de dependências.

• A filtragem pode modificar ou descartar a telemetria antes de ser enviada do SDK ao implementar ITelemetryProcessor. Por exemplo, você pode reduzir o volume de telemetria excluindo solicitações de robôs. Ao contrário da amostragem, você tem controle total sobre o que é enviado ou descartado, mas isso afeta qualquer métrica baseada em logs agregados. Dependendo de como você descarta itens, você também pode perder a capacidade de navegar entre itens relacionados.

• pt-PT: Adicione ou modifique propriedades a qualquer telemetria enviada da sua aplicação implementando um ITelemetryInitializer. Por exemplo, você pode adicionar valores calculados ou números de versão para filtrar os dados no portal.

• A amostragem reduz o volume de telemetria sem afetar suas estatísticas. Ele mantém juntos pontos de dados relacionados para que você possa navegar entre eles quando diagnosticar um problema. No portal, as contagens totais são multiplicadas para compensar pela amostragem.

Filtering

Essa técnica oferece controle direto sobre o que está incluído ou excluído do fluxo de telemetria. A filtragem pode ser usada para impedir que itens de telemetria sejam enviados para o Application Insights. Você pode usar a filtragem com amostragem ou separadamente.

Para filtrar a telemetria, escreva um processador de telemetria e registe-o com TelemetryConfiguration. Toda a telemetria passa pelo seu processador. Você pode optar por soltá-lo do fluxo ou entregá-lo ao próximo processador na cadeia. A telemetria dos módulos padrão, como o coletor de solicitação HTTP e o coletor de dependência, e a telemetria que você mesmo rastreou estão incluídas. Por exemplo, é possível filtrar a telemetria sobre solicitações de robôs ou chamadas de dependência bem-sucedidas.

ITelemetryProcessor e ITelemetryInitializer

Qual é a diferença entre processadores de telemetria e inicializadores de telemetria?

• Existem algumas sobreposições no que você pode fazer com eles. Ambos podem ser usados para adicionar ou modificar propriedades de telemetria, embora recomendemos que você use inicializadores para essa finalidade.
• Os inicializadores de telemetria sempre são executados antes dos processadores de telemetria.
• Os inicializadores de telemetria podem ser chamados mais de uma vez. Por convenção, eles não configuram nenhuma propriedade que já estava configurada.
• Os processadores de telemetria permitem substituir ou descartar completamente um item de telemetria.
• Todos os inicializadores de telemetria registrados são chamados para cada item de telemetria. Para processadores de telemetria, o SDK assegura a invocação do primeiro processador de telemetria. Se o resto dos processadores são chamados ou não é decidido pelos processadores de telemetria anteriores.
• Use inicializadores de telemetria para enriquecer a telemetria com mais propriedades ou substituir uma existente. Use um processador de telemetria para filtrar a telemetria.

Adicionar/modificar propriedades

Use inicializadores de telemetria para enriquecer a telemetria com informações adicionais ou para substituir as propriedades de telemetria definidas pelos módulos de telemetria padrão.

Por exemplo, o Application Insights para um pacote web recolhe telemetria sobre solicitações HTTP. Por padrão, ele sinaliza qualquer solicitação com um código >de resposta =400 como falha. Se, em vez disso, quiser tratar 400 como um sucesso, você pode fornecer um inicializador de telemetria que define a propriedade success.

Se você fornecer um inicializador de telemetria, ele será chamado sempre que qualquer um dos métodos Track*() for chamado. Este inicializador inclui métodos Track() chamados pelos módulos padrão de telemetria. Por convenção, esses módulos não definem nenhuma propriedade que já tenha sido definida por um inicializador. Os inicializadores de telemetria são chamados antes de chamar os processadores de telemetria, portanto, qualquer enriquecimento feito pelos inicializadores é visível para os processadores.

Inicializadores de telemetria

Para enriquecer a telemetria com informações adicionais ou substituir as propriedades de telemetria definidas pelos módulos de telemetria padrão, use inicializadores de telemetria.

Os inicializadores de telemetria definem propriedades de contexto que são enviadas junto com cada item de telemetria. Você pode escrever seus próprios inicializadores para definir propriedades de contexto.

Os inicializadores padrão são todos definidos pelos pacotes NuGet da Web ou do WindowsServer:

Adicionar ITelemetryInitializer

Este blog descreve um projeto para diagnosticar problemas de dependência enviando automaticamente pings regulares para dependências.

1. Defina o inicializador

   using System;
   using Microsoft.ApplicationInsights.Channel;
   using Microsoft.ApplicationInsights.DataContracts;
   using Microsoft.ApplicationInsights.Extensibility;
   
   namespace MvcWebRole.Telemetry
   {
     /*
      * Custom TelemetryInitializer that overrides the default SDK
      * behavior of treating response codes >= 400 as failed requests
      *
      */
       public class MyTelemetryInitializer : ITelemetryInitializer
       {
           public void Initialize(ITelemetry telemetry)
           {
               var requestTelemetry = telemetry as RequestTelemetry;
               // Is this a TrackRequest() ?
               if (requestTelemetry == null) return;
               int code;
               bool parsed = Int32.TryParse(requestTelemetry.ResponseCode, out code);
               if (!parsed) return;
               if (code >= 400 && code < 500)
               {
                   // If we set the Success property, the SDK won't change it:
                   requestTelemetry.Success = true;
   
                   // Allow us to filter these requests in the portal:
                   requestTelemetry.Properties["Overridden400s"] = "true";
               }
               // else leave the SDK to set the Success property
           }
       }
   }
   

2. Carregue o inicializador

ASP.NET

Opção 1: Configuração no código

protected void Application_Start()
{
    // ...
    TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
}

Opção 2: Configuração no ApplicationInsights.config

<ApplicationInsights>
    <TelemetryInitializers>
    <!-- Fully qualified type name, assembly name: -->
    <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/>
    ...
    </TelemetryInitializers>
</ApplicationInsights>

Veja mais deste exemplo.

ASP.NET Core

Adicionar um inicializador usando ApplicationInsights.config ou TelemetryConfiguration.Active não é válido para aplicativos ASP.NET Core.

Para aplicativos escritos usando o ASP.NET Core, a adição de um novo inicializador de telemetria é feita adicionando-o DependencyInjection ao contêiner, conforme mostrado. Execute este passo no método Startup.ConfigureServices.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

Remover inicializadores de telemetria

Por padrão, os inicializadores de telemetria estão presentes. Para remover todos os inicializadores de telemetria ou específicos, use o código de exemplo a seguir depois de executar .

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

Serviço ao Trabalhador

Adicionar um inicializador usando ApplicationInsights.config ou TelemetryConfiguration.Active não é válido para o SDK do Serviço de Trabalho.

Para aplicações escritas usando o Serviço de Trabalho, a adição de um novo inicializador de telemetria é feita ao adicioná-lo ao contêiner DependencyInjection, conforme mostrado. Execute este passo no método Startup.ConfigureServices.

    using Microsoft.ApplicationInsights.Extensibility;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
        services.AddApplicationInsightsTelemetryWorkerService();
    }

Remover inicializadores de telemetria

Os inicializadores de telemetria estão presentes por padrão. Para remover todos os inicializadores de telemetria ou específicos, use o código de exemplo a seguir depois de executar .

   public void ConfigureServices(IServiceCollection services)
   {
        services.AddApplicationInsightsTelemetryWorkerService();
        // Remove a specific built-in telemetry initializer.
        var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                            (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
        if (tiToRemove != null)
        {
            services.Remove(tiToRemove);
        }

        // Remove all initializers.
        // This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
        services.RemoveAll(typeof(ITelemetryInitializer));
   }

Exemplo de ITelemetryInitializers

Adicionar uma propriedade personalizada

O inicializador de exemplo a seguir adiciona uma propriedade personalizada a cada telemetria controlada.

public void Initialize(ITelemetry item)
{
    var itemProperties = item as ISupportProperties;
    if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
    {
        itemProperties.Properties["customProp"] = "customValue";
    }
}

Adicionar um nome de função de nuvem e uma instância de função de nuvem

Etapa 1: Escreva Inicializador de Telemetria personalizado

O inicializador de exemplo a seguir define o nome da função de nuvem para cada telemetria rastreada.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;

namespace CustomInitializer.Telemetry
{
    public class MyTelemetryInitializer : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {
            if (string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
            {
                //set custom role name here
                telemetry.Context.Cloud.RoleName = "Custom RoleName";
                telemetry.Context.Cloud.RoleInstance = "Custom RoleInstance";
            }
        }
    }
}

Etapa 2: Carregar um inicializador para TelemetryConfiguration

ASP.NET

No ficheiro ApplicationInsights.config :

    <ApplicationInsights>
      <TelemetryInitializers>
        <!-- Fully qualified type name, assembly name: -->
        <Add Type="CustomInitializer.Telemetry.MyTelemetryInitializer, CustomInitializer"/>
        ...
      </TelemetryInitializers>
    </ApplicationInsights>

Um método alternativo para ASP.NET aplicativos Web é instanciar o inicializador no código. O exemplo a seguir mostra o código no arquivo Global.aspx.cs :

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;

    protected void Application_Start()
    {
        // ...
        TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
    }

ASP.NET Core

Para adicionar uma nova TelemetryInitializer instância, adicione-a ao contêiner de injeção de dependência. O exemplo a seguir mostra essa abordagem. Adicione este código no ConfigureServices método da sua Startup.cs classe.

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;
 public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyTelemetryInitializer>();
}

Controle o endereço IP do cliente usado para mapeamentos de geolocalização

O inicializador de exemplo a seguir define o IP do cliente, que é usado para mapeamento de geolocalização, em vez do endereço IP do soquete do cliente, durante a ingestão de telemetria.

public void Initialize(ITelemetry telemetry)
{
    var request = telemetry as RequestTelemetry;
    if (request == null) return true;
    request.Context.Location.Ip = "{client ip address}"; // Could utilize System.Web.HttpContext.Current.Request.UserHostAddress;   
    return true;
}

Processadores de telemetria

Os processadores de telemetria podem filtrar e modificar cada item de telemetria antes de ser enviado do SDK para o portal.

Implementar ITelemetryProcessor

Os processadores de telemetria constroem uma cadeia de processamento. Quando você instancia um processador de telemetria, obtém uma referência ao próximo processador na cadeia. Quando um ponto de dados de telemetria é passado para o método de processo, ele faz seu trabalho e, em seguida, chama (ou não chama) o próximo processador de telemetria na cadeia.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.DataContracts;

public class SuccessfulDependencyFilter : ITelemetryProcessor
{
    private ITelemetryProcessor Next { get; set; }

    // next will point to the next TelemetryProcessor in the chain.
    public SuccessfulDependencyFilter(ITelemetryProcessor next)
    {
        this.Next = next;
    }

    public void Process(ITelemetry item)
    {
        // To filter out an item, return without calling the next processor.
        if (!OKtoSend(item)) { return; }

        this.Next.Process(item);
    }

    // Example: replace with your own criteria.
    private bool OKtoSend (ITelemetry item)
    {
        var dependency = item as DependencyTelemetry;
        if (dependency == null) return true;

        return dependency.Success != true;
    }
}

Adicione o seu processador

ASP.NET

Insira este trecho em ApplicationInsights.config:

<TelemetryProcessors>
    <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9">
    <!-- Set public property -->
    <MyParamFromConfigFile>2-beta</MyParamFromConfigFile>
    </Add>
</TelemetryProcessors>

Você pode passar valores de string do arquivo .config fornecendo propriedades nomeadas públicas na sua classe.

Como alternativa, você pode inicializar o filtro no código. Em uma classe de inicialização adequada, por exemplo, AppStart em Global.asax.cs, insira o seu processador numa cadeia:

var builder = TelemetryConfiguration.Active.DefaultTelemetrySink.TelemetryProcessorChainBuilder;
builder.Use((next) => new SuccessfulDependencyFilter(next));

// If you have more processors:
builder.Use((next) => new AnotherProcessor(next));

builder.Build();

Os clientes de telemetria criados após este ponto usam seus processadores.

Processador de telemetria de amostragem adaptável (da versão 2.0.0-beta3)

Esta funcionalidade está ativada por predefinição. Se o seu aplicativo enviar uma telemetria considerável, esse processador removerá parte dela.

    <TelemetryProcessors>
        <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
        </Add>
    </TelemetryProcessors>

O parâmetro fornece o destino que o algoritmo tenta alcançar. Cada instância do SDK funciona de forma independente. Assim, se o seu servidor for um cluster de várias máquinas, o volume real de telemetria será multiplicado de acordo.

Saiba mais sobre amostragem.

Processador de telemetria de amostragem de taxa fixa (a partir de 2.0.0-beta1)

Há também um processador de telemetria de amostragem padrão (a partir da versão 2.0.1):

    <TelemetryProcessors>
        <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

        <!-- Set a percentage close to 100/N where N is an integer. -->
        <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
        <SamplingPercentage>10</SamplingPercentage>
        </Add>
    </TelemetryProcessors>

ASP.NET Core

Para ASP.NET Core, a adição de um novo processador de telemetria é feita usando o AddApplicationInsightsTelemetryProcessor método de extensão em IServiceCollection, conforme mostrado. Este método é chamado no ConfigureServices método da sua Startup.cs classe.

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

Para registrar processadores de telemetria que precisam de parâmetros no ASP.NET Core, crie uma classe personalizada implementando ITelemetryProcessorFactory. Chame o construtor com os parâmetros desejados no método Create e, em seguida, use AddSingleton<ITelemetryProcessorFactory, MyTelemetryProcessorFactory>().

Serviço ao Trabalhador

Para o Serviço Worker, adicionar um novo processador de telemetria é feito usando o método de extensão AddApplicationInsightsTelemetryProcessor em IServiceCollection, conforme mostrado. Este método é chamado no ConfigureServices método da sua Startup.cs classe.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();
        // If you have more processors:
        services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
    }

Exemplos de filtros

Pedidos sintéticos

Filtre os bots e testes da web. Embora o Metrics Explorer ofereça a opção de filtrar fontes sintéticas, essa opção reduz o tráfego e o tamanho da ingestão filtrando-os no próprio SDK.

public void Process(ITelemetry item)
{
    if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
    
    // Send everything else:
    this.Next.Process(item);
}

Falha na autenticação

Filtre as solicitações com uma resposta "401".

public void Process(ITelemetry item)
{
    var request = item as RequestTelemetry;

    if (request != null &&
    request.ResponseCode.Equals("401", StringComparison.OrdinalIgnoreCase))
    {
        // To filter out an item, return without calling the next processor.
        return;
    }

    // Send everything else
    this.Next.Process(item);
}

Filtrar chamadas rápidas de dependência remota

Se você quiser diagnosticar apenas chamadas que são lentas, filtre as rápidas.

public void Process(ITelemetry item)
{
    var request = item as DependencyTelemetry;

    if (request != null && request.Duration.TotalMilliseconds < 100)
    {
        return;
    }
    this.Next.Process(item);
}

Amostragem

Para saber como configurar a amostragem para aplicativos ASP.NET e ASP.NET Core, consulte Amostragem no Application Insights.

Serviço ao Trabalhador

O SDK do Application Insights for Worker Service oferece suporte à amostragem de taxa fixa e à amostragem adaptável. A amostragem adaptável está habilitada por padrão. A amostragem pode ser desabilitada usando a EnableAdaptiveSampling opção em ApplicationInsightsServiceOptions.

Para definir outras configurações de amostragem, você pode usar o seguinte exemplo:

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.ApplicationInsights.Extensibility;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<TelemetryConfiguration>(telemetryConfiguration =>
{
   var telemetryProcessorChainBuilder = telemetryConfiguration.DefaultTelemetrySink.TelemetryProcessorChainBuilder;

   // Using adaptive sampling
   telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond: 5);

   // Alternately, the following configures adaptive sampling with 5 items per second, and also excludes DependencyTelemetry from being subject to sampling:
   // telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond:5, excludedTypes: "Dependency");
});

builder.Services.AddApplicationInsightsTelemetryWorkerService(new ApplicationInsightsServiceOptions
{
   EnableAdaptiveSampling = false,
});

var app = builder.Build();

Enriqueça dados através de HTTP

ASP.NET

var requestTelemetry = HttpContext.Current?.Items["Microsoft.ApplicationInsights.RequestTelemetry"] as RequestTelemetry;

if (requestTelemetry != null)
{
    requestTelemetry.Properties["myProp"] = "someData";
}

ASP.NET Core

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

Nesta secção

• Telemetria de filtro e pré-processo
• Inicializadores de telemetria
• Processador de telemetria
• Amostragem
• Várias funções para aplicativos com vários componentes

Filtrar e pré-processar telemetria

Você pode escrever código para filtrar, modificar ou enriquecer sua telemetria antes que ela seja enviada do SDK. O processamento inclui dados enviados dos módulos padrão de telemetria, como a recolha de pedidos HTTP e a recolha de dependências.

• A filtragem pode modificar ou descartar a telemetria antes de ser enviada do SDK ao implementar ITelemetryProcessor. Por exemplo, você pode reduzir o volume de telemetria excluindo solicitações de robôs. Ao contrário da amostragem, você tem controle total sobre o que é enviado ou descartado, mas isso afeta qualquer métrica baseada em logs agregados. Dependendo de como você descarta itens, você também pode perder a capacidade de navegar entre itens relacionados.

• pt-PT: Adicione ou modifique propriedades a qualquer telemetria enviada da sua aplicação implementando um ITelemetryInitializer. Por exemplo, você pode adicionar valores calculados ou números de versão para filtrar os dados no portal.

• A amostragem reduz o volume de telemetria sem afetar suas estatísticas. Ele mantém juntos pontos de dados relacionados para que você possa navegar entre eles quando diagnosticar um problema. No portal, as contagens totais são multiplicadas para compensar pela amostragem.

Filtering

Essa técnica oferece controle direto sobre o que está incluído ou excluído do fluxo de telemetria. A filtragem pode ser usada para impedir que itens de telemetria sejam enviados para o Application Insights. Você pode usar a filtragem com amostragem ou separadamente.

Para filtrar a telemetria, escreva um processador de telemetria e registe-o com TelemetryConfiguration. Toda a telemetria passa pelo seu processador. Você pode optar por soltá-lo do fluxo ou entregá-lo ao próximo processador na cadeia. A telemetria dos módulos padrão, como o coletor de solicitação HTTP e o coletor de dependência, e a telemetria que você mesmo rastreou estão incluídas. Por exemplo, é possível filtrar a telemetria sobre solicitações de robôs ou chamadas de dependência bem-sucedidas.

ITelemetryProcessor e ITelemetryInitializer

Qual é a diferença entre processadores de telemetria e inicializadores de telemetria?

• Existem algumas sobreposições no que você pode fazer com eles. Ambos podem ser usados para adicionar ou modificar propriedades de telemetria, embora recomendemos que você use inicializadores para essa finalidade.
• Os inicializadores de telemetria sempre são executados antes dos processadores de telemetria.
• Os inicializadores de telemetria podem ser chamados mais de uma vez. Por convenção, eles não configuram nenhuma propriedade que já estava configurada.
• Os processadores de telemetria permitem substituir ou descartar completamente um item de telemetria.
• Todos os inicializadores de telemetria registrados são chamados para cada item de telemetria. Para processadores de telemetria, o SDK assegura a invocação do primeiro processador de telemetria. Se o resto dos processadores são chamados ou não é decidido pelos processadores de telemetria anteriores.
• Use inicializadores de telemetria para enriquecer a telemetria com mais propriedades ou substituir uma existente. Use um processador de telemetria para filtrar a telemetria.

Adicionar/modificar propriedades

Use inicializadores de telemetria para enriquecer a telemetria com informações adicionais ou para substituir as propriedades de telemetria definidas pelos módulos de telemetria padrão.

Por exemplo, o Application Insights para um pacote web recolhe telemetria sobre solicitações HTTP. Por padrão, ele sinaliza qualquer solicitação com um código >de resposta =400 como falha. Se, em vez disso, quiser tratar 400 como um sucesso, você pode fornecer um inicializador de telemetria que define a propriedade success.

Se você fornecer um inicializador de telemetria, ele será chamado sempre que qualquer um dos métodos Track*() for chamado. Este inicializador inclui métodos Track() chamados pelos módulos padrão de telemetria. Por convenção, esses módulos não definem nenhuma propriedade que já tenha sido definida por um inicializador. Os inicializadores de telemetria são chamados antes de chamar os processadores de telemetria, portanto, qualquer enriquecimento feito pelos inicializadores é visível para os processadores.

Processadores de telemetria

Você pode processar e filtrar os dados coletados antes que eles sejam enviados para retenção usando processadores de telemetria. Os processadores de telemetria são chamados um a um na ordem em que foram adicionados antes que o item de telemetria seja enviado para a nuvem.

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

Se um processador de telemetria retornar false, esse item de telemetria não será enviado.

Todos os processadores de telemetria recebem os dados de telemetria e seu envelope para inspecionar e modificar. Eles também recebem um objeto de contexto. O conteúdo deste objeto é definido pelo parâmetro contextObjects ao chamar um método de tracking para telemetria rastreada manualmente. Para telemetria coletada automaticamente, esse objeto é preenchido com informações de solicitação disponíveis e o conteúdo de solicitação persistente conforme fornecido por appInsights.getCorrelationContext() (se a correlação de dependência automática estiver habilitada).

O tipo TypeScript para um processador de telemetria é:

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

Por exemplo, um processador que elimina dados de rastreamento de pilhas a partir de exceções pode ser criado e incorporado da seguinte forma:

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

Adicionar um nome de função de nuvem e uma instância de função de nuvem

Defina o nome da função na nuvem por meio de tags de contexto diretas:

var appInsights = require("applicationinsights");
appInsights.setup('CONNECTION_STRING').start();
appInsights.defaultClient.context.tags["ai.cloud.role"] = "your role name";
appInsights.defaultClient.context.tags["ai.cloud.roleInstance"] = "your role instance";

Defina o nome da função na nuvem por meio do processador de telemetria:

var appInsights = require("applicationinsights");
appInsights.setup('CONNECTION_STRING').start();

appInsights.defaultClient.addTelemetryProcessor(envelope => {
    envelope.tags["ai.cloud.role"] = "your role name";
    envelope.tags["ai.cloud.roleInstance"] = "your role instance"
});

Amostragem

Por padrão, o SDK envia todos os dados coletados para o serviço Application Insights. Se você quiser habilitar a amostragem para reduzir a quantidade de dados, defina o samplingPercentageconfig campo no objeto de um cliente. Definir samplingPercentage como 100 (o padrão) significa que todos os dados serão enviados e 0 significa que nada será enviado.

Se você estiver usando a correlação automática, todos os dados associados a uma única solicitação serão incluídos ou excluídos como uma unidade.

Adicione um código como o seguinte para habilitar a amostragem:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

Várias funções para aplicativos com vários componentes

Em alguns cenários, seu aplicativo pode consistir em vários componentes que você deseja instrumentar todos com a mesma cadeia de conexão. Você ainda deseja ver esses componentes como unidades separadas no portal, como se estivessem usando cadeias de conexão separadas. Um exemplo é a separação de nós no Application Map. Você precisa configurar manualmente o campo para distinguir a telemetria RoleName de um componente de outros componentes que enviam dados para seu recurso do Application Insights.

Use o seguinte código para definir o RoleName campo:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

Nesta secção

• Canais de telemetria
• Módulos de telemetria
• Desativar telemetria
• Cadeia de conexão
• Provedor ApplicationId

Você pode personalizar o SDK do Application Insights para ASP.NET, ASP.NET Core e Serviço de Trabalho para alterar a configuração padrão.

ASP.NET

O SDK do .NET do Application Insights consiste em muitos pacotes NuGet. O pacote principal fornece a API para enviar telemetria para o Application Insights. Mais pacotes fornecem módulos de telemetria e inicializadores para rastrear automaticamente a telemetria do seu aplicativo e seu contexto. Ajustando o arquivo de configuração, você pode habilitar ou desabilitar módulos de telemetria e inicializadores. Você também pode definir parâmetros para alguns deles.

O arquivo de configuração é nomeado ApplicationInsights.config ou ApplicationInsights.xml. O nome depende do tipo do seu pedido. Ele é adicionado automaticamente ao seu projeto quando você instala a maioria das versões do SDK.

Por padrão, quando você usa a experiência automatizada dos projetos de modelo do Visual Studio que oferecem suporte a Telemetria Add>Application Insights, o ApplicationInsights.config arquivo é criado na pasta raiz do projeto. Depois de compilar, ele é copiado para a pasta bin. Ele também é adicionado a um aplicativo Web pelo Application Insights Agent em um servidor IIS.

Não há um arquivo equivalente para controlar o SDK em uma página da Web.

ASP.NET Core

Em aplicativos ASP.NET Core, todas as alterações de configuração são feitas no ConfigureServices() método de sua classe Startup.cs , a menos que indicado de outra forma.

Serviço ao Trabalhador

O padrão TelemetryConfiguration utilizado pelo SDK do Serviço do Trabalhador é semelhante à configuração utilizada automaticamente em uma aplicação ASP.NET ou ASP.NET Core, à exceção dos inicializadores de telemetria que são usados para melhorar a telemetria do HttpContext.

Você pode personalizar o SDK do Application Insights para o Serviço de Trabalho para alterar a configuração padrão. Os usuários do SDK do Application Insights ASP.NET Core podem estar familiarizados com a alteração da configuração usando a injeção de dependência interna do ASP.NET Core. O SDK do Serviço de Trabalho também se baseia em princípios semelhantes. Faça quase todas as alterações de configuração na ConfigureServices() seção chamando os métodos apropriados no IServiceCollection, conforme detalhado na próxima seção.

Canais de telemetria

Os canais de telemetria são parte integrante dos SDKs do Application Insights. Eles gerenciam o buffer e a transmissão de telemetria para o serviço Application Insights. As versões .NET e .NET Core dos SDKs têm dois canais de telemetria internos: InMemoryChannel e ServerTelemetryChannel. Esta seção descreve cada canal e mostra como personalizar o comportamento do canal.

O que são canais de telemetria?

Os canais de telemetria são responsáveis por armazenar itens de telemetria em buffer e enviá-los para o serviço Application Insights, onde são armazenados para consulta e análise. Um canal de telemetria é qualquer classe que implementa a Microsoft.ApplicationInsights.ITelemetryChannel interface.

O Send(ITelemetry item) método de um canal de telemetria é chamado depois que todos os inicializadores de telemetria e processadores de telemetria são chamados. Assim, qualquer item descartado por um processador de telemetria não chega ao canal. Normalmente Send() , o método não envia os itens para o back-end instantaneamente. Normalmente, ele os armazena em buffer na memória e os envia em lotes para uma transmissão eficiente.

Evite ligar Flush() , a menos que seja fundamental enviar telemetria em buffer imediatamente. Use-o somente em cenários como desligamento de aplicativos, tratamento de exceções ou ao usar processos de curta duração, como trabalhos em segundo plano ou ferramentas de linha de comando. Em aplicativos Web ou serviços de longa execução, o SDK lida com o envio de telemetria automaticamente. Chamar Flush() desnecessariamente pode causar problemas de desempenho.

Live Metrics Stream também tem um canal personalizado que alimenta a transmissão ao vivo de telemetria. Este canal é independente do canal de telemetria regular, e este documento não se aplica a ele.

Canais de telemetria integrados

Os SDKs .NET e .NET Core do Application Insights são fornecidos com dois canais internos:

• InMemoryChannel: Um canal leve que armazena itens em buffer na memória até que eles sejam enviados. Os itens são armazenados em buffer na memória e liberados uma vez a cada 30 segundos ou sempre que 500 itens são armazenados em buffer. Este canal oferece garantias mínimas de confiabilidade porque não tenta enviar telemetria novamente após uma falha. Este canal também não mantém itens no disco. Assim, todos os itens não enviados são perdidos permanentemente após o desligamento do aplicativo, seja ele gracioso ou não. Esse canal implementa um Flush() método que pode ser usado para forçar a liberação de quaisquer itens de telemetria na memória de forma síncrona. Este canal é adequado para aplicações de curta duração onde uma descarga síncrona é ideal.

  Esse canal faz parte do pacote NuGet maior do Microsoft.ApplicationInsights e é o canal padrão que o SDK usa quando nada mais é configurado.

• ServerTelemetryChannel: Um canal mais avançado que tem políticas de repetição e a capacidade de armazenar dados em um disco local. Este canal tenta novamente enviar telemetria se ocorrerem erros transitórios. Esse canal também usa armazenamento em disco local para manter itens no disco durante interrupções de rede ou altos volumes de telemetria. Devido a esses mecanismos de repetição e armazenamento em disco local, esse canal é considerado mais confiável. Recomendamos para todos os cenários de produção. Este canal é o padrão para aplicativos ASP.NET e ASP.NET Core que são configurados de acordo com a documentação oficial. Esse canal é otimizado para cenários de servidor com processos de longa execução. O Flush() método implementado por este canal não é síncrono.

  Esse canal é fornecido como o pacote NuGet Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel e é adquirido automaticamente quando você usa o pacote NuGet Microsoft.ApplicationInsights.Web ou Microsoft.ApplicationInsights.AspNetCore.

Configurar um canal de telemetria

Configure um canal de telemetria definindo-o para a configuração de telemetria ativa. Para aplicativos ASP.NET, a configuração envolve definir a instância do canal de telemetria para TelemetryConfiguration.Active ou modificando ApplicationInsights.config. Para aplicativos ASP.NET Core, a configuração envolve a adição do canal ao contêiner de injeção de dependência.

As seções a seguir mostram exemplos de configuração da StorageFolder configuração para o canal em vários tipos de aplicativos. StorageFolder é apenas uma das configurações configuráveis. Para obter a lista completa de definições de configuração, consulte a seção Configurações configuráveis em canais mais adiante neste artigo.

ASP.NET

Opção 1: Configuração no código

O código a seguir configura uma ServerTelemetryChannel instância com StorageFolder definido para um local personalizado. Adicione esse código no início do aplicativo, normalmente no Application_Start() método em Global.aspx.cs.

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

Opção 2: Configuração no ApplicationInsights.config

A seção a seguir do ApplicationInsights.config mostra o ServerTelemetryChannel canal configurado com StorageFolder definido para um local personalizado:

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>

ASP.NET Core

Modifique o ConfigureServicesStartup.cs método da classe como mostrado aqui:

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

Substituindo ServerTelemetryChannel

O canal de telemetria padrão é ServerTelemetryChannel. O exemplo a seguir mostra como substituí-lo.

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

Serviço ao Trabalhador

O canal padrão é ServerTelemetryChannel. Você pode substituí-lo como mostra o exemplo a seguir:

using Microsoft.ApplicationInsights.Channel;

    public void ConfigureServices(IServiceCollection services)
    {
        // Use the following to replace the default channel with InMemoryChannel.
        // This can also be applied to ServerTelemetryChannel.
        services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

        services.AddApplicationInsightsTelemetryWorkerService();
    }

Configuração em código para aplicativos de console

Para aplicativos de console, o código é o mesmo para .NET e .NET Core:

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

Detalhes operacionais do ServerTelemetryChannel

ServerTelemetryChannel armazena os itens que chegam em um buffer na memória. Os itens são serializados, compactados e armazenados em uma Transmission instância uma vez a cada 30 segundos ou quando 500 itens são armazenados em buffer. Uma única Transmission instância contém até 500 itens e representa um lote de telemetria que é enviado por uma única chamada HTTPS para o serviço Application Insights.

Por padrão, um máximo de 10 Transmission instâncias podem ser enviadas em paralelo. Se a telemetria estiver chegando a taxas mais rápidas, ou se a rede ou o back-end do Application Insights estiver lento, Transmission as instâncias serão armazenadas na memória. A capacidade padrão desse buffer na memória Transmission é de 5 MB. Quando a capacidade na memória é excedida, Transmission as instâncias são armazenadas no disco local até um limite de 50 MB.

Transmission As instâncias são armazenadas no disco local também quando há problemas de rede. Somente os itens armazenados em um disco local sobrevivem a uma falha de aplicativo. Eles são enviados sempre que o aplicativo é reiniciado. Se os problemas de rede persistirem, ServerTelemetryChannel usa uma lógica de backoff exponencial que varia de 10 segundos a 1 hora antes de tentar enviar novamente a telemetria.

Configurações configuráveis em canais

Para obter a lista completa de configurações configuráveis para cada canal, consulte:

• InMemoryChannel
• ServerTelemetryChannel

Aqui estão as configurações mais usadas para ServerTelemetryChannel:

• MaxTransmissionBufferCapacity: A quantidade máxima de memória, em bytes, usada pelo canal para buffer transmissões na memória. Quando essa capacidade é atingida, novos itens são armazenados diretamente no disco local. O valor padrão é 5 MB. Definir um valor mais alto leva a menos uso do disco, mas lembre-se de que os itens na memória são perdidos se o aplicativo falhar.

• MaxTransmissionSenderCapacity: O número máximo de Transmission instâncias que são enviadas para o Application Insights ao mesmo tempo. O valor padrão é 10. Essa configuração pode ser configurada para um número maior, o que recomendamos quando um grande volume de telemetria é gerado. O volume elevado ocorre normalmente durante o teste de carga ou quando a amostragem está desligada.

• StorageFolder: A pasta usada pelo canal para armazenar itens no disco conforme necessário. No Windows, %LOCALAPPDATA% ou %TEMP% é usado se nenhum outro caminho for especificado explicitamente. Em ambientes diferentes do Windows, por padrão, os seguintes locais são usados (na ordem): %TMPDIR%, /var/tmp/ ou /tmp/.

Que canal devo utilizar?

Recomendamos ServerTelemetryChannel para a maioria dos cenários de produção que envolvem aplicativos de longa execução. Para obter mais informações sobre a telemetria de lavagem, leia sobre como usar Flush()o .

Quando utilizar Flush()

O Flush() método envia qualquer telemetria em buffer imediatamente. No entanto, só deve ser utilizado em cenários específicos.

Utilize Flush() quando:

• O aplicativo está prestes a ser desligado e você deseja garantir que a telemetria seja enviada antes de sair.
• Você está em um manipulador de exceções e precisa garantir que a telemetria seja entregue.
• Você está escrevendo um processo de curta duração, como um trabalho em segundo plano ou uma ferramenta CLI que sai rapidamente.

Evite usar Flush() em aplicativos de longa execução, como serviços Web. O SDK gerencia automaticamente o buffer e a transmissão. Ligar Flush() desnecessariamente pode causar problemas de desempenho e não garante que todos os dados sejam enviados, especialmente ao usar ServerTelemetryChannelo , que não é liberado de forma síncrona.

Módulos de telemetria

O Application Insights coleta automaticamente telemetria sobre cargas de trabalho específicas sem exigir rastreamento manual pelo usuário.

Por padrão, os seguintes módulos de coleta automática estão habilitados. Você pode desativá-los ou configurá-los para alterar seu comportamento padrão.

ASP.NET

Cada módulo de telemetria coleta um tipo específico de dados e usa a API principal para enviar os dados. Os módulos são instalados por diferentes pacotes NuGet, que também adicionam as linhas necessárias ao arquivo .config.

ASP.NET Core

Configurar módulos de telemetria

ASP.NET

Use a TelemetryModules seção no ApplicationInsights.config para configurar, adicionar ou remover módulos. Os seguintes exemplos:

• Configure DependencyTrackingTelemetryModule (ative a injeção de cabeçalho W3C).
• Configurar EventCounterCollectionModule (limpar padrões e adicionar um único contador).
• Desative a coleta perf-counter removendo PerformanceCollectorModuleo .

<ApplicationInsights>
  <TelemetryModules>

    <!-- Dependency tracking -->
    <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
      <!-- Match Core example: enable W3C header injection -->
      <EnableW3CHeadersInjection>true</EnableW3CHeadersInjection>
    </Add>

    <!-- EventCounterCollectionModule: add a single counter (if you use event counters) -->
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.EventCounterCollectionModule, Microsoft.AI.PerfCounterCollector">
      <Counters>
        <!-- Mirrors Core example: only collect 'gen-0-size' from System.Runtime -->
        <Add ProviderName="System.Runtime" CounterName="gen-0-size" />
      </Counters>
    </Add>

    <!-- PerformanceCollectorModule (classic Windows performance counters).
         To DISABLE perf-counter collection, do NOT include this module.
         If it already exists in your file, remove or comment it out.
         Example of the line you would remove:
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector" />
    -->

  </TelemetryModules>
</ApplicationInsights>

ASP.NET Core

Opção 1: Configurar módulos de telemetria usando ConfigureTelemetryModule

Para configurar qualquer padrão TelemetryModule, use o método ConfigureTelemetryModule<T> extension no IServiceCollection, conforme mostrado no exemplo a seguir:

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

Opção 2: Configurar módulos de telemetria usando ApplicationInsightsServiceOptions

Nas versões 2.12.2 e posteriores do SDK, você pode modificar algumas configurações comuns passando ApplicationInsightsServiceOptions para AddApplicationInsightsTelemetry, como neste exemplo:

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

Esta tabela tem a lista completa de ApplicationInsightsServiceOptions configurações:

Para obter a lista mais atual, consulte as configurações configuráveis em ApplicationInsightsServiceOptions.

Recomendação de configuração para Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 e posterior

Em Microsoft.ApplicationInsights.AspNetCore SDK versão 2.15.0 e posterior, configure todas as configurações disponíveis no ApplicationInsightsServiceOptions, incluindo ConnectionString. Use a instância do IConfiguration aplicativo. As configurações devem estar na seção ApplicationInsights, conforme mostrado no exemplo a seguir. A seção a seguir do appsettings.json configura a cadeia de conexão e desabilita a amostragem adaptativa e a coleta do contador de desempenho.

{
    "ApplicationInsights": {
    "ConnectionString": "<YOUR-CONNECTION-STRING>",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

Se builder.Services.AddApplicationInsightsTelemetry(aiOptions) for usado para ASP.NET Core 6.0 ou services.AddApplicationInsightsTelemetry(aiOptions) para ASP.NET Core 3.1 e versões anteriores, ele substituirá as configurações do Microsoft.Extensions.Configuration.IConfiguration.

Serviço ao Trabalhador

Opção 1: Configurar módulos de telemetria usando ConfigureTelemetryModule

O Application Insights usa módulos de telemetria para coletar automaticamente telemetria sobre cargas de trabalho específicas sem exigir rastreamento manual.

Os seguintes módulos de coleta automática são habilitados por padrão. Estes módulos são responsáveis pela recolha automática da telemetria. Você pode desativá-los ou configurá-los para alterar seu comportamento padrão.

• DependencyTrackingTelemetryModule
• PerformanceCollectorModule
• QuickPulseTelemetryModule
• AppServicesHeartbeatTelemetryModule (Atualmente, há um problema envolvendo este módulo de telemetria. Para obter uma solução temporária, consulte GitHub Issue 1689.)
• AzureInstanceMetadataTelemetryModule

Para configurar qualquer módulo de telemetria padrão, use o método de extensão ConfigureTelemetryModule em IServiceCollection, conforme mostrado no exemplo a seguir.

    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();

            // The following configures QuickPulseTelemetryModule.
            // Similarly, any other default modules can be configured.
            services.ConfigureTelemetryModule<QuickPulseTelemetryModule>((module, o) =>
            {
                module.AuthenticationApiKey = "<YOUR-API-KEY-HERE>";
            });

            // The following removes PerformanceCollectorModule to disable perf-counter collection.
            // Similarly, any other default modules can be removed.
            var performanceCounterService = services.FirstOrDefault<ServiceDescriptor>
                                        (t => t.ImplementationType == typeof(PerformanceCollectorModule));
            if (performanceCounterService != null)
            {
                services.Remove(performanceCounterService);
            }
    }

Opção 2: Configurar módulos de telemetria usando ApplicationInsightsServiceOptions

Você pode modificar algumas configurações comuns passando ApplicationInsightsServiceOptions para AddApplicationInsightsTelemetryWorkerService, como neste exemplo:

using Microsoft.ApplicationInsights.WorkerService;

public void ConfigureServices(IServiceCollection services)
{
    var aiOptions = new ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

    // Disables live metrics (also known as QuickPulse).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetryWorkerService(aiOptions);
}

O ApplicationInsightsServiceOptions neste SDK está no namespace Microsoft.ApplicationInsights.WorkerService em oposição ao Microsoft.ApplicationInsights.AspNetCore.Extensions SDK do ASP.NET Core.

A tabela a seguir lista as configurações mais usadas no ApplicationInsightsServiceOptions.

Para obter a lista mais atualizada, consulte as definições configuráveis em ApplicationInsightsServiceOptions.

Desativar telemetria

ASP.NET

Há um nó no arquivo de configuração para cada módulo. Para desativar um módulo, exclua o nó ou comente-o.

ASP.NET Core

Se quiser desativar a telemetria de forma condicional e dinâmica, pode resolver a instância TelemetryConfiguration usando um contentor de injeção de dependência ASP.NET Core em qualquer parte do código e definir o sinalizador DisableTelemetry na instância.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

O exemplo de código anterior impede o envio de telemetria para o Application Insights. Isso não impede que nenhum módulo de coleta automática colete telemetria. Se quiser remover um módulo de coleta automática específico, consulte Módulos de telemetria.

Serviço ao Trabalhador

Se quiser desativar a telemetria de forma condicional e dinâmica, pode resolver a instância TelemetryConfiguration usando um contentor de injeção de dependência ASP.NET Core em qualquer parte do código e definir o sinalizador DisableTelemetry na instância.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
    {
        configuration.DisableTelemetry = true;
        ...
    }

Cadeia de ligação

Essa configuração determina o recurso do Application Insights no qual seus dados aparecem. Normalmente, você cria um recurso separado, com uma cadeia de conexão separada, para cada um dos seus aplicativos.

Consulte Cadeias de conexão no Application Insights para obter exemplos de código.

Se você quiser definir a cadeia de conexão dinamicamente, por exemplo, para enviar resultados do seu aplicativo para recursos diferentes, você pode omitir a cadeia de conexão do arquivo de configuração e defini-la no código.

ASP.NET

Para definir a cadeia de conexão para todas as instâncias do , incluindo módulos de telemetria padrão, execute esta etapa em um método de TelemetryClientinicialização, como global.aspx.cs em um serviço ASP.NET:

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.ConnectionString = "<YOUR-CONNECTION-STRING>";
        var telemetryClient = new TelemetryClient(configuration);

Se quiser enviar um conjunto específico de eventos para um recurso diferente, você pode definir a chave para um cliente de telemetria específico:

    var tc = new TelemetryClient();
    tc.Context.ConnectionString = "<YOUR-CONNECTION-STRING>";
    tc.TrackEvent("myEvent");
    // ...

Para obter uma nova cadeia de conexão, crie um novo recurso no portal do Application Insights.

ASP.NET Core

No ASP.NET Core, configure a cadeia de conexão durante Program.cs a inicialização do aplicativo usando o TelemetryConfiguration contêiner do DI (injeção de dependência):

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

// Resolve TelemetryConfiguration from DI and set the connection string
var config = app.Services.GetRequiredService<TelemetryConfiguration>();
config.ConnectionString = "<YOUR-CONNECTION-STRING>";

app.Run();

Se quiser enviar um conjunto específico de eventos para um recurso diferente, você pode criar uma nova TelemetryClient instância e definir sua cadeia de conexão explicitamente:

using Microsoft.ApplicationInsights;

var tc = new TelemetryClient();
tc.Context.ConnectionString = "<YOUR-CONNECTION-STRING>";
tc.TrackEvent("myEvent");
// ...

Provedor ApplicationId

O objetivo desse provedor é pesquisar uma ID de aplicativo com base em uma cadeia de conexão. O ID do aplicativo é incluído e RequestTelemetryDependencyTelemetry usado para determinar a correlação no portal.

Esta funcionalidade está disponível através da definição TelemetryConfiguration.ApplicationIdProvider.

Interface: IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string connectionString, out string applicationId);
}

Fornecemos duas implementações no SDK do Microsoft.ApplicationInsights : ApplicationInsightsApplicationIdProvider e DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Este wrapper é para a nossa API de perfil. Ele acelera solicitações e resultados de cache. Esse provedor é incluído automaticamente quando você instala Microsoft.ApplicationInsights.DependencyCollector ou Microsoft.ApplicationInsights.Web.

A classe expõe uma propriedade opcional chamada ProfileQueryEndpoint. Por padrão, ele é definido como https://dc.services.visualstudio.com/api/profiles/{0}/appId.

Se você precisar configurar um proxy, recomendamos fazer proxy do endereço base e garantir que o caminho inclua /api/profiles/{0}/appId. Em tempo de execução, {0} é substituída pela string de ligação de cada pedido.

ASP.NET

Exemplo de configuração via ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Exemplo de configuração via código

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

ASP.NET Core

Você pode substituir o provedor padrão ou personalizar seu ProfileQueryEndpointarquivo .

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

// Replace default provider with custom configuration
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new ApplicationInsightsApplicationIdProvider
    {
        ProfileQueryEndpoint = "https://custom-proxy/api/profiles/{0}/appId"
    });

var app = builder.Build();
app.Run();

DictionaryApplicationIdProvider

Este fornecedor estático baseia-se nos pares de strings de ligação configurados/ID de aplicação.

Esta classe tem a propriedade Defined, que é um conjunto de pares de string de conexão/ID de aplicação Dictionary<string,string>.

Essa classe tem a propriedade Nextopcional , que pode ser usada para configurar outro provedor a ser usado quando uma cadeia de conexão é solicitada que não existe em sua configuração.

ASP.NET

Exemplo de configuração via ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="ConnectionString_1" value="ApplicationId_1"/>
            <Type key="ConnectionString_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Exemplo de configuração via código

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"ConnectionString_1", "ApplicationId_1"},
        {"ConnectionString_2", "ApplicationId_2"}
    }
};

ASP.NET Core

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Register DictionaryApplicationIdProvider
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new DictionaryApplicationIdProvider
    {
        Defined = new Dictionary<string, string>
        {
            { "ConnectionString_1", "ApplicationId_1" },
            { "ConnectionString_2", "ApplicationId_2" }
        },
        Next = new ApplicationInsightsApplicationIdProvider() // optional fallback
    });

var app = builder.Build();
app.Run();

Nesta secção

• Cadeia de conexão
• Opção de configuração avançada
• Instrumentação automática de terceiros

O appInsights objeto fornece muitos métodos de configuração. Eles estão listados no trecho a seguir com seus valores padrão.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

Para correlacionar totalmente os eventos num serviço, confirme que define .setAutoDependencyCorrelation(true). Com esta opção definida, o SDK pode monitorizar o contexto em chamadas de retorno assíncronas em Node.js.

Analise as descrições no recurso de sugestões de tipos integrado no seu IDE ou no applicationinsights.ts para obter informações detalhadas e argumentos secundários opcionais.

Cadeia de ligação

Essa configuração determina o recurso do Application Insights no qual seus dados aparecem. Normalmente, você cria um recurso separado, com uma cadeia de conexão separada, para cada um dos seus aplicativos.

Consulte Cadeias de conexão no Application Insights para obter exemplos de código.

Se você quiser definir a cadeia de conexão dinamicamente, por exemplo, para enviar resultados do seu aplicativo para recursos diferentes, você pode omitir a cadeia de conexão do arquivo de configuração e defini-la no código.

Usar várias cadeias de conexão

Você pode criar vários recursos do Application Insights e enviar dados diferentes para cada um usando suas respetivas cadeias de conexão.

Por exemplo:

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

Opções avançadas de configuração

O objeto client contém uma config propriedade com muitas configurações opcionais para cenários avançados. Para defini-los, use:

client.config.PROPERTYNAME = VALUE;

Essas propriedades são específicas do cliente, portanto, você pode configurar appInsights.defaultClient separadamente dos clientes criados com new appInsights.TelemetryClient()o .

Instrumentação automática de terceiros

Para controlar o contexto em chamadas assíncronas, algumas alterações são necessárias em bibliotecas de terceiros, como MongoDB e Redis. Por padrão, o Application Insights usa diagnostic-channel-publishers para aplicar monkey-patch a algumas dessas bibliotecas. Esse recurso pode ser desativado definindo a variável de APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL ambiente.

Os patches de macaco individuais podem ser desativados definindo a variável de ambiente como uma lista separada por vírgulas APPLICATION_INSIGHTS_NO_PATCH_MODULES de pacotes a serem desabilitados. Por exemplo, use APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis para evitar a aplicação de patches nos console e redis pacotes.

Atualmente, nove pacotes são instrumentados: bunyan,console,mongodb,mongodb-core,,mysql,redis,,winstonpg e pg-pool. Para obter informações sobre exatamente qual versão desses pacotes foi corrigida, consulte o README dos "diagnostic-channel-publishers".

Os patches bunyan, winston e console geram eventos de rastreamento do Application Insights com base na ativação de setAutoCollectConsole. Os restantes componentes geram eventos de dependência do Application Insights com base no estado de ativação de setAutoCollectDependencies.

As seções anteriores forneceram orientação sobre métodos para configurar automática e manualmente o monitoramento do lado do servidor. Para adicionar monitorização do lado do cliente, use o SDK de JavaScript do lado do cliente. Você pode monitorar as transações do lado do cliente de qualquer página da Web adicionando um JavaScript (Web) SDK Loader Script antes da tag de fechamento </head> do HTML da página.

Embora seja possível adicionar manualmente o JavaScript (Web) SDK Loader Script ao cabeçalho de cada página HTML, recomendamos que você adicione o JavaScript (Web) SDK Loader Script a uma página primária. Essa ação injeta o JavaScript (Web) SDK Loader Script em todas as páginas de um site.

ASP.NET

Para o aplicativo MVC de ASP.NET baseado em modelo deste artigo, o arquivo que você precisa editar é _Layout.cshtml. Você pode encontrá-lo em Visualizações>compartilhadas. Para adicionar monitoramento do lado do cliente, abra _Layout.cshtml e siga as instruções de configuração baseadas em script do JavaScript (Web) SDK Loader do artigo sobre a configuração do JavaScript SDK do lado do cliente.

ASP.NET Core

Se o seu aplicativo tiver componentes do lado do cliente, siga os próximos passos para começar a coletar telemetria de uso através da injeção do Script Loader do SDK de JavaScript (Web) por configuração.

1. Em _ViewImports.cshtml, adicione injeção:

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

2. Em _Layout.cshtml, insira HtmlHelper no final da <head> seção, mas antes de qualquer outro script. Se você quiser relatar qualquer telemetria JavaScript personalizada da página, injete-a após este trecho:

       @Html.Raw(JavaScriptSnippet.FullScript)
   </head>
   

Como alternativa ao uso FullScriptdo , ScriptBody está disponível a partir do SDK do Application Insights para ASP.NET Core versão 2.14. Use ScriptBody se precisar controlar a <script> tag para definir uma Política de Segurança de Conteúdo:

<script> // apply custom changes to this script tag.
    @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>

Os nomes de arquivo .cshtml mencionados anteriormente são de um modelo de aplicativo MVC padrão. Em última análise, se você quiser habilitar corretamente o monitoramento do lado do cliente para seu aplicativo, o JavaScript (Web) SDK Loader Script deve aparecer na <head> seção de cada página do seu aplicativo que você deseja monitorar. Adicione o JavaScript (Web) SDK Loader Script ao _Layout.cshtml em um modelo de aplicativo para habilitar o monitoramento do lado do cliente.

Se seu projeto não incluir _Layout.cshtml, você ainda poderá adicionar monitoramento do lado do cliente adicionando o JavaScript (Web) SDK Loader Script a um arquivo equivalente que controla todas <head> as páginas do seu aplicativo. Como alternativa, você pode adicionar o JavaScript (Web) SDK Loader Script a várias páginas, mas não o recomendamos.

A instrumentação automática da Web pode ser ativada para o servidor Node.js por injeção de script do carregador SDK JavaScript (Web) através de configuração.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

ou definindo a variável APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = truede ambiente .

A Instrumentação da Web é ativada em respostas do servidor node quando todos os seguintes requisitos são atendidos.

• A resposta tem o código de estado 200.
• O método de resposta é GET.
• A resposta do servidor contém Content-Type código HTML.
• A resposta do servidor contém ambas as <head> tags e </head> .
• Se a resposta for compactada, ela deverá ter apenas um Content-Encoding tipo, e o tipo de codificação deverá ser um dos gzip, br ou deflate.
• A resposta não contém pontos de extremidade CDN de /backup de instrumentação web atuais. (pontos de extremidade atuais e de backup da CDN de instrumentação da Web aqui)

O ponto de extremidade CDN da Instrumentação da Web pode ser alterado definindo a variável de ambiente APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints". A cadeia de conexão da Instrumentação da Web pode ser alterada definindo a variável de ambiente APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

private TelemetryClient telemetry = new TelemetryClient();

Se você vir uma mensagem informando que esse método está obsoleto, consulte microsoft/ApplicationInsights-dotnet#1152 para obter mais informações.

As solicitações HTTP recebidas são capturadas automaticamente. Talvez queiras criar mais instâncias de TelemetryClient para outros módulos da tua aplicação. Por exemplo, você pode ter uma TelemetryClient instância em sua classe middleware para relatar eventos de lógica de negócios. Você pode definir propriedades como UserId e DeviceId para identificar a máquina. Essas informações são anexadas a todos os eventos enviados pela instância.

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

var telemetry = applicationInsights.defaultClient;

Você pode usar new applicationInsights.TelemetryClient(instrumentationKey?) para criar uma nova instância. Recomendamos essa abordagem apenas para cenários que exigem configuração isolada do singleton defaultClient.

telemetry.TrackEvent("WinGame");

telemetry.trackEvent({name: "WinGame"});

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

telemetry.trackMetric({name: "queueLength", value: 42.0});

telemetry.TrackPageView("GameReviewPage");

Não aplicável.

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here uses the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

Para obter mais informações sobre correlação, consulte Correlação de telemetria no Application Insights.

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, telemetry item is sent.

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

Em adaptadores de log .NET, use esta API para enviar logs de terceiros para o portal.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

Não aplicável.

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

Quando utiliza Flush(), recomendamos este padrão:

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

Quando utiliza FlushAsync(), recomendamos este padrão:

await telemetryClient.FlushAsync()
// No need to sleep

Recomendamos sempre o despejo como parte do encerramento da aplicação para garantir que a telemetria não seja perdida.

A função é assíncrona para o canal de telemetria do servidor.

telemetry.flush();

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry is automatically sent with the context property:
gameTelemetry.TrackEvent("WinGame");

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

telemetry.config.disableAppInsights = true;

Para desabilitar coletores padrão selecionados, por exemplo, contadores de desempenho, solicitações HTTP ou dependências, no momento da inicialização, encadeie métodos de configuração ao código de inicialização do SDK.

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

Para desabilitar esses coletores após a inicialização, use o objeto Configuration: applicationInsights.Configuration.setAutoCollectRequests(false).

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Por Node.js, você pode habilitar o modo de desenvolvedor habilitando o registro interno via setInternalLogging e definindo maxBatchSize como 0, o que faz com que sua telemetria seja enviada assim que for coletada.

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

Não aplicável.