Monitorar aplicativos e serviços do .NET com o Application Insights (API Clássica)

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

Cenários com suporte

Adicionar Application Insights

Pré-requisitos

Criar um aplicativo Web básico

Se você ainda não tem um aplicativo Web funcional, use as diretrizes a seguir para criar um.

Adicionar o Application Insights automaticamente (Visual Studio)

Esta seção orienta você a adicionar automaticamente o Application Insights a um aplicativo Web baseado em modelo.

Adicionar o Application Insights manualmente (sem Visual Studio)

Esta seção orienta você a adicionar manualmente o Application Insights a um aplicativo Web baseado em modelo.

Verificar se o Application Insights recebe telemetria

Configurar telemetria

Nesta seção

• Métricas dinâmicas
• Rastreamentos (logs)
• Rastreamento distribuído
• Dependências
• Exceções
• Métricas personalizadas
• Operações personalizadas

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.

Habilitar métricas dinâmicas usando código para qualquer aplicativo .NET

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.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
            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-HERE";
            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();
            }
        }
    }
}

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

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
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-HERE";
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();
}

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

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

Rastreamentos (logs)

Esta seção explica como enviar logs de rastreamento de diagnóstico de ASP.NET ou aplicativos do 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.

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

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. No Gerenciador de Soluções, clique com o botão direito do mouse em seu projeto e selecione Gerenciar Pacotes NuGet.

2. Pesquise Application Insights.

3. Selecione um dos seguintes pacotes:

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

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

Instruções de instalação:

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

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

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

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

var app = builder.Build();

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

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

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

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

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

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

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

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

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 na Pesquisa de Transações todas as mensagens de um nível de severidade específico relacionado 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:

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

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

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.

Explorar na Pesquisa de Transações

No painel de visão geral do aplicativo no portal do Application Insights, selecione Pesquisa de Transações , 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.

Explorar nos Logs do Azure Monitor

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

Exemplo

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

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

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 criador de perfil de desempenho que funciona como pilhas de chamadas para arquiteturas de nuvem e microsserviços.

O Azure Monitor fornece duas experiências para consumir dados de rastreamento distribuídos: a exibição de diagnóstico de transação para uma única transação/solicitação e a exibição do mapa do aplicativo 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.

Example

Vamos examinar 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 de ações tem uma página chamada Ações que o navegador da Web do 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.

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: carrega a coleção de pares nome-valor das propriedades de rastreamento distribuído.

O Application Insights também define a extensão para o protocolo HTTP de correlação. Ele usa pares nome-valor de Request-Context para propagar a coleção de propriedades usadas pelo computador chamado ou chamador imediato. 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:

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/.NET Core, juntamente com a compatibilidade retroativa com o protocolo herdado Request-Id.

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 ao distribuído com a ajuda de Activity e DiagnosticSource

O SDK do .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 enviados com DependencyTrackingTelemetryModule, que é um módulo de telemetria que coleta dependências automaticamente. 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:

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.

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

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

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

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.

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

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.

Exceptions

Exceções em aplicativos Web podem ser relatadas com o Application Insights. Você pode correlacionar solicitações com falha com exceções e outros eventos no cliente e no servidor, para 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.

Diagnosticar falhas e exceções

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:

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

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

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.

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

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.

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

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 pode executar vários jogos, será possível localizar todos 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

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.

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

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

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

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

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

Web API

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.

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

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

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

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

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

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

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

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

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

WCF

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

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

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

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

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

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

            ai.TrackException(error);
            return false;
        }

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

Adicione o atributo 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 Agente do Application Insights do Azure Monitor no servidor, poderá obter um gráfico da taxa de exceções medida pelo .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 Application Insights do Azure Monitor para .NET e .NET Core têm dois métodos diferentes de coleta de 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.

Introdução ao método GetMetric

Para nossos exemplos, vamos usar um aplicativo básico do 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, aparece o loop while sendo executado várias vezes sem que a telemetria seja enviada na janela de saída do Visual Studio. Um único item de telemetria é enviado em torno da marca de 60 segundos, que em nosso teste se parece com:

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

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

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.

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.

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

Caso você execute o código de exemplo por pelo menos 60 segundos, três itens diferentes de telemetria são enviados ao 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.

No gerenciador de métricas:

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.

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.

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

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.

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 does not 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 do .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 da Web do Application Insights coleta automaticamente as solicitações HTTP para aplicativos ASP.NET executados em um pipeline do IIS e para todos os aplicativos do 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á.

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, como a Fila do Armazenamento do Azure, exigem que o contexto seja codificado no conteúdo da mensagem.

Fila do Barramento de Serviço

Para saber mais sobre o rastreamento, confira Rastreamento distribuído e correlação por meio de mensagens do Barramento de Serviço do Azure.

Fila de Armazenamento do Azure

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

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 do servidor, consulte Monitorar, diagnosticar e solucionar problemas do Armazenamento do Azure.

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

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

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 Microsoft Azure
• Azure Event Hubs para Hubs de Eventos do Azure
• Azure Service Bus para Barramento de Serviço do Azure

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 do Barramento de Serviço ou fila de Armazenamento pode servir como exemplos de tal 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.

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

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.

Visão geral

Contadores de desempenho

O Windows fornece vários contadores de desempenho, como os usados para coletar estatísticas de uso do processador, da memória e do 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. Os aplicativos em execução como os Aplicativos Web do Azure não podem acessar diretamente contadores de desempenho, mas o Application Insights coleta um subconjunto de contadores disponíveis.

Pré-requisitos

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

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

Visualizar contadores

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

Adicionar contadores

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

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 .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 nos Aplicativos Web do Azure e Contêineres do Windows no Serviço de Aplicativo do Azure

Os aplicativos ASP.NET e ASP.NET Core implantados nos aplicativos Web do Azure são executados em um ambiente de área restrita especial. Os aplicativos implantados no Serviço de Aplicativo do Azure podem utilizar um contêiner de Windows ou ser hospedados em um ambiente de área restrita. Se o aplicativo for implantado em um Contêiner do Windows, todos os contadores de desempenho padrão estarão disponíveis na imagem de 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. Para obter a lista completa, confira Contadores perf expostos como variáveis de ambiente.

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

Consultas do Log Analytics para contadores de desempenho

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

O esquema performanceCounters expõe o 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. Os EventCounters têm suporte em todas as plataformas de 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 qualquer contador de eventos personalizado para atender às suas necessidades, o .NET publica um conjunto desses contadores por padrão. Esse documento apresenta as etapas necessárias para coletar e exibir contadores de eventos (definidos pelo sistema ou pelo usuário) no Azure Application Insights.

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, é recomendável também 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 ver uma lista de contadores conhecidos publicados pelo runtime do .NET, confira o documento Contadores disponíveis.

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 exemplo de código de um aplicativo ASP.NET Core. Para outros tipos de aplicativos, consulte configurar módulos de telemetria.

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

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

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

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

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 do Log Analytics para contadores de eventos

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

Por exemplo, execute a 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.

Filtrar e enriquecer a telemetria

Nesta seção

• Filtrar e pré-processar telemetria
• Inicializadores de telemetria
• Processador de telemetria
• Amostragem
• Enriquecer dados por meio de HTTP

Filtrar e pré-processar telemetria

Você pode escrever código para filtrar, modificar ou enriquecer sua telemetria antes que ela seja enviada do SDK. O processamento inclui dados enviados dos módulos 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.

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, é possível filtrar a telemetria sobre solicitações de robôs ou sobre chamadas de dependência bem-sucedidas.

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:

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

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

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

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

    using Microsoft.ApplicationInsights.Extensibility;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
        services.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

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

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

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

 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.

1. Implemente ITelemetryProcessor.

   Os processadores de telemetria constrói uma cadeia de processamento. Ao instanciar um processador de telemetria, você obtém uma referência para o próximo processador da 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;
       }
   }
   

2. Adicione seu processador.

   • ASP.NET
   • ASP.NET Core
   • Serviço de Trabalho

   Insira este trecho de código 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>
   

Filtros de exemplo

Solicitações sintéticas

Filtre os bots e os 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.

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

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

amostragem

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

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

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

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

Gerenciar componentes do SDK

Nesta seção

• Canais de telemetria
• Módulos de telemetria
• Desabilitar telemetria
• Provedor ApplicationId
• Coleção de instantâneos

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.

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 integrados: InMemoryChannel e ServerTelemetryChannel. Esta seção descreve cada canal e mostra como personalizar o comportamento do canal.

O que são canais de telemetria?

Os canais de telemetria são responsáveis por armazenar itens de telemetria em buffer e enviá-los 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 integrados:

• 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. Este 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. Nos aplicativos ASP.NET, a configuração envolve definir a instância do canal de telemetria como TelemetryConfiguration.Active ou modificando o ApplicationInsights.config. Nos aplicativos ASP.NET Core, a configuração envolve adicionar o 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.

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

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

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

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

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:

• InMemoryChannel
• ServerTelemetryChannel

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. No Windows,% LOCALAPPDATA% ou% TEMP% é usado se nenhum outro caminho for especificado explicitamente. Em ambientes diferentes do Windows, por padrão, os seguintes locais são usados (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.

Configurar módulos de telemetria

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

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

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

{
    "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

    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 = "keyhere";
            });

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

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

Desabilitar telemetria

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

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

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

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

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

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
        var telemetryClient = new TelemetryClient(configuration);

    var tc = new TelemetryClient();
    tc.Context.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
    tc.TrackEvent("myEvent");
    // ...

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 = "InstrumentationKey=00000000-0000-0000-0000-000000000000";

app.Run();

using Microsoft.ApplicationInsights;

var tc = new TelemetryClient();
tc.Context.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
tc.TrackEvent("myEvent");
// ...

Provedor de ID de Aplicativo

A finalidade desse provedor é pesquisar uma ID do aplicativo com base em uma cadeia 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

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

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

ApplicationInsightsApplicationIdProvider

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 chave de instrumentação para cada solicitação.

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

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

Esse provedor estático depende dos pares de chave de instrumentação/ID do aplicativo configurados.

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

Essa classe tem a propriedade Nextopcional, que pode ser usada para configurar outro provedor a ser usado quando uma cadeia de conexão é solicitada que não existe em sua configuração.

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

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>
        {
            { "InstrumentationKey_1", "ApplicationId_1" },
            { "InstrumentationKey_2", "ApplicationId_2" }
        },
        Next = new ApplicationInsightsApplicationIdProvider() // optional fallback
    });

var app = builder.Build();
app.Run();

Configurar a coleção de instantâneos

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

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.

<script> // apply custom changes to this script tag.
    @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>

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

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:

   • .NET
   • Node.js

   using Microsoft.ApplicationInsights;
   

Obter uma instância do TelemetryClient

Obter uma instância de TelemetryClient:

private TelemetryClient telemetry = new TelemetryClient();

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

var telemetry = applicationInsights.defaultClient;

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 de Diagnóstico como ocorrências individuais. (Não está relacionado ao MVC ou a outros "eventos") da estrutura.

Insira chamadas de TrackEvent em seu código para fazer a contagem de 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");

telemetry.trackEvent({name: "WinGame"});

Eventos personalizados no Log Analytics

A telemetria está disponível na tabela customEvents, 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).

GetMetric

Para saber como usar efetivamente a GetMetric() chamada para capturar métricas pré-configuradas localmente para aplicativos .NET e .NET Core, consulte a coleção de métricas personalizadas no .NET e no .NET Core.

TrackMetric

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

telemetry.trackMetric({name: "queueLength", value: 42.0});

Métricas personalizadas no Log Analytics

A telemetria está disponível na tabela no customMetricsApplication Insights Analytics. Cada linha representa uma chamada para trackMetric(..) em 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.

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.

Dados de usuário e de sessão são enviados como propriedades, juntamente com exibições de páginas, assim, os gráficos de usuário e sessão são ativados quando há telemetria de exibições de páginas.

Exibições de página personalizadas

telemetry.TrackPageView("GameReviewPage");

Telemetria de página no 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 as exibições de página a chamadas AJAX, utilize 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.

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, telemetry item is sent.

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ê chamar StopOperation explicitamente. Se você usar RequestTelemetry como o tipo de telemetria, sua duração será definida como o intervalo cronometrado entre iniciar e parar.

Itens de telemetria relatados em um escopo da operação se tornam “filhos” dessa operação. Contextos de operação podem ser aninhados.

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

Para obter mais informações sobre o acompanhamento de operações personalizadas, consulte Rastrear operações personalizadas com o SDK do .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:

• Para contá-las como uma indicação da frequência de um problema.
• Para examinar ocorrências individuais.

Os relatórios incluem os rastreamentos de pilha.

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

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: 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 importante já foi extraída em variáveis separadas, mas você pode extrair e separar a estrutura details 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 as solicitações relacionadas a exceções, use uma junção:

exceptions
| join (requests) on operation_Id

TrackTrace

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

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

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

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

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 no 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 chamada TrackDependency para acompanhar os tempos de resposta e as taxas de êxito das chamadas a um trecho de código externo. 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.

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

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 as solicitações relacionadas a dependências, 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.

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

await telemetryClient.FlushAsync()
// No need to sleep

telemetry.flush();

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.

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

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

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

Medidas e propriedades personalizadas no Log Analytics

No Log Analytics, as métricas e propriedades personalizadas aparecem 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 JSON customDimensions ou customMeasurements, ele tem o tipo dinâmico, portanto, você deve convertê-lo em tostring ou todouble.
• Para levar em conta a possibilidade de amostragem, use sum(itemCount) não count().

Eventos de tempo

À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");

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "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;

telemetry.config.disableAppInsights = true;

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

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;

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

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 quanto ao número de métricas e eventos por aplicativo, ou seja, por chave de instrumentação. Os limites dependem do plano de preços que você escolher.

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.

Serviço de Trabalho do .NET Core: use este exemplo se você tiver um aplicativo do Serviço de Trabalho do .NET de acordo com as diretrizes oficiais.

Resolução de problemas

Confira o artigo de solução de problemas dedicado.

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

Ler e contribuir com o código.

Para obter as atualizações mais recentes e correções de bug, consulte as notas de versão.

Notas de Lançamento

Para a versão 2.12 e versões mais recente: SDKs (kits de desenvolvimento de software) do .NET, incluindo ASP.NET, ASP.NET Core e adaptadores de registro em log

Nossas Atualizações de Serviço também resumem as principais melhorias do Application Insights.

Próximas etapas

• Para examinar perguntas frequentes (perguntas frequentes), consulte:
  • Perguntas frequentes sobre o Application Insights para ASP.NET
  • Perguntas frequentes sobre o Application Insights for ASP.NET Core
  • Perguntas frequentes sobre aplicativos do Serviço de Trabalho
  • Perguntas frequentes sobre a API do Application Insights para eventos e métricas personalizados
• Valide se você está executando uma versão com suporte do SDK do Application Insights.
• Consulte o modelo de dados para modelo de dados e tipos do Application Insights.
• Adicione transações sintéticas para testar se o site está disponível em todo o mundo com monitoramento de disponibilidade.
• Confira o Guia do Usuário de System.Diagnostics.Activity para ver como correlacionar telemetria.
• Configure uma coleta de instantâneos para ver o estado do código-fonte e as variáveis no momento em que uma exceção é lançada.

Documentos de Referência

• Referência de tipos de dados para o SDK ASP.NET e o SDK do ASP.NET Core.
• Código do SDK para ASP.NET SDK e ASP.NET Core SDK.