API do Application Insights 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 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:
Adicione o SDK do Application Insights ao seu projeto:
No seu dispositivo ou código do servidor Web, inclua:
C#:
using Microsoft.ApplicationInsights;
Visual Basic:
Imports Microsoft.ApplicationInsights
Java:
import com.microsoft.applicationinsights.TelemetryClient;
Node.js:
var applicationInsights = require("applicationinsights");
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 no .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 valor3
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ê invocaTrackMetric
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 porvalueCount
.valueCount
: O número de medições que foram agregadas nestatrackMetric(..)
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 estopTrackPage
.
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 StopOperation
explicitamente . 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 .
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:
- Para contá-los, como uma indicação da frequência de um problema.
- Examinar ocorrências individuais.
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:
- ASP.NET: Escreva código para capturar exceções.
- Java EE: As exceções são capturadas automaticamente.
- JavaScript: As exceções são capturadas automaticamente. Se você quiser desativar a coleta automática, adicione uma linha ao JavaScript (Web) SDK Loader Script que você insere em suas páginas da Web:
({
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.
- Revise a configuração do Autoflush: habilitar o autoflush em seu
web.config
arquivo pode levar à degradação do desempenho em aplicativos .NET instrumentados com o Application Insights. Com o autoflush habilitado, cada invocação de métodos resulta em itens deSystem.Diagnostics.Trace.Trace*
telemetria individuais sendo enviados como solicitações da Web distintas separadas para o serviço de ingestão. Isso pode potencialmente causar esgotamento da rede e do armazenamento em seus servidores Web. Para melhorar o desempenho, recomenda-se desativar o autoflush e também utilizar o ServerTelemetryChannel, projetado para uma transmissão de dados de telemetria mais eficaz.
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
oucustomMeasurements
JSON, ele tem tipo dinâmico, então você deve convertê-lotostring
outodouble
. - Para ter em conta a possibilidade de amostragem, não
count()
utilizarsum(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 ITelemetryInitializer
o .
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 | |
Contagem de testes de disponibilidade por grupo de recursos | 800 | 800 | Consulte Azure Resource Manager |
Testes de disponibilidade: redirecionamentos máximos por teste | 10 | 10 | |
Frequência mínima de teste dos testes de disponibilidade | 300 segundos | Frequências de teste personalizadas ou frequências inferiores a 5 minutos requerem implementações personalizadas de TrackAvailability . | |
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
- .NET reference (Referência de .NET)
- Java reference (Referência de Java)
- Referência JavaScript
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.