Monitorar aplicativos .NET e Node.js com o Application Insights (API Clássica 2.x)

Cuidado

  • O Node.js SDK da API Clássica do Application Insights 2.x foi desativado.
  • O SDK da API Clássica do .NET Application Insights 2.x está obsoleto e será desativado em 31/03/2027.
  • Para permanecer com suporte, migre para um SDK 3.x baseado em OpenTelemetry ou, preferencialmente, o OpenTelemetry Distro.
  • Para obter detalhes da política de suporte, consulte as diretrizes de suporte do SDK do Application Insights.

Importante

Para novos aplicativos, use a Distribuição OpenTelemetry do Azure Monitor.

Este artigo explica como habilitar e configurar Application Insights para aplicativos .NET (ASP.NET, ASP.NET Core e Serviço de Trabalho) e Node.js. O Application Insights pode coletar a seguinte telemetria dos seus aplicativos:

  • Solicitações
  • Dependências
  • Exceções
  • Contadores de desempenho
  • Rastreamentos (Logs)
  • Pulsações
  • Eventos e métricas personalizados (requer instrumentação manual)
  • Exibições de página (requer SDK do JavaScript para páginas da Web)
  • Testes de disponibilidade (requer a configuração manual de testes de disponibilidade)

Cenários com suporte

Supported ASP.NET ASP.NET Core Serviço de Trabalho
Sistema operacional Windows Windows, Linux ou macOS Windows, Linux ou macOS
Método de hospedagem Em processo (IIS ou IIS Express) Em processo ou fora de processo Console ou serviço em segundo plano (é executado como um processo, normalmente por meio da dotnet CLI ou como um daemon do Windows Service/Linux)
Método de implantação Implantação da Web, MSI ou cópia de arquivo manual Dependente da estrutura ou autocontido Dependente da estrutura ou autocontido
Servidor Web Serviços de Informações da Internet (IIS) Internet Information Server (IIS) ou Kestrel Não aplicável (nenhum servidor Web; projetado para cargas de trabalho não HTTP, como mensagens, tarefas em segundo plano e aplicativos de console)
Plataforma de hospedagem Azure App Service (Windows), Azure Virtual Machines ou servidores locais O recurso Web Apps de Azure App Service, Azure Virtual Machines, Docker e Azure Kubernetes Service (AKS) Máquinas Virtuais do Azure, AKS (Serviço de Kubernetes do Azure), contêineres ou qualquer ambiente em que o .NET Core tem suporte
Versão .NET .NET Framework 4.6.1 e posterior Todas as versões do .NET oficialmente suportadas que não estão em versão prévia. Todas as versões do .NET oficialmente suportadas que não estão em versão prévia.

O SDK do Worker Service não coleta telemetria por si só. Em vez disso, ele traz outros coletores de automóveis conhecidos do Application Insights, como DependencyCollector, PerfCounterCollector e ApplicationInsightsLoggingProvider. O SDK expõe extensões de métodos em IServiceCollection para habilitar e configurar a coleta de telemetria.

Observação

Um serviço de trabalho é um aplicativo em segundo plano de execução longa que executa tarefas fora de um pipeline de solicitação/resposta HTTP. O Application Insights SDK for Worker Service pode ser usado no recém-introduzido .NET Core Worker Service, em tarefas em segundo plano no ASP.NET Core e além de aplicativos de console como .NET Core e .NET Framework.

Adicionar Application Insights

Nesta seção

Pré-requisitos

Instrumentar seu aplicativo com o SDK do Application Insights

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

ASP.NET

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

  2. Em alguns casos, o arquivo ApplicationInsights.config é criado automaticamente para você. Se o arquivo já estiver presente, pule para a quarta etapa.

    Se ele ainda não tiver sido criado, faça isso. 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 exibir 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 marca de fechamento </ApplicationInsights> em ApplicationInsights.config, adicione a cadeia de conexão ao recurso do Application Insights. Você encontrará a cadeia de conexão no painel de visão geral do recurso recém-criado do Application Insights.

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

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

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

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

  5. No mesmo nível do projeto que o arquivo ApplicationInsights.config, crie uma pasta chamada ErrorHandler com um novo arquivo C# chamado AiHandleErrorAttribute.cs. O conteúdo do arquivo é semelhante ao seguinte:

    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 o Web.config já estiver atualizado, ignore esta etapa. Caso contrário, atualize o arquivo conforme mostrado a seguir:


    Expandir para exibir 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>

Até aqui, você configurou com sucesso o monitoramento de aplicativos do lado do servidor. Se você executar o aplicativo Web, a telemetria começará a aparecer no Application Insights.

ASP.NET Core

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

    Recomendamos sempre usar a versão estável mais recente. Encontre notas de versão completas para o SDK no repositório de código aberto do GitHub.

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

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

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

    Adicione builder.Services.AddApplicationInsightsTelemetry(); após o método WebApplication.CreateBuilder(), 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 o connection string, que pode ser feito de três maneiras:

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

      Defina o connection string em appsettings.json e verifique se o arquivo de configuração foi 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 o connection string na variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING 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 locais compatíveis com esse SDK.

      Observação

      Um connection string especificado no código supera a variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING, que vence outras opções.

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

      Forneça um connection string como parte do argumento ApplicationInsightsServiceOptions para AddApplicationInsightsTelemetry na classe program.cs.

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

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

No Microsoft.ApplicationInsights.AspNetCore versão 2.15.0 e posterior, chamar services.AddApplicationInsightsTelemetry() lê automaticamente a cadeia de conexão de Microsoft.Extensions.Configuration.IConfiguration do aplicativo. Não é necessário fornecer IConfiguration explicitamente.

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

Serviço de Trabalho

Nesta seção
Usar o SDK do Application Insights para Serviços de Trabalho

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

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

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

  2. Configure o connection string na variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING ou na configuração (appsettings.json).

    Captura de tela exibindo a visão geral do Application Insights e a cadeia de conexão.

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

Instruções específicas para cada tipo de aplicativo são descritas nas seções a seguir.

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. Configurar a cadeia de conexão.

    Captura de tela que mostra a visão geral do Application Insights e 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 em appsettings.json. Certifique-se de que appsettings.json foi copiado para a pasta raiz do aplicativo durante a publicação.

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

Como alternativa, especifique o connection string na variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING.

Normalmente, APPLICATIONINSIGHTS_CONNECTION_STRING especifica a cadeia de conexão para aplicativos implantados em aplicativos web como trabalhos da web.

Observação

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

Tarefas de segundo plano do ASP.NET Core 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 a lógica da tarefa de fundo reside.

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

Conforme 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 regular. Este pacote tem como alvo netstandard2.0, portanto, pode ser usado para 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();
            }
        }
    }

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

Implantar o Application Insights Agent para servidores locais

Nesta seção

O Application Insights Agent é um módulo do PowerShell publicado na Galeria do PowerShell. Ele substitui o Status Monitor. A telemetria é enviada para o portal Azure, no qual você pode monitor seu aplicativo.

Para obter uma lista completa de cenários de autoinstrumentação com suporte, consulte ambientes, idiomas e provedores de recursos com suporte.

Observação

Atualmente, o módulo dá suporte à instrumentação sem código de aplicativos Web ASP.NET e ASP.NET Core hospedados com o IIS (Servidor de Informações da Internet). Use um SDK para instrumentar aplicativos Java e Node.js.

Observação

O monitoramento do lado do cliente é habilitado por padrão para aplicativos ASP.NET Core. Se você quiser desabilitar o monitoramento do lado do cliente, defina uma variável de ambiente no servidor com as seguintes informações:

  • Nome:APPINSIGHTS_JAVASCRIPT_ENABLED
  • Valor: false

Como começar

Esta seção contém os comandos de início rápido que devem funcionar para a maioria dos ambientes. As instruções dependem de PowerShell Gallery para distribuir atualizações. Esses comandos são suportados pelo parâmetro -Proxy do PowerShell.

Para obter uma explicação sobre esses comandos, instruções de personalização e informações sobre solução de problemas, veja as instruções detalhadas.

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Observação

Para obter os pré-requisitos necessários, consulte o suporte do TLS (PowerShell Gallery Transport Layer Security).

  1. Instalar o módulo (executar como administrador):

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted
Install-Module -Name PowerShellGet -Force

  2. Instalar o Application Insights Agent (executar como administrador):

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
Install-Module -Name Az.ApplicationMonitor -AllowPrerelease -AcceptLicense

    Observação

    A opção AllowPrerelease no cmdlet Install-Module permite a instalação da versão beta.

    Para obter mais informações, confira Install-Module.

  3. Habilitar o monitoramento:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
Enable-ApplicationInsightsMonitoring -ConnectionString 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/'
Opção 2: baixar e instalar o agente do Application Insights manualmente (opção offline)

  1. Baixe manualmente a versão mais recente do módulo de PowerShell Gallery.

  2. Descompacte e instale o Application Insights Agent:

    $pathToNupkg = "C:\Users\t\Desktop\Az.ApplicationMonitor.0.3.0-alpha.nupkg"
$pathToZip = ([io.path]::ChangeExtension($pathToNupkg, "zip"))
$pathToNupkg | rename-item -newname $pathToZip
$pathInstalledModule = "$Env:ProgramFiles\WindowsPowerShell\Modules\Az.ApplicationMonitor"
Expand-Archive -LiteralPath $pathToZip -DestinationPath $pathInstalledModule

  3. Habilitar o monitoramento:

    Enable-ApplicationInsightsMonitoring -ConnectionString 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/'

Instruções detalhadas

Esta seção descreve como integrar à Galeria do PowerShell e baixar o módulo ApplicationMonitor. Estão incluídos os parâmetros mais comuns de que você precisa para começar. Também fornecemos instruções de download manual caso você não tenha acesso à Internet.

Executar o PowerShell como administrador com uma política de execução elevada

Importante

O PowerShell precisa de permissões de nível de administrador para fazer alterações em seu computador.

Política de execução

  • Descrição: por padrão, a execução de scripts do PowerShell está desabilitada. Recomendamos permitir scripts RemoteSigned apenas para o escopo atual.
  • Referência: Sobre políticas de execução e Set-ExecutionPolicy.
  • Comando: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process.
  • Parâmetro opcional:
    • -Force. Ignora o prompt de confirmação.

Erros de exemplo

Install-Module : The 'Install-Module' command was found in the module 'PowerShellGet', but the module could not be
loaded. For more information, run 'Import-Module PowerShellGet'.

Import-Module : File C:\Program Files\WindowsPowerShell\Modules\PackageManagement\1.3.1\PackageManagement.psm1 cannot
be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https://go.microsoft.com/fwlink/?LinkID=135170.
Pré-requisitos para PowerShell

Faça auditoria da instância do PowerShell executando o comando $PSVersionTable. Esse comando gera a seguinte saída:

Name                           Value
----                           -----
PSVersion                      5.1.17763.316
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
BuildVersion                   10.0.17763.316
CLRVersion                     4.0.30319.42000
WSManStackVersion              3.0
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1

Essas instruções foram escritas e testadas em um computador executando Windows 10 e as versões a seguir.

Estas etapas preparam o servidor para baixar módulos do PowerShell Gallery.

Observação

PowerShell Gallery tem suporte em Windows 10, Windows Server 2016 e PowerShell 6+. Para obter informações sobre versões anteriores, confira Instalar o PowerShellGet.

  1. Execute o PowerShell como administrador com uma política de execução elevada.

  2. Instale o provedor do pacote NuGet.

    • Descrição: você precisa que esse provedor interaja com repositórios baseados em NuGet, como PowerShell Gallery.
    • Referência: Install-PackageProvider.
    • Comando: Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201.
    • Parâmetros opcionais:
      • -Proxy. Especifica um servidor proxy para a solicitação.
      • -Force. Ignora o prompt de confirmação.

    Você receberá esse aviso se o NuGet não estiver configurado:

    NuGet provider is required to continue
PowerShellGet requires NuGet provider version '2.8.5.201' or newer to interact with NuGet-based repositories.
The NuGet provider must be available in 'C:\Program Files\PackageManagement\ProviderAssemblies' or
'C:\Users\t\AppData\Local\PackageManagement\ProviderAssemblies'. You can also install the NuGet provider by running
'Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force'. Do you want PowerShellGet to install and import
the NuGet provider now?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):

  3. Configure PowerShell Gallery como um repositório confiável.

    • Descrição: por padrão, PowerShell Gallery é um repositório não confiável.
    • Referência: Set-PSRepository.
    • Comando: Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted.
    • Parâmetro opcional:
      • -Proxy. Especifica um servidor proxy para a solicitação.

    Você receberá esse prompt se PowerShell Gallery não for confiável:

    Untrusted repository
You are installing the modules from an untrusted repository.
If you trust this repository, change its InstallationPolicy value
by running the Set-PSRepository cmdlet. Are you sure you want to
install the modules from 'PSGallery'?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"):

    Você pode confirmar essa alteração e auditar todos os PSRepositories executando o comando Get-PSRepository.

  4. Instale a versão mais recente do PowerShellGet.

    • Descrição: este módulo contém as ferramentas usadas para obter outros módulos de PowerShell Gallery. A versão 1.0.0.1 é fornecida com Windows 10 e Windows Server. A versão 1.6.0 ou superior é necessária. Para determinar qual versão está instalada, execute o comando Get-Command -Module PowerShellGet.
    • Referência: Instalar o PowerShellGet.
    • Comando: Install-Module -Name PowerShellGet.
    • Parâmetros opcionais:
      • -Proxy. Especifica um servidor proxy para a solicitação.
      • -Force. Ignora o aviso "já instalado" e instala a versão mais recente.

    Você receberá esse erro se não estiver usando a versão mais recente do PowerShellGet:

    Install-Module : A parameter cannot be found that matches parameter name 'AllowPrerelease'.
At line:1 char:20
Install-Module abc -AllowPrerelease
               ~~~~~~~~~~~~~~~~
CategoryInfo          : InvalidArgument: (:) [Install-Module], ParameterBindingException
FullyQualifiedErrorId : NamedParameterNotFound,Install-Module

  5. Reinicie o PowerShell. Não é possível carregar a versão nova na sessão atual. As novas sessões do PowerShell carregam a versão mais recente do PowerShellGet.

Estas etapas baixam o módulo Az.ApplicationMonitor do PowerShell Gallery.

  1. Verifique se todos os pré-requisitos para PowerShell Gallery são atendidos.
  2. Execute o PowerShell como administrador com uma política de execução elevada.
  3. Instale o módulo Az.ApplicationMonitor.
    • Referência: Install-Module.
    • Comando: Install-Module -Name Az.ApplicationMonitor.
    • Parâmetros opcionais:
      • -Proxy. Especifica um servidor proxy para a solicitação.
      • -AllowPrerelease. Permite a instalação de versões alfa e beta.
      • -AcceptLicense. Ignora o prompt "Aceitar licença"
      • -Force. Ignora o aviso "Repositório não confiável".
Opção 2: baixar e instalar o módulo manualmente (opção offline)

Se por algum motivo não for possível se conectar ao módulo do PowerShell, você poderá baixar e instalar manualmente o módulo Az.ApplicationMonitor.

Baixar manualmente o arquivo nupkg mais recente
  1. Clique em https://www.powershellgallery.com/packages/Az.ApplicationMonitor.
  2. Selecione a versão mais recente do arquivo na tabela de Histórico de versão.
  3. Em Opções de instalação, selecione Download manual.
Opção 2.1: instalar em um diretório de módulos do PowerShell

Instale o módulo do PowerShell baixado manualmente em um diretório do PowerShell para que ele possa ser descoberto por sessões do PowerShell. Para obter mais informações, confira Instalar um módulo do PowerShell.

Descompactar nupkg como um arquivo zip usando Expand-Archive (v1.0.1.0)

  • Descrição: a versão base do Microsoft.PowerShell.Archive (v 1.0.1.0) não pode descompactar arquivos nupkg. Renomeie o arquivo com a extensão .zip.

  • Referência: Expand-Archive.

  • Comando:

    $pathToNupkg = "C:\az.applicationmonitor.0.3.0-alpha.nupkg"
$pathToZip = ([io.path]::ChangeExtension($pathToNupkg, "zip"))
$pathToNupkg | rename-item -newname $pathToZip
$pathInstalledModule = "$Env:ProgramFiles\WindowsPowerShell\Modules\az.applicationmonitor"
Expand-Archive -LiteralPath $pathToZip -DestinationPath $pathInstalledModule

Descompactar nupkg usando Expand-Archive (v1.1.0.0)

  • Descrição: use uma versão atual do Expand-Archive para descompactar arquivos nupkg sem alterar a extensão.

  • Referência: Expand-Archive e Microsoft.PowerShell.Archive.

  • Comando:

    $pathToNupkg = "C:\az.applicationmonitor.0.2.1-alpha.nupkg"
$pathInstalledModule = "$Env:ProgramFiles\WindowsPowerShell\Modules\az.applicationmonitor"
Expand-Archive -LiteralPath $pathToNupkg -DestinationPath $pathInstalledModule
Opção 2.2: descompactar e importar nupkg manualmente

Instale o módulo do PowerShell baixado manualmente em um diretório do PowerShell para que ele possa ser descoberto por sessões do PowerShell. Para obter mais informações, confira Instalar um módulo do PowerShell.

Se você estiver instalando o módulo em qualquer outro diretório, importe o módulo manualmente usando Import-Module.

Importante

As DLLs (bibliotecas de link dinâmico) são instaladas por meio de caminhos relativos. Armazene o conteúdo do pacote em seu diretório de runtime pretendido e confirme se as permissões de acesso permitem leitura, mas não gravação.

  1. Altere a extensão para ".zip" e extraia o conteúdo do pacote no diretório de instalação pretendido.
  2. Localize o caminho do arquivo de Az.ApplicationMonitor.psd1.
  3. Execute o PowerShell como administrador com uma política de execução elevada.
  4. Carregue o módulo usando o comando Import-Module Az.ApplicationMonitor.psd1.
Rotear o tráfego por meio de um proxy

Ao monitorar um computador na sua intranet privada, você precisa rotear o tráfego HTTP por meio de um proxy.

Os comandos do PowerShell para baixar e instalar o Az.ApplicationMonitor do PowerShell Gallery dão suporte a um parâmetro -Proxy. Examine as instruções anteriores ao escrever seus scripts de instalação.

O SDK do Application Insights precisa enviar a telemetria do seu aplicativo para a Microsoft. Recomendamos que você defina as configurações de proxy para seu aplicativo no arquivo web.config. Para obter mais informações, confira Como obter passagem de proxy?.

Habilitar o monitoramento

Use o comando Enable-ApplicationInsightsMonitoring para habilitar o monitoramento.

Confira a referência da API para obter uma descrição detalhada de como usar esse cmdlet.

Referência de API

Importante

  • Os cmdlets a seguir exigem uma sessão do PowerShell com permissões de administrador e uma política de execução elevada. Para obter mais informações, consulte Executar o PowerShell como administrador com uma política de execução elevada.
  • Os cmdlets a seguir exigem que você examine e aceite nossa licença e política de privacidade.
  • O mecanismo de instrumentação adiciona mais sobrecarga e está desativado por padrão.

Esta seção descreve os seguintes cmdlets, que são membros do Az.ApplicationMonitor PowerShell module:

Observação

Expanda qualquer uma das seções abaixo para obter mais informações, incluindo exemplos, parâmetros e saída.

Enable-InstrumentationEngine

Habilita o mecanismo de instrumentação definindo algumas chaves do Registro. Reinicie o IIS para que as alterações entrem em vigor.

O mecanismo de instrumentação pode complementar os dados coletados pelos SDKs (Kits de Desenvolvimento de Software) do .NET. Ele coleta eventos e mensagens que descrevem a execução de um processo gerenciado. Esses eventos e mensagens incluem códigos de resultados de dependências, verbos HTTP e textos de comando SQL.

Habilite o mecanismo de instrumentação se:

  • Você já habilitou o monitoramento com o cmdlet Enable, mas não habilitou o mecanismo de instrumentação.
  • Você instrumentou manualmente seu aplicativo com os SDKs do .NET e deseja coletar telemetria extra.
Exemplos
Enable-InstrumentationEngine
Parâmetros
Parâmetro Descrição
-AceitarLicença Opcional. Use essa opção para aceitar a licença e a política de privacidade em instalações sem periféricos.
-Prolixo Parâmetro comum. Use essa opção para gerar logs detalhados.
Saída

Exemplo de saída da bem-sucedida habilitação do mecanismo de instrumentação.

Configuring IIS Environment for instrumentation engine...
Configuring registry for instrumentation engine...
Enable-ApplicationInsightsMonitoring

Habilita o monitoramento de anexação sem código de aplicativos IIS em um computador de destino.

Esse cmdlet modifica o applicationHost.config do IIS e define algumas chaves de registro. Ele cria um arquivo applicationinsights.ikey.config, que define a chave de instrumentação usada por cada aplicativo. O IIS carrega o RedfieldModule na inicialização, que injeta o SDK do Application Insights nos aplicativos à medida que os aplicativos são iniciados. Reinicie o IIS para que as suas alterações entrem em vigor.

Depois de habilitar o monitoramento, recomendamos que você use o Live Metrics para verificar rapidamente se seu aplicativo está enviando telemetria para nós.

Exemplos
Exemplo com uma única cadeia de conexão

Neste exemplo, todos os aplicativos no computador atual são fornecidos com uma única string de conexão.

Enable-ApplicationInsightsMonitoring -ConnectionString 'InstrumentationKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/'
Exemplo com uma única chave de instrumentação

Neste exemplo, todos os aplicativos no computador atual são fornecidos com uma única chave de instrumentação.

Enable-ApplicationInsightsMonitoring -InstrumentationKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Exemplo com um mapa de chaves de instrumentação

Neste exemplo:

  • MachineFilter corresponde ao computador atual usando o caractere curinga '.*'.
  • AppFilter='WebAppExclude' fornece uma chave de instrumentação null. O aplicativo especificado não é instrumentado.
  • AppFilter='WebAppOne' atribui ao aplicativo especificado uma chave de instrumentação exclusiva.
  • AppFilter='WebAppTwo' atribui ao aplicativo especificado uma chave de instrumentação exclusiva.
  • AppFilter usa o curinga '.*' para corresponder a todos os aplicativos Web que ainda não correspondem e atribui uma chave de instrumentação padrão.
  • Os espaços são adicionados para facilitar a leitura.
Enable-ApplicationInsightsMonitoring -InstrumentationKeyMap `
    ` @(@{MachineFilter='.*';AppFilter='WebAppExclude'},
        ` @{MachineFilter='.*';AppFilter='WebAppOne';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1'}},
        ` @{MachineFilter='.*';AppFilter='WebAppTwo';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2'}},
        ` @{MachineFilter='.*';AppFilter='.*';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault'}})
  • MachineFilter é uma expressão regex obrigatória em C# do nome do computador ou da máquina virtual (VM).
    • '.*' corresponde a todos
    • 'ComputerName' corresponde apenas a computadores com o nome exato especificado.
  • AppFilter é um regex do C# necessário do Nome do Site do IIS. Você pode obter uma lista de sites em seu servidor executando o comando get-iissite.
    • '.*' corresponde a todos
    • 'SiteName' corresponde apenas ao Site do IIS com o nome exato especificado.
  • InstrumentationKey é necessário para habilitar o monitoramento de aplicativos que correspondem aos dois filtros anteriores.
    • Deixe esse valor como null se você quiser definir regras para excluir o monitoramento.
Parâmetros
Parâmetro Descrição
-EnableInstrumentationEngine Opcional. Use essa opção para habilitar o mecanismo de instrumentação para coletar eventos e mensagens sobre o que está acontecendo durante a execução de um processo gerenciado. Esses eventos e mensagens incluem códigos de resultados de dependências, verbos HTTP e textos de comando SQL.

O mecanismo de instrumentação aumenta a sobrecarga e está desativado por padrão.
-AceitarLicença Opcional. Use essa opção para aceitar a licença e a política de privacidade em instalações sem periféricos.
-IgnoreSharedConfig Quando você tiver um cluster de servidores Web, talvez esteja usando uma configuração compartilhada. O HttpModule não pode ser injetado nessa configuração compartilhada. Esse script falha com a mensagem de que etapas extras de instalação são necessárias. Use essa opção para ignorar essa verificação e continuar instalando os pré-requisitos.

Para obter mais informações, consulte Conflito conhecido com a configuração compartilhada do IIS
-Prolixo Parâmetro comum. Use essa opção para exibir logs detalhados.
-WhatIf Parâmetro comum. Use essa opção para testar e validar os parâmetros de entrada sem realmente habilitar o monitoramento.
Saída
Exemplo de saída de uma habilitação bem-sucedida
Initiating Disable Process
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-52z'
in :1,237
No element in the source document matches '/configuration/location[@path='']/system.webServer/modules/add[@name='ManagedHttpModuleHelper']'
Not executing RemoveAll (transform line 1, 546)
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'disable'
GAC Module will not be removed, since this operation might cause IIS instabilities
Configuring IIS Environment for codeless attach...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring IIS Environment for instrumentation engine...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring registry for instrumentation engine...
Successfully disabled Application Insights Agent
Installing GAC module 'C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\0.2.0\content\Runtime\Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.dll'
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
Found GAC module Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.ManagedHttpModuleHelper, Microsoft.AppInsights.IIS.ManagedHttpModuleHelper, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-52z_1'
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'enable'
Configuring IIS Environment for codeless attach...
Configuring IIS Environment for instrumentation engine...
Configuring registry for instrumentation engine...
Updating app pool permissions...
Successfully enabled Application Insights Agent
Disable-InstrumentationEngine

Desabilita o mecanismo de instrumentação removendo algumas chaves do Registro. Reinicie o IIS para que as alterações entrem em vigor.

Exemplos
Disable-InstrumentationEngine
Parâmetros
Parâmetro Descrição
-Prolixo Parâmetro comum. Use essa opção para gerar logs detalhados.
Saída
Exemplo de saída de uma desabilitação bem-sucedida do mecanismo de instrumentação
Configuring IIS Environment for instrumentation engine...
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]'
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]'
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]'
Configuring registry for instrumentation engine...
Disable-ApplicationInsightsMonitoring

Desabilita o monitoramento no computador de destino. Esse cmdlet remove edições no applicationHost.config do IIS e remove chaves do Registro.

Exemplos
Disable-ApplicationInsightsMonitoring
Parâmetros
Parâmetro Descrição
-Prolixo Parâmetro comum. Use essa opção para exibir logs detalhados.
Saída
Exemplo de saída de uma desabilitação bem-sucedida do monitoramento
Initiating Disable Process
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-00z'
in :1,237
No element in the source document matches '/configuration/location[@path='']/system.webServer/modules/add[@name='ManagedHttpModuleHelper']'
Not executing RemoveAll (transform line 1, 546)
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'disable'
GAC Module will not be removed, since this operation might cause IIS instabilities
Configuring IIS Environment for codeless attach...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring IIS Environment for instrumentation engine...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring registry for instrumentation engine...
Successfully disabled Application Insights Agent
Get-ApplicationInsightsMonitoringConfig

Obtém o arquivo de configuração e imprime os valores no console.

Exemplos
Get-ApplicationInsightsMonitoringConfig
Parâmetros

Nenhum parâmetro é necessário.

Saída
Exemplo de saída da leitura do arquivo de configuração
RedfieldConfiguration:
Filters:
0)InstrumentationKey: AppFilter: WebAppExclude MachineFilter: .*
1)InstrumentationKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2 AppFilter: WebAppTwo MachineFilter: .*
2)InstrumentationKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault AppFilter: .* MachineFilter: .*
Get-ApplicationInsightsMonitoringStatus

Esse cmdlet fornece informações para solucionar problemas sobre o Application Insights Agent. Use este cmdlet para investigar o status de monitoramento, a versão do módulo do PowerShell e para inspecionar o processo em execução. Esse cmdlet relata informações de versão e informações sobre os principais arquivos necessários para o monitoramento.

Exemplos
Exemplo: status do aplicativo

Execute o comando Get-ApplicationInsightsMonitoringStatus para exibir o status do monitoramento de sites.

Get-ApplicationInsightsMonitoringStatus

IIS Websites:

SiteName               : Default Web Site
ApplicationPoolName    : DefaultAppPool
SiteId                 : 1
SiteState              : Stopped

SiteName               : DemoWebApp111
ApplicationPoolName    : DemoWebApp111
SiteId                 : 2
SiteState              : Started
ProcessId              : not found

SiteName               : DemoWebApp222
ApplicationPoolName    : DemoWebApp222
SiteId                 : 3
SiteState              : Started
ProcessId              : 2024
Instrumented           : true
InstrumentationKey     : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx123

SiteName               : DemoWebApp333
ApplicationPoolName    : DemoWebApp333
SiteId                 : 4
SiteState              : Started
ProcessId              : 5184
AppAlreadyInstrumented : true

Neste exemplo:

  • Identificador da máquina é uma ID anônima usada para identificar exclusivamente o servidor. Se você criar uma solicitação de suporte, precisaremos dessa ID para encontrar os registros do seu servidor.

  • Site padrão está Parado no IIS

  • O IIS mostra DemoWebApp111 como iniciado, mas o aplicativo não recebe nenhuma solicitação. O relatório não mostra nenhum processo em execução (ProcessId: não encontrado).

  • DemoWebApp222 está sendo executado e está sendo monitorado (instrumentado: true). Com base na configuração do usuário, a chave de instrumentação xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx123 foi assiociada este site.

  • O DemoWebApp333 é instrumentado manualmente usando o SDK do Application Insights. O Application Insights Agent detecta o SDK e não monitora este site.

  • A presença de AppAlreadyInstrumented : true significa que o agente do Application Insights identificou uma dll conflitante carregada no aplicativo Web, presumiu que o aplicativo Web é instrumentado manualmente e que o agente fez o backup e não está instrumentando esse processo.

  • Instrumented : true indica que o agente do Application Insights instrumentou com êxito o aplicativo Web em execução no processo w3wp.exe especificado.

Exemplo: informações do módulo do PowerShell

Execute o comando Get-ApplicationInsightsMonitoringStatus -PowerShellModule para exibir informações sobre o módulo atual:

Get-ApplicationInsightsMonitoringStatus -PowerShellModule

PowerShell Module version:
0.4.0-alpha

Application Insights SDK version:
2.9.0.3872

Executing PowerShell Module Assembly:
Microsoft.ApplicationInsights.Redfield.Configurator.PowerShell, Version=2.8.14.11432, Culture=neutral, PublicKeyToken=31bf3856ad364e35

PowerShell Module Directory:
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\0.2.2\content\PowerShell

Runtime Paths:
ParentDirectory (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content

ConfigurationPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\applicationInsights.ikey.config

ManagedHttpModuleHelperPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.dll

RedfieldIISModulePath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll

InstrumentationEngine86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\MicrosoftInstrumentationEngine_x86.dll

InstrumentationEngine64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\MicrosoftInstrumentationEngine_x64.dll

InstrumentationEngineExtensionHost86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\Microsoft.ApplicationInsights.ExtensionsHost_x86.dll

InstrumentationEngineExtensionHost64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.ExtensionsHost_x64.dll

InstrumentationEngineExtensionConfig86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\Microsoft.InstrumentationEngine.Extensions.config

InstrumentationEngineExtensionConfig64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.InstrumentationEngine.Extensions.config

ApplicationInsightsSdkPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.dll
Exemplo: status do runtime

Você pode inspecionar os processos no computador instrumentado para determinar se todas as DLLs estão carregadas. Se o monitoramento estiver funcionando, pelo menos 12 DLLs deverão estar carregadas.

Execute o comando Get-ApplicationInsightsMonitoringStatus -InspectProcess:

Get-ApplicationInsightsMonitoringStatus -InspectProcess

iisreset.exe /status
Status for IIS Admin Service ( IISADMIN ) : Running
Status for Windows Process Activation Service ( WAS ) : Running
Status for Net.Msmq Listener Adapter ( NetMsmqActivator ) : Running
Status for Net.Pipe Listener Adapter ( NetPipeActivator ) : Running
Status for Net.Tcp Listener Adapter ( NetTcpActivator ) : Running
Status for World Wide Web Publishing Service ( W3SVC ) : Running

handle64.exe -accepteula -p w3wp
BF0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.ServerTelemetryChannel.dll
C58: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.AzureAppServices.dll
C68: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.DependencyCollector.dll
C78: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.WindowsServer.dll
C98: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.Web.dll
CBC: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.PerfCounterCollector.dll
DB0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.Agent.Intercept.dll
B98: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll
BB4: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.Contracts.dll
BCC: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.Redfield.Lightup.dll
BE0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.dll

listdlls64.exe -accepteula w3wp
0x0000000019ac0000  0x127000  C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\MicrosoftInstrumentationEngine_x64.dll
0x00000000198b0000  0x4f000   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.ExtensionsHost_x64.dll
0x000000000c460000  0xb2000   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.Extensions.Base_x64.dll
0x000000000ad60000  0x108000  C:\Windows\TEMP\2.4.0.0.Microsoft.ApplicationInsights.Extensions.Intercept_x64.dll
Parâmetros

Por padrão, esse cmdlet relata o status de monitoramento dos aplicativos Web. Use esta opção para examinar se o aplicativo foi instrumentado de forma bem-sucedida. Você também pode examinar qual chave de instrumentação foi associada ao seu site.

Parâmetro Descrição
-PowerShellModule Opcional. Use essa opção para relatar os números de versão e os caminhos de DLLs necessários para o monitoramento. Use esta opção se você precisar identificar a versão de qualquer DLL, incluindo do SDK do Application Insights.
-InspectProcess Opcional. Use essa opção para relatar se o IIS está em execução. Ele baixa ferramentas externas para determinar se as DLLs necessárias são carregadas no tempo de execução do IIS. Se esse processo falhar por algum motivo, você poderá executar estes comandos manualmente:

* iisreset.exe /status
* \[handle64.exe\](/sysinternals/downloads/handle) -p w3wp \| findstr /I "InstrumentationEngine AI. ApplicationInsights"
* \[listdlls64.exe\](/sysinternals/downloads/listdlls) w3wp \| findstr /I "InstrumentationEngine AI ApplicationInsights"
-Força Opcional. Usado somente com InspectProcess. Use essa opção para ignorar a solicitação do usuário que aparece antes do download de mais ferramentas.
Set-ApplicationInsightsMonitoringConfig

Define o arquivo de configuração sem fazer uma reinstalação completa. Reinicie o IIS para que as suas alterações entrem em vigor.

Importante

Este cmdlet requer uma sessão do PowerShell com permissões de administrador.

Exemplos
Exemplo com uma única chave de instrumentação

Neste exemplo, todos os aplicativos no computador atual são fornecidos com uma única chave de instrumentação.

Enable-ApplicationInsightsMonitoring -InstrumentationKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Exemplo com um mapa de chaves de instrumentação

Neste exemplo:

  • MachineFilter corresponde ao computador atual usando o caractere curinga '.*'.
  • AppFilter='WebAppExclude' fornece uma chave de instrumentação null. O aplicativo especificado não é instrumentado.
  • AppFilter='WebAppOne' atribui ao aplicativo especificado uma chave de instrumentação exclusiva.
  • AppFilter='WebAppTwo' atribui ao aplicativo especificado uma chave de instrumentação exclusiva.
  • AppFilter usa o curinga '.*' para corresponder a aplicativos Web que ainda não correspondem e atribui uma chave de instrumentação padrão.
  • Os espaços são adicionados para facilitar a leitura.
Enable-ApplicationInsightsMonitoring -InstrumentationKeyMap `
    ` @(@{MachineFilter='.*';AppFilter='WebAppExclude'},
      ` @{MachineFilter='.*';AppFilter='WebAppOne';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1'}},
      ` @{MachineFilter='.*';AppFilter='WebAppTwo';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2'}},
      ` @{MachineFilter='.*';AppFilter='.*';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault'}})
Parâmetros
Parâmetro Descrição
-InstrumentationKey Obrigatório Use esse parâmetro para fornecer uma chave de instrumentação única para ser usada por todos os aplicativos no computador de destino.
-InstrumentationKeyMap Obrigatório Use esse parâmetro para fornecer várias chaves de instrumentação e um mapeamento das chaves de instrumentação usadas por cada aplicativo.

Você pode criar um único script de instalação para vários computadores definindo MachineFilter.

Importante

Os aplicativos correspondem às regras na ordem em que você as fornece. Especifique as regras mais específicas primeiro e as regras mais genéricas por último.

Importante

InstrumentationKeyMap é um recurso de roteamento avançado que mapeia aplicativos do IIS (Serviços de Informações da Internet) no mesmo computador para recursos do Application Insights. O recurso se aplica aos aplicativos ASP.NET e ASP.NET Core hospedados pelo IIS que o Application Insights Agent estrutura automaticamente.

Como funciona a combinação

  • O mapa define uma lista ordenada de regras nomeadas filters. A primeira regra correspondente entra em vigor. Coloque as regras específicas em primeiro lugar e finalize com uma regra abrangente (catch-all).
  • Cada regra pode atribuir um recurso diferente do Application Insights a aplicativos correspondentes. Prefira cadeias de conexão em cenários com suporte porque as chaves de instrumentação são herdadas.

Filtros disponíveis

  • MachineFilter ou machineFilter: expressão regular C# que corresponde ao nome do computador ou da VM (máquina virtual). .* corresponde a todos os nomes.
  • AppFilter ou appFilter: expressão regular C# que corresponde ao nome do site do IIS (HostingEnvironment.SiteName). Esse filtro é necessário quando VirtualPathFilter ou virtualPathFilter não é fornecido.
  • VirtualPathFilter ou virtualPathFilter: expressão regular C# que corresponde ao caminho virtual do IIS (HostingEnvironment.ApplicationVirtualPath). Use esse filtro para direcionar um único aplicativo em um site.

Mapeamento de terminologia

  • Os cmdlets do PowerShell usam MachineFilter, AppFiltere VirtualPathFilter.
  • A extensão JSON das Máquinas Virtuais do Azure e dos Conjuntos de Dimensionamento de Máquinas Virtuais usa machineFilter, appFilter, virtualPathFilter e define o recurso com instrumentationSettings.

Dica

Inclua uma regra final que corresponda a todos os aplicativos, como .*, e aplique um recurso padrão para tornar o comportamento explícito.

A forma do mapa deste cmdlet

  • Forneça -InstrumentationKeyMap como uma matriz de hashtables do PowerShell.
  • Para este cmdlet, defina o recurso de destino por regra com InstrumentationSettings=@{ InstrumentationKey = '<ikey>' }.
  • Se você quiser um único recurso para todos os aplicativos no computador, use -ConnectionString ou -InstrumentationKey em vez disso.
Start-ApplicationInsightsMonitoringTrace

Recolhe eventos do Rastreamento de Eventos para Windows (ETW) que o runtime de anexação sem código emite. Use esse cmdlet como uma alternativa mais simples para executar o PerfView.

Os eventos são impressos no console em tempo real e também gravados em um .etl arquivo. Você pode abrir o .etl arquivo com o PerfView para uma análise mais profunda.

Esse cmdlet é executado até atingir o tempo limite, o padrão é 5 minutos ou até que você o interrompa manualmente com Ctrl + C.

Exemplos
Como coletar eventos

Use esse fluxo quando precisar investigar por que um aplicativo IIS não está sendo instrumentado.

O runtime de anexação sem código gera eventos ETW quando o IIS é iniciado e quando seu aplicativo é iniciado.

  1. Em um prompt de comando administrativo, execute iisreset /stop para interromper o IIS e todos os aplicativos Web.
  2. Comece a rastrear executando este cmdlet.
  3. Em um prompt de comando administrativo, execute iisreset /start para iniciar o IIS.
  4. Acione a inicialização navegando até o seu aplicativo.
  5. Depois que o aplicativo terminar de carregar, pressione Ctrl + C para parar ou permita o tempo limite para encerrar a sessão.
Quais eventos coletar

Você pode escolher quais fontes de evento incluir:

  1. -CollectSdkEvents coleta eventos do SDK do Application Insights.
  2. -CollectRedfieldEvents coleta eventos do Application Insights Agent e do runtime do Redfield, o que é útil para o diagnóstico do IIS e da inicialização de aplicativos.
  3. Colete ambos os conjuntos especificando ambas as opções.
  4. Se você não especificar uma opção, ambos os conjuntos serão coletados por padrão.
Parâmetros
Parâmetro Descrição
-MaxDurationEmMinutos Opcional. Configura a duração da coleta antes do tempo limite. O padrão é 5 minutos.
-LogDirectory Opcional. Diretório em que o .etl arquivo deve ser gravado. Por padrão, o arquivo é criado no diretório do PowerShell do módulo. O caminho completo é mostrado quando a sessão é iniciada.
-CollectSdkEvents Opcional. Inclua eventos do SDK do Application Insights.
-CollectRedfieldEvents Opcional. Inclua eventos do Application Insights Agent e do tempo de execução do Redfield.
-Prolixo Parâmetro comum. Gera logs detalhados.

Saída

Exemplo de logs de inicialização do aplicativo
Start-ApplicationInsightsMonitoringTrace -CollectRedfieldEvents
Starting...
Log File: C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\logs\20190627_144217_ApplicationInsights_ETW_Trace.etl
Tracing enabled, waiting for events.
Tracing will timeout in 5 minutes. Press CTRL+C to cancel.
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Resolved variables to: MicrosoftAppInsights_ManagedHttpModulePath='C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll', MicrosoftAppInsights_ManagedHttpModuleType='Microsoft.ApplicationInsights.RedfieldIISModule.RedfieldIISModule'
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Resolved variables to: MicrosoftDiagnosticServices_ManagedHttpModulePath2='', MicrosoftDiagnosticServices_ManagedHttpModuleType2=''
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Environment variable 'MicrosoftDiagnosticServices_ManagedHttpModulePath2' or 'MicrosoftDiagnosticServices_ManagedHttpModuleType2' is null, skipping managed dll loading

Implantar o Application Insights Agent para VMs (máquinas virtuais) e conjuntos de dimensionamento de máquinas virtuais

Nesta seção

Habilitar o monitoramento do Azure MonitorApplication Insights por meio de autoinstrumentação para aplicativos ASP.NET e ASP.NET Core hospedados no Internet Information Server (IIS) em Máquinas Virtuais do Azure e Conjuntos de Dimensionamento de Máquinas Virtuais do Azure.

Implantar o Agente do Application Insights com uma extensão de máquina virtual. O agente coleta automaticamente os mesmos sinais de dependência que o SDK. Usar o PowerShell para automatizar implantações em larga escala.

Observação

Para obter uma lista completa dos cenários de autoinstrumentação suportados, confira Ambientes, linguagens e provedores de recursos suportados.

Habilitar o monitoramento de máquinas virtuais

Você pode usar o portal do Azure ou PowerShell para habilitar o monitoramento de VMs.

Opção 1: portal Azure

  1. No portal do Azure, vá para o recurso do Application Insights. Copie a cadeia de conexão para a área de transferência.

    Captura de tela que mostra a cadeia de conexão.

  2. Acesse a sua máquina virtual. Na seção Configurações, no menu à esquerda, selecione Extensões + aplicativos>Adicionar.

    Captura de tela que mostra o painel Extensões + aplicativos com o botão Adicionar.

  3. Selecione Application Insights Agent>Avançar.

    Captura de tela que mostra o painel Instalar uma Extensão com o botão Avançar.

  4. Cole a cadeia de conexão copiada na etapa 1 e selecione Examinar + criar.

    Captura de tela que mostra a guia Criar com o botão Examinar + criar.

Opção 2: PowerShell

Observação

Novo no PowerShell? Confira o Guia de introdução.

Instalar ou atualizar o Application Insights Agent como uma extensão para máquinas virtuais do Azure:

# define variables to match your environment before running
$ResourceGroup = "<myVmResourceGroup>"
$VMName = "<myVmName>"
$Location = "<myVmLocation>"
$ConnectionString = "<myAppInsightsResourceConnectionString>"

$publicCfgJsonString = @"
{
    "redfieldConfiguration": {
        "instrumentationKeyMap": {
        "filters": [
            {
            "appFilter": ".*",
            "machineFilter": ".*",
            "virtualPathFilter": ".*",
            "instrumentationSettings" : {
                "connectionString": "$ConnectionString"
            }
            }
        ]
        }
    }
    }
"@

$privateCfgJsonString = '{}'
    
Set-AzVMExtension -ResourceGroupName $ResourceGroup -VMName $VMName -Location $Location -Name "ApplicationMonitoringWindows" -Publisher "Microsoft.Azure.Diagnostics" -Type "ApplicationMonitoringWindows" -Version "2.8" -SettingString $publicCfgJsonString -ProtectedSettingString $privateCfgJsonString

Observação

Para implantações em escala mais complicadas, você pode usar um loop do PowerShell para instalar ou atualizar a extensão do Application Insights Agent em várias VMs.

Consultar o status da extensão do Application Insights Agent para máquinas virtuais do Azure:

Get-AzVMExtension -ResourceGroupName "<myVmResourceGroup>" -VMName "<myVmName>" -Name ApplicationMonitoringWindows -Status

Obtenha uma lista de extensões instaladas para máquinas virtuais Azure:

Get-AzResource -ResourceId "/subscriptions/<mySubscriptionId>/resourceGroups/<myVmResourceGroup>/providers/Microsoft.Compute/virtualMachines/<myVmName>/extensions"

Desinstalar a extensão do Application Insights Agent de máquinas virtuais do Azure:

Remove-AzVMExtension -ResourceGroupName "<myVmResourceGroup>" -VMName "<myVmName>" -Name "ApplicationMonitoring"

Observação

Verifique a instalação selecionando Live Metrics Stream no Recurso do Application Insights associado à cadeia de conexão usada para implantar a extensão do Application Insights Agent. Se você estiver enviando dados de várias máquinas virtuais, selecione as máquinas virtuais do Azure de destino em Nome do Servidor. Pode levar até um minuto para que os dados comecem a fluir.

instrumentationKeyMap (configurações de extensão)

Importante

InstrumentationKeyMap é um recurso de roteamento avançado que mapeia aplicativos do IIS (Serviços de Informações da Internet) no mesmo computador para recursos do Application Insights. O recurso se aplica aos aplicativos ASP.NET e ASP.NET Core hospedados pelo IIS que o Application Insights Agent estrutura automaticamente.

Como funciona a combinação

  • O mapa define uma lista ordenada de regras nomeadas filters. A primeira regra correspondente entra em vigor. Coloque as regras específicas em primeiro lugar e finalize com uma regra abrangente (catch-all).
  • Cada regra pode atribuir um recurso diferente do Application Insights a aplicativos correspondentes. Prefira cadeias de conexão em cenários com suporte porque as chaves de instrumentação são herdadas.

Filtros disponíveis

  • MachineFilter ou machineFilter: expressão regular C# que corresponde ao nome do computador ou da VM (máquina virtual). .* corresponde a todos os nomes.
  • AppFilter ou appFilter: expressão regular C# que corresponde ao nome do site do IIS (HostingEnvironment.SiteName). Esse filtro é necessário quando VirtualPathFilter ou virtualPathFilter não é fornecido.
  • VirtualPathFilter ou virtualPathFilter: expressão regular C# que corresponde ao caminho virtual do IIS (HostingEnvironment.ApplicationVirtualPath). Use esse filtro para direcionar um único aplicativo em um site.

Mapeamento de terminologia

  • Os cmdlets do PowerShell usam MachineFilter, AppFiltere VirtualPathFilter.
  • A extensão JSON das Máquinas Virtuais do Azure e dos Conjuntos de Dimensionamento de Máquinas Virtuais usa machineFilter, appFilter, virtualPathFilter e define o recurso com instrumentationSettings.

Dica

Inclua uma regra final que corresponda a todos os aplicativos, como .*, e aplique um recurso padrão para tornar o comportamento explícito.

Para onde vai a extensão VM e Conjuntos de Dimensionamento de Máquinas Virtuais

Coloque o mapa em redfieldConfiguration.instrumentationKeyMap.filters nas configurações públicas da extensão (-SettingString para VMs, -Setting para Conjuntos de Dimensionamento de Máquinas Virtuais). Os nomes das propriedades estão em minúsculas concatenadas. Defina o recurso de destino por regra com instrumentationSettings.connectionString.

{
  "redfieldConfiguration": {
    "instrumentationKeyMap": {
      "filters": [
        {
          "machineFilter": ".*",
          "appFilter": ".*",
          "instrumentationSettings": {
            "connectionString": "<your-APPLICATIONINSIGHTS_CONNECTION_STRING>"
          }
        }
      ]
    }
  }
}

Ativar monitoramento para conjuntos de escalonamento de máquinas virtuais

Você pode usar o portal Azure ou o PowerShell para habilitar o monitoramento para conjuntos de dimensionamento de máquinas virtuais.

Opção 1: portal Azure

Siga as etapas anteriores para VMs, mas navegue até os conjuntos de dimensionamento de máquinas virtuais em vez da VM.

Opção 2: PowerShell

Instalar ou atualizar o Application Insights Agent como uma extensão para conjuntos de dimensionamento de máquinas virtuais:

# Set resource group, vmss name, and connection string to reflect your environment
$ResourceGroup = "<myVmResourceGroup>"
$VMSSName = "<myVmName>"
$ConnectionString = "<myAppInsightsResourceConnectionString>"
$publicCfgHashtable =
@{
  "redfieldConfiguration"= @{
    "instrumentationKeyMap"= @{
      "filters"= @(
        @{
          "appFilter"= ".*";
          "machineFilter"= ".*";
          "virtualPathFilter"= ".*";
          "instrumentationSettings" = @{
            "connectionString"= "$ConnectionString"
          }
        }
      )
    }
  }
};
$privateCfgHashtable = @{};
$vmss = Get-AzVmss -ResourceGroupName $ResourceGroup -VMScaleSetName $VMSSName
Add-AzVmssExtension -VirtualMachineScaleSet $vmss -Name "ApplicationMonitoringWindows" -Publisher "Microsoft.Azure.Diagnostics" -Type "ApplicationMonitoringWindows" -TypeHandlerVersion "2.8" -Setting $publicCfgHashtable -ProtectedSetting $privateCfgHashtable
Update-AzVmss -ResourceGroupName $vmss.ResourceGroupName -Name $vmss
# Note: Depending on your update policy, you might need to run Update-AzVmssInstance for each instance

Obter uma lista de extensões instaladas para conjuntos de dimensionamento de máquinas virtuais:

Get-AzResource -ResourceId "/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.Compute/virtualMachineScaleSets/<myVmssName>/extensions"

Desinstale a extensão de monitoramento de aplicativos dos conjuntos de dimensionamento de máquinas virtuais:

# set resource group and vmss name to reflect your environment
$vmss = Get-AzVmss -ResourceGroupName "<myResourceGroup>" -VMScaleSetName "<myVmssName>"
Remove-AzVmssExtension -VirtualMachineScaleSet $vmss -Name "ApplicationMonitoringWindows"
Update-AzVmss -ResourceGroupName $vmss.ResourceGroupName -Name $vmss.Name -VirtualMachineScaleSet $vmss
# Note: Depending on your update policy, you might need to run Update-AzVmssInstance for each instance

Solução de problemas

Para obter etapas dedicadas de solução de problemas, consulte Problemas ao implantar a extensão do Agente de Monitoramento do Application Insights para VMs e conjuntos de dimensionamento de máquinas virtuais.

Verificar se o Application Insights recebe telemetria

ASP.NET e ASP.NET Core

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

Serviço de Trabalho

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 delimitadas dentro da chamada StartOperation de TelemetryClient, que é usada para criar uma operação. Neste exemplo, RequestTelemetry é denominado "operação".

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

Essa operação RequestTelemetry personalizada pode ser considerada como o equivalente a uma solicitação Web de entrada em um 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 pertencente logicamente à mesma operação.

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

Coletando dados de telemetria

Nesta seção

Métricas em tempo real

Métricas dinâmicas podem ser usadas para verificar rapidamente se o monitoramento de aplicativo 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 dinâmicas 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, rastreamentos etc.

Observação

As métricas dinâmicas são habilitadas por padrão quando você a integra usando as instruções recomendadas para aplicativos .NET.

Introdução

  1. Habilite as métricas dinâmicas com os SDKs do Application Insights seguindo as diretrizes específicas do idioma:

    • ASP.NET: habilitado por padrão, mas também pode ser habilitado manualmente usando código.
    • ASP.NET Core: habilitado por padrão, mas também pode ser habilitado manualmente usando código.
    • .NET/.NET Core Console/Worker: habilitado por padrão.

  2. Abra o recurso Application Insights para o seu aplicativo no portal do Azure. Selecione as Métricas dinâmicas, que estão listadas em Investigar no menu à esquerda.

  3. Proteja o canal de controle habilitando a autenticação do Microsoft Entra se você usar filtros personalizados.

Recursos com suporte
Linguagem Métricas básicas Métricas de desempenho Filtragem personalizada Exemplo de telemetria Divisão de CPU por processo
.NET Framework Com suporte (LTS) Com suporte (LTS) Com suporte (LTS) Com suporte (LTS) Com suporte (LTS)
.NET Core (destino = .NET Framework) Com suporte (LTS) Com suporte (LTS) Com suporte (LTS) Com suporte (LTS) Com suporte (LTS)
.NET Core (target=.NET Core) Com suporte (LTS) Supported* Com suporte (LTS) Com suporte (LTS) Sem suporte

As métricas básicas incluem solicitação, dependência e taxa de exceção. As métricas de desempenho (contadores de desempenho) incluem memória e CPU. O exemplo de telemetria mostra um fluxo de informações detalhadas para solicitações e dependências com falha, exceções, eventos e rastreamentos.

O suporte ao PerfCounters varia ligeiramente entre versões do .NET Core que não têm como destino o .NET Framework:

  • Há suporte para métricas perfCounters ao executar em Azure App Service para Windows (ASP.NET Core SDK versão 2.4.1 ou superior).
  • PerfCounters têm suporte quando o aplicativo está sendo executado em qualquer computador do Windows para aplicativos direcionados ao .NET Core LTS ou superior.
  • Há suporte para PerfCounters quando o aplicativo é executado em qualquer lugar (como Linux, Windows, Serviço de Aplicativo para Linux ou contêineres) nas últimas versões, mas somente para aplicativos direcionados ao .NET Core LTS ou posterior.

Habilitar métricas dinâmicas 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 exemplo de código de aplicativo de console a seguir mostra como configurar as métricas dinâmicas:

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 exemplo de código de aplicativo de console a seguir mostra como configurar as métricas dinâmicas:

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 acima é para um aplicativo de console, mas o mesmo código pode ser usado em qualquer aplicativo .NET.

Importante

Se outros módulos de telemetria estiverem habilitados para coletar telemetria automaticamente, verifique se a mesma configuração usada para inicializar esses módulos é usada para o módulo de métricas ao vivo.

Observação

A configuração padrão coleta logs ILoggerWarning e logs mais graves. Para saber mais, confira Como personalizar a coleta de logs do ILogger?.

Serviço de Trabalho

Logs emitidos via ILogger com severidade de Aviso ou superior são capturados automaticamente. Para alterar esse comportamento, substitua explicitamente a configuração de log do provedor ApplicationInsights, conforme mostrado no código a seguir. A configuração a seguir permite que o Application Insights capture todos os Information logs e logs mais graves.

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

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

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

Observação

O Application Insights respeita os níveis de log configurados por meio de ConfigureLogging(...) no código. Se apenas appsettings.json for usado e ConfigureLogging não for substituído explicitamente, o nível de log padrão será Aviso.

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

Rastreamentos (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 correlacionar-os com outros eventos e relatórios de exceção.

O Application Insights captura logs de ASP.NET Core e outros aplicativos .NET por meio de ILogger e de ASP.NET clássico (.NET Framework) por meio do SDK clássico e de adaptadores.

Observação

  • Por padrão, o provedor do Application Insights só envia logs com gravidade Warning ou superior. Para incluir logs de Information ou nível inferior, atualize as configurações de nível de log em appsettings.json.

  • O pacote NuGet Microsoft.ApplicationInsights.WorkerService, usado para habilitar o Application Insights para serviços em segundo plano, está fora do escopo.

  • Para examinar perguntas frequentes (FAQ), consulte Logging com .NET FAQ.

Instalar registro no seu aplicativo

ASP.NET

Escolha uma estratégia de logging para produzir logs de diagnóstico que o Application Insights pode capturar.

Para aplicativos de ASP.NET clássicos que usam o rastreamento System.Diagnostics, configure um Application Insights TraceListener no arquivo de 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>

Observação

O módulo de captura de log é um adaptador útil para agentes de terceiros. No entanto, se você ainda não estiver usando NLog, log4Net ou System.Diagnostics.Trace, considere chamar o Application Insights TrackTrace() diretamente.

Configurar o Application Insights para a coleta de logs

Opção 1: Adicione o Application Insights ao seu projeto se você ainda não fez isso. Ao adicionar o Application Insights no Visual Studio, há uma opção para incluir o coletor de logs.

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

Observação

Se você estiver perdendo o menu do Application Insights ou a opção coletor de logs, consulte o artigo de solução de problemas dedicado.

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á chamar builder.Logging.AddApplicationInsights() e pode ignorar as instruções de instalação do ILogger a seguir.

Se você precisar apenas de encaminhamento de logs e não de toda a pilha de telemetria, poderá usar o pacote do provedor Microsoft.Extensions.Logging.ApplicationInsights para capturar logs.

Instalação manual

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

  1. Em Solution Explorer, clique com o botão direito do mouse em seu projeto e selecione Manage NuGet Packages.

  2. Pesquise Application Insights.

  3. Selecione um dos seguintes pacotes:

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

Instruções de instalação:

Observação

Expanda qualquer uma das seções abaixo para obter instruções de instalação específicas do pacote.


Ilogger

  1. Instale os Microsoft.Extensions.Logging.ApplicationInsights.

  2. Adicionar ApplicationInsightsLoggerProvider:

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();

Com o pacote NuGet instalado e o provedor sendo registrado com injeção de dependência, o aplicativo está pronto para o log. Com a injeção de construtor, exija uma ILogger ou a alternativa de tipo genérico ILogger<TCategoryName>, conforme necessário. Quando essas implementações forem resolvidas, o ApplicationInsightsLoggerProvider as fornecerá. As mensagens ou exceções registradas são enviadas para o Application Insights.

Considere o seguinte exemplo de controlador:

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

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

Inserir chamadas de log de diagnóstico (System.Diagnostics.Trace/log4net/NLog)

Se você usar System.Diagnostics.Trace, uma chamada típica será:

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

Se preferir log4net ou NLog, use:

    logger.Warn("Slow response - database01");
Usar eventos EventSource

Você pode configurar eventos System.Diagnostics.Tracing.EventSource para serem enviados ao Application Insights como rastreamentos.

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

  2. Edite a TelemetryModules seção do arquivo ApplicationInsights.config :

        <Add Type="Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule, Microsoft.ApplicationInsights.EventSourceListener">
      <Sources>
        <Add Name="MyCompany" Level="Verbose" />
      </Sources>
    </Add>

Para cada origem, você pode definir os seguintes parâmetros:

  • O nome especifica o nome do EventSource a ser coletado.
  • O nível especifica o nível de log a ser coletado: Crítico, Erro, Informativo, LogAlways, Detalhado ou Aviso.
  • Palavras-chave (opcional) especificam o valor inteiro das combinações de palavras-chave a serem usadas.
Usar eventos do DiagnosticSource

Você pode configurar eventos System.Diagnostics.DiagnosticSource para serem enviados ao Application Insights como rastreamentos.

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

  2. Edite a TelemetryModules seção do arquivo ApplicationInsights.config :

        <Add Type="Microsoft.ApplicationInsights.DiagnosticSourceListener.DiagnosticSourceTelemetryModule, Microsoft.ApplicationInsights.DiagnosticSourceListener">
      <Sources>
        <Add Name="MyDiagnosticSourceName" />
      </Sources>
    </Add>

Para cada fonte de diagnóstico que você deseja rastrear, adicione uma entrada com o Name atributo definido como o nome da fonte de diagnóstico.

Usar eventos ETW

Você pode configurar eventos de ETW (Rastreamento de Eventos para Windows) a serem enviados ao Application Insights como rastreamentos.

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

  2. Edite a seção "TelemetryModules" do arquivo ApplicationInsights.config :

Observação

Os eventos ETW só poderão ser coletados se o processo que hospeda o SDK for executado por uma identidade que é membro de Usuários do Log de Desempenho ou de Administradores.

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

Para cada origem, você pode definir os seguintes parâmetros:

  • ProviderName é o nome do provedor ETW a ser coletado.
  • ProviderGuid especifica o GUID do provedor ETW para coleta. Ele pode ser usado em vez de ProviderName.
  • O nível define o nível de log a ser coletado. Pode ser Crítico, Erro, Informativo, LogAlways, Detalhado ou Aviso.
  • Palavras-chave (opcional) definem o valor inteiro das combinações de palavras-chave a serem usadas.
Utilizar a API de Rastreio diretamente

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

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

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

Você também pode adicionar um nível de severidade à sua mensagem. E, como outra telemetria, você pode adicionar propriedades para ajudar a filtrar ou pesquisar diferentes conjuntos de rastros. 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 você pode filtrar facilmente em Pesquisar todas as mensagens de um determinado nível de severidade relacionadas a um banco de dados específico.

Aplicativo de console

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

O exemplo a seguir usa o pacote Microsoft.Extensions.Logging.ApplicationInsights e demonstra o comportamento padrão de um aplicativo de console. O pacote Microsoft.Extensions.Logging.ApplicationInsights 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, confira Qual tipo de telemetria do Application Insights é produzido a partir de logs do ILogger? Onde posso ver os logs do ILogger no Application Insights?.

Escopos de registro de log

Observação

As diretrizes a seguir se aplicam a cenários ILogger (somente ASP.NET Core e console). Ele não se aplica ao ASP.NET clássico.

ApplicationInsightsLoggingProvider dá suporte a escopos de log, que estã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") nas 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");
}

Localizar seus logs

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

No painel de visão geral do aplicativo no portal do Application Insights, selecione Pesquisar onde você pode:

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

Observação

Se o aplicativo enviar grandes quantidades de dados e você estiver usando o SDK do Application Insights para ASP.NET versão 2.0.0-beta3 ou posterior, o recurso de amostragem adaptável poderá operar e enviar apenas uma parte da telemetria. Saiba mais sobre amostragem.

Explorar nos Logs do Azure Monitor

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

Exemplo

No portal do Azure, acesse o Application Insights e execute:

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

Rastreamento distribuído

As arquiteturas modernas de nuvem e microsserviços habilitaram serviços simples e independentemente implantáveis que reduzem os custos, aumentando a disponibilidade e a taxa de transferência. No entanto, tornou os sistemas como um todo mais difíceis de compreender e depurar. O rastreamento distribuído resolve esse problema fornecendo um profiler de desempenho que funciona como pilhas de chamadas para arquiteturas de nuvem e microsserviços.

Azure Monitor fornece duas experiências para consumir dados de rastreamento distribuídos: a exibição transaction diagnostics para uma única transação/solicitação e a exibição application map para mostrar como os sistemas interagem.

O Application Insights pode monitorar cada componente separadamente e detectar qual componente é responsável por falhas ou degradação de 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.

Habilitar o rastreamento distribuído por meio do Application Insights por meio de SDKs ou auto-instrumentação

Os agentes do Application Insights e os SDKs para .NET, .NET Core, Java, Node.jse JavaScript dão suporte ao rastreamento distribuído nativamente.

Com o SDK do Application Insights adequado instalado e configurado, as informações de rastreamento são coletadas automaticamente para estruturas, bibliotecas e tecnologias populares por coletores automáticos de dependência do SDK. A lista completa de tecnologias com suporte está disponível na Documentação de autocoleta de dependência.

Qualquer tecnologia também pode ser rastreada manualmente usando 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 se você perder 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. Telemetria de solicitação define essas operações. Cada item de telemetria de solicitação tem o seu próprio id que o identifica exclusivamente e globalmente. E todos os itens de telemetria (como rastreamentos e exceções) associados à solicitação devem definir o operation_parentId ao valor da solicitação id.

A telemetria de dependência representa todas as operações de saída, como uma chamada HTTP para outro componente. Ele também define seu próprio id que é globalmente exclusivo. A telemetria de solicitação, iniciada por essa chamada de dependência, usa este id como 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 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 dados de várias instâncias, consulte Consultar dados em espaços de trabalho, aplicativos e recursos do Log Analytics no Azure Monitor.

Exemplo

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

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 do Ajax é feita a partir da página, uma nova ID exclusiva (qJSXU) é atribuída à telemetria de dependência e a ID do pageView é usada como operation_ParentId. Em seguida, a solicitação do servidor usa a ID do Ajax como operation_ParentId.

tipoDeItem nome ID operation_ParentId ID_de_operação
pageView Página de ações financeiras STYz STYz
dependência GET /Inicio/Estoque qJSXU STYz STYz
solicitação GET Início/Estoque KqKwlrSt9PA= qJSXU STYz
dependência GET /api/stock/value bBrf2L7mm2g= KqKwlrSt9PA= STYz

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

Cabeçalhos de correlação usando o TraceContext W3C

O Application Insights está fazendo a transição para o Contexto de Rastreamento do W3C, que define:

  • traceparent: Carrega a ID de operação globalmente única e o identificador exclusivo da chamada.
  • tracestate: contém o contexto de rastreamento específico do sistema.

A versão mais recente do SDK do Application Insights dá suporte ao protocolo Trace-Context, mas talvez seja necessário aceitar. (A compatibilidade retroativa com o protocolo de correlação anterior, suportado pelo SDK do Application Insights, é mantida.)

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

  • Request-Id: Carrega a identificação global exclusiva da chamada.
  • Correlation-Context: Transporta 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 pares nome-valor Request-Context para propagar a coleção de propriedades usadas pelo chamador imediato ou pelo receptor de chamada. O SDK do Application Insights usa esse cabeçalho para definir os campos dependency.target e request.source.

Os modelos de dados do Contexto de Rastreamento do W3C e do Application Insights são mapeados da seguinte maneira:

Application Insights W3C TraceContext
Id de Request e Dependency parent-id
Operation_Id trace-id
Operation_ParentId ID pai do intervalo pai desta seção. Esse campo deve estar vazio se for um intervalo raiz.

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

Habilitar 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 e do .NET Core, juntamente com a compatibilidade retroativa com o protocolo Request-Id legado.

Correlação de telemetria

A correlação é tratada por padrão ao integrar um aplicativo. Nenhuma ação especial é necessária.

O runtime do .NET dá suporte à distribuição distribuída com a ajuda de Atividade e DiagnosticSource

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

Dependências

Dependências acompanhadas automaticamente

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

No momento, DependencyTrackingTelemetryModule acompanha as seguintes dependências automaticamente:

Dependências Detalhes
HTTP/HTTPS Chamadas HTTP/HTTPS locais ou remotas.
Chamadas WCF Somente acompanhadas automaticamente se associações baseadas em HTTP forem usadas.
SQL Chamadas feitas com SqlClient. Consulte a seção Acompanhamento avançado do SQL para obter a consulta SQL completa para capturar consultas do SQL.
Azure Blob Storage, Armazenamento de Tabelas ou Armazenamento de Filas Chamadas feitas com o cliente Azure Storage.
SDK do cliente do Azure Event Hubs Use o pacote mais recente: https://nuget.org/packages/Azure.Messaging.EventHubs.
SDK do cliente do Azure Service Bus Use o pacote mais recente: https://nuget.org/packages/Azure.Messaging.ServiceBus.
Azure Cosmos DB Acompanhado automaticamente se HTTP/HTTPS é usado. O rastreamento de operações no modo direto com TCP é capturado automaticamente usando o pacote de visualização >= 3.33.0-preview. Para obter mais detalhes, acesse a documentação.

Se a dependência não for coletada automaticamente, você poderá acompanhá-la manualmente com um comando acompanhar chamada de dependência.

Para saber mais sobre o funcionamento do acompanhamento de dependências, confira Acompanhamento de dependências no Application Insights.

Como funciona o monitoramento automático de dependência?

  • A instrumentação de código de byte é aplicada em torno de métodos selecionados usando InstrumentationEngine, podendo ser habilitada por meio de StatusMonitor ou da extensão Application Insights para Azure App Service.

  • EventSource callbacks são usados para capturar dados de telemetria de bibliotecas .NET que emitem eventos estruturados.

  • DiagnosticSource Os retornos de chamada da são usados em SDKs mais recentes do .NET e do .NET Core para coletar a telemetria de bibliotecas que dão suporte ao rastreamento distribuído.

Configurar o acompanhamento automático de dependência em aplicativos de console

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

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

Observação

Para aplicativos de console do .NET Core, TelemetryConfiguration.Active está obsoleto.

Como acompanhar dependências manualmente

Veja a seguir exemplos de dependências que não são coletadas automaticamente e exigem acompanhamento manual:

  • O Azure Cosmos DB é acompanhado automaticamente somente se HTTP/HTTPS é usado. O modo TCP não é capturado automaticamente pelo Application Insights para versões do SDK anteriores a 2.22.0-Beta1.
  • Redis

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

Exemplo

Se você criar seu código com um assembly que não programou, você pode cronometrar todas as chamadas para ele. Esse cenário permitiria que você descobrisse qual a contribuição dele para o seu tempo 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 acompanhar manualmente as dependências, conforme mostrado em Rastreamento de dependências de saída.

Desabilitar o módulo de acompanhamento de dependências padrão

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

Acompanhamento de SQL avançado para obter a consulta SQL completa

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

Observação

Azure Functions requer configurações separadas para habilitar a coleção de texto SQL. Para obter mais informações, confira Habilitar a coleta de consultas SQL.

ASP.NET

Para aplicativos ASP.NET, o texto completo da consulta SQL é coletado com a ajuda da instrumentação de código de byte, que requer o uso do mecanismo de instrumentação ou usando o pacote NuGet Microsoft.Data.SqlClient em vez da biblioteca System.Data.SqlClient. As etapas específicas da plataforma para habilitar a coleta completa da consulta SQL são descritas na tabela a seguir.

Plataforma Etapas necessárias para obter a consulta SQL completa
Web Apps em Azure App Service No painel de controle do aplicativo Web, open o painel do Application Insights e habilite comandos SQL em .NET.
Servidor IIS (Azure Virtual Machines, local e assim por diante) Use o pacote NuGet Microsoft.Data.SqlClient ou o módulo Monitor do PowerShell para o Application Insights Agent para instalar o mecanismo de instrumentação e reiniciar o IIS.
Serviços de Nuvem do Azure Adicionar uma tarefa de inicialização para instalar o StatusMonitor.
Seu aplicativo deve ser integrado ao SDK do ApplicationInsights no momento do build instalando pacotes NuGet para aplicativos ASP.NET ou ASP.NET Core.
IIS Express Use o pacote NuGet Microsoft.Data.SqlClient.
WebJobs no Azure App Service Use o pacote NuGet Microsoft.Data.SqlClient.

Além das etapas anteriores específicas da plataforma, você também precisa optar explicitamente por habilitar a coleção de comandos SQL modificando o arquivo ApplicationInsights.config 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 ativar a coleção de texto SQL usando:

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

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

Exceções

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 poder diagnosticar as causas rapidamente. Nesta seção, você aprenderá a configurar relatórios de exceções, relatar exceções explicitamente, diagnosticar falhas e muito mais.

Configurar os relatórios de exceção

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ê precisará da extensão ou do SDK apropriado.

Server-side

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

  • Adicione a extensão Application Insights para aplicativos Web Azure.
  • Adicione a Extensão de Monitoramento de Aplicativos para VMs do Azure e conjuntos de dimensionamento de máquinas virtuais do Azure aplicativos hospedados pelo IIS.
  • Adicione o SDK do Application Insights ao código do seu aplicativo, execute o Application Insights Agent para servidores Web IIS ou ative o agente Java para aplicativos web Java.
Client-side

O SDK do JavaScript 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 aplicativo

Algumas estruturas do aplicativo exigem mais configuração. Considere as seguintes tecnologias:

Importante

Esta seção se concentra em aplicativos do .NET Framework de uma perspectiva de exemplo de código. Alguns dos métodos que funcionam para o .NET Framework são obsoletos no SDK do .NET Core.

Diagnosticar falhas e exceções

portal do Azure

O Application Insights vem com uma experiência de Gerenciamento de desempenho de aplicativos coletada para lhe ajudar a diagnosticar falhas nos aplicativos monitorados.

Para obter instruções detalhadas, confira 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, em seu servidor ou na máquina de desenvolvimento, usando F5. Recrie a exceção.

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

  3. Selecione um relatório de exceções para mostrar o rastreamento de pilha. Selecione uma referência de linha no rastreamento de pilha para abrir o arquivo de código relevante.

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

    Captura de tela mostrando a notificação de exceções do CodeLens.

Dados personalizados de rastreamento e log

Para obter dados de diagnóstico específicos do aplicativo, você pode inserir código para enviar seus próprios dados de telemetria. Sua telemetria personalizada ou os dados de log são exibidos na pesquisa de diagnóstico junto com a solicitação, exibição de página e outros dados coletados automaticamente.

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

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

Captura de tela mostrando a tela de Pesquisa.

Observação

Se o aplicativo gerar grandes quantidades de telemetria, o módulo de amostragem adaptável reduzirá automaticamente o volume enviado ao portal, enviando apenas uma fração representativa dos eventos. Eventos que fazem parte da mesma operação são selecionados ou desmarcados como um grupo para que você possa navegar entre eventos relacionados. Para obter mais informações, consulte Amostragem no Application Insights.

Consultar dados POST de solicitação

Os detalhes da solicitação não incluem os dados enviados ao seu aplicativo em uma chamada POST. Para que esses dados sejam relatados:

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

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

É possível:

  • Registrar as exceções explicitamente inserindo código em manipuladores de exceção para relatar as exceções.
  • Capturar exceções automaticamente configurando sua estrutura do ASP.NET. As inclusões necessárias são diferentes para diferentes tipos de estrutura.
Relatar exceções explicitamente

A maneira mais simples de relatar é inserir uma chamada a trackException() em um manipulador de exceção.

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 medidas e propriedades são opcionais, mas são úteis para filtrar e adicionar informações extras. Por exemplo, se você tiver um aplicativo que possa executar vários jogos, poderá encontrar os relatórios de exceção relacionados a um jogo específico. Você pode adicionar quantos itens desejar a cada dicionário.

Exceções de navegador

A maioria das exceções de navegador são relatados.

Se sua página da web inclui arquivos de script de redes de distribuição de conteúdo ou de outros domínios, certifique-se de sua marca de script com o atributo crossorigin="anonymous" e que o servidor envia cabeçalhos CORS. Esse comportamento permite obter um rastreamento de pilha e detalhes para exceções de JavaScript sem tratamento desses recursos.

Reutilizar o cliente de telemetria

Observação

Recomendamos que você instancie TelemetryClient uma vez e reutilize-o durante toda a vida útil de um aplicativo.

Com Injeção de dependência (DI) no .NET, o SDK do .NET apropriado e configurando corretamente o Application insights para DI, você pode exigir o TelemetryClient como um parâmetro de construtor.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

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

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

Formulários da Web

Para Web forms, o Módulo HTTP pode coletar exceções quando não há redirecionamentos configurados com CustomErrors. Contudo, quando você tiver redirecionamentos ativos, adicione as seguintes linhas à função Application_Error em Global.asax.cs.

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

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

MVC

Começar com o SDK do Application Insights Web versão 2.6 (beta 3 e posterior), exceções de coleta sem tratamento do Application Insights lançadas automaticamente nos métodos de controladores MVC 5+. Se você adicionou anteriormente um manipulador personalizado para acompanhar essas exceções, poderá removê-lo para evitar o acompanhamento duplo de exceções.

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

  • De construtores do controlador
  • De manipuladores de mensagens
  • Durante o roteamento
  • Durante a serialização do conteúdo da resposta
  • Durante a inicialização do aplicativo
  • Em tarefas em segundo plano

Todas as exceções tratadas pelo aplicativo ainda precisam ser controladas manualmente. Exceções sem tratamento provenientes de controladores geralmente resultam em resposta de "Erro interno do servidor" 500. Se a resposta for criada manualmente como resultado de uma exceção tratada ou nenhuma exceção, ele é rastreado em telemetria de solicitação correspondente com ResultCode 500. Porém, o SDK do Application Insights não poderá controlar a exceção correspondente.

Suporte de versões anteriores

Se você usa o MVC 4 (e versões anteriores) do Application Insights Web SDK 2.5 (e versões anteriores), consulte os exemplos a seguir para rastrear exceções.


Expandir para ver as instruções de versões anteriores

Se a configuração CustomErrors for Off, as exceções estarão disponíveis para o Módulo HTTP coletar. No entanto, se estiver definido como RemoteOnly (padrão) ou On, a exceção será apagada e não estará disponível para coleta automática do Application Insights. Você pode corrigir esse comportamento substituindo a classe System.Web.Mvc.HandleErrorAttribute e aplicando a classe substituída conforme mostrado para as diferentes versões do MVC aqui (consulte a origem GitHub):

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);
        }
    }
}

MVC 2

Substitua o atributo HandleError pelo novo atributo em seus controladores:

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

Amostra

MVC 3

Registrar AiHandleErrorAttribute como um filtro global em Global.asax.cs:

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

Amostra

MVC 4, MVC 5

Registrar AiHandleErrorAttribute como um filtro global em FilterConfig.cs:

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

Amostra

Web API

Começar com o SDK do Application Insights Web versão 2.6 (beta 3 e posterior), exceções de coleta sem tratamento do Application Insights lançadas automaticamente nos métodos de controladores para Web API 2+. Se você adicionou anteriormente um manipulador personalizado para acompanhar essas exceções, conforme descrito nos exemplos a seguir, poderá removê-lo para evitar o acompanhamento duplo de exceções.

Os filtros de exceção não podem lidar com vários casos. Por exemplo:

  • Exceções geradas por construtores de controlador.
  • Exceções geradas por manipuladores de mensagens.
  • Exceções geradas durante o roteamento.
  • Exceções geradas durante a serialização de conteúdo da 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 controladas manualmente. Exceções sem tratamento provenientes de controladores geralmente resultam em resposta de "Erro interno do servidor" 500. Se uma resposta for criada manualmente como resultado de uma exceção tratada ou nenhuma exceção, ele é rastreado em uma telemetria de solicitação correspondente com ResultCode 500. Porém, o SDK do Application Insights não poderá controlar a exceção correspondente.

Suporte de versões anteriores

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


Expandir para ver as instruções de versões anteriores

API Web 1.x

Substituir System.Web.Http.Filters.ExceptionFilterAttribute:

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);
    }
    }
}

Você pode adicionar esse atributo substituído para controladores específicos ou adicioná-lo à configuração de filtros globais na classe WebApiConfig:

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());
        }
    }
}

Amostra

API Web 2.x

Adicionar uma implementação de IExceptionLogger:

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);
        }
    }
}

Adicione este snippet aos serviços em WebApiConfig:

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());
        }
    }
}

Amostra

Como alternativas, você pode:

  • Substitua a única instância ExceptionHandler por uma implementação personalizada de IExceptionHandler. O manipulador de exceção é chamado apenas quando a estrutura ainda é capaz de escolher a mensagem de resposta para enviar, não quando a conexão é anulada, por exemplo.
  • Use os filtros de exceção, como descrito na seção controladores acima da API Web 1.x, que não são chamados em todos os casos.

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 para as implementações de serviço:

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

Amostra

Contadores de desempenho de exceção

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

Abra uma guia do metrics explorer 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.

Isso é diferente da contagem 'Exceções' calculada pelo portal do Application Insights contando relatórios TrackException. Os intervalos de amostragem são diferentes, e o SDK não envia relatórios TrackException a todas as exceções tratadas e sem tratamento.

Coleta de métricas personalizadas

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

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

É recomendável usar a agregação, portanto TrackMetric()não é mais o método preferencial de coletar métricas personalizadas. Este artigo explica como usar o método GetMetric() e alguns fundamentos por trás do seu funcionamento.


Expandir para saber mais sobre API com pré-agregação e sem pré-agregação

O método TrackMetric() envia telemetria bruta que indica uma métrica. Não é eficiente enviar um único item de telemetria para cada valor. O método TrackMetric() também é ineficiente em termos de desempenho, porque cada TrackMetric(item) passa pelo pipeline completo do SDK de inicializadores e processadores de telemetria.

Ao contrário de TrackMetric(), GetMetric() se encarrega da pré-agregação local para você e, a seguir, envia apenas uma métrica resumida agregada a um intervalo fixo de um minuto. Caso seja necessário monitorar de perto alguma métrica personalizada em segundos ou até mesmo milissegundos, é possível fazer isso com o custo de armazenamento e tráfego de rede do monitoramento a cada minuto. Esse comportamento também reduz bastante o risco de limitação, pois o número total de itens de telemetria que precisam ser enviados para uma métrica agregada é muito reduzido.

Em Application Insights, as métricas personalizadas coletadas por meio de TrackMetric() e GetMetric() não estão sujeitas à amostragem. A amostragem de métricas importantes pode levar a cenários em que os alertas criados em torno dessas métricas se tornam não confiáveis. Não fazendo a amostragem das métricas personalizadas, você geralmente tem a certeza de que um alerta é acionado quando os limites de alerta são violados. Como as métricas personalizadas não são amostradas, há algumas preocupações em potencial.

O acompanhamento de tendências de uma métrica a cada segundo ou em um intervalo ainda mais detalhado pode ter os seguintes resultados:

  • Aumento dos custos de armazenamento de dados. Há um custo associado à quantidade de dados que você envia para Azure Monitor. Quanto mais dados enviados, maior é o custo geral de monitoramento.
  • Aumento do tráfego de rede ou sobrecarga de desempenho. Em alguns cenários, essa sobrecarga pode ter um custo monetário e de desempenho do aplicativo.
  • Risco de limitação de ingestão. O Azure Monitor remove (“restringe”) os pontos de dados quando o aplicativo envia uma taxa alta de telemetria em um curto intervalo de tempo.

A limitação é preocupante, pois pode causar alertas perdidos. A condição para disparar um alerta pode ocorrer no local e ser removida no ponto de extremidade de ingestão devido ao excesso de dados enviados. Não recomendamos usar TrackMetric() para .NET e .NET Core, a menos que você tenha implementado sua própria lógica de agregação local. Se você está tentando rastrear todas as instâncias em que um evento ocorre durante um determinado período, TrackEvent() é uma opção melhor. Tenha em mente que, ao contrário das métricas personalizadas, os eventos personalizados estão sujeitos à amostragem. Você continua podendo usar TrackMetric(), mesmo sem escrever sua própria pré-agregação local. No entanto, se você fizer isso, tenha cuidado com percalços.

Em resumo, recomendamos o método GetMetric() porque faz a pré-agregação, acumula valores de todas as chamadas Track() e envia um resumo/agregação a cada minuto. O método GetMetric() pode reduzir significativamente o custo e a sobrecarga de desempenho enviando menos pontos de dados, mais ainda coletando todas as informações relevantes.

Introdução ao método GetMetric

Para nossos exemplos, usaremos um aplicativo básico de serviço de trabalho do .NET Core 3.1. Se você quiser replicar o ambiente de teste usado com esses exemplos, siga as etapas 1 a 6 no aplicativo .NET Core Worker Service. Essas etapas adicionam o Application Insights a um modelo básico de projeto de serviço de trabalho. Os conceitos são aplicáveis a qualquer aplicativo geral em que o SDK possa ser usado, incluindo aplicativos Web e aplicativos de console.

Enviar métrica

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);
            }
        }
    }
}

Ao executar o código de exemplo, você verá o loop while em execução repetidamente sem que nenhuma telemetria seja enviada na janela de saída 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 item de telemetria único representa uma agregação de 41 medidas de métricas distintas. Como estamos enviando o mesmo valor várias vezes, temos um desvio padrão (stDev) de 0 com valores máximos (max) e mínimos (min) idênticos. A propriedade value representa a soma de todos os valores individuais que foram agregados.

Observação

O método GetMetric é incompatível com o acompanhamento do último valor (por exemplo, gauge), tampouco com o acompanhamento de histogramas ou distribuições.

Se examinássemos nosso recurso do Application Insights na experiência Log Analytics, o item individual de telemetria se pareceria com a captura de tela abaixo.

Captura de tela que mostra a visualização de consultas do Log Analytics.

Observação

Como o item de telemetria bruta não continha um campo nem uma propriedade de soma explícita depois de ser ingerido, criamos um para você. Nesse caso, as propriedades value e valueSum representam a mesma coisa.

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

Captura de tela mostrando a visualização do Metrics explorer.

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

É possível observar os valores de métrica 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. Esse resultado significa acompanhar 10 mil valores por segundo. Nesses cenários de alta taxa de transferência, talvez os usuários precisem ajudar o SDK evitando algumas pesquisas.

O exemplo acima realizou uma pesquisa de um identificador para a métrica ComputersSold e rastreou um valor observado de 42. Em vez disso, é possível armazenar em cache o identificador em várias invocações de rastreamento:

//...

        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 acima também reduziu Task.Delay para 50 milissegundos. Assim, o loop pôde ser executado com mais frequência. O resultado é 772 invocações TrackValue().

Métricas multidimensionais

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

Este é 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 em três itens de telemetria distintos sendo enviados para Azure. Cada um representa a agregação de um dos três fatores forma. Como antes, você pode examiná-los melhor na exibição do Log Analytics.

Screenshot que mostra a exibição da Log Analytics de métrica multidimensional.

No gerenciador de métricas:

Captura de tela mostrando Métricas personalizadas.

Não é possível dividir a métrica pela nova dimensão personalizada nem exibir a dimensão personalizada com a exibição de métricas.

Captura de tela mostrando suporte à separação.

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

Habilitar métricas multidimensionais

Para habilitar métricas multidimensionais para um recurso do Application Insights, selecione Uso e custos estimados>Métricas personalizadas>Habilitar alertas em dimensões de métricas personalizadas>OK. Para saber mais, confira Dimensões de métricas personalizadas e pré-agregação.

Depois de fazer essa alteração e enviar uma nova telemetria multidimensional, selecione Aplicar divisão.

Observação

Somente as métricas enviadas recentemente depois que o recurso foi ativado no portal têm dimensões armazenadas.

Captura de tela mostrando a aplicação da separação.

Exiba suas agregações de métrica para cada dimensão FormFactor.

Captura de tela que mostra os fatores de forma.

Usar MetricIdentifier quando há mais de três dimensões

No momento, há suporte para dez dimensões. Usar mais de três dimensões requer o uso 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 de métrica personalizada

Se você quer alterar a configuração de uma métrica, é necessário fazer isso no local em que a métrica é inicializada.

Nomes de dimensão especiais

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

As agregações de métrica enviadas pela métrica Special Operation Request Size a seguir não tem Context.Operation.Name definidas como Special Operation. O método TrackMetric() ou qualquer outro método TrackXXX() tem 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 classe MetricDimensionNames para especificar os valores TelemetryContext.

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

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

O valor dessa dimensão especial é copiado em TelemetryContext e não é usado como uma dimensão normal. Se você também quiser manter uma dimensão de operação para exploração de métrica normal, você 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");
Dimensão e utilização de limitação da série temporal

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

Importante

Use valores cardeais baixos nas dimensões para evitar a limitação.

No contexto de dimensão e utilização de limite da série temporal, usamos Metric.TrackValue(..) para garantir que os limites sejam cumpridos. Se os limites já estiverem atingidos, Metric.TrackValue(..) retornará False e o valor não será rastreado. Caso contrário, ele retornará True. Esse comportamento será útil se os dados de uma métrica se originarem da entrada de usuário.

O construtor MetricConfiguration obtém algumas opções sobre como gerenciar diferentes séries dentro da respectiva métrica e um objeto de uma classe que implementa IMetricSeriesConfiguration 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érie temporal de dados que uma métrica pode ter. Quando esse limite é atingido, as chamadas para TrackValue(), que costumam ter uma nova série como resultado, retornam false.
  • valuesPerDimensionLimit limita o número de valores distintos por dimensão de maneira semelhante.
  • restrictToUInt32Values determina se apenas valores inteiros não negativos devem ser acompanhados.

Este é um exemplo de como enviar uma mensagem para saber se os limites de tampa 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 chamadas e solicitações HTTP recebidas por serviços dependentes, como solicitações HTTP e consultas SQL. O acompanhamento e a correlação de solicitações e dependências fornecem visibilidade sobre a capacidade de resposta e a confiabilidade do aplicativo inteiro em todos os microsserviços que combinados nesse aplicativo.

Há uma classe de padrões de aplicativo que não tem suporte genérico. O monitoramento adequado de tais padrões requer a instrumentação de código manual. 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 execução prolongada.

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

Visão geral

Uma operação é um trabalho lógico executado por um aplicativo. Ela tem nome, hora de início, duração e resultado, além de um contexto de execução como nome de usuário, propriedades e resultado. Se a operação A tiver sido iniciada pela operação B, então a operação B será definida como pai para A. Uma operação pode ter somente um pai, mas pode ter muitas operações filhas. Para saber mais sobre operações e correlação de telemetria, confira Correlação de telemetria do Application Insights.

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

Acompanhamento de operações de entrada

O SDK web do Application Insights coleta automaticamente solicitações HTTP para aplicativos ASP.NET que são executados em um pipeline do IIS e todos os aplicativos ASP.NET Core. Há soluções com suporte da comunidade para outras plataformas e estruturas. Se o aplicativo não for compatível com nenhuma das soluções padrão ou com suporte da comunidade, instrumente-o manualmente.

Outro exemplo que requer um acompanhamento personalizado é o trabalho que recebe os itens da fila. Para alguns filas, a chamada para adicionar uma mensagem a essa fila é acompanhada como dependência. A operação geral que descreve o processamento de mensagens não é coletada automaticamente.

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

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

Solicitação HTTP no aplicativo autohospedado Owin

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


Expandir para exibir código 
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 cabeçalho Correlation-Context. Ela é omitida aqui para fins de simplificação.

Instrumentação de fila

O Contexto de Rastreamento W3C e o Protocolo HTTP para correlação passa 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 da fila. Alguns protocolos de fila, como AMQP, permitem a transmissão de mais metadados. Outros protocolos, como Azure Storage Queue, exigem que o contexto seja incorporado na carga útil da mensagem.

Observação

O rastreamento entre componentes ainda não é compatível com filas.

Com HTTP, se o produtor e o consumidor enviarem telemetria para diferentes recursos do Application Insights, a experiência de diagnóstico de transação e o Mapa do Aplicativo mostrarão transações e farão o mapeamento de ponta a ponta. Para filas, essa funcionalidade ainda não tem suporte.

a fila do Service Bus

Para obter informações de rastreamento, consulte Rastreamento distribuído e correlação através de mensagens do Azure Service Bus.

Azure Storage fila

O exemplo a seguir mostra como acompanhar as operações da fila do Azure Storage e correlacionar a telemetria entre o produtor, o consumidor e o Azure Storage.

A fila de Armazenamento tem uma API HTTP. Todas as chamadas à fila são rastreadas pelo coletor de dependência do Application Insights para solicitações HTTP. Ele é configurado por padrão em aplicativos ASP.NET e ASP.NET Core. Com outros tipos de aplicativos, confira a Documentação de aplicativos do console.

Também convém correlacionar a ID da operação do Application Insights à ID de 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 Monitor, diagnosticar e solucionar problemas Azure Storage.

Enfileirar

Como as filas de Armazenamento do Azure dão suporte a API HTTP, todas as operações com a fila automaticamente são acompanhadas pelo Application Insights. Em muitos casos, essa instrumentação deve ser suficiente. Para correlacionar rastreamentos do consumidor com rastreamentos do produtor, transmita algum contexto de correlação de maneira semelhante a feita em HTTP Protocol for Correlation.

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

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

A operação Enqueue é filho de uma operação pai. Um exemplo é uma solicitação HTTP de entrada. A chamada de dependência HTTP é filho da operação Enqueue e neto 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 o seu aplicativo relata ou se você não quiser acompanhar a operação Enqueue por outros motivos, use a API Activity diretamente:

  • Crie (e inicie) um novo Activity em vez de iniciar a operação do Application Insights. Você não precisa atribuir nenhuma propriedade a ela, exceto o nome da operação.
  • Serializar yourActivity.Id para o conteúdo da mensagem, em vez de operation.Telemetry.Id. Também é possível usar Activity.Current.Id.
Remover da fila

Da mesma forma que Enqueue, a solicitação HTTP real para a fila de Armazenamento é acompanhada automaticamente pelo Application Insights. A operação Enqueue presumivelmente ocorre no contexto do pai, como no contexto de uma solicitação de entrada. Os SDKs do Application Insights correlacionam automaticamente essa operação e sua parte HTTP com a solicitação pai e outras telemetrias relatadas no mesmo escopo.

A operação Dequeue é complicada. O SDK do Application Insights acompanha automaticamente as solicitações HTTP. No entanto, o contexto de correlação permanece desconhecido até a conclusão da análise da mensagem. Não é possível correlacionar a solicitação HTTP para obter a mensagem com o restante da telemetria, principalmente 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 espiar deve ser instrumentada da mesma maneira que uma operação de remoção da fila. A instrumentação de operações de gerenciamento de fila não é necessária. O Application Insights acompanha operações como HTTP e, na maioria dos casos, isso é suficiente.

Ao instrumentar a exclusão de mensagem, verifique se você definiu os identificadores da operação (correlação). Como alternativa, você pode usar a API Activity. Assim, você não precisa definir identificadores de operação nos itens de telemetria porque o SDK do Application Insights faz isso para você:

  • Crie um novo Activity depois que tiver obtido um item da fila.
  • Use Activity.SetParentId(message.ParentId) para correlacionar os logs de produtor e consumidor.
  • Inicie o Activity.
  • Acompanhe as operações de remoção da fila, processamento e exclusão usando auxiliares Start/StopOperation. Faça isso do mesmo fluxo de controle assíncrono (contexto de execução). Dessa forma, elas são correlacionadas corretamente.
  • Pare o Activity.
  • Use Start/StopOperation ou chame a telemetria Track manualmente.
Tipos de dependência

Application Insights usa o tipo de dependência para personalizar experiências de interface do usuário. Para filas, os seguintes tipos de DependencyTelemetry que melhoram a Experiência do diagnóstico de transação são reconhecidos:

  • Azure queue para filas do Armazenamento do Azure
  • Azure Event Hubs para Azure Event Hubs
  • Azure Service Bus para Azure Service Bus
Processamento em lotes

Com algumas filas, você pode remover da fila várias mensagens com uma solicitação. O processamento dessas mensagens é supostamente independente e pertence a 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 no seu próprio fluxo de controle assíncrono. Para obter mais informações, consulte a seção Acompanhamento de dependências de saída.

Tarefas em segundo plano de execução longa

Alguns aplicativos iniciam operações de longa execução que podem ser causadas por solicitações de usuário. Da perspectiva do rastreamento/instrumentação, isso não é diferente da instrumentação de solicitação ou de 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, o telemetryClient.StartOperation cria DependencyTelemetry e preenche o contexto de correlação. Digamos que você tem uma operação pai criada por solicitações de entrada que agendaram a operação. Desde que BackgroundTask inicie no mesmo fluxo de controle assíncrono que uma solicitação de entrada, ela será correlacionada com essa operação pai. BackgroundTask e todos os itens de telemetria aninhados são automaticamente correlacionados com a solicitação a causou, mesmo após o término da solicitação.

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

Acompanhamento de dependências de saída

Você pode controlar sua própria variante de dependência ou uma operação sem suporte pelo Application Insights.

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

A abordagem geral ao acompanhamento de dependência personalizado é:

  • Chame o método TelemetryClient.StartOperation (extensão) que preenche as propriedades DependencyTelemetry necessárias para correlação e algumas outras, como início, carimbo de data/hora e duração.
  • Definir outras propriedades personalizadas no DependencyTelemetry: tais como nome e qualquer outro contexto necessário.
  • Fazer uma chamada de dependência e esperar por ela.
  • Interromper a operação com StopOperation quando concluída.
  • Tratar 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.
        }
    }
}

Como descartar uma operação faz com que ela seja interrompida, é possível fazer isso em vez de chamar StopOperation.

Aviso

Em alguns casos, uma exceção não tratada pode impedir a chamada de finally, impedindo o rastreamento das operações.

Rastreamento e processamento de operações paralelas

A chamada de StopOperation só interrompe a operação iniciada. Se a operação de execução atual não corresponder à que você deseja interromper, StopOperation não fará nada. Essa situação pode acontecer ao iniciar diversas 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;

Sempre chame StartOperation e processe a operação no mesmo método assíncrono para isolar as operações executadas em paralelo. Se a operação for síncrona (ou não assíncrona), envolva o processo e faça o rastreamento 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 versus System.Diagnostics.Activity

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

As atividades no Application Insights são funcionalidades de nível superior. A dependência automática e a coleta de solicitações dependem muito delas e dos eventos DiagnosticSource. Se você criou o Activity em seu aplicativo, isso não cria a telemetria do Application Insights. O Application Insights precisa receber DiagnosticSource eventos e saber os nomes de eventos e cargas para traduzir Activity em telemetria.

Cada operação do Application Insights (solicitação ou dependência) envolve Activity. Quando StartOperation é chamado, ele cria Activity abaixo. StartOperation é a maneira recomendada para controlar a telemetrias de solicitação ou dependência manualmente e garantir que tudo esteja correlacionado.

Contadores

O Application Insights dá 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.

  • Performance counters são integrados ao sistema operacional Windows e oferecem métricas predefinidas, como uso de CPU, consumo de memória e atividade de disco. Esses contadores são ideais para monitorar métricas de desempenho padrão com configuração mínima. Eles ajudam a controlar a utilização de recursos ou a solucionar problemas de gargalos no nível do sistema em aplicativos baseados em Windows, mas não dão suporte a métricas personalizadas específicas do aplicativo.

  • os contadores Event funcionam em várias plataformas, incluindo Windows, Linux e macOS. Eles permitem que os desenvolvedores definam e monitorem métricas leves e personalizáveis específicas do aplicativo, proporcionando mais flexibilidade do que os contadores de desempenho. Os contadores de eventos são úteis quando as métricas do sistema são insuficientes ou quando a telemetria detalhada é necessária em aplicativos entre plataformas. Eles exigem implementação e configuração explícitas, o que torna a instalação mais trabalhosa.

Contadores de desempenho

Windows fornece vários contadores de performance, como aqueles usados para coletar estatísticas de uso de processador, memória e disco. Também é possível definir contadores de desempenho próprios.

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

Dica

Como outras métricas, você pode definir um alerta para avisar se um contador ultrapassar um limite especificado. Para definir um alerta, abra o painel Alertas e selecione Adicionar Alerta.

Pré-requisitos

Conceda permissão à conta de serviço do pool de aplicativos para monitorar contadores de desempenho adicionando-o ao grupo Performance Monitor Users.

net localgroup "Performance Monitor Users" /add "IIS APPPOOL\NameOfYourPool"
Visualizar 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
  • Solicitações por segundo de ASP.NET
  • Exceções lançadas do CLR (.NET Common Language Runtime) / seg
  • Tempo de execução de solicitação de aplicativos ASP.NET
  • Process\Private Bytes (Bytes Privados do Processo)
  • Processo\Bytes de dados de E/S/segundo
  • ASP.NET Aplicativos\Solicitações na Fila de Aplicativos
  • Processador(_Total)\% Tempo de 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
  • Process\Private Bytes (Bytes Privados do Processo)
  • Processo\Bytes de dados de E/S/segundo
  • Processador(_Total)\% Tempo de Processador

Observação

O suporte para contadores de desempenho no ASP.NET Core é limitado:

  • SDK versões 2.4.1 e posteriores coletam contadores de desempenho se o aplicativo estiver em execução em Azure Web Apps (Windows).
  • As versões do SDK 2.7.1 e posteriores coletam contadores de desempenho se o aplicativo estiver executando no Windows e compatível com NETSTANDARD2.0 ou versões posteriores.
  • Para aplicativos direcionados ao .NET Framework, todas as versões do SDK dão suporte a contadores de desempenho.
  • As versões 2.8.0 e posteriores dão suporte ao contador de CPU/memória no Linux. Nenhum outro contador tem suporte no Linux. Para obter contadores do sistema no Linux (e em outros ambientes não Windows), use contadores de eventos.
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 no 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 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>

Capture os contadores padrão e os contadores que você mesmo implementa. \Objects\Processes é um exemplo de um contador padrão que está disponível em todos os sistemas de 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 apenas \Category\Counter para categorias que não têm instâncias.

O parâmetro ReportAs é necessário para nomes de contador que não correspondem a [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

Veja a seção a seguir.

ASP.NET Core

Configure PerformanceCollectorModule após o método WebApplication.CreateBuilder() 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 no código para aplicativos Web ASP.NET ou aplicativos de console do .NET/.NET Core

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

    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 em execução em contêineres de Azure Web Apps e Windows em Azure App Service

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 em Azure App Service podem utilizar um contêiner Windows ou ser hospedados em um ambiente de área restrita. Se o aplicativo for implantado em um contêiner 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 Perf expostos como variáveis de ambiente. Só um subconjunto de contadores está disponível nesse ambiente.

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

Log Analytics consultas para contadores de desempenho

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

O esquema performanceCounters expõe o nome category, counter e o nome instance de cada contador de desempenho. Na telemetria de cada aplicativo, você verá 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 se refere à instância do contador de desempenho, não à função ou à instância do computador do servidor. O nome da instância do contador de desempenho normalmente segmenta os contadores, como tempo de processador, pelo nome do processo ou aplicativo.

Para obter um gráfico da memória disponível no período recente:

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

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

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

Para examinar as perguntas frequentes, consulte Perguntas frequentes sobre contadores de desempenho.

Contadores de eventos

EventCounter é o mecanismo do .NET/.NET Core para publicar e consumir contadores ou estatísticas. EventCounters têm suporte em todas as plataformas do sistema operacional – Windows, Linux e macOS. Ele pode ser considerado como um equivalente multiplataforma para o PerformanceCounters que só tem suporte em sistemas Windows.

Embora os usuários possam publicar contadores de eventos personalizados para atender às suas necessidades, .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 definidos pelo usuário) no Azure Application Insights.

Dica

Como outras métricas, você pode definir um alerta para avisar se um contador ultrapassar um limite especificado. Para definir um alerta, abra o painel Alertas e selecione Adicionar Alerta.

Usar o Application Insights para coletar EventCounters

O Application Insights é compatível com a coleta de EventCounters com seu EventCounterCollectionModule, que faz parte do pacote NuGet recém-lançado Microsoft.ApplicationInsights.EventCounterCollector. EventCounterCollectionModule é habilitado automaticamente ao usar AspNetCore ou WorkerService. EventCounterCollectionModule coleta contadores com uma frequência de coleta 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 SDK do AspNetCore ou do SDK do WorkerService, nenhum contador é coletado por padrão. O próprio módulo está habilitado, para que os usuários possam simplesmente adicionar os contadores desejados e coletá-los.

Para obter uma lista de contadores conhecidos publicados pelo .NET Runtime, consulte o documento Available Counters.

Personalizar os contadores a serem coletados

O exemplo a seguir mostra como adicionar/remover contadores. Essa personalização seria feita como parte da configuração de serviço de aplicativo depois que a coleção de telemetria do Application Insights for habilitada usando AddApplicationInsightsTelemetry() ou AddApplicationInsightsWorkerService(). Veja a seguir um código de exemplo 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"));
        }
    );
Desabilitar o módulo de coleta EventCounter

EventCounterCollectionModule pode ser desabilitado com ApplicationInsightsServiceOptions.

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

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 de 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 consulta a seguir 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) no período recente, execute a consulta a seguir.

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, o customMetrics também tem uma coluna cloud_RoleInstance que indica a identidade da instância do servidor host no 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 de servidor.

Perguntas frequentes sobre contadores de eventos

Para examinar as perguntas frequentes, consulte Perguntas frequentes sobre contadores de eventos.

Coleção de instantâneos

Para saber como configurar a coleção de instantâneos para aplicativos ASP.NET e ASP.NET Core, consulte Enable Snapshot Debugger para aplicativos .NET em Azure Service Fabric, Serviços de Nuvem e Virtual Machines.

Processamento e filtragem de telemetria

Nesta seção

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 de telemetria padrão, como coleta de solicitações HTTP e coleção de dependências.

  • A filtragem pode modificar ou descartar a telemetria antes de ser enviada do SDK implementando 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 pode afetar as métricas que se baseiam em logs agregados. Dependendo de como você descarta itens, você também pode perder a capacidade de navegar entre itens relacionados.

  • Adicione ou modifique propriedades de qualquer telemetria enviada de seu aplicativo implementando um ITelemetryInitializer. Por exemplo, você pode adicionar valores calculados ou números de versão pelos quais filtrar os dados no portal.

  • A amostragem reduz o volume de telemetria sem afetar suas estatísticas. Ele mantém juntos os 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 a amostragem.

Observação

A API do SDK é usada para enviar eventos e métricas personalizados.

Filtragem

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

Para filtrar a telemetria, você escreve um processador de telemetria e registra-o com TelemetryConfiguration. Toda a telemetria passa pelo processador. Você pode optar por removê-lo do fluxo ou passá-lo para o próximo processador na cadeia. A telemetria dos módulos padrão, como o coletor de solicitações HTTP e o coletor de dependências, e a telemetria que você mesmo rastreou está incluída. Por exemplo, você pode filtrar a telemetria sobre solicitações de robôs ou chamadas de dependência bem-sucedidas.

Aviso

Filtrar a telemetria enviada do SDK usando processadores pode distorcer as estatísticas que você vê no portal e dificultar o acompanhamento de itens relacionados.

Em vez disso, considere usar amostragem.

ITelemetryProcessor e ITelemetryInitializer

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

  • Há algumas sobreposições no que você pode fazer com eles. Ambos podem ser usados para adicionar ou modificar propriedades de telemetria, embora seja recomendável 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, normalmente não configuram propriedades que já estão configuradas.
  • Os processadores de telemetria permitem substituir ou descartar completamente um item de telemetria.
  • Todos os inicializadores de telemetria registrados são acionados para cada item de telemetria. Para processadores de telemetria, o SDK garante a chamada do primeiro processador de telemetria. Os processadores de telemetria anteriores é que decidem se o restante dos processadores será chamado ou não.
  • 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 coleta 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, você quiser tratar 400 como um sucesso, poderá fornecer um inicializador de telemetria que define a propriedade de sucesso.

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

Inicializadores de telemetria

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

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:

Inicializador Descrição
AccountIdTelemetryInitializer Define a propriedade AccountId
AuthenticatedUserIdTelemetryInitializer Define a AuthenticatedUserId propriedade como definida pelo SDK do JavaScript.
AzureRoleEnvironmentTelemetryInitializer Atualiza as propriedades RoleName e RoleInstance do contexto Device para todos os itens de telemetria com informações extraídas do ambiente de execução do Azure.
BuildInfoConfigComponentVersionTelemetryInitializer Atualiza a propriedade Version do contexto Component para todos os itens de telemetria com o valor extraído do arquivo BuildInfo.config produzido pelo MS Build.
ClientIpHeaderTelemetryInitializer Atualiza a Ip propriedade do Location contexto de todos os itens de telemetria com base no X-Forwarded-For cabeçalho HTTP da solicitação.
DeviceTelemetryInitializer Atualiza as seguintes propriedades do Device contexto para todos os itens de telemetria:

• Type é definido como PC.
• Id é definido como o nome de domínio do computador em que o aplicativo Web está em execução.
• OemName é definido como o valor extraído do campo Win32_ComputerSystem.Manufacturer usando WMI.
• Model é definido como o valor extraído do campo Win32_ComputerSystem.Model usando WMI.
• NetworkType é definido como o valor extraído da NetworkInterface propriedade.
• Language é definido como o nome da CurrentCulture propriedade.
DomainNameRoleInstanceTelemetryInitializer Atualiza a propriedade RoleInstance do contexto Device para todos os itens de telemetria com o nome de domínio do computador em que o aplicativo web está em execução.
OperationNameTelemetryInitializer Atualiza a propriedade Name de RequestTelemetry e a propriedade Name do contexto Operation de todos os itens de telemetria com base no método HTTP e os nomes do controlador de ASP.NET MVC e da ação invocado para processar a solicitação.
OperationIdTelemetryInitializer ou OperationCorrelationTelemetryInitializer Atualiza a Operation.Id propriedade de contexto de todos os itens de telemetria rastreados durante o tratamento de uma solicitação com o gerado automaticamente RequestTelemetry.Id.
SessionTelemetryInitializer Atualiza a propriedade Id do contexto Session de todos os itens de telemetria com o valor extraído do cookie ai_session gerado pelo código de instrumentação JavaScript ApplicationInsights em execução no navegador do usuário.
SyntheticTelemetryInitializer ou SyntheticUserAgentTelemetryInitializer Atualiza as propriedades de contexto User, Session e Operation de todos os itens de telemetria monitorados ao lidar com uma solicitação de uma origem sintética, como um teste de disponibilidade ou bots de mecanismo de busca. Por padrão, o Metrics Explorer não exibe telemetria sintética.

O <Filters> conjunto que identifica as propriedades das solicitações.
UserTelemetryInitializer Atualiza as propriedades Id e AcquisitionDate do contexto User para todos os itens de telemetria com valores extraídos do cookie ai_user, gerado pelo código de instrumentação JavaScript do Application Insights em execução no navegador do usuário.
WebTestTelemetryInitializer Define a ID do usuário, a ID da sessão e as propriedades de origem sintética para solicitações HTTP provenientes de testes de disponibilidade.

O <Filters> conjunto que identifica as propriedades das solicitações.

Observação

Para aplicativos .NET em execução no Azure Service Fabric, você pode incluir o pacote NuGet Microsoft.ApplicationInsights.ServiceFabric. Esse pacote inclui uma FabricTelemetryInitializer propriedade, que adiciona propriedades do Service Fabric a itens de telemetria. Para obter mais informações, consulte a página do GitHub sobre as propriedades adicionadas por este pacote NuGet.

Adicionar ITelemetryInitializer

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

  1. Definir seu 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 seu 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.

Observação

Verifique se o arquivo applicationinsights.config está no diretório de saída e contém alterações recentes.

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 ASP.NET Core, a adição de um novo inicializador de telemetria é feita adicionando-o ao contêiner DependencyInjection, conforme mostrado. Realize esta etapa no método Startup.ConfigureServices.

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Observação

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); funciona com inicializadores simples. Para outros, builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); é necessário.

Remover inicializadores de telemetria

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

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 de Trabalho

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

Para aplicativos escritos usando o Worker Service, a adição de um novo inicializador de telemetria é realizada ao adicioná-lo ao contêiner DependencyInjection, conforme mostrado. Realize esta etapa 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 alguns específicos, use o código de exemplo a seguir depois de chamar AddApplicationInsightsTelemetryWorkerService().

   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: Gravar TelemetryInitializer personalizado

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

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 arquivo 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 esse código no ConfigureServices método de sua Startup.cs classe.

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;
 public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyTelemetryInitializer>();
}
Controlar o endereço IP do cliente usado para mapeamentos de localização geográfica

O inicializador de exemplo a seguir define o IP do cliente, que é usado para mapeamento de localização geográfica, 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 serem enviados do SDK para o portal.

Implementa ITelemetryProcessor

Os processadores de telemetria constrói uma cadeia de processamento. Ao criar uma instância de um processador de telemetria, você 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;
    }
}

Adicionar seu processador

ASP.NET

Insira este snippet no 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 ao definir propriedades públicas nomeadas na sua classe.

Aviso

Tome cuidado para corresponder o nome do tipo e quaisquer nomes de propriedade no arquivo .config aos nomes de classe e propriedades no código. Se o arquivo .config fizer referência a um tipo ou propriedade inexistente, o SDK poderá falhar silenciosamente ao enviar qualquer telemetria.

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

Observação

O exemplo de código a seguir é obsoleto, mas é disponibilizado aqui para posteridade. Considere começar a usar o OpenTelemetry ou migrar para o OpenTelemetry.

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 esse ponto usam seus processadores.

Processador de telemetria de amostragem adaptável (de 2.0.0-beta3)

Essa funcionalidade está habilitada por padrão. Se seu aplicativo enviar telemetria considerável, esse processador removerá parte dessa telemetria.


    <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. Portanto, se o servidor for um cluster de vários computadores, o volume real de telemetria será multiplicado adequadamente.

Saiba mais sobre amostragem.

Processador de telemetria de amostragem com taxa fixa (de 2.0.0-beta1)

Há também um processador de telemetria de amostragem padrão (de 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

Observação

Adicionar um processador usando ApplicationInsights.config ou TelemetryConfiguration.Active não é válido para aplicativos do ASP.NET Core ou se você estiver usando o SDK Microsoft.ApplicationInsights.WorkerService.

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

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 use AddSingleton<ITelemetryProcessorFactory, MyTelemetryProcessorFactory>().

Serviço de Trabalho

Observação

Adicionar um processador usando ApplicationInsights.config ou TelemetryConfiguration.Active não é válido para aplicativos do ASP.NET Core ou se você estiver usando o SDK Microsoft.ApplicationInsights.WorkerService.

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

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

Filtros de exemplo

Solicitações sintéticas

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

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

Filtre 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 de dependência rápidas remotas

Se você quiser diagnosticar apenas chamadas lentas, filtre as rápidas.

Observação

Essa filtragem distorce as estatísticas que você vê no portal.

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 Sampling no Application Insights.

Serviço de Trabalho

O SDK do Application Insights para Serviço de Trabalho dá suporte à amostragem de taxa fixa e à amostragem adaptativa. A amostragem adaptável é habilitada por padrão. A amostragem pode ser desabilitada usando a opção EnableAdaptiveSamplingem 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();

Enriquecer dados por meio 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

Configuração do SDK

Nesta seção

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 .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 acompanhar 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 aplicativo. 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 Visual Studio que dão suporte a Add>Application Insights Telemetry, o arquivo ApplicationInsights.config é 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.

Importante

O arquivo de configuração será ignorado se a extensão para sites do Azure ou a extensão para VMs do Azure e conjuntos de dimensionamento de máquinas virtuais do Azure for usada.

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 método ConfigureServices() da classe Startup.cs, a menos que seja direcionado de outra forma.

Observação

Em aplicativos ASP.NET Core, não há suporte para alterar a configuração modificando TelemetryConfiguration.Active.

Serviço de Trabalho

O padrão TelemetryConfiguration usado pelo SDK do Serviço de Trabalho é semelhante à configuração automática usada em um aplicativo ASP.NET ou ASP.NET Core, exceto os inicializadores de telemetria usados para enriquecer a telemetria provenientes de 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 embutida no 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 seção ConfigureServices() chamando os métodos apropriados em IServiceCollection, conforme detalhado na próxima seção.

Observação

Quando você usa o SDK do Serviço de Trabalho, não há suporte para alterar a configuração modificando TelemetryConfiguration.Active e as alterações não serão refletidas.

Canais de telemetria

Os canais de telemetria são parte integrante dos SDKs do Application Insights. Eles gerenciam o armazenamento em buffer e a transmissão de telemetria para o serviço do 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.

Observação

Para examinar as perguntas frequentes, consulte Perguntas frequentes sobre canais de telemetria

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 ao serviço Application Insights, onde são armazenados para consulta e análise. Um canal de telemetria é qualquer classe que implemente a interface Microsoft.ApplicationInsights.ITelemetryChannel.

O método Send(ITelemetry item) de um canal de telemetria é chamado depois que todos os inicializadores e processadores de telemetria são chamados. Portanto, todos os itens descartados por um processador de telemetria não chegam ao canal. O método Send() geralmente não envia os itens para o back-end de forma instantânea. Normalmente, ele os armazena em buffers na memória e os envia em lotes, para obter uma transmissão eficiente.

Evite chamar Flush() a menos que seja essencial enviar a telemetria armazenada em buffer imediatamente. Use-o apenas em cenários como desligamento do aplicativo, 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 execução longa, 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 possibilita a transmissão ao vivo de telemetria. Este canal é independente do canal regular de telemetria e este documento não se aplica a ele.

Canais de telemetria integrados

Os SDKs do Application Insights .NET e .NET Core 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 novamente a telemetria após uma falha. Esse canal também não mantém itens em disco. Portanto, todos os itens não enviados são perdidos permanentemente após o desligamento do aplicativo, sejam eles normais ou não. Este canal implementa um método Flush() que pode ser usado para forçar a liberação de qualquer item 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.

    Este canal faz parte do pacote Microsoft.ApplicationInsights NuGet maior e é o canal padrão que o SDK usa quando nada mais está 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 enviar novamente a telemetria se ocorrerem erros transitórios. Este canal também usa armazenamento em disco local para manter itens no disco durante interrupções de rede ou altos volumes de telemetria. Por causa desses mecanismos de repetição e armazenamento em disco local, esse canal é considerado mais confiável. Isso é recomendado em todos os cenários de produção. Esse canal é o padrão para aplicativos ASP.NET e ASP.NET Core configurados de acordo com a documentação oficial. Este canal é otimizado para cenários de servidor com processos de longa duração. O método Flush() que é implementado por esse canal não é síncrono.

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

Configure um canal de telemetria

Você configura um canal de telemetria definindo-o para a configuração de telemetria ativa. Para aplicativos ASP.NET, a configuração envolve a configuração da instância do canal de telemetria como 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 como definir a configuração StorageFolder do 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, confira a seção Configurações configuráveis nos canais mais tarde neste artigo.

ASP.NET

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

O código a seguir configura uma instância ServerTelemetryChannel com StorageFolder definido como um local personalizado. Adicione este código no início do aplicativo, normalmente no método Application_Start() 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 de ApplicationInsights.config mostra o canal ServerTelemetryChannel 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 método ConfigureServices da classe Startup.cs conforme 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();
}

Importante

Não há suporte para configurar o canal usando TelemetryConfiguration.Active para aplicativos ASP.NET Core.

Substituir 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();

Observação

Se quiser liberar o buffer, consulte Liberar dados. Por exemplo,você poderá querer liberar o buffer se estiver usando o SDK em um aplicativo que é desligado.

Serviço de Trabalho

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 no 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 de ServerTelemetryChannel

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

Por padrão, no máximo 10 instâncias Transmission 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 for lento, as instâncias Transmission serão armazenadas na memória. A capacidade padrão desse buffer Transmission na memória é 5 MB. Quando a capacidade na memória é excedida, as instâncias Transmission são armazenadas em disco local até um limite de 50 MB.

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

Configurações configuráveis em canais

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

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

  • MaxTransmissionBufferCapacity: A quantidade máxima de memória, em bytes, usada pelo canal para fazer o buffer das 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 de disco, mas lembre-se de que os itens na memória serão perdidos se o aplicativo falhar.

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

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

Qual canal devo usar?

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

Quando usar Flush()

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

Use Flush() quando:

  • O aplicativo está prestes a ser desligado e você quer garantir que a telemetria seja enviada antes da saída.
  • Você está em um manipulador de exceção 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 da CLI que sai rapidamente.

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

Módulos de telemetria

O Application Insights coleta automaticamente a telemetria sobre cargas de trabalho específicas sem a necessidade de acompanhamento manual do usuário.

Os módulos de coleta automática a seguir estão habilitados por padrão. Você pode desabilitá-los ou configurá-los para alterar o comportamento padrão deles.

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.

Area Descrição
Acompanhamento de solicitações Coleta telemetria de solicitação (tempo de resposta, código de resultado) para solicitações da Web de entrada.

Módulo:Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.Web
Acompanhamento de dependência Coleta telemetria sobre dependências de saída (chamadas HTTP, chamadas SQL). Para trabalhar no IIS, instale o Agente de Application Insights. Também é possível escrever o acompanhamento de dependência personalizado usando a API TrackDependency. Dá suporte à autoinstrumentação com o Serviço de Aplicativo e o monitoramento de VMs e conjuntos de dimensionamento de máquinas virtuais.

Módulo:Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.DependencyCollector
Contadores de desempenho Coleta Contadores de Desempenho do Windows (CPU, memória, carga de rede de instalações do IIS). Especifique quais contadores (incluindo os personalizados). Para obter mais informações, consulte Coletar contadores de desempenho do sistema.

Módulo:Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
NuGet:Microsoft.ApplicationInsights.PerfCounterCollector
Contadores de eventos Coleta .NET EventCounters. Recomendado para ASP.NET Core e multissistema em vez dos contadores de desempenho do Windows.

Módulo:EventCounterCollectionModule (SDK ≥ 2.8.0)
Métricas dinâmicas (QuickPulse) Coleta a telemetria para o painel Live Metrics.

Módulo:QuickPulseTelemetryModule
Pulsações (Serviço de Aplicativo) Envia pulsações e métricas personalizadas para o ambiente do Serviço de Aplicativo.

Módulo:AppServicesHeartbeatTelemetryModule
Pulsações (VMs e conjuntos de dimensionamento de máquinas virtuais) Envia pulsações e métricas personalizadas para o ambiente de VM do Azure.

Módulo:AzureInstanceMetadataTelemetryModule
Telemetria de diagnóstico Relata erros no código de instrumentação do Application Insights (por exemplo, contadores ausentes, exceções ITelemetryInitializer). A telemetria de rastreamento é exibida na Pesquisa de Diagnóstico.

Módulo:Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
NuGet:Microsoft.ApplicationInsights

Observação: se você instalar esse pacote apenas, o arquivo ApplicationInsights.config não será criado automaticamente.
Modo de desenvolvedor (depurador anexado) Força o TelemetryChannel a enviar de itens imediatamente quando o depurador é anexado. Reduz a latência, mas aumenta a sobrecarga de CPU/rede.

Módulo:Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
NuGet:Application Insights Windows Server
Acompanhamento de exceções (Web) Rastreia exceções sem tratamento em aplicativos Web. Consulte Falhas e exceções

Módulo:Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.Web
Acompanhamento de exceção (não observado/sem tratamento) Controla exceções de tarefa não observadas e exceções sem tratamento para funções de trabalho, serviços Windows e aplicativos de console.

Módulos:
 • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule
 • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule
NuGet:Microsoft.ApplicationInsights.WindowsServer
Acompanhamento de EventSource Envia eventos EventSource configurados para o Application Insights como rastreamentos.

Módulo:Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
NuGet:Microsoft.ApplicationInsights.EventSourceListener
Coletor ETW Envia eventos de provedor ETW configurados para o Application Insights como rastreamentos.

Módulo:Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
NuGet:Microsoft.ApplicationInsights.EtwCollector
API principal (não um módulo) API principal usada por outros componentes de telemetria e para telemetria personalizada.

Módulo:Microsoft.ApplicationInsights package
NuGet:Microsoft.ApplicationInsights
Observação: se você instalar esse pacote apenas, o arquivo ApplicationInsights.config não será criado automaticamente.
ASP.NET Core
Area Descrição
Acompanhamento de solicitações Acompanhamento de solicitações integrado, por meio da integração do Application Insights no ASP.NET Core.

Módulo:nenhuma classe de módulo separada.
NuGet:Microsoft.ApplicationInsights.AspNetCore
Acompanhamento de dependência Por meio do Coletor de Dependências.

NuGet:Microsoft.ApplicationInsights.DependencyCollector
Contadores de desempenho somente Windows! Em plataforma cruzada, use EventCounterCollectionModule (consulte a próxima linha).

NuGet:Microsoft.ApplicationInsights.PerfCounterCollector
Contadores de eventos Coleta .NET EventCounters. Recomendado para ASP.NET Core e multissistema em vez dos contadores de desempenho do Windows.

Módulo:EventCounterCollectionModule (SDK 2.8.0 e superior)
NuGet:Microsoft.ApplicationInsights.EventCounterCollector
Métricas dinâmicas (QuickPulse) Métricas ao vivo habilitadas na integração do Application Insights com o ASP.NET Core.

Módulo:nenhuma classe de módulo separada.
NuGet:Microsoft.ApplicationInsights.AspNetCore
Coletor de pulsações (Serviço de Aplicativo) Envia pulsações (como métricas personalizadas) com detalhes sobre o Ambiente do Serviço de Aplicativo. Interno por meio do SDK base quando hospedado no Serviço de Aplicativo.

Módulo:nenhuma classe de módulo separada.
NuGet:Microsoft.ApplicationInsights.AspNetCore
Coletor de pulsações (VMs e conjuntos de dimensionamento de máquinas virtuais) Envia pulsações (como métricas personalizadas) com detalhes sobre o ambiente de VM do Azure. Integrado por meio do SDK base quando hospedado em VMs do Azure e conjuntos de escalonamento de máquinas virtuais do Azure.

Módulo:nenhuma classe de módulo separada.
NuGet:Microsoft.ApplicationInsights.AspNetCore
Telemetria de diagnóstico Relata erros no próprio código de instrumentação do Application Insights (por exemplo, não é possível acessar contadores de desempenho, ITelemetryInitializer gera uma exceção). A telemetria de rastreamento é exibida na Pesquisa de Diagnóstico.

Módulo:Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
NuGet:Microsoft.ApplicationInsights
Modo de desenvolvedor (depurador anexado) Mesmo comportamento disponível; A classe faz parte do pacote Windows Server.

Módulo:Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
NuGet:Microsoft.ApplicationInsights.WindowsServer
Acompanhamento de exceções (Web) Acompanhamento automático de exceções na integração do ASP.NET Core Application Insights

Módulo:nenhuma classe de módulo separada.
NuGet:Microsoft.ApplicationInsights.AspNetCore
Acompanhamento de exceção (não observado/sem tratamento) Comportamento semelhante por meio da execução/integração do ASP.NET Core; os nomes das classes são específicos do Windows Server.

NuGet:Microsoft.ApplicationInsights.WindowsServer
Acompanhamento de EventSource Envia eventos EventSource configurados para o Application Insights como rastreamentos.

Módulo:Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
NuGet:Microsoft.ApplicationInsights.EventSourceListener
Coletor ETW ETW (somente Windows). Envia eventos de provedor ETW configurados para o Application Insights como rastreamentos.

Módulo:Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
NuGet:Microsoft.ApplicationInsights.EtwCollector
API principal (não um módulo) API principal usada por outros componentes de telemetria e para telemetria personalizada.

Módulo:Microsoft.ApplicationInsights package
NuGet:Microsoft.ApplicationInsights

Configurar módulos de telemetria

ASP.NET

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

  • Configurar DependencyTrackingTelemetryModule (habilitar a injeção de cabeçalho W3C).
  • Configurar EventCounterCollectionModule (limpar padrões e adicionar um único contador).
  • Desabilite a coleção de contadores de desempenho removendo PerformanceCollectorModule.
<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>

Observação

O conjunto exato de módulos presentes em seu ApplicationInsights.config depende de quais pacotes do SDK você instalou.

ASP.NET Core

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

Para configurar qualquer TelemetryModule padrão, use o método de extensão ConfigureTelemetryModule<T> em IServiceCollection, conforme mostrado no seguinte exemplo:

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 do SDK 2.12.2 e posteriores, você poderá 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 das configurações ApplicationInsightsServiceOptions:

Configurações Descrição Default
EnablePerformanceCounterCollectionModule Habilita/desabilita PerformanceCounterCollectionModule. Verdade
EnableRequestTrackingTelemetryModule Habilita/desabilita RequestTrackingTelemetryModule. Verdade
EnableEventCounterCollectionModule Habilita/desabilita EventCounterCollectionModule. Verdade
EnableDependencyTrackingTelemetryModule Habilita/desabilita DependencyTrackingTelemetryModule. Verdade
EnableAppServicesHeartbeatTelemetryModule Habilita/desabilita AppServicesHeartbeatTelemetryModule. Verdade
HabilitarAzureInstanceMetadataTelemetryModule Habilita/desabilita AzureInstanceMetadataTelemetryModule. Verdade
EnableQuickPulseMetricStream Habilitar/desabilitar o recurso LiveMetrics. Verdade
EnableAdaptiveSampling Habilita/Desabilita a Amostragem Adaptável. Verdade
AtivarBatimentoCardíaco Habilitar/desabilitar o recurso de pulsações. Ele periodicamente (padrão de 15 minutos) envia uma métrica personalizada chamada HeartbeatState com informações sobre o runtime, como a versão do .NET e informações do ambiente do Azure, se aplicável. Verdade
AddAutoCollectedMetricExtractor Habilitar/desabilitar o AutoCollectedMetrics extractor. Esse processador de telemetria envia métricas pré-agregadas sobre solicitações/dependências antes que a amostragem ocorra. Verdade
RequestCollectionOptions.TrackExceptions Habilitar/desabilitar o relatório de monitoramento de exceções sem tratamento pelo módulo de coleta de solicitações. False em netstandard2.0 (porque as exceções são acompanhadas com ApplicationInsightsLoggerProvider). Caso contrário, true.
HabilitarMóduloDeTelemetriaDiagnóstica Habilita/desabilita DiagnosticsTelemetryModule. Desabilitar faz com que as seguintes configurações sejam ignoradas: EnableHeartbeat, EnableAzureInstanceMetadataTelemetryModule e EnableAppServicesHeartbeatTelemetryModule. Verdade

Confira as definições configuráveis no ApplicationInsightsServiceOptions para obter a lista mais atualizada.

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

No SDK do Microsoft.ApplicationInsights.AspNetCore versão 2.15.0 e posterior, defina todas as configurações disponíveis em ApplicationInsightsServiceOptions, incluindo ConnectionString. Use a instância de IConfiguration do 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) para ASP.NET Core 6.0 ou services.AddApplicationInsightsTelemetry(aiOptions) para ASP.NET Core 3.1 e anteriores for usado, ele substituirá as configurações de Microsoft.Extensions.Configuration.IConfiguration.

Serviço de Trabalho

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

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

Os módulos de autocolleção a seguir são habilitados por padrão. Esses módulos são responsáveis por coletar automaticamente a telemetria. Você pode desabilitá-los ou configurá-los para alterar o comportamento padrão deles.

  • DependencyTrackingTelemetryModule
  • PerformanceCollectorModule
  • QuickPulseTelemetryModule
  • AppServicesHeartbeatTelemetryModule (no momento, há um problema envolvendo este módulo de telemetria. Para obter uma solução alternativa 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 vez de Microsoft.ApplicationInsights.AspNetCore.Extensions no SDK do ASP.NET Core.

A tabela a seguir lista as configurações comumente usadas em ApplicationInsightsServiceOptions.

Configurações Descrição Default
EnableQuickPulseMetricStream Habilitar/desabilitar o recurso de métricas dinâmicas. Verdade
EnableAdaptiveSampling Habilita/Desabilita a Amostragem Adaptável. Verdade
AtivarBatimentoCardíaco Habilitar/desabilitar o recurso Heartbeats, que periodicamente (padrão de 15 minutos) envia uma métrica personalizada chamada "HeartBeatState" com informações sobre o tempo de execução, como a versão do .NET e, se aplicável, o ambiente do Azure. Verdade
AddAutoCollectedMetricExtractor Habilite/desabilite o extrator AutoCollectedMetrics, que é um processador de telemetria que envia métricas pré-configuradas sobre solicitações/dependências antes da amostragem ocorrer. Verdade
HabilitarMóduloDeTelemetriaDiagnóstica Habilita/desabilita DiagnosticsTelemetryModule. Desabilitar essa configuração faz com que as seguintes configurações sejam ignoradas: EnableHeartbeat, e EnableAzureInstanceMetadataTelemetryModuleEnableAppServicesHeartbeatTelemetryModule. Verdade

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

Desabilitar telemetria

ASP.NET

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

ASP.NET Core

Se quiser desabilitar a telemetria de modo condicional e dinâmico, você pode resolver a instância TelemetryConfiguration com um contêiner de injeção de dependência do ASP.NET Core em qualquer lugar do seu código e definir o sinalizador DisableTelemetry nele.

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. Ele não impede que nenhum módulo de coleta automática colete telemetria. Caso queira remover um módulo de coleta automática específico, consulte os módulos de telemetria.

Serviço de Trabalho

Se quiser desabilitar a telemetria de modo condicional e dinâmico, você pode resolver a instância TelemetryConfiguration com um contêiner de injeção de dependência do ASP.NET Core em qualquer lugar do seu código e definir o sinalizador DisableTelemetry nele.

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

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

string de conexão

Essa configuração determina o recurso application insights no qual seus dados são exibidos. 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 aplicativo para recursos diferentes, poderá 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 de TelemetryClient, incluindo módulos de telemetria padrão, execute esta etapa em um método de inicialização, como global.aspx.cs em um serviço de 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 você quiser enviar um conjunto específico de eventos para um recurso diferente, poderá 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 em Program.cs durante a inicialização do aplicativo usando o TelemetryConfiguration do contêiner 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 você quiser enviar um conjunto específico de eventos para um recurso diferente, poderá criar uma nova instância TelemetryClient e definir seu connection string explicitamente:

using Microsoft.ApplicationInsights;

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

Provedor de ID de Aplicativo

Observação

Para ASP.NET, esse provedor está disponível a partir do SDK v2.6.0*.

A finalidade desse provedor é pesquisar uma ID do aplicativo com base em uma string de conexão. O ID do aplicativo está incluído em RequestTelemetry e DependencyTelemetry e é usado para determinar a correlação no portal.

Essa funcionalidade está disponível por meio da configuração TelemetryConfiguration.ApplicationIdProvider.

Interface: IApplicationIdProvider (Provedor de ID de Aplicação)

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string connectionString, out string applicationId);
}

Fornecemos duas implementações no SDK do Microsoft.ApplicationInsights : ApplicationInsightsApplicationIdProvider e DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider (Provedor de ID de Aplicação de Insights de Aplicativos)

Esse wrapper é para nossa API de Perfil. Ele limita as solicitações e os resultados do cache. Esse provedor é incluído automaticamente ao instalar 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.

Caso precise configurar um proxy, recomendamos fazer proxy do endereço base e garantir que o caminho inclua /api/profiles/{0}/appId. Em runtime, {0} é substituído pela cadeia de conexão para cada solicitação.

ASP.NET

Configuração de exemplo por meio de 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>

Configuração de exemplo por meio de código

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();
ASP.NET Core

Observação

Em ASP.NET Core, não há nenhum arquivo ApplicationInsights.config. A configuração é feita por meio da DI (injeção de dependência) em Program.cs ou Startup.cs.

É possível substituir o provedor padrão ou personalizar seu ProfileQueryEndpoint.

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 provedor estático depende dos pares de string de conexão e ID do aplicativo que você configurou.

Essa classe tem a propriedade Defined, que é um Dictionary<string,string> dos pares de cadeia de conexão/ID do aplicativo.

Essa classe tem a propriedade opcional Next, que pode ser usada para configurar outro provedor a ser usado quando um connection string é solicitado que não existe em sua configuração.

ASP.NET

Configuração de exemplo por meio de 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>

Configuração de exemplo por meio de 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();

Adicionar monitoramento do lado do cliente

As seções anteriores forneceram orientações sobre métodos para configurar o monitoramento do lado do servidor de forma automática e manual. Para adicionar o monitoramento do lado do cliente, use o SDK do JavaScript cliente. Você pode monitorar as transações do lado do cliente de qualquer página da Web adicionando um Script do Carregador de SDK do JavaScript (Web) antes da marca de fechamento </head> do HTML da página.

Embora seja possível adicionar manualmente o Script do Carregador do SDK do JavaScript (Web) ao cabeçalho de cada página HTML, recomendamos que você adicione o Script do Carregador do SDK do JavaScript (Web) a uma página principal. Essa ação injeta o script carregador do SDK de JavaScript (Web) em todas as páginas de um site.

ASP.NET

Para o aplicativo ASP.NET MVC baseado em modelo deste artigo, o arquivo que você precisa editar é _Layout.cshtml. Encontre-o em Exibições>Compartilhado. Para adicionar o monitoramento do lado do cliente, abra _Layout.cshtml e siga as instruções de configuração baseadas no Script do Carregador do SDK do JavaScript (Web) no artigo sobre configuração do SDK do JavaScript do lado do cliente.

ASP.NET Core

Se seu aplicação possui componentes do lado do cliente, siga as próximas etapas para começar a coletar telemetria de uso usando a injeção do script carregador do SDK JavaScript (Web) por configuração.

  1. Em _ViewImports.cshtml, adicione a injeção:

    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

  2. Em _Layout.cshtml, insira HtmlHelper no final da seção <head>, antes de qualquer outro script. Se você quiser gerar relatórios sobre qualquer telemetria personalizada de JavaScript da página, insira-a após este snippet:

        @Html.Raw(JavaScriptSnippet.FullScript)
</head>

Como alternativa ao uso FullScript, ScriptBody está disponível a partir do SDK do Application Insights para ASP.NET Core versão 2.14. Use ScriptBody se você precisar controlar a tag <script> 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 referenciados anteriormente são de um modelo de aplicativo MVC padrão. Se você quiser habilitar corretamente o monitoramento do lado do cliente para o aplicativo, o Script de Carregador de SDK do JavaScript (Web) deverá aparecer na seção <head> de cada página do aplicativo que deseja monitorar. Adicione o Script de Carregador de SDK do JavaScript (Web) a _Layout.cshtml em um modelo de aplicativo para habilitar o monitoramento do lado do cliente.

Se o projeto não incluir _Layout.cshtml, você ainda poderá adicionar o monitoramento do lado do cliente adicionando o script carregador de SDK do JavaScript (Web) a um arquivo equivalente que controla o <head> de todas as páginas no aplicativo. Como alternativa, é possível adicionar o script carregador de SDK do JavaScript (Web) a várias páginas, mas não recomendamos isso.

Observação

A injeção de JavaScript fornece uma experiência de configuração padrão. Se você precisar de configuração além de definir a cadeia de conexão, será necessário remover a autoinjeção conforme descrito anteriormente e adicionar manualmente o SDK JavaScript.

API principal para eventos e métricas personalizados

Insira algumas linhas de código em seu aplicativo para descobrir o que os usuários estão fazendo com ele ou para ajudar a diagnosticar problemas. Você pode enviar telemetria de aplicativos de dispositivo e desktop, clientes Web e servidores Web. Use a API de telemetria principal do Application Insights para enviar eventos e métricas personalizados e suas próprias versões da telemetria padrão. Essa API é a mesma API que os coletores de dados padrão do Application Insights usam.

Resumo da API

A API principal é uniforme em todas as plataformas, além de algumas variações como GetMetric (somente .NET).

Método Usado para
TrackPageView Páginas, telas, painéis ou formulários.
TrackEvent Ações do usuário e outros eventos. Usado para acompanhar o comportamento do usuário ou monitorar o desempenho.
GetMetric Métricas zero e multidimensionais, agregação configurada centralmente, somente C#.
TrackMetric Medidas de desempenho, como comprimentos de fila não relacionados a eventos específicos.
TrackException Registro de exceções para diagnóstico. Rastreie onde eles ocorrem em relação a outros eventos e examine os rastreamentos de pilha.
TrackRequest Registrando em log a frequência e a duração das solicitações de servidor para análise de desempenho.
TrackTrace Mensagens de log de Diagnóstico de Recursos. Você também pode capturar logs de terceiros.
TrackDependency Registrar em log a duração e a frequência das chamadas para componentes externos dos quais seu aplicativo depende.

Você pode anexar propriedades e métricas à maioria dessas chamadas de telemetria.

Pré-requisitos

Se você ainda não possui uma referência ao SDK do Application Insights:

  1. Adicione o SDK do Application Insights ao seu projeto.

  2. No código do dispositivo ou servidor Web, inclua:

    using Microsoft.ApplicationInsights;

Obter uma instância do TelemetryClient

Obter uma instância de TelemetryClient:

Observação

Se você usar Azure Functions v2+ ou Azure WebJobs v3+, consulte Monitor Azure Functions.

Observação

Para aplicativos ASP.NET Core e para aplicações Non-HTTP/Worker para .NET/.NET Core, obtenha uma instância do contêiner de injeção de dependência TelemetryClient, conforme explicado na documentação respectiva.

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 de entrada são capturadas automaticamente. Talvez você queira criar mais instâncias de TelemetryClient para outros módulos do seu aplicativo. 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 identificar o computador. Essas informações são anexadas a todos os eventos que a instância envia.

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

Observação

TelemetryClient é thread-safe.

TrackEvent

No Application Insights, um evento personalizado é um ponto de dados que você pode exibir no Metrics Explorer como uma contagem agregada e na Pesquisa como ocorrências individuais. (Não está relacionado ao MVC ou a outros "eventos") da estrutura.

Insira TrackEvent chamadas em seu código para contar vários eventos. Por exemplo, talvez você queira acompanhar a frequência com que os usuários escolhem um recurso específico. Ou talvez você queira saber com que frequência eles atingem determinadas metas ou cometem tipos específicos de erros.

Por exemplo, em um aplicativo de jogo, envie um evento sempre que um usuário ganhar o jogo:

telemetry.TrackEvent("WinGame");

Eventos personalizados no Log Analytics

A telemetria está disponível na customEvents tabela na guia Logs do Application Insights ou na experiência de uso. Os eventos podem vir de trackEvent(..) ou do plug-in de Coleta Automática do Click Analytics.

Se a amostragem estiver em operação, a itemCount propriedade mostrará um valor maior que 1. Por exemplo, itemCount==10 significa que, de 10 chamadas para trackEvent(), o processo de amostragem transmitiu apenas uma delas. Para obter uma contagem correta de eventos personalizados, use código como customEvents | summarize sum(itemCount).

Observação

itemCount tem um valor mínimo de um; o registro em si representa uma entrada.

GetMetric

Para saber como usar efetivamente a chamada GetMetric() para capturar métricas localmente pré-agregadas para aplicativos .NET e .NET Core, consulte Conjunto de métricas customizadas em .NET e .NET Core.

TrackMetric

Observação

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric não é o método preferencial para enviar métricas. As métricas devem ser sempre pré-agregadas ao longo de um período de tempo antes de serem enviadas. Use uma das sobrecargas de GetMetric(..) para obter um objeto de métrica a fim de acessar as funcionalidades de pré-agregação do SDK.

Se você estiver implementando sua própria lógica de pré-agregação, poderá usar o TrackMetric() método para enviar as agregações resultantes. Se o aplicativo exigir o envio de um item de telemetria separado em todas as ocasiões sem agregação ao longo do tempo, você provavelmente terá um caso de uso para telemetria de eventos. Consulte TelemetryClient.TrackEvent(Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

O Application Insights pode mapear métricas que não estão anexadas a eventos específicos. Por exemplo, você pode monitorar um comprimento de fila em intervalos regulares. Com as métricas, as medidas individuais são de menor interesse do que as variações e tendências e, portanto, os gráficos estatísticos são úteis.

Para enviar métricas para o Application Insights, você pode usar a TrackMetric(..) API. Há duas maneiras de enviar uma métrica:

  • Valor único. Sempre que você executa uma medida em seu aplicativo, envia o valor correspondente para o Application Insights.

    Por exemplo, suponha que você tenha uma métrica que descreva o número de itens em um contêiner. Durante um período de tempo específico, primeiro você coloca três itens no contêiner e, em seguida, remove dois itens. Assim, você ligaria TrackMetric duas vezes. Primeiro, você passaria o valor 3 e, em seguida, passaria o valor -2. O Application Insights armazena os dois valores para você.

  • Agregação. Quando você trabalha com métricas, cada medida raramente é de interesse. Em vez disso, um resumo do que aconteceu durante um determinado período de tempo é importante. Chamamos essa síntese de agregação.

    No exemplo anterior, a soma da métrica de agregação para esse período de tempo é 1 e a contagem dos valores de métrica é 2. Ao usar a abordagem de agregação, você invoca TrackMetric apenas uma vez por período de tempo e envia os valores agregados. Recomendamos essa abordagem porque ela pode reduzir significativamente a sobrecarga de custo e desempenho enviando menos pontos de dados para o Application Insights, enquanto ainda coleta todas as informações relevantes.

Exemplos de valor único

Para enviar um único valor de métrica:

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

Métricas personalizadas no Log Analytics

A telemetria está disponível na tabela no customMetricsApplication Insights Analytics. Cada linha representa uma chamada em trackMetric(..) seu aplicativo.

  • valueSum: a soma das medidas. Para obter o valor médio, divida por valueCount.
  • valueCount: o número de medições que foram agregadas nesta trackMetric(..) chamada.

Observação

valueCount tem um valor mínimo de um; o registro em si representa uma entrada.

Exibições de página

Em um aplicativo ou página da Web, a telemetria de exibição de página é enviada por padrão quando cada tela ou página é carregada. Mas você pode alterar o padrão para acompanhar exibições de página em momentos mais ou diferentes. Por exemplo, em um aplicativo que exibe guias ou painéis, talvez você queira rastrear uma página sempre que o usuário abrir um novo painel.

Os dados do usuário e da sessão são enviados como propriedades, juntamente com exibições de página, para que os gráficos de usuário e de sessão ganhem vida quando houver telemetria de exibição de página.

Exibições de página personalizadas

telemetry.TrackPageView("GameReviewPage");

Telemetria de página em Log Analytics

No Log Analytics, duas tabelas mostram dados das operações do navegador:

  • pageViews: contém dados sobre a URL e o título da página.
  • browserTimings: contém dados sobre o desempenho do cliente, como o tempo necessário para processar os dados de entrada.

Para descobrir quanto tempo o navegador leva para processar páginas diferentes:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

Para descobrir a popularidade de navegadores diferentes:

pageViews
| summarize count() by client_Browser

Para associar exibições de página a chamadas AJAX, conecte com dependências:

pageViews
| join (dependencies) on operation_Id

TrackRequest

O SDK do servidor usa TrackRequest para logar requisições HTTP.

Você também pode chamá-lo por conta própria se quiser simular solicitações em um contexto em que não tenha o módulo de serviço Web em execução.

A maneira recomendada de enviar telemetria de solicitação é onde a solicitação atua como um contexto de operação.

Contexto da operação

Você pode correlacionar itens de telemetria ao associá-los ao contexto da operação. O módulo de acompanhamento de solicitações padrão faz isso para exceções e outros eventos que são enviados enquanto uma solicitação HTTP está sendo processada. Em Pesquisa e Análise, você pode encontrar facilmente todos os eventos associados à solicitação usando sua ID de operação.

Ao acompanhar a telemetria manualmente, a maneira mais fácil de garantir a correlação de telemetria é usando esse padrão:

// 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 a correlação de telemetria no Application Insights.

Junto com a configuração de um contexto de operação, StartOperation cria um item de telemetria do tipo que você especificar. Ele envia o item de telemetria quando você descarta a operação ou se você chama StopOperationexplicitamente. Se você usar RequestTelemetry como o tipo de telemetria, sua duração será definida como o intervalo cronometrado entre iniciar e parar.

Os itens de telemetria relatados dentro de um escopo de operação passam a ser considerados como parte dessa operação. Contextos de operação podem ser aninhados.

Na Pesquisa, o contexto da operação é usado para criar a lista Itens Relacionados .

Captura de tela que mostra a lista Itens Relacionados.

Para obter mais informações sobre o acompanhamento de operações personalizadas, consulte Acompanhar operações personalizadas com o SDK .NET do Application Insights.

Solicitações no Log Analytics

No Application Insights Analytics, as solicitações aparecem na requests tabela.

Se a amostragem estiver em operação, a itemCount propriedade mostrará um valor maior que 1. Por exemplo, itemCount==10 significa que, de 10 chamadas para trackRequest(), o processo de amostragem transmitiu apenas uma delas. Para obter uma contagem correta de solicitações e duração média segmentada por nomes de solicitação, use código como:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Enviar exceções ao Application Insights:

Os relatórios incluem os rastreamentos de pilha.

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

Os SDKs capturam muitas exceções automaticamente, para que você nem sempre precise chamar TrackException explicitamente.

Exceções no Log Analytics

No Application Insights Analytics, as exceções aparecem na exceptions tabela.

Se a amostragem estiver em operação, a itemCount propriedade mostrará um valor maior que 1. Por exemplo, itemCount==10 significa que, de 10 chamadas para trackException(), o processo de amostragem transmitiu apenas uma delas. Para obter uma contagem correta de exceções segmentada por tipo de exceção, use código como:

exceptions
| summarize sum(itemCount) by type

A maioria das informações de pilha importantes já é extraída em variáveis separadas, mas você pode separar a details estrutura para obter mais. Como essa estrutura é dinâmica, você deve converter o resultado para o tipo esperado. Por exemplo:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Para associar exceções às solicitações relacionadas, use uma junção:

exceptions
| join (requests) on operation_Id

TrackTrace

Use TrackTrace para ajudar a diagnosticar problemas enviando uma "trilha de navegação" para Application Insights. Você pode enviar partes de dados de diagnóstico e inspecioná-los na Pesquisa.

Em .NET Log adapters, use essa API para enviar logs de terceiros para o portal.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

Registre um evento de diagnóstico, como entrar ou sair de um método.

Parâmetro Descrição
message Dados de diagnóstico. Pode ser muito mais longo do que um nome.
properties Mapa de string para string. Mais dados são usados para filtrar exceções no portal. O padrão é vazio.
severityLevel Valores com suporte: SeverityLevel.ts.

Você pode pesquisar no conteúdo da mensagem, mas ao contrário dos valores de propriedade, não é possível filtrar nele.

O limite de tamanho para message é muito maior do que o limite de propriedades. Uma vantagem de TrackTrace é que você pode colocar dados relativamente longos na mensagem. Por exemplo, você pode codificar dados POST lá.

Você também pode adicionar um nível de severidade à sua mensagem. E, assim como outra telemetria, você pode adicionar valores de propriedade para ajudá-lo a filtrar ou pesquisar diferentes conjuntos de traços. Por exemplo:

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

Na Pesquisa, você pode filtrar facilmente todas as mensagens de um nível de severidade específico relacionado a um banco de dados específico.

Rastreamentos em Log Analytics

No Application Insights Analytics, as chamadas para TrackTrace aparecem na tabela traces.

Se a amostragem estiver em operação, a itemCount propriedade mostrará um valor maior que 1. Por exemplo, itemCount==10 significa que, de 10 chamadas para trackTrace(), o processo de amostragem transmitiu apenas uma delas. Para obter uma contagem correta de chamadas de rastreamento, use código como traces | summarize sum(itemCount).

TrackDependency

Use a TrackDependency chamada para acompanhar os tempos de resposta e as taxas de êxito das chamadas para uma parte externa do código. Os resultados aparecem nos gráficos de dependência no portal. O snippet de código a seguir deve ser adicionado sempre que houver uma chamada de dependência.

Observação

Para .NET e .NET Core, você também pode usar o método TelemetryClient.StartOperation (extensão) que preenche as propriedades DependencyTelemetry necessárias para correlação e algumas outras propriedades, como a hora de início e a duração, para que você não precise criar um temporizador personalizado como nos exemplos a seguir. Para obter mais informações, consulte a seção sobre o rastreamento de dependências externas em operações personalizadas no Track custom operations with Application Insights .NET SDK.

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);
}

Lembre-se de que os SDKs do servidor incluem um módulo de dependência que descobre e rastreia determinadas chamadas de dependência automaticamente, por exemplo, para bancos de dados e APIs REST. Você precisa instalar um agente no servidor para fazer o módulo funcionar.

Você usará essa chamada se quiser acompanhar as chamadas que o acompanhamento automatizado não captura.

Para desativar o módulo de controle de dependência padrão em C#, edite ApplicationInsights.config e exclua a referência para DependencyCollector.DependencyTrackingTelemetryModule.

Dependências no Log Analytics

No Application Insights Analytics, chamadas aparecem na tabela .

Se a amostragem estiver em operação, a itemCount propriedade mostrará um valor maior que 1. Por exemplo, itemCount==10 significa que, de 10 chamadas para trackDependency(), o processo de amostragem transmitiu apenas uma delas. Para obter uma contagem correta de dependências segmentadas pelo componente de destino, use código como:

dependencies
| summarize sum(itemCount) by target

Para associar dependências às solicitações relacionadas, use uma junção:

dependencies
| join (requests) on operation_Id

Liberando dados

Normalmente, o SDK envia dados em intervalos fixos, normalmente 30 segundos ou sempre que o buffer está cheio, que normalmente é de 500 itens. Em alguns casos, talvez você queira liberar o buffer. Um exemplo é se você está usando o SDK em um aplicativo que é desligado.

Ao usar Flush(), recomendamos este padrão:

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

Ao usar FlushAsync(), recomendamos este padrão:

await telemetryClient.FlushAsync()
// No need to sleep

É recomendável sempre liberar como parte do desligamento do aplicativo para garantir que a telemetria não seja perdida.

Observação

Revisar configuração do Autoflush: Habilitar autoflush em seu arquivo web.config pode levar à degradação de desempenho em aplicativos .NET monitorados com o Application Insights. Com o salvamento automático habilitado, cada invocação de métodos System.Diagnostics.Trace.Trace* resulta em itens de telemetria individuais sendo enviados como solicitações da Web distintas separadas para o serviço de ingestão. Isso pode potencialmente causar esgotamento de rede e armazenamento em seus servidores Web. Para melhorar o desempenho, é recomendável desabilitar a autoflush e, também, utilizar o ServerTelemetryChannel, projetado para uma transmissão de dados de telemetria mais eficaz.

A função é assíncrona para o canal de telemetria do servidor.

Usuários autenticados

Por padrão, em um aplicativo web, os usuários são identificados com cookies. Um usuário poderá ser contado mais de uma vez se acessar seu aplicativo de um computador ou navegador diferente ou se excluir cookies.

Se os usuários entrarem em seu aplicativo, você poderá obter uma contagem mais precisa definindo a ID de usuário autenticada no código do navegador. Não é necessário usar o nome de entrada real do usuário. Precisa apenas ser uma identificação exclusiva para este usuário. Ele não deve incluir espaços nem nenhum dos caracteres ,;=|.

A ID do usuário também é definida em um cookie de sessão e enviada para o servidor. Se o SDK do servidor estiver instalado, a ID de usuário autenticada será enviada como parte das propriedades de contexto da telemetria do cliente e do servidor. Em seguida, você pode filtrar e pesquisar nele.

Se o aplicativo agrupar usuários em contas, você também poderá passar um identificador para a conta. As mesmas restrições de caractere se aplicam.

No Metrics Explorer, você pode criar um gráfico que conta Usuários Autenticados e Contas de Usuários.

Você também pode pesquisar pontos de dados do cliente com nomes de usuário e contas específicas.

Observação

A propriedade EnableAuthenticationTrackingJavaScript na classe ApplicationInsightsServiceOptions no SDK do .NET Core simplifica a configuração javaScript necessária para injetar o nome de usuário como a ID de Autenticação para cada rastreamento enviado pelo SDK javaScript do Application Insights.

Quando essa propriedade é definida como true, o nome de usuário do usuário no ASP.NET Core é impresso juntamente com client-side telemetry. Por esse motivo, adicionar appInsights.setAuthenticatedUserContext manualmente não é mais necessário porque ele já é injetado pelo SDK para ASP.NET Core. A ID de autenticação também é enviada para o servidor onde o SDK no .NET Core identifica e o usa para qualquer telemetria do lado do servidor, conforme descrito na referência à API JavaScript.

Para aplicativos JavaScript que não funcionam da mesma maneira que ASP.NET Core MVC, como aplicativos Web SPA, você ainda precisa adicionar appInsights.setAuthenticatedUserContext manualmente.

Filtrar, pesquisar e segmentar seus dados usando propriedades

Você pode anexar propriedades e medidas a seus eventos, métricas, exibições de página, exceções e outros dados de telemetria.

As propriedades são valores de cadeia de caracteres que você pode usar para filtrar sua telemetria nos relatórios de uso. Por exemplo, se seu aplicativo fornecer vários jogos, você poderá anexar o nome do jogo a cada evento para que você possa ver quais jogos são mais populares.

Há um limite de 8.192 no comprimento da cadeia de caracteres. Se você quiser enviar grandes partes de dados, use o parâmetro de mensagem de TrackTrace.

As métricas são valores numéricos que podem ser apresentados graficamente. Por exemplo, talvez você queira ver se há um aumento gradual nas pontuações que seus jogadores alcançam. Os grafos podem ser segmentados pelas propriedades enviadas com o evento para que você possa obter grafos separados ou empilhados para jogos diferentes.

Os valores de métrica devem ser maiores ou iguais a 0 para serem exibidos corretamente.

Há alguns limites no número de propriedades, valores de propriedade e métricas que você pode usar.

// 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);

Importante

Verifique se você não registra informações de identificação pessoal nas propriedades.

Maneira alternativa de definir propriedades e métricas

Se for mais conveniente, você poderá coletar os parâmetros de um evento em um objeto separado:

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

Aviso

Não reutilize a mesma instância de item de telemetria (event neste exemplo) para chamar Track*() várias vezes. Essa prática pode fazer com que a telemetria seja enviada com configuração incorreta.

Medidas e propriedades personalizadas no Log Analytics

Em Log Analytics, as métricas e as propriedades personalizadas são mostradas nos atributos customMeasurements e customDimensions de cada registro de telemetria.

Por exemplo, se você adicionar uma propriedade chamada "game" à telemetria de requisição, essa consulta conta as ocorrências de diferentes valores de "game" e mostra a média da métrica personalizada "score".

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Observe que:

  • Quando você extrai um valor do customDimensions ou customMeasurements JSON, ele tem um tipo dinâmico, portanto, você deve convertê-lo ou fazer casting para tostring ou todouble.
  • Para levar em conta a possibilidade de amostragem, use sum(itemCount) não count().

Eventos de temporização

Às vezes, você deseja mapear quanto tempo leva para executar uma ação. Por exemplo, talvez você queira saber quanto tempo os usuários levam para considerar as opções em um jogo. Para obter essas informações, use o parâmetro de medida.

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);

Propriedades padrão para telemetria personalizada

Se você quiser definir valores de propriedade padrão para alguns dos eventos personalizados que você escreve, defina-os em uma TelemetryClient instância. Eles são anexados a todos os itens de telemetria enviados desse cliente.

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");

Chamadas de telemetria individuais podem substituir os valores padrão em seus dicionários de propriedades.

Para adicionar propriedades a todas as telemetrias, incluindo os dados de módulos de coleta padrão, implemente ITelemetryInitializer.

Desabilitar telemetria

Para interromper e iniciar dinamicamente a coleção e a transmissão da telemetria:

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Modo de desenvolvedor

Durante a depuração, é útil ter sua telemetria emitida pelo pipeline para que você possa ver os resultados imediatamente. Você também recebe outras mensagens que ajudam a rastrear problemas com a telemetria. Desative-o na produção porque pode diminuir a velocidade do aplicativo.

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Definir a chave de instrumentação para a telemetria personalizada selecionada

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

Cadeia de conexão dinâmica

Para evitar misturar a telemetria de ambientes de desenvolvimento, teste e produção, você pode criar recursos separados do Application Insights e alterar suas chaves, dependendo do ambiente.

Em vez de obter a chave de instrumentação do arquivo de configuração, você pode defini-la em seu código. Defina a chave em um método de inicialização, como global.aspx.cs em um serviço ASP.NET:

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

TelemetryContext

TelemetryClient tem uma propriedade Context, que contém valores que são enviados junto com todos os dados de telemetria. Eles normalmente são definidos pelos módulos de telemetria padrão, mas você também pode defini-los por conta própria. Por exemplo:

telemetry.Context.Operation.Name = "MyOperationName";

Se você definir qualquer um desses valores por conta própria, considere remover a linha relevante de ApplicationInsights.config para que seus valores e os valores padrão não fiquem confusos.

  • Componente: o aplicativo e sua versão.
  • Dispositivo: dados sobre o dispositivo em que o aplicativo está sendo executado. Em aplicativos Web, é o servidor ou o dispositivo cliente que envia telemetria.
  • InstrumentationKey: o recurso Application Insights no Azure em que a telemetria é exibida. Geralmente é obtido a partir de ApplicationInsights.config.
  • Local: a localização geográfica do dispositivo.
  • Operação: em aplicativos Web, a solicitação HTTP atual. Em outros tipos de aplicativo, você pode definir esse valor para agrupar eventos.
    • ID: um valor gerado que correlaciona eventos diferentes para que, ao inspecionar qualquer evento na Pesquisa de Diagnóstico, você possa encontrar itens relacionados.
    • Nome: um identificador, geralmente a URL da solicitação HTTP.
    • SyntheticSource: se não for nulo ou vazio, uma cadeia de caracteres que indica que a origem da solicitação foi identificada como um teste de robô ou web. Por padrão, ele é excluído dos cálculos no Metrics Explorer.
  • Sessão: a sessão do usuário. A ID é definida como um valor gerado, que é alterado quando o usuário não está ativo há algum tempo.
  • Usuário: Informações do usuário.

Limits

Há alguns limites no número de métricas e eventos por aplicativo, ou seja, por cadeia de conexão. Os limites dependem do plano de preços que você escolher.

Recurso Limite padrão Limite máximo Observações
Total de dados por dia 100 GB Fale com o suporte. Você pode definir um limite para reduzir os dados. Caso precise de mais dados, você pode aumentar o limite no portal, até 1.000 GB. Para capacidades maiores que 1.000 GB, envie um email para AIDataCap@microsoft.com.
Throttling 32.000 eventos por segundo Fale com o suporte. O limite é medido em um minuto.
Logs de retenção de dados De 30 a 730 dias 730 dias Este recurso é para Logs.
Métricas de retenção de dados 90 dias 90 dias Este recurso é para Metrics Explorer.
Retenção de resultados detalhados do Teste de disponibilidade em várias etapas 90 dias 90 dias Esse recurso fornece resultados detalhados de cada etapa.
Tamanho máximo do item de telemetria 64 KB 64 KB
Máximo de itens de telemetria por lote 64.000 64.000
Tamanho dos nomes de propriedade e métrica 150 150 Veja esquemas de tipo.
Tamanho da cadeia de caracteres do valor da propriedade 8.192 8.192 Veja esquemas de tipo.
Comprimento da mensagem de rastreamento e de exceção 32,768 32,768 Veja esquemas de tipo.
Contagem de testes de disponibilidade por recurso do Application Insights 100 100
Contagem de testes de disponibilidade por grupo de recursos 800 800 Consulte Azure Resource Manager
Máximo de redirecionamentos por teste de testes de disponibilidade 10 10
Testes de disponibilidade frequência mínima de teste 300 segundos Frequências de teste personalizadas ou inferiores a cinco minutos requerem implementações TrackAvailability personalizadas.
Retenção de dados do .NET Profiler e do Depurador de Instantâneos Duas semanas Entre em contato com o suporte. O limite máximo de retenção é de seis meses.
Dados do .NET Profiler enviados por dia Sem limite Não há limite.
Dados do Depurador de Instantâneos enviados por dia 30 instantâneos por dia por aplicativo monitorado Não há limite. O número de instantâneos coletados por aplicativo pode ser modificado por meio da configuração.

Para obter mais informações sobre preços e cotas, confira Cobrança do Application Insights.

Para evitar atingir o limite de taxa de dados, use amostragem.

Para determinar por quanto tempo os dados são mantidos, consulte Retenção de dados e privacidade.

Aplicativos de exemplo

Aplicativo de console do .NET Core: use este exemplo se você estiver usando um aplicativo de console escrito no .NET Core (2.0 ou superior) ou no .NET Framework (4.7.2 ou superior).

Tarefas em segundo plano no ASP.NET Core com HostedServices: use este exemplo se você estiver no ASP.NET Core e criando tarefas em segundo plano de acordo com as diretrizes oficiais.

.NET Core Worker Service: Use este exemplo se você tiver um aplicativo .NET Worker Service de acordo com as diretrizes oficiais.

Solução de problemas

Consulte os artigos de solução de problemas dedicados para .NET e Node.js.

Testar a conectividade entre o host do aplicativo e o serviço de ingestão

Os SDKs e agentes do Application Insights enviam telemetria para serem ingeridos como chamadas REST nos nossos pontos de extremidade de ingestão. Você pode testar a conectividade do servidor Web ou do computador host do aplicativo nos pontos de extremidade do serviço de ingestão usando clientes REST brutos do PowerShell ou comandos curl. Consulte Como solucionar problemas de ausência de telemetria de aplicativos no Azure Monitor Application Insights.

SDK do código-fonte aberto

Leia e contribua para o código para .NET e Node.js.

Notas de Lançamento

As Atualizações de Serviço também resumem as principais melhorias do Application Insights.

Próximas Etapas 

  • Last updated on