API do Application Insights para métricas e eventos personalizados

  • Artigo

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 da área de trabalho e de dispositivo, clientes Web e servidores Web. Use a API de telemetria de núcleo do Application Insights para enviar eventos e métricas personalizados, bem como suas próprias versões de telemetria padrão. Essa API é a mesma API usada pelos coletores de dados padrão do Application Insights.

Observação

Em 31 de março de 31, 2025, o suporte à ingestão de chave de instrumentação será encerrado. A ingestão de chave de instrumentação continuará funcionando, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar as novas funcionalidades.

Resumo da API

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

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

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

Antes de começar

Se você ainda não tem uma referência no SDK do Application Insights:

Obter uma instância do TelemetryClient

Obter uma instância de TelemetryClient (exceto em JavaScript em páginas da Web):

Para aplicativos ASP.NET Core e aplicativos Não HTTP/Worker for .NET/.NET Core, obtenha uma instância do TelemetryClient do contêiner de injeção de dependência conforme explicado em sua respectiva documentação.

Se você usar o Azure Functions v2+ ou Azure WebJobs v3+, confira Monitorar o Azure Functions.

C#

private TelemetryClient telemetry = new TelemetryClient();

Se você vir uma mensagem informando que esse método está obsoleto, confira microsoft/ApplicationInsights-dotnet#1152 para obter mais informações.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient é seguro para threads.

Para projetos ASP.NET e Java, as solicitações HTTP de entrada são capturadas automaticamente. Talvez seja interessante criar mais instâncias de TelemetryClient para outros módulos do seu aplicativo. Por exemplo, você pode ter uma instância de TelemetryClient em sua classe de middleware para relatar eventos de lógica de negócios. Você pode definir propriedades, como UserId e DeviceId, para identificar o computador. Essas informações são anexadas a todos os eventos que a instância envia.

C#

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

Java

telemetry.getContext().getUser().setId("...");
telemetry.getContext().getDevice().setId("...");

Em projetos Node.js, você pode usar new applicationInsights.TelemetryClient(instrumentationKey?) para criar uma instância. Recomendamos essa abordagem somente para cenários que exigem configuração isolada do singleton 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. (Ele não está relacionado ao MVC ou a outros “eventos” de estrutura.)

Insira chamadas de TrackEvent em seu código para fazer a contagem de vários eventos. Por exemplo, talvez seja interessante acompanhar a frequência com que os usuários escolhem um recurso específico. Ou talvez valha a pena 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:

JavaScript

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

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

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 funcionamento, a propriedade itemCount vai mostrar um valor maior que 1. Por exemplo, itemCount==10 significa que de 10 chamadas a trackEvent(), o processo de amostragem transmitiu somente uma. Para obter uma contagem correta de eventos personalizados, use um código como customEvents | summarize sum(itemCount).

Observação

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

GetMetric

Para saber como usar efetivamente a chamada GetMetric() a fim de capturar métricas pré-agregadas localmente para aplicativos .NET e .NET Core, confira a coleta de métricas personalizadas no .NET e no .NET Core.

TrackMetric

Observação

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

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

O Application Insights pode traçar o gráfico de métrica que não estão associadas 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 menos interessantes que as variações e tendências, então gráficos estatísticos são úteis.

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

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

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

  • Agregação. Ao trabalhar com as métricas, raramente há interesse em cada uma delas separadamente. Em vez disso, o mais importante é obter um resumo do que aconteceu durante um determinado período. Esse tipo de resumo é chamado de agregação.

    No exemplo anterior, a soma de métricas agregadas para aquele período é 1 e a contagem dos valores de métrica é 2. Ao usar a abordagem de agregação, você chamará TrackMetric somente uma vez por período e enviará os valores de agregação. Recomendamos essa abordagem, pois ela pode reduzir significativamente a sobrecarga de custo e desempenho enviando menos pontos de dados para o Application Insights, ainda assim coletando todas as informações relevantes.

Exemplos de valor único

Para enviar um único valor de métrica:

JavaScript

appInsights.trackMetric({name: "queueLength", average: 42});

C#

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

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

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

Métricas personalizadas no Log Analytics

A telemetria está disponível na tabela customMetrics na Análise do Application Insights. 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 medidas que foram agregadas nessa chamada a trackMetric(..).

Observação

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

Exibições de página

Em um aplicativo de página da Web ou dispositivo, a telemetria de exibição de páginas é enviada por padrão quando cada tela ou página é carregada. Porém, você pode alterar o padrão para acompanhar as exibições de páginas em momentos diferentes ou mais ocasiões. Por exemplo, em um aplicativo que exibe guias ou painéis, talvez você queira acompanhar uma página sempre que o usuário abrir uma 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áginas personalizadas

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Se você tiver várias guias contidas em diferentes páginas HTML, você pode especificar a URL também:

appInsights.trackPageView("tab1", "http://fabrikam.com/page1.htm");

Definindo o tempo das exibições de página

Por padrão, os tempos relatados como Tempo de carregamento da exibição de página são medidos do momento em que o navegador envia a solicitação até o momento em que o evento de carregamento de página do navegador é chamado.

Em vez disso, é possível:

  • Defina uma duração explícita na chamada trackPageView: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Usar as chamadas de definição de tempo da exibição de página startTrackPage e stopTrackPage.

JavaScript

// To start timing a page:
appInsights.startTrackPage("Page1");

...

// To stop timing and log the page:
appInsights.stopTrackPage("Page1", url, properties, measurements);

O nome que você usa como o primeiro parâmetro associa as chamadas de início e parada. Ele usa o nome da página atual como padrão.

As durações de carregamento de página resultantes exibidas no Metrics Explorer são derivadas do intervalo entre as chamadas de início e parada. Cabe a você definir qual intervalo terá o tempo definido.

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 diferentes navegadores:

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 registrar solicitações HTTP.

Você mesmo também poderá chamá-la se desejar simular solicitações em um contexto em que você não tenha o módulo de serviço Web em execução.

A maneira recomendada para enviar uma telemetria de solicitação é aquela em que a solicitação atua como um contexto de operação.

Contexto de operação

Você pode correlacionar os itens de telemetria, associando-os ao contexto de operação. O módulo de rastreamento de solicitação padrão faz isso para exceções e outros eventos que são enviados enquanto uma solicitação HTTP está sendo processada. Em Pesquisar e em Análise, você pode usar a ID para localizar com facilidade os eventos associados à solicitação usando a respectiva ID de operação.

Para obter mais informações sobre correlação, confira Correlação de telemetria no Application Insights.

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

C#

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here will use 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.

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 limitado entre o início e a parada.

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 de operação é usado para criar a lista Itens Relacionados.

Captura de tela que mostra a lista de Itens relacionados.

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

Solicitações no Log Analytics

Na Análise do Application Insights, as solicitações aparecem na tabela requests.

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

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

TrackException

Envie exceções ao Application Insights:

Os relatórios incluem os rastreamentos de pilha.

C#

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

Java

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

JavaScript

try
{
    ...
}
catch (ex)
{
    appInsights.trackException({exception: ex});
}

Node.js

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

Os SDKs capturam muitas exceções automaticamente; portanto, nem sempre você precisa chamar TrackException explicitamente:

({
    instrumentationKey: "your key",
    disableExceptionTracking: true
})

Exceções no Log Analytics

Na Análise do Application Insights, as exceções aparecem na tabela exceptions.

Se a amostragem estiver em funcionamento, a propriedade itemCount vai mostrar um valor maior que 1. Por exemplo, itemCount==10 significa que de 10 chamadas a trackException(), o processo de amostragem transmitiu somente uma. Para obter uma contagem correta de exceções segmentadas por tipo de exceção, use um 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ê deverá 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.

No .NET, os adaptadores de log usam essa API para enviar logs de terceiros ao portal.

No Java, o Agente Java do Application Insights coleta automaticamente e envia logs ao portal.

C#

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

Java

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

Node.js

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

JavaScript do lado do cliente/navegador

trackTrace({
    message: string,
    properties?: {[string]:string},
    severityLevel?: SeverityLevel
})

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

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

Você pode pesquisar no conteúdo da mensagem, mas (diferentemente de valores de propriedade) não é possível filtrar com base nele.

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

Você também pode adicionar um nível de severidade à mensagem. E, como ocorre com outros casos de telemetria, você pode adicionar valores de propriedade para ajudar a filtrar ou a pesquisar diferentes conjuntos de rastreamentos. Por exemplo:

C#

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

Java

Map<String, Integer> properties = new HashMap<>();
properties.put("Database", db.ID);
telemetry.trackTrace("Slow Database response", SeverityLevel.Warning, properties);

Em Pesquisar, você pode filtrar com facilidade todas as mensagens de um nível de gravidade específico que se relacionam a um determinado banco de dados.

Rastreamentos no Log Analytics

Na Análise do Application Insights, as chamadas a TrackTrace aparecem na tabela traces.

Se a amostragem estiver em funcionamento, a propriedade itemCount vai mostrar um valor maior que 1. Por exemplo, itemCount==10 significa que de 10 chamadas a trackTrace(), o processo de amostragem transmitiu somente uma. Para obter uma contagem correta de chamadas de rastreamento, use um 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 são exibidos nos gráficos de dependência no portal. O trecho de código a seguir precisa ser adicionado sempre que uma chamada de dependência for feita.

Observação

Para .NET e .NET Core, você pode, como alternativa, usar o método (extensão) TelemetryClient.StartOperation que preenche as propriedades DependencyTelemetry que são necessárias para a correlação e algumas outras propriedades, como a hora de início e a duração, para que você não precise criar um temporizador personalizado como com os exemplos a seguir. Para obter mais informações, confira a seção sobre o acompanhamento de dependência de saída em Rastrear operações personalizadas com o SDK do .NET do Application Insights.

C#

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

Java

boolean success = false;
Instant startTime = Instant.now();
try {
    success = dependency.call();
}
finally {
    Instant endTime = Instant.now();
    Duration delta = Duration.between(startTime, endTime);
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    dependencyTelemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

Node.js

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 de servidor incluem um módulo de dependência que descobre e rastreia automaticamente determinadas chamadas de dependência; por exemplo, para bancos de dados e APIs REST. Você precisa instalar um agente em seu servidor para fazer com que o módulo funcione.

No Java, muitas chamadas de dependência podem ser rastreadas automaticamente usando o agente Java do Application Insights.

Você usará essa chamada se quiser acompanhar chamadas que o acompanhamento automatizado não captura.

Para desativar o módulo padrão de rastreamento de dependência no módulo C#, edite ApplicationInsights.config e exclua a referência a DependencyCollector.DependencyTrackingTelemetryModule. No Java, confira Como suprimir telemetrias específicas coletadas automaticamente.

Dependências no Log Analytics

Na Análise do Application Insights, as chamadas a trackDependency aparecem na tabela dependencies.

Se a amostragem estiver em funcionamento, a propriedade itemCount mostrará um valor maior que 1. Por exemplo, itemCount==10 significa que de 10 chamadas a trackDependency(), o processo de amostragem transmitiu somente uma. Para obter uma contagem correta das dependências segmentadas por componente de destino, use um 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 (em geral, 30 segundos) ou sempre que o buffer estiver cheio (em geral, com 500 itens). Em alguns casos, talvez seja interessante liberar o buffer. Um exemplo é se você estiver usando o SDK em um aplicativo que é desligado.

.NET

Quando você usa Flush(), recomendamos este padrão:

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

Quando você usa FlushAsync(), recomendamos este padrão:

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

É recomendável sempre liberar como parte do desligamento do aplicativo para garantir que a telemetria não seja perdida.

Java

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Node.js

telemetry.flush();

A função é assíncrona para o canal de telemetria do servidor.

Observação

Os SDKs Java e JavaScript liberam automaticamente no desligamento do aplicativo.

usuários autenticados

Em um aplicativo Web, os usuários são identificados por cookies por padrão. Um usuário pode ser contado mais de uma vez se ele acessar seu aplicativo de um computador ou navegador diferente, ou se ele excluir cookies.

Se os usuários entrarem em seu aplicativo, você poderá obter uma contagem mais precisa, definindo a ID do usuário autenticado no código do navegador:

JavaScript

// Called when my app has identified the user.
function Authenticated(signInId) {
    var validatedId = signInId.replace(/[,;=| ]+/g, "_");
    appInsights.setAuthenticatedUserContext(validatedId);
    ...
}

Em um aplicativo MVC Web ASP.NET, por exemplo:

Razor

@if (Request.IsAuthenticated)
{
    <script>
        appInsights.setAuthenticatedUserContext("@User.Identity.Name
            .Replace("\\", "\\\\")"
            .replace(/[,;=| ]+/g, "_"));
    </script>
}

Não é necessário usar o nome do usuário real de conexão. Só é preciso ser uma ID que seja exclusiva para esse usuário. Não deve incluir espaços, nem os caracteres ,;=|.

A ID de usuário também é definida em um cookie de sessão e enviada ao servidor. Se o SDK do servidor estiver instalado, a ID de usuário autenticado será enviada como parte das propriedades de contexto da telemetria do cliente e do servidor. Assim, você poderá filtrar e pesquisar nele.

Se seu aplicativo agrupa os usuários em contas, você também pode passar um identificador para a conta. As mesmas restrições de caractere se aplicam.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

No Metrics Explorer, você pode criar um gráfico que contabiliza Usuários Autenticados e Contas de usuário.

Você também pode pesquisar por pontos de dados do cliente com contas e nomes de usuário específicos.

Observação

A propriedade EnableAuthenticationTrackingJavaScript, na classe ApplicationInsightsServiceOptions do SDK do .NET Core simplifica a configuração do JavaScript necessária para injetar o nome de usuário como a ID de autenticação para cada rastreamento enviado pelo SDK do JavaScript do Application Insights.

Quando essa propriedade é definida como true, o nome de usuário no ASP.NET Core é impresso juntamente com a telemetria do lado do cliente. Por esse motivo, adicionar appInsights.setAuthenticatedUserContext manualmente não seria mais necessário, uma vez que ele já foi injetado pelo SDK do ASP.NET Core. A ID de autenticação também é enviada ao servidor onde o SDK do .NET Core a identifica e a usa para qualquer telemetria do lado do servidor, conforme descrito na referência da API do JavaScript.

Para aplicativos JavaScript que não funcionam da mesma forma que ASP.NET Core MVC, como aplicativos Web do SPA, você ainda precisará adicionar appInsights.setAuthenticatedUserContext manualmente.

Filtre, pesquise e segmente seus dados por meio das propriedades

Você pode anexar propriedades e medidas aos seus eventos, métricas, exibições de página, exceções e outros dados de telemetria.

Propriedades são valores de cadeia de caracteres que você pode usar para filtrar a telemetria nos relatórios de uso. Por exemplo, se o aplicativo fornecer vários jogos, você poderá anexar o nome do jogo a cada evento, de modo que seja possível ver quais jogos são mais populares.

Há um limite de 8.192 caracteres para o tamanho da cadeia de caracteres. Se você deseja enviar grandes quantidades de dados, use o parâmetro de mensagem de TrackTrace.

Métricas são valores numéricos que podem ser apresentados graficamente. Por exemplo, convém verificar se há um aumento gradual nas pontuações que seus jogadores atingem. Os grafos podem ser segmentados pelas propriedades enviadas com o evento para que você possa obter grafos separado ou empilhados para diferentes cenários.

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.

JavaScript

appInsights.trackEvent({
  name: 'some event',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

appInsights.trackPageView({
  name: 'some page',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

C#

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

Node.js

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

Visual Basic

' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("game", currentGame.Name)
properties.Add("difficulty", currentGame.Difficulty)

Dim metrics = New Dictionary (Of String, Double)
metrics.Add("Score", currentGame.Score)
metrics.Add("Opponents", currentGame.OpponentCount)

' Send the event:
telemetry.TrackEvent("WinGame", properties, metrics)

Java

Map<String, String> properties = new HashMap<String, String>();
properties.put("game", currentGame.getName());
properties.put("difficulty", currentGame.getDifficulty());

Map<String, Double> metrics = new HashMap<String, Double>();
metrics.put("Score", currentGame.getScore());
metrics.put("Opponents", currentGame.getOpponentCount());

telemetry.trackEvent("WinGame", properties, metrics);

Observação

Tome cuidado para não registrar informações de identificação pessoal nas propriedades.

Maneira alternativa de definir propriedades e métricas

Se for mais conveniente, você poderá coletar os parâmetros de um evento em um objeto separado:

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

Aviso

Não reutilize a mesma instância de item de telemetria (event, neste exemplo) para chamar Track*() várias vezes. Essa prática pode fazer com que a telemetria seja enviada com a configuração incorreta.

Medidas e propriedades personalizadas no Log Analytics

No Log Analytics, as métricas e as propriedades personalizadas são exibidas nos atributos customMeasurements e customDimensions de cada registro de telemetria.

Por exemplo, se você adicionar uma propriedade chamada "game" para a telemetria da solicitação, essa consulta contará as ocorrências de valores diferentes de "game" e exibirá a média da "pontuação" da métrica personalizada:

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), e não count().

Eventos de tempo

Às vezes, você quer colocar em gráfico quanto tempo leva para realizar uma ação. Por exemplo, talvez você queira saber quanto tempo os usuários levam para considerar as opções de um jogo. Para obter essas informações, use o parâmetro de medida.

C#

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

Java

long startTime = System.currentTimeMillis();

// Perform timed action

long endTime = System.currentTimeMillis();
Map<String, Double> metrics = new HashMap<>();
metrics.put("ProcessingTime", (double)endTime-startTime);

// Setup some properties
Map<String, String> properties = new HashMap<>();
properties.put("signalSource", currentSignalSource.getName());

// Send the event
telemetry.trackEvent("SignalProcessed", properties, metrics);

Propriedades padrão para telemetria personalizada

Se quiser definir valores de propriedade padrão para alguns dos eventos personalizados que escrever, defina-os em um instância de TelemetryClient. Eles são anexados a cada item de telemetria enviado do cliente.

C#

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame");

Visual Basic

Dim gameTelemetry = New TelemetryClient()
gameTelemetry.Context.GlobalProperties("Game") = currentGame.Name
' Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame")

Java

import com.microsoft.applicationinsights.TelemetryClient;
import com.microsoft.applicationinsights.TelemetryContext;
...

TelemetryClient gameTelemetry = new TelemetryClient();
TelemetryContext context = gameTelemetry.getContext();
context.getProperties().put("Game", currentGame.Name);

gameTelemetry.TrackEvent("WinGame");

Node.js

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 clientes Web JavaScript, use inicializadores de telemetria JavaScript.

Para adicionar propriedades a toda a telemetria, incluindo os dados de módulos de coleta padrão, implemente ITelemetryInitializer.

Telemetria de exemplo, de filtro e de processo

Veja Filtrar e pré-processar dados telemétricos no SDK do Application Insights.

Desabilitar telemetria

Para parar e iniciar dinamicamente a coleta e a transmissão de telemetria:

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Para desabilitar os coletores padrão selecionados ꟷ por exemplo, contadores de desempenho, solicitações HTTP ou dependências ꟷ exclua ou comente as linhas relevantes no arquivo ApplicationInsights.config. Um exemplo disso é quando você quer enviar dados TrackRequest próprios.

Node.js

telemetry.config.disableAppInsights = true;

Para desabilitar coletores padrão selecionados – por exemplo, contadores de desempenho, solicitações HTTP ou dependências – no momento da inicialização, vincule os métodos de configuração ao código de inicialização do SDK.

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

Para desabilitar esses coletores após a inicialização, use o objeto de configuração: applicationInsights.Configuration.setAutoCollectRequests(false).

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 obtém outras mensagens que ajudarão a rastrear problemas com a telemetria. Desative-a na produção, pois isso pode tornar seu aplicativo mais lento.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Para o Node.js, você pode habilitar o modo de desenvolvedor ativando o registro interno por meio de setInternalLogging e definindo maxBatchSize como 0, o que faz com que sua telemetria seja enviada tão logo seja coletada.

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

Definir a chave de instrumentação para telemetria personalizada selecionada

C#

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

Chave de instrumentação dinâmica

Para evitar a mistura de telemetria dos ambientes de desenvolvimento, teste e produção, você pode criar recursos separados do Application Insights e alterar suas chaves de acordo com o 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 do ASP.NET:

C#

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

JavaScript

appInsights.config.instrumentationKey = myKey;

Em páginas da Web, talvez seja interessante defini-la com base no estado do servidor Web, em vez de codificá-la literalmente no script. Por exemplo, em uma página da Web gerada em um aplicativo ASP.NET:

JavaScript no Razor

<script type="text/javascript">
// Standard Application Insights webpage script:
var appInsights = window.appInsights || function(config){ ...
// Modify this part:
}({instrumentationKey:
    // Generate from server property:
    @Microsoft.ApplicationInsights.Extensibility.
        TelemetryConfiguration.Active.InstrumentationKey;
}) // ...

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

TelemetryContext

TelemetryClient tem uma propriedade de Contexto, que contém valores que serão enviadas com todos os dados de telemetria. Normalmente, eles são definidos pelos módulos padrão de telemetria, mas você pode também defini-las 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 do arquivo ApplicationInsights.config, de modo que não haja confusão entre os seus valores e os valores padrão.

  • Componente: o aplicativo e sua versão.
  • Dispositivo: dados sobre o dispositivo onde o aplicativo está sendo executado. Em aplicativos Web, esse é o servidor ou o dispositivo cliente do qual a telemetria é enviada.
  • InstrumentationKey: o recurso do Application Insights no Azure em que a telemetria aparece. Normalmente, é coletado 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 aplicativos, 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 localizar itens relacionados.
    • Nome: um identificador, geralmente a URL da solicitação HTTP.
    • SyntheticSource: se não for nula ou vazia, essa cadeia de caracteres indica que a origem da solicitação foi identificada como um teste de robô ou Web. Por padrão, ela é excluída dos cálculos no Metrics Explorer.
  • Sessão: a sessão do usuário. A ID é definida para um valor gerado, que é alterado quando o usuário ficar inativo por um tempo.
  • Usuário: informações do usuário.

Limites

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.

Recurso Limite padrão Limite máximo Observações
Total de dados por dia 100 GB Fale com o suporte. Você pode definir um limite para reduzir os dados. Caso precise de mais dados, é possível aumentar o limite até 1.000 GB. Para capacidades maiores que 1.000 GB, envie um email para AIDataCap@microsoft.com.
Limitação 32.000 eventos/s Fale com o suporte. O limite é medido em um minuto.
Logs de retenção de dados De 30 a 730 dias 730 dias Este recurso é para Logs.
Métricas de retenção de dados 90 dias 90 dias Este recurso é para Metrics Explorer.
Retenção de resultados detalhados do Teste de disponibilidade em várias etapas 90 dias 90 dias Esse recurso fornece resultados detalhados de cada etapa.
Tamanho máximo do item de telemetria 64 KB 64 KB
Máximo de itens de telemetria por lote 64.000 64.000
Tamanho dos nomes de propriedade e métrica 150 150 Veja esquemas de tipo.
Tamanho da cadeia de caracteres do valor da propriedade 8\.192 8\.192 Veja esquemas de tipo.
Comprimento da mensagem de rastreamento e de exceção 32.768 32.768 Veja esquemas de tipo.
Contagem de testes de disponibilidade por recurso do Application Insights 100 100
Retenção de dados do Profiler e Snapshot Duas semanas Entre em contato com o suporte. O limite máximo de retenção é de seis meses.
Dados do criador de perfil enviados por dia Sem limite Não há limite.
Dados de Snapshot enviados por dia 30 instantâneos por dia por aplicativo monitorado Não há limite. O número de instantâneos coletados por aplicativo pode ser modificado por meio da configuração.

Para obter mais informações sobre preços e cotas, confira Cobrança do Application Insights.

Para evitar atingir o limite de taxa de dados, use amostragem.

Para determinar por quanto tempo os dados são mantidos, confira Retenção e privacidade de dados.

Documentos de Referência

Código do SDK

Perguntas frequentes

Esta seção fornece respostas para perguntas comuns.

Por que não tenho dados telemétricos?

Os dois TelemetryChannels perderão a telemetria em buffer se ela não for liberada antes que um aplicativo seja desligado.

Para evitar a perda de dados, libere o TelemetryClient quando um aplicativo estiver sendo desligado.

Para saber mais, confira Como liberar dados.

Que exceções podem ser lançadas por chamadas Track_()?

Nenhum. Você não precisa encapsulá-las em cláusulas try-catch. Se o SDK encontrar problemas, ele vai registrar mensagens na saída do console de depuração e, se elas passarem despercebidas, na Pesquisa de Diagnóstico.

Há uma API REST para obter dados do portal?

Sim, a API de acesso a dados. Outras maneiras de extrair dados incluem o Power BI no caso da migração para um recurso baseado em workspace ou a exportação contínua no caso de um recurso clássico.

Por que minhas chamadas para APIs de eventos e métricas personalizados são ignoradas?

O SDK do Application Insights não é compatível com a instrumentação automática. Se a instrumentação automática estiver habilitada, as chamadas para Track() e outros eventos personalizados e APIs de métricas serão ignoradas.

Desative a instrumentação automática no portal do Azure na guia Application Insights da página do Serviço de Aplicativo ou defina ApplicationInsightsAgent_EXTENSION_VERSION como disabled.

Por que as contagens nos gráficos de Pesquisa e Métricas são desiguais?

A Amostragem reduz o número de itens de telemetria ( como solicitações e eventos personalizados) que são enviados de seu aplicativo para o portal. Em Pesquisa, você visualiza o número de itens recebidos. Nos gráficos de métrica que exibem uma contagem de eventos, você visualiza o número de eventos originais que ocorreu.

Cada item transmitido carrega uma propriedade itemCount que mostra quantos eventos originais esse item representa. Para observar a amostragem na operação, é possível executar essa consulta no Log Analytics:

    requests | summarize original_events = sum(itemCount), transmitted_events = count()

Como configurar um alerta em um evento?

Os alertas do Azure são somente em métricas. Crie uma métrica personalizada que cruze um limite de valor sempre que o evento ocorrer. Em seguida, configure um alerta na métrica. Você recebe uma notificação sempre que a métrica ultrapassa o limite em qualquer direção. Você não receberá uma notificação até o primeiro cruzamento, independentemente de o valor inicial ser alto ou baixo. Há sempre uma latência de alguns minutos.

Próximas etapas