API do Application Insights para eventos e métricas 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 de dispositivo e desktop, clientes da Web e servidores da Web. Use a API de telemetria principal do Application Insights para enviar eventos e métricas personalizados e suas próprias versões de telemetria padrão. Essa API é a mesma que os coletores de dados padrão do Application Insights usam.

Nota

A 31 de março de 2025, o suporte da ingestão de chaves de instrumentação terminará. A ingestão de chaves de instrumentação continuará a funcionar, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar os novos recursos.

Resumo da API

A API principal é uniforme em todas as plataformas, com exceção de algumas variações, como GetMetric (somente .NET).

Método Utilizado para
TrackPageView Páginas, telas, painéis ou formulários.
TrackEvent Ações do usuário e outros eventos. Usado para rastrear o comportamento do usuário ou para monitorar o desempenho.
GetMetric Métricas zero e multidimensionais, agregação configurada centralmente, somente C#.
TrackMetric Medições de desempenho, como comprimentos de fila não relacionados a eventos específicos.
TrackException Registro de exceções para diagnóstico. Rastreie onde eles ocorrem em relação a outros eventos e examine os rastreamentos de pilha.
TrackRequest Registro da frequência e duração das solicitações do servidor para análise de desempenho.
TrackTrace Mensagens de log de diagnóstico de recursos. Você também pode capturar logs de terceiros.
TrackDependency Registrar 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 tiver uma referência no SDK do Application Insights:

Obter uma instância TelemetryClient

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

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

Se você usa o Azure Functions v2+ ou o Azure WebJobs v3+, consulte Monitorar o Azure Functions.

C#

private TelemetryClient telemetry = new TelemetryClient();

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

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient é thread safe.

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

C#

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

Java

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

Em Node.js projetos, você pode usar new applicationInsights.TelemetryClient(instrumentationKey?) para criar uma nova instância. Recomendamos essa abordagem apenas para cenários que exigem configuração isolada do singleton defaultClient.

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 com MVC ou outros "eventos" de estrutura.)

Insira TrackEvent chamadas no seu código para contar vários eventos. Por exemplo, talvez você queira acompanhar a frequência com que os usuários escolhem um recurso específico. Ou você pode querer saber com que frequência eles atingem certos objetivos 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 customEvents está disponível na tabela na guia Logs do Application Insights ou na experiência de uso. Os eventos podem vir do plug-in de coleta automática do trackEvent(..)Click Analytics.

Se a amostragem estiver em operação, a propriedade mostrará itemCount 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 um código como customEvents | summarize sum(itemCount).

Nota

itemCount tem um valor mínimo de um; o próprio registo representa uma entrada.

GetMetric

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

TrackMetric

Nota

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

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

O Application Insights pode traçar métricas que não estão anexadas a eventos específicos. Por exemplo, você pode monitorar o comprimento de uma fila em intervalos regulares. Com métricas, as medições individuais são de menor interesse do que as variações e tendências, e por isso 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. Toda vez que você executa uma medição 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, você primeiro 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 ambos os valores para você.

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

    No exemplo anterior, a soma métrica agregada para esse período de tempo é 1 e a contagem dos valores métricos é 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:

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 customMetrics está disponível na tabela em Application Insights Analytics. Cada linha representa uma chamada para em trackMetric(..) seu aplicativo.

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

Nota

valueCount tem um valor mínimo de um; o próprio registo representa uma entrada.

Visualizações de página

Em um dispositivo ou aplicativo de 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 controlar visualizações de página em momentos mais ou diferentes. Por exemplo, em um aplicativo que exibe guias ou painéis, talvez você queira acompanhar uma página sempre que o usuário abrir um novo painel.

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

Visualizações de página personalizadas

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Se tiver vários separadores em páginas HTML diferentes, também pode especificar o URL:

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

Cronometragem das visualizações de página

Por padrão, os tempos relatados como tempo de carregamento da visualização Página são medidos desde quando o navegador envia a solicitação até que o evento de carregamento de página do navegador seja chamado.

Em vez disso, você pode:

  • Defina uma duração explícita na chamada trackPageView : appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Utilize as chamadas startTrackPage de temporização da vista de página 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. O padrão é o nome da página atual.

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. Depende de você qual intervalo você realmente temporiza.

Telemetria de página no Log Analytics

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

  • pageViews: Contém dados sobre o 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 saber quanto tempo o navegador demora a 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 visualizações de página a chamadas AJAX, associe-se a dependências:

pageViews
| join (dependencies) on operation_Id

TrackRequest

O SDK do servidor usa TrackRequest para registrar solicitações HTTP.

Você também pode chamá-lo você mesmo 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 é quando a solicitação atua como um contexto de operação.

Contexto da operação

Você pode correlacionar itens de telemetria associando-os ao contexto da operação. O módulo de controle 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. No Search and Analytics, você pode encontrar facilmente quaisquer eventos associados à solicitação usando seu ID de operação.

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

Quando você controla a telemetria manualmente, a maneira mais fácil de garantir a correlação de telemetria é usando este 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.

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

Os itens de telemetria reportados dentro de um escopo de operação tornam-se filhos de tal operação. Os contextos de operação podem ser aninhados.

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

Captura de ecrã que mostra a lista Itens Relacionados.

Para obter mais informações sobre o acompanhamento de operações personalizadas, consulte Controlar 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 propriedade mostrará itemCount 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ódigos como:

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

TrackException

Envie exceções para o 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, para que você nem sempre precise chamar TrackException explicitamente:

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

Exceções no Log Analytics

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

Se a amostragem estiver em operação, a propriedade mostrará itemCount 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 segmentadas por tipo de exceção, use códigos como:

exceptions
| summarize sum(itemCount) by type

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

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

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

exceptions
| join (requests) on operation_Id

Rastreio

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

Em adaptadores de log .NET, use essa API para enviar logs de terceiros para o portal.

Em Java, o agente Java do Application Insights coleta automaticamente e envia logs para o 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
})

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

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

Você pode pesquisar no conteúdo da mensagem, mas, ao contrário dos valores de propriedade, não pode filtrá-lo.

O limite de tamanho é message muito maior do que o limite de propriedades. Uma vantagem é 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 gravidade à sua mensagem. E, como outras telemetrias, você pode adicionar valores de propriedade para ajudá-lo a filtrar ou 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);

Na Pesquisa, você pode filtrar facilmente todas as mensagens de um determinado nível de gravidade relacionadas a um determinado banco de dados.

Rastreamentos no Log Analytics

No Application Insights Analytics, as traces chamadas aparecem TrackTrace na tabela.

Se a amostragem estiver em operação, a propriedade mostrará itemCount 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 um código como traces | summarize sum(itemCount).

TrackDependency

Use a TrackDependency chamada para controlar os tempos de resposta e as taxas de sucesso de chamadas para uma parte externa do código. Os resultados aparecem nos gráficos de dependência no portal. O trecho de código a seguir deve ser adicionado sempre que uma chamada de dependência for feita.

Nota

Para .NET e .NET Core, você pode alternativamente usar o TelemetryClient.StartOperation método (extensão) que preenche as propriedades necessárias para correlação DependencyTelemetry e algumas outras propriedades, como a hora de início e a duração, para que você não precise criar um temporizador personalizado como nos exemplos a seguir. Para obter mais informações, consulte a seção sobre rastreamento de dependência de saída em Controlar 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 determinadas chamadas de dependência automaticamente, por exemplo, para bancos de dados e APIs REST. Você tem que instalar um agente no seu servidor para fazer o módulo funcionar.

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

Você usa essa chamada se quiser rastrear chamadas que o rastreamento automatizado não deteta.

Para desativar o módulo de controle de dependência padrão em C#, edite ApplicationInsights.config e exclua a referência a DependencyCollector.DependencyTrackingTelemetryModule. Para Java, consulte Suprimindo telemetria específica coletada automaticamente.

Dependências no Log Analytics

No Application Insights Analytics, trackDependency as chamadas aparecem na dependencies tabela.

Se a amostragem estiver em operação, a itemCount propriedade mostra 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 por componente de destino, use um código como:

dependencies
| summarize sum(itemCount) by target

Para associar dependências às solicitações relacionadas, use uma associação:

dependencies
| join (requests) on operation_Id

Dados de limpeza

Normalmente, o SDK envia dados em intervalos fixos, normalmente 30 segundos, ou sempre que o buffer está cheio, o que normalmente é de 500 itens. Em alguns casos, você pode querer liberar o buffer. Um exemplo é se você estiver usando o SDK em um aplicativo que é desligado.

.NET

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

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

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

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

Recomendamos sempre a lavagem 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.

Nota

Os SDKs Java e JavaScript são liberados automaticamente no desligamento do aplicativo.

Utilizadores autenticados

Numa aplicação Web, os utilizadores são identificados por cookies por predefinição. Um utilizador pode ser contado mais do que uma vez se aceder à sua aplicação a partir de uma máquina ou navegador diferente, ou se eliminar cookies.

Se os utilizadores iniciarem sessão na sua aplicação, pode obter uma contagem mais precisa definindo o ID de utilizador autenticado no código do browser:

JavaScript

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

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

Navalha

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

Não é necessário usar o nome de login real do usuário. Só tem de ser um ID que seja exclusivo para esse utilizador. Não deve incluir espaços ou qualquer um dos caracteres ,;=|.

O ID de utilizador também é definido num cookie de sessão e enviado para o servidor. Se o SDK do servidor estiver instalado, o ID do usuário autenticado será enviado como parte das propriedades de contexto da telemetria do cliente e do servidor. Você pode então filtrar e pesquisar nele.

Se o seu aplicativo agrupar usuários em contas, você também poderá passar um identificador para a conta. Aplicam-se as mesmas restrições de caracteres.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

No Metrics Explorer, você pode criar um gráfico que conte as contas de Usuários, Autenticados e Usuários.

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

Nota

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

Quando essa propriedade é definida como true, o nome de usuário do usuário no ASP.NET Core é impresso junto com a telemetria do lado do cliente. Por esse motivo, adicionar appInsights.setAuthenticatedUserContext manualmente não seria mais necessário porque já é injetado pelo SDK para ASP.NET Core. O ID de autenticação também será enviado para o servidor onde o SDK no .NET Core o identificará e o usará para qualquer telemetria do lado do servidor, conforme descrito na referência da API JavaScript.

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

Filtrar, pesquisar e segmentar seus dados usando propriedades

Você pode anexar propriedades e medidas aos seus eventos, métricas, visualizaçõ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 a sua aplicação fornecer vários jogos, pode anexar o nome do jogo a cada evento para ver quais os jogos mais populares.

Há um limite de 8.192 no comprimento da corda. Se você quiser enviar grandes blocos de dados, use o parâmetro message de TrackTrace.

As métricas são valores numéricos que podem ser apresentados graficamente. Por exemplo, você pode querer ver se há um aumento gradual nas pontuações que seus jogadores alcançam. Os gráficos podem ser segmentados pelas propriedades que são enviadas com o evento para que você possa obter gráficos separados ou empilhados para jogos diferentes.

Os valores métricos 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);

Nota

Certifique-se de que não regista informações de identificação pessoal nas propriedades.

Maneira alternativa de definir propriedades e métricas

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

var event = new EventTelemetry();

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

telemetry.TrackEvent(event);

Aviso

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

Medidas e propriedades personalizadas no Log Analytics

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

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

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Repare que:

  • Quando você extrai um valor do customDimensions ou customMeasurements JSON, ele tem tipo dinâmico, então você deve convertê-lo tostring ou todouble.
  • Para ter em conta a possibilidade de amostragem, não count()utilizar sum(itemCount) .

Eventos de cronometragem

Às vezes, você quer mapear quanto tempo leva para executar uma ação. Por exemplo, você pode querer saber quanto tempo os usuários levam para considerar as escolhas em um jogo. Para obter essas informações, use o parâmetro de medição.

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 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 cada item de telemetria enviado por esse 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 propriedade.

Para clientes da 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 ITelemetryInitializero .

Telemetria de amostra, filtro e processo

Consulte Telemetria de filtro e pré-processamento no SDK do Application Insights.

Desativar telemetria

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

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Para desabilitar coletores padrão selecionados, por exemplo, contadores de desempenho, solicitações HTTP ou dependências, exclua ou comente as linhas relevantes em ApplicationInsights.config. Um exemplo é se você quiser enviar seus próprios TrackRequest dados.

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, encadeie métodos de configuração ao código de inicialização do SDK.

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

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

Modo de desenvolvedor

Durante a depuração, é útil ter sua telemetria acelerada através do pipeline para que você possa ver os resultados imediatamente. Você também recebe outras mensagens que o ajudam a rastrear quaisquer problemas com a telemetria. Desligue-o na produção porque pode tornar a sua aplicação mais lenta.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Por Node.js, você pode habilitar o modo de desenvolvedor habilitando o registro interno via setInternalLogging e definindo maxBatchSize como 0, o que faz com que sua telemetria seja enviada assim que for coletada.

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

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

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, você pode querer defini-lo a partir do estado do servidor Web em vez de codificá-lo literalmente no script. Por exemplo, em uma página da Web gerada em um aplicativo ASP.NET:

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

TelemetriaContexto

TelemetryClient tem uma propriedade Context, que contém valores que são enviados junto com todos os dados de telemetria. Eles são normalmente 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, 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, é do servidor ou dispositivo cliente que a telemetria é enviada.
  • InstrumentationKey: O recurso do Application Insights no Azure onde a telemetria aparece. Geralmente é pego de ApplicationInsights.config.
  • Localização: 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 robô ou teste da Web. Por padrão, ele é excluído dos cálculos no Metrics Explorer.
  • Sessão: A sessão do usuário. O ID é definido como um valor gerado, que é alterado quando o usuário não está ativo há algum tempo.
  • Usuário: Informações do usuário.

Limites

Existem alguns limites no 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 escolher.

Recurso Limite predefinido Limite máximo Notas
Total de dados por dia 100 GB Contacte o suporte. Você pode definir um limite para reduzir os dados. Se precisar de mais dados, pode aumentar o limite no portal, até 1.000 GB. Para capacidades superiores a 1.000 GB, envie um e-mail para AIDataCap@microsoft.com.
Limitação 32.000 eventos/segundo Contacte o suporte. O limite é mediso ao longo de um minuto.
Registos de retenção de dados 30 a 730 dias 730 dias Este recurso é para Logs.
Métricas de retenção de dados 90 dias 90 dias Este recurso é para o Metrics Explorer.
Disponibilidade, teste em várias etapas, retenção detalhada de resultados 90 dias 90 dias Este recurso fornece resultados detalhados de cada passo.
Tamanho máximo do item de telemetria 64 KB 64 KB
Máximo de itens de telemetria por lote 64,000 64,000
Comprimento do nome da propriedade e da métrica 150 150 Consulte esquemas de tipo.
Comprimento da cadeia de valor da propriedade 8,192 8,192 Consulte esquemas de tipo.
Comprimento da mensagem de exceção e de rastreio 32,768 32,768 Consulte esquemas de tipo.
Contagem de testes de disponibilidade por recurso do Application Insights 100 100
Retenção de dados do Profiler e do Snapshot Duas semanas Contacte o suporte. O limite máximo de retenção é de seis meses.
Dados do Profiler enviados por dia Sem limite Sem limite.
Dados de snapshot enviados por dia 30 instantâneos por dia por aplicativo monitorado Sem limite. O número de snapshots coletados por aplicativo pode ser modificado por meio da configuração.

Para obter mais informações sobre preços e cotas, consulte Faturamento do Application Insights.

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

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

Documentos de referência

Código SDK

Perguntas mais frequentes

Esta secção fornece respostas a perguntas comuns.

Por que estou faltando dados de telemetria?

Ambos os 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 obter mais informações, consulte Liberando dados.

Que exceções podem Track_() ser chamadas de lançamento?

Nenhum. Você não precisa envolvê-los em cláusulas try-catch. Se o SDK encontrar problemas, ele registrará as mensagens na saída do console de depuração e, se as mensagens passarem, na Pesquisa de diagnóstico.

Existe uma API REST para obter dados do portal?

Sim, a API de acesso a dados. Outras maneiras de extrair dados incluem o Power BI se você tiver migrado para um recurso baseado em espaço de trabalho ou a exportação contínua se ainda estiver em um recurso clássico.

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

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

Desative a autoinstrumentação no portal do Azure na guia Application Insights da página 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 do seu aplicativo para o portal. Em Pesquisar, você vê o número de itens recebidos. Em gráficos de métricas que exibem uma contagem de eventos, você vê o número de eventos originais que ocorreram.

Cada item transmitido carrega uma itemCount propriedade que mostra quantos eventos originais esse item representa. Para observar a amostragem em operação, você pode executar esta consulta no Log Analytics:

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

Como posso definir um alerta sobre um evento?

Os alertas do Azure são apenas em métricas. Crie uma métrica personalizada que ultrapasse um limite de valor sempre que o evento ocorrer. Em seguida, defina um alerta na métrica. Você recebe uma notificação sempre que a métrica cruza o limite em qualquer direção. Você não receberá uma notificação até a primeira travessia, não importa se o valor inicial é alto ou baixo. Há sempre uma latência de alguns minutos.

Próximos passos