API do Application Insights para métricas e eventos personalizadosApplication Insights API for custom events and metrics

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.Insert a few lines of code in your application to find out what users are doing with it, or to help diagnose issues. Você pode enviar telemetria de aplicativos da área de trabalho e de dispositivo, clientes Web e servidores Web.You can send telemetry from device and desktop apps, web clients, and web servers. Use a API de telemetria de núcleo do Azure Application Insights para enviar eventos e métricas personalizados, bem como suas próprias versões de telemetria padrão.Use the Azure Application Insights core telemetry API to send custom events and metrics, and your own versions of standard telemetry. Essa API é a mesma API usada pelos coletores de dados padrão do Application Insights.This API is the same API that the standard Application Insights data collectors use.

Resumo da APIAPI summary

A API principal é uniforme em todas as plataformas, além de algumas variações como GetMetric (somente .NET).The core API is uniform across all platforms, apart from a few variations like GetMetric(.NET only).

MétodoMethod Usado paraUsed for
TrackPageView Páginas, telas, folhas ou formulários.Pages, screens, blades, or forms.
TrackEvent Ações de usuário e outros eventos.User actions and other events. Usado para acompanhar o comportamento do usuário ou para monitorar o desempenho.Used to track user behavior or to monitor performance.
GetMetric Métricas zeradas e multidimensionais, agregação configurada centralmente, apenas C#.Zero and multi-dimensional metrics, centrally configured aggregation, C# only.
TrackMetric Medições de desempenho, como comprimentos de fila, não relacionadas a eventos específicos.Performance measurements such as queue lengths not related to specific events.
TrackException Registrar em log as exceções para diagnóstico.Logging exceptions for diagnosis. Rastrear onde elas ocorrem em relação a outros eventos e examinar os rastreamentos de pilha.Trace where they occur in relation to other events and examine stack traces.
TrackRequest Registrar em log a frequência e a duração das solicitações do servidor para análise de desempenho.Logging the frequency and duration of server requests for performance analysis.
TrackTrace Mensagens de log de diagnóstico de recurso.Resource Diagnostic log messages. Você também pode capturar logs de terceiros.You can also capture third-party logs.
TrackDependency Registrar em log a duração e a frequência das chamadas para componentes externos dos quais seu aplicativo depende.Logging the duration and frequency of calls to external components that your app depends on.

Você pode anexar propriedades e métricas à maioria dessas chamadas de telemetria.You can attach properties and metrics to most of these telemetry calls.

Antes de começarBefore you start

Se você ainda não tem uma referência no SDK do Application Insights:If you don't have a reference on Application Insights SDK yet:

Obter uma instância do TelemetryClientGet a TelemetryClient instance

Obter uma instância de TelemetryClient (exceto em JavaScript em páginas da Web):Get an instance of TelemetryClient (except in JavaScript in webpages):

Para aplicativos ASP.NET Core e não http/Worker para aplicativos .net/.NET Core , é recomendável obter uma instância do TelemetryClient do contêiner de injeção de dependência, conforme explicado em sua respectiva documentação.For ASP.NET Core apps and Non HTTP/Worker for .NET/.NET Core apps, it is recommended to get an instance of TelemetryClient from the dependency injection container as explained in their respective documentation.

Se você usar AzureFunctions v2 + ou Azure WebJobs v3 +, siga este documento:https://docs.microsoft.com/azure/azure-functions/functions-monitoring#version-2x-and-higherIf you use AzureFunctions v2+ or Azure WebJobs v3+ - follow this document: https://docs.microsoft.com/azure/azure-functions/functions-monitoring#version-2x-and-higher

C#C#

private TelemetryClient telemetry = new TelemetryClient();

Para qualquer pessoa que veja esse método é mensagens obsoletas, visite Microsoft/ApplicationInsights-dotnet # 1152 para obter mais detalhes.For anyone seeing this method is obsolete messages please visit microsoft/ApplicationInsights-dotnet#1152 for further details.

Visual BasicVisual Basic

Private Dim telemetry As New TelemetryClient

JavaJava

private TelemetryClient telemetry = new TelemetryClient();

Node.jsNode.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient é thread-safe.TelemetryClient is thread-safe.

Para projetos ASP.NET e Java, as solicitações HTTP de entrada são automaticamente capturadas.For ASP.NET and Java projects, incoming HTTP Requests are automatically captured. Você talvez queira criar instâncias adicionais do TelemetryClient para outro módulo do seu aplicativo.You might want to create additional instances of TelemetryClient for other module of your app. Por exemplo, você pode ter uma instância de TelemetryClient em sua classe de middleware para relatar eventos de lógica de negócios.For instance, you may have one TelemetryClient instance in your middleware class to report business logic events. Você pode definir propriedades, como UserId e DeviceId para identificar a máquina.You can set properties such as UserId and DeviceId to identify the machine. Essas informações são anexadas a todos os eventos que a instância envia.This information is attached to all events that the instance sends.

C#C#

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

JavaJava

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

Em projetos de Node.js, é possível usar new applicationInsights.TelemetryClient(instrumentationKey?) para criar uma nova instância, mas isso só é recomendado para cenários que exigem a configuração isolada do defaultClient singleton.In Node.js projects, you can use new applicationInsights.TelemetryClient(instrumentationKey?) to create a new instance, but this is recommended only for scenarios that require isolated configuration from the singleton defaultClient.

TrackEventTrackEvent

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.In Application Insights, a custom event is a data point that you can display in Metrics Explorer as an aggregated count, and in Diagnostic Search as individual occurrences. (Ele não está relacionado ao MVC ou a outros “eventos” de estrutura.)(It isn't related to MVC or other framework "events.")

Insira chamadas de TrackEvent em seu código para fazer a contagem de vários eventos.Insert TrackEvent calls in your code to count various events. Com que frequência os usuários escolhem um determinado recurso, com que frequência eles atingem metas específicas ou talvez com que frequência cometem tipos de erro específicos.How often users choose a particular feature, how often they achieve particular goals, or maybe how often they make particular types of mistakes.

Por exemplo, em um aplicativo de jogo, envie um evento sempre que um usuário ganhar o jogo:For example, in a game app, send an event whenever a user wins the game:

JavaScriptJavaScript

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

C#C#

telemetry.TrackEvent("WinGame");

Visual BasicVisual Basic

telemetry.TrackEvent("WinGame")

JavaJava

telemetry.trackEvent("WinGame");

Node.jsNode.js

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

Eventos personalizados na AnáliseCustom events in Analytics

A telemetria está disponível na tabela customEvents na Análise do Application Insights.The telemetry is available in the customEvents table in Application Insights Analytics. Cada linha representa uma chamada para trackEvent(..) em seu aplicativo.Each row represents a call to trackEvent(..) in your app.

Se a amostragem estiver em funcionamento, a propriedade itemCount mostrará um valor maior que 1.If sampling is in operation, the itemCount property shows a value greater than 1. Para exemplo itemCount==10 significa que de 10 chamadas para trackEvent(), o processo de amostragem somente transmitirá um deles.For example itemCount==10 means that of 10 calls to trackEvent(), the sampling process only transmitted one of them. Para obter uma contagem correta de eventos personalizados, você deve, portanto, usar um código como customEvents | summarize sum(itemCount) .To get a correct count of custom events, you should therefore use code such as customEvents | summarize sum(itemCount).

GetMetricGetMetric

Para saber como usar efetivamente a chamada getmetric () para capturar métricas previamente agregadas localmente para aplicativos .NET e .NET Core, visite a documentação do getmetric .To learn how to effectively use the GetMetric() call to capture locally pre-aggregated metrics for .NET and .NET Core applications visit the GetMetric documentation.

TrackMetricTrackMetric

Observação

Microsoft. ApplicationInsights. TelemetryClient. TrackMetric não é o método preferencial para enviar métricas.Microsoft.ApplicationInsights.TelemetryClient.TrackMetric is not the preferred method for sending metrics. As métricas devem sempre ser agregadas previamente em um período de tempo antes de serem enviadas.Metrics should always be pre-aggregated across a time period before being sent. Use uma das sobrecargas GetMetric(..) para obter um objeto de métrica para acessar as funcionalidades de pré-agregação do SDK.Use one of the GetMetric(..) overloads to get a metric object for accessing SDK pre-aggregation capabilities. Se você estiver implementando sua própria lógica de pré-autenticação, poderá usar o método TrackMetric () para enviar as agregações resultantes.If you are implementing your own pre-aggregation logic, you can use the TrackMetric() method to send the resulting aggregates. 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. Confira TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).If your application requires sending a separate telemetry item at every occasion without aggregation across time, you likely have a use case for event telemetry; see 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.Application Insights can chart metrics that are not attached to particular events. Por exemplo, você pode monitorar um comprimento de fila em intervalos regulares.For example, you could monitor a queue length at regular intervals. 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.With metrics, the individual measurements are of less interest than the variations and trends, and so statistical charts are useful.

Para enviar métricas para o Application Insights, você poderá usar a API TrackMetric(..).In order to send metrics to Application Insights, you can use the TrackMetric(..) API. Há duas maneiras de enviar uma métrica:There are two ways to send a metric:

  • Valor único.Single value. Toda vez que você realiza uma medida em seu aplicativo, envia o valor correspondente para o Application Insights.Every time you perform a measurement in your application, you send the corresponding value to Application Insights. Por exemplo, suponha que você tenha uma métrica que descreve o número de itens em um contêiner.For example, assume that you have a metric describing the number of items in a container. Durante um período de tempo específico, você primeiro coloca três itens no contêiner e, em seguida, remove dois itens.During a particular time period, you first put three items into the container and then you remove two items. Da mesma forma, você chamaria TrackMetric duas vezes: primeiro, passando o valor 3 e, em seguida, o valor -2.Accordingly, you would call TrackMetric twice: first passing the value 3 and then the value -2. O Application Insights armazena os dois valores em seu nome.Application Insights stores both values on your behalf.

  • Agregação.Aggregation. Ao trabalhar com as métricas, raramente há interesse em cada medida.When working with metrics, every single measurement is rarely of interest. Em vez disso, um resumo do que aconteceu durante um determinado período de tempo é importante.Instead a summary of what happened during a particular time period is important. Esse tipo de resumo é chamado de agregação.Such a summary is called aggregation. No exemplo acima, a soma de métricas agregadas para esse período de tempo é 1 e a contagem dos valores de métrica é 2.In the above example, the aggregate metric sum for that time period is 1 and the count of the metric values is 2. Ao usar a abordagem de agregação, você chamará somente TrackMetric uma vez por período de tempo e enviará os valores de agregação.When using the aggregation approach, you only invoke TrackMetric once per time period and send the aggregate values. Essa é a abordagem recomendada 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.This is the recommended approach since it can significantly reduce the cost and performance overhead by sending fewer data points to Application Insights, while still collecting all relevant information.

ExemplosExamples

Valores únicosSingle values

Para enviar um único valor de métrica:To send a single metric value:

JavaScriptJavaScript

appInsights.trackMetric("queueLength", 42.0);

C#C#

var sample = new MetricTelemetry();
sample.Name = "metric name";
sample.Value = 42.3;
telemetryClient.TrackMetric(sample);

JavaJava

telemetry.trackMetric("queueLength", 42.0);

Node.jsNode.js

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

Métricas personalizadas no AnalyticsCustom metrics in Analytics

A telemetria está disponível na tabela customMetrics na Análise do Application Insights.The telemetry is available in the customMetrics table in Application Insights Analytics. Cada linha representa uma chamada para trackMetric(..) em seu aplicativo.Each row represents a call to trackMetric(..) in your app.

  • valueSum – essa é a soma das medidas.valueSum - This is the sum of the measurements. Para obter o valor médio, divida por valueCount.To get the mean value, divide by valueCount.
  • valueCount – o número de medidas que foram agregadas nessa chamada para trackMetric(..).valueCount - The number of measurements that were aggregated into this trackMetric(..) call.

Exibições de páginaPage views

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.In a device or webpage app, page view telemetry is sent by default when each screen or page is loaded. Porém, você pode alterar isso para acompanhar as exibições de páginas em momentos diferentes ou adicionais.But you can change that to track page views at additional or different times. Por exemplo, em um aplicativo que exibe guias ou folhas, talvez você queira acompanhar uma página sempre que o usuário abrir uma nova folha.For example, in an app that displays tabs or blades, you might want to track a page whenever the user opens a new blade.

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.User and session data is sent as properties along with page views, so the user and session charts come alive when there is page view telemetry.

Exibições de páginas personalizadasCustom page views

JavaScriptJavaScript

appInsights.trackPageView("tab1");

C#C#

telemetry.TrackPageView("GameReviewPage");

Visual BasicVisual Basic

telemetry.TrackPageView("GameReviewPage")

JavaJava

telemetry.trackPageView("GameReviewPage");

Se você tiver várias guias contidas em diferentes páginas HTML, você pode especificar a URL também:If you have several tabs within different HTML pages, you can specify the URL too:

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

Definindo o tempo das exibições de páginaTiming page views

Por padrão, os tempos relatados como Tempo de carregamento da exibição de página são medidos a partir 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.By default, the times reported as Page view load time are measured from when the browser sends the request, until the browser's page load event is called.

Em vez disso, é possível:Instead, you can either:

  • Defina uma duração explícita na chamada trackPageView: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.Set an explicit duration in the trackPageView call: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Usar as chamadas de definição de tempo da exibição de página startTrackPage e stopTrackPage.Use the page view timing calls startTrackPage and stopTrackPage.

JavaScriptJavaScript

// 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.The name that you use as the first parameter associates the start and stop calls. Ele usa o nome da página atual como padrão.It defaults to the current page name.

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.The resulting page load durations displayed in Metrics Explorer are derived from the interval between the start and stop calls. Cabe a você definir qual intervalo terá o tempo definido.It's up to you what interval you actually time.

Telemetria de página na AnálisePage telemetry in Analytics

Na Análise, duas tabelas mostram dados das operações do navegador:In Analytics two tables show data from browser operations:

  • A tabela pageViews contém dados sobre a URL e o título da páginaThe pageViews table contains data about the URL and page title
  • A tabela browserTimings contém dados sobre o desempenho do cliente, como o tempo necessário para processar os dados de entradaThe browserTimings table contains data about client performance, such as the time taken to process the incoming data

Para descobrir quanto tempo o navegador leva para processar páginas diferentes:To find how long the browser takes to process different pages:

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

Para descobrir as popularidades de navegadores diferentes:To discover the popularities of different browsers:

pageViews
| summarize count() by client_Browser

Para associar as exibições de página a chamadas AJAX, utilize dependências:To associate page views to AJAX calls, join with dependencies:

pageViews
| join (dependencies) on operation_Id 

TrackRequestTrackRequest

O SDK do servidor usa TrackRequest para registrar solicitações HTTP no log.The server SDK uses TrackRequest to log HTTP requests.

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.You can also call it yourself if you want to simulate requests in a context where you don't have the web service module running.

No entanto, a maneira recomendada para enviar uma telemetria de solicitação é aquela em que a solicitação atua como um contexto de operação.However, the recommended way to send request telemetry is where the request acts as an operation context.

Contexto de operaçãoOperation context

Você pode correlacionar os itens de telemetria, associando-os ao contexto de operação.You can correlate telemetry items together by associating them with operation context. 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.The standard request-tracking module does this for exceptions and other events that are sent while an HTTP request is being processed. Em pesquisa e análise, você pode encontrar facilmente todos os eventos associados à solicitação usando sua ID de operação.In Search and Analytics, you can easily find any events associated with the request using its operation ID.

Consulte Correlação de telemetria no Application Insights para obter mais informações.See Telemetry correlation in Application Insights for more details on correlation.

Ao acompanhar a telemetria manualmente, a maneira mais fácil de garantir a correlação de telemetria usando esse padrão:When tracking telemetry manually, the easiest way to ensure telemetry correlation by using this pattern:

C#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.Along with setting an operation context, StartOperation creates a telemetry item of the type that you specify. Ele envia o item de telemetria quando você descarta a operação ou se você chamar StopOperation explicitamente.It sends the telemetry item when you dispose the operation, or if you explicitly call StopOperation. 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.If you use RequestTelemetry as the telemetry type, its duration is set to the timed interval between start and stop.

Itens de telemetria relatados em um escopo da operação se tornam “filhos” dessa operação.Telemetry items reported within a scope of operation become 'children' of such operation. Contextos de operação podem ser aninhados.Operation contexts could be nested.

Na pesquisa, o contexto de operação é usado para criar a lista de itens relacionados :In Search, the operation context is used to create the Related Items list:

Itens relacionados

Consulte Acompanhar operações personalizadas com o SDK do .NET do Application Insights para obter mais informações sobre o acompanhamento de operações personalizadas.See Track custom operations with Application Insights .NET SDK for more information on custom operations tracking.

Consultas na AnáliseRequests in Analytics

Na Análise do Application Insights, as solicitações aparecem na tabela requests.In Application Insights Analytics, requests show up in the requests table.

Se a amostragem estiver em funcionamento, a propriedade itemCount mostrará um valor maior que 1.If sampling is in operation, the itemCount property will show a value greater than 1. Para exemplo itemCount==10 significa que de 10 chamadas para trackRequest(), o processo de amostragem somente transmitirá um deles.For example itemCount==10 means that of 10 calls to trackRequest(), the sampling process only transmitted one of them. 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:To get a correct count of requests and average duration segmented by request names, use code such as:

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

TrackExceptionTrackException

Envie exceções ao Application Insights:Send exceptions to Application Insights:

Os relatórios incluem os rastreamentos de pilha.The reports include the stack traces.

C#C#

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

JavaJava

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

JavaScriptJavaScript

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

Node.jsNode.js

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

Os SDKs capturam muitas exceções automaticamente; portanto, você não precisa chamar sempre explicitamente o TrackException.The SDKs catch many exceptions automatically, so you don't always have to call TrackException explicitly.

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

Exceções na AnáliseExceptions in Analytics

Na Análise do Application Insights, as exceções aparecem na tabela exceptions.In Application Insights Analytics, exceptions show up in the exceptions table.

Se a amostragem estiver em funcionamento, a propriedade itemCount mostrará um valor maior que 1.If sampling is in operation, the itemCount property shows a value greater than 1. Para exemplo itemCount==10 significa que de 10 chamadas para trackException(), o processo de amostragem somente transmitirá um deles.For example itemCount==10 means that of 10 calls to trackException(), the sampling process only transmitted one of them. Para obter uma contagem correta de exceções segmentadas por tipo de exceção, use um código como:To get a correct count of exceptions segmented by type of exception, use code such as:

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.Most of the important stack information is already extracted into separate variables, but you can pull apart the details structure to get more. Como essa estrutura é dinâmica, você deverá converter o resultado para o tipo esperado.Since this structure is dynamic, you should cast the result to the type you expect. Por exemplo:For example:

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

Para associar as solicitações relacionadas a exceções, use uma junção:To associate exceptions with their related requests, use a join:

exceptions
| join (requests) on operation_Id

TrackTraceTrackTrace

Use TrackTrace para ajudar a diagnosticar problemas enviando uma "trilha de navegação estrutural" ao Application Insights.Use TrackTrace to help diagnose problems by sending a "breadcrumb trail" to Application Insights. Você pode enviar partes de dados de diagnóstico e inspecioná-los na pesquisa de diagnóstico.You can send chunks of diagnostic data and inspect them in Diagnostic Search.

No .NET, os Adaptadores de log usam essa API para enviar logs de terceiros ao portal.In .NET Log adapters use this API to send third-party logs to the portal.

Em Java para Standard loggers like Log4J, Logback use o Application Insights Log4j ou Logback Appenders para enviar logs de terceiros para o portal.In Java for Standard loggers like Log4J, Logback use Application Insights Log4j or Logback Appenders to send third-party logs to the portal.

C#C#

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

JavaJava

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

Node.jsNode.js

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

JavaScript do lado do cliente/navegadorClient/Browser-side JavaScript

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

Registrar um evento de diagnóstico, como entrar ou sair de um método.Log a diagnostic event such as entering or leaving a method.

ParâmetroParameter DescriçãoDescription
message Dados de diagnóstico.Diagnostic data. Pode ser muito mais longo do que um nome.Can be much longer than a name.
properties Mapa de cadeia de caracteres para cadeia de caracteres: dados adicionais usados para Filtrar exceções no Portal.Map of string to string: Additional data used to filter exceptions in the portal. O padrão é vazio.Defaults to empty.
severityLevel Valores com suporte: nível. TSSupported values: SeverityLevel.ts

Você pode pesquisar no conteúdo da mensagem, mas (diferentemente de valores de propriedade) não é possível filtrar nele.You can search on message content, but (unlike property values) you can't filter on it.

O limite de tamanho de message é muito maior do que o limite de propriedades.The size limit on message is much higher than the limit on properties. Uma vantagem de TrackTrace é que você pode colocar dados relativamente compridos na mensagem.An advantage of TrackTrace is that you can put relatively long data in the message. Por exemplo, você pode codificar dados POST.For example, you can encode POST data there.

Além disso, você pode adicionar um nível de severidade à mensagem.In addition, you can add a severity level to your message. 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.And, like other telemetry, you can add property values to help you filter or search for different sets of traces. Por exemplo:For example:

C#C#

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

JavaJava

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.In Search, you can then easily filter out all the messages of a particular severity level that relate to a particular database.

Rastreamentos na AnáliseTraces in Analytics

Na Análise do Application Insights, as chamadas para TrackTrace aparecem na tabela traces.In Application Insights Analytics, calls to TrackTrace show up in the traces table.

Se a amostragem estiver em funcionamento, a propriedade itemCount mostrará um valor maior que 1.If sampling is in operation, the itemCount property shows a value greater than 1. Para exemplo itemCount==10 significa que de 10 chamadas para trackTrace(), o processo de amostragem somente transmitirá um deles.For example itemCount==10 means that of 10 calls to trackTrace(), the sampling process only transmitted one of them. Para obter uma contagem correta de chamadas de rastreamento, você deverá, portanto, usar um código como traces | summarize sum(itemCount).To get a correct count of trace calls, you should use therefore code such as traces | summarize sum(itemCount).

TrackDependencyTrackDependency

Use a chamada a TrackDependency para acompanhar os tempos de resposta e taxas de êxito de chamadas a uma parte externa do código.Use the TrackDependency call to track the response times and success rates of calls to an external piece of code. Os resultados são exibidos nos gráficos de dependência no portal.The results appear in the dependency charts in the portal. O trecho de código abaixo precisa ser adicionado sempre que uma chamada de dependência é feita.The code snippet below needs to be added wherever a dependency call is made.

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

JavaJava

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);
    RemoteDependencyTelemetry.setTimeStamp(startTime);
    RemoteDependencyTelemetry.trackDependency(dependencyTelemetry);
}

Node.jsNode.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.Remember that the server SDKs include a dependency module that discovers and tracks certain dependency calls automatically--for example, to databases and REST APIs. Você precisa instalar um agente em seu servidor para fazer com que o módulo funcione.You have to install an agent on your server to make the module work.

Em Java, algumas chamadas de dependência podem ser automaticamente rastreadas com o Agente Java.In Java, certain dependency calls can be automatically tracked using Java Agent.

Use essa chamada se quiser rastrear chamadas que o rastreamento automatizado não captura ou se não quiser instalar o agente.You use this call if you want to track calls that the automated tracking doesn't catch, or if you don't want to install the agent.

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.To turn off the standard dependency-tracking module in C#, edit ApplicationInsights.config and delete the reference to DependencyCollector.DependencyTrackingTelemetryModule. Em Java, não instale o agente de java se você não deseja coletar dependências padrão automaticamente.In Java, please do not install java agent if you do not want to collect standard dependencies automatically.

Dependências na AnáliseDependencies in Analytics

Na Análise do Application Insights, as chamadas para trackDependency aparecem na tabela dependencies.In Application Insights Analytics, trackDependency calls show up in the dependencies table.

Se a amostragem estiver em funcionamento, a propriedade itemCount mostrará um valor maior que 1.If sampling is in operation, the itemCount property shows a value greater than 1. Para exemplo itemCount==10 significa que de 10 chamadas para trackDependency(), o processo de amostragem somente transmitirá um deles.For example itemCount==10 means that of 10 calls to trackDependency(), the sampling process only transmitted one of them. Para obter uma contagem correta das dependências segmentadas por componente de destino, use um código como:To get a correct count of dependencies segmented by target component, use code such as:

dependencies
| summarize sum(itemCount) by target

Para associar as solicitações relacionadas a dependências, use uma junção:To associate dependencies with their related requests, use a join:

dependencies
| join (requests) on operation_Id

Liberando dadosFlushing data

Normalmente, o SDK envia dados em intervalos fixos (normalmente 30 segundos) ou sempre que o buffer estiver cheio (normalmente 500 itens).Normally, the SDK sends data at fixed intervals (typically 30 secs) or whenever buffer is full (typically 500 items). No entanto, em alguns casos, você talvez queira liberar o buffer - por exemplo, se estiver usando o SDK em um aplicativo que é desligado.However, in some cases, you might want to flush the buffer--for example, if you are using the SDK in an application that shuts down.

C#C#

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

JavaJava

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

Node.jsNode.js

telemetry.flush();

A função é assíncrona para o canal de telemetria do servidor.The function is asynchronous for the server telemetry channel.

Idealmente, o método flush () deve ser usado na atividade de desligamento do Aplicativo.Ideally, flush() method should be used in the shutdown activity of the Application.

usuários autenticadosAuthenticated users

Em um aplicativo Web, os usuários são (por padrão) identificados por cookies.In a web app, users are (by default) identified by cookies. 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.A user might be counted more than once if they access your app from a different machine or browser, or if they delete 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:If users sign in to your app, you can get a more accurate count by setting the authenticated user ID in the browser code:

JavaScriptJavaScript

// 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:In an ASP.NET web MVC application, for example:

RazorRazor

@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.It isn't necessary to use the user's actual sign-in name. Só é preciso ser uma ID que seja exclusiva para esse usuário.It only has to be an ID that is unique to that user. Não deve incluir espaços, nem os caracteres ,;=|.It must not include spaces or any of the characters ,;=|.

A ID de usuário também é definida em um cookie de sessão e enviada ao servidor.The user ID is also set in a session cookie and sent to the server. 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.If the server SDK is installed, the authenticated user ID is sent as part of the context properties of both client and server telemetry. Assim, você poderá filtrar e pesquisar nele.You can then filter and search on it.

Se seu aplicativo agrupa os usuários em contas, você também pode passar um identificador para a conta (com as mesmas restrições de caracteres).If your app groups users into accounts, you can also pass an identifier for the account (with the same character restrictions).

appInsights.setAuthenticatedUserContext(validatedId, accountId);

No Metrics Explorer, você pode criar um gráfico que contabiliza Usuários Autenticados e Contas de usuário.In Metrics Explorer, you can create a chart that counts Users, Authenticated, and User accounts.

Você também pode Pesquisar pontos de dados do cliente com contas e nomes de usuário específicos.You can also Search for client data points with specific user names and accounts.

Filtragem, pesquisa e segmentação de dados usando propriedadesFiltering, searching, and segmenting your data by using properties

Você pode anexar propriedades e medidas para seus eventos (e também para métricas, exibições de página e outros dados de telemetria).You can attach properties and measurements to your events (and also to metrics, page views, exceptions, and other telemetry data).

Propriedades são valores de cadeia de caracteres que você pode usar para filtrar a telemetria nos relatórios de uso.Properties are string values that you can use to filter your telemetry in the usage reports. 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.For example, if your app provides several games, you can attach the name of the game to each event so that you can see which games are more popular.

Há um limite de 8192 para o tamanho da cadeia de caracteres.There's a limit of 8192 on the string length. (Se você deseja enviar grandes quantidades de dados, use o parâmetro de mensagem de TrackTrace.)(If you want to send large chunks of data, use the message parameter of TrackTrace.)

Métricas são valores numéricos que podem ser apresentados graficamente.Metrics are numeric values that can be presented graphically. Por exemplo, convém verificar se há um aumento gradual nas pontuações que seus jogadores atingem.For example, you might want to see if there's a gradual increase in the scores that your gamers achieve. Os grafos podem ser segmentados pelas propriedades enviadas com o evento para que você possa obter grafos separado ou empilhados para jogos diferentes.The graphs can be segmented by the properties that are sent with the event, so that you can get separate or stacked graphs for different games.

Para que os valores de métrica sejam exibidos corretamente, eles devem ser maiores ou iguais a 0.For metric values to be correctly displayed, they should be greater than or equal to 0.

Há alguns limites no número de propriedades, valores de propriedade e métricas que você pode usar.There are some limits on the number of properties, property values, and metrics that you can use.

JavaScriptJavaScript

appInsights.trackEvent
    ("WinGame",
        // String properties:
        {Game: currentGame.name, Difficulty: currentGame.difficulty},
        // Numeric metrics:
        {Score: currentGame.score, Opponents: currentGame.opponentCount}
        );

appInsights.trackPageView
    ("page name", "http://fabrikam.com/pageurl.html",
        // String properties:
        {Game: currentGame.name, Difficulty: currentGame.difficulty},
        // Numeric metrics:
        {Score: currentGame.score, Opponents: currentGame.opponentCount}
        );

C#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.jsNode.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 BasicVisual 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)

JavaJava

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.Take care not to log personally identifiable information in properties.

Maneira alternativa de definir propriedades e métricasAlternative way to set properties and metrics

Se for mais conveniente, você poderá coletar os parâmetros de um evento em um objeto separado:If it's more convenient, you can collect the parameters of an event in a separate object:

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.Don't reuse the same telemetry item instance (event in this example) to call Track*() multiple times. Isso pode fazer com que a telemetria seja enviada com a configuração incorreta.This may cause telemetry to be sent with incorrect configuration.

Medidas personalizadas e propriedades na AnáliseCustom measurements and properties in Analytics

Na Análise, as métricas personalizadas e as propriedades são exibidas nos atributos customMeasurements e customDimensions de cada registro de telemetria.In Analytics, custom metrics and properties show in the customMeasurements and customDimensions attributes of each telemetry record.

Por exemplo, se você tiver adicionado uma propriedade chamada "game" para a telemetria de solicitação, essa consulta contará as ocorrências de valores diferentes de "game" e mostrará a média da "pontuação" da métrica personalizada:For example, if you have added a property named "game" to your request telemetry, this query counts the occurrences of different values of "game", and show the average of the custom metric "score":

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

Observe que:Notice that:

  • Quando você extrai um valor do JSON customDimensions ou customMeasurements, ele tem o tipo dinâmico e, portanto, você deve convertê-lo em tostring ou todouble.When you extract a value from the customDimensions or customMeasurements JSON, it has dynamic type, and so you must cast it tostring or todouble.
  • Para levar em conta a possibilidade de amostragem, você deverá usar sum(itemCount), e não count().To take account of the possibility of sampling, you should use sum(itemCount), not count().

Eventos de tempoTiming events

Às vezes, você quer colocar em gráfico quanto tempo leva para realizar uma ação.Sometimes you want to chart how long it takes to perform an action. Por exemplo, talvez você queira saber quanto tempo os usuários levam para considerar as opções de um jogo.For example, you might want to know how long users take to consider choices in a game. Você pode usar o parâmetro measurement para isso.You can use the measurement parameter for this.

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

JavaJava

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 personalizadaDefault properties for custom telemetry

Se quiser definir valores de propriedade padrão para alguns dos eventos personalizados que escrever, você poderá defini-los em uma instância de TelemetryClient.If you want to set default property values for some of the custom events that you write, you can set them in a TelemetryClient instance. Eles são anexados a cada item de telemetria enviado do cliente.They are attached to every telemetry item that's sent from that client.

C#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 BasicVisual 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")

JavaJava

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.jsNode.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.Individual telemetry calls can override the default values in their property dictionaries.

Para clientes Web JavaScript, use inicializadores de telemetria JavaScript.For JavaScript web clients, use JavaScript telemetry initializers.

Para adicionar propriedades a toda a telemetria, incluindo os dados de módulos de coleta padrão, implemente ITelemetryInitializer.To add properties to all telemetry, including the data from standard collection modules, implement ITelemetryInitializer.

Amostragem, filtragem e processamento da telemetriaSampling, filtering, and processing telemetry

É possível escrever códigos para processar a telemetria antes que ela seja enviada do SDK.You can write code to process your telemetry before it's sent from the SDK. O processamento inclui dados que são enviados dos módulos de telemetria padrão, como a coleta de solicitação HTTP e a coleta de dependência.The processing includes data that's sent from the standard telemetry modules, such as HTTP request collection and dependency collection.

Adicione propriedades à telemetria implementando ITelemetryInitializer.Add properties to telemetry by implementing ITelemetryInitializer. Por exemplo, é possível adicionar números de versão ou valores que são calculados de outras propriedades.For example, you can add version numbers or values that are calculated from other properties.

A filtragem pode modificar ou descartar a telemetria antes que ela seja enviada do SDK pela implementação de ITelemetryProcessor.Filtering can modify or discard telemetry before it's sent from the SDK by implementing ITelemetryProcessor. Você controla o que é enviado ou descartado, mas precisa levar em conta o efeito em suas métricas.You control what is sent or discarded, but you have to account for the effect on your metrics. Dependendo de como você descartar os itens, você poderá perder a capacidade de navegar entre itens relacionados.Depending on how you discard items, you might lose the ability to navigate between related items.

A amostragem é uma solução em pacote para reduzir o volume de dados enviados de seu aplicativo ao portal.Sampling is a packaged solution to reduce the volume of data that's sent from your app to the portal. Isso é feito sem afetar as métricas exibidas.It does so without affecting the displayed metrics. E também sem afetar sua capacidade de diagnosticar problemas ao navegar entre itens relacionados, como exceções, solicitações e exibições de página.And it does so without affecting your ability to diagnose problems by navigating between related items such as exceptions, requests, and page views.

Saiba mais.Learn more.

Desabilitando a telemetriaDisabling telemetry

Para parar e iniciar dinamicamente a coleta e a transmissão de telemetria:To dynamically stop and start the collection and transmission of telemetry:

C#C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

JavaJava

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 em ApplicationInsights.config. Você pode fazer isso, por exemplo, se quiser enviar seus próprios dados do TrackRequest.To disable selected standard collectors--for example, performance counters, HTTP requests, or dependencies--delete or comment out the relevant lines in ApplicationInsights.config. You can do this, for example, if you want to send your own TrackRequest data.

Node.jsNode.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:To disable selected standard collectors--for example, performance counters, HTTP requests, or dependencies--at initialization time, chain configuration methods to your SDK initialization code:

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)To disable these collectors after initialization, use the Configuration object: applicationInsights.Configuration.setAutoCollectRequests(false)

Modo de desenvolvedorDeveloper mode

Durante a depuração, é útil ter sua telemetria emitida pelo pipeline para que você possa ver os resultados imediatamente.During debugging, it's useful to have your telemetry expedited through the pipeline so that you can see results immediately. Você também obtém mensagens adicionais que ajudarão a rastrear problemas com a telemetria.You also get additional messages that help you trace any problems with the telemetry. Desative-a na produção, pois isso pode tornar seu aplicativo mais lento.Switch it off in production, because it may slow down your app.

C#C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual BasicVisual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.jsNode.js

Por Node.js, você pode habilitar o modo de desenvolvedor habilitando o log interno por meio setInternalLogging maxBatchSize da configuração para 0, o que faz com que a telemetria seja enviada assim que for coletada.For Node.js, you can enable developer mode by enabling internal logging via setInternalLogging and setting maxBatchSize to 0, which causes your telemetry to be sent as soon as it is collected.

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

Definição da chave de instrumentação para telemetria personalizada selecionadaSetting the instrumentation key for selected custom telemetry

C#C#

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

Chave de instrumentação dinâmicaDynamic instrumentation key

Para evitar a mistura de telemetria de ambientes de desenvolvimento, teste e produção, você pode criar Application insights recursos separados e alterar suas chaves, dependendo do ambiente.To avoid mixing up telemetry from development, test, and production environments, you can create separate Application Insights resources and change their keys, depending on the environment.

Em vez de obter a chave de instrumentação do arquivo de configuração, você pode defini-la em seu código.Instead of getting the instrumentation key from the configuration file, you can set it in your code. Defina a chave em um método de inicialização como global.aspx.cs em um serviço ASP.NET:Set the key in an initialization method, such as global.aspx.cs in an ASP.NET service:

C#C#

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

JavaScriptJavaScript

appInsights.config.instrumentationKey = myKey;

Em páginas da Web, convém defini-la com base no estado do servidor Web, em vez de codificá-la literalmente no script.In webpages, you might want to set it from the web server's state, rather than coding it literally into the script. Por exemplo, em uma página da Web gerada em um aplicativo ASP.NET:For example, in a webpage generated in an ASP.NET app:

JavaScript no RazorJavaScript in 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);
    }

TelemetryContextTelemetryContext

TelemetryClient tem uma propriedade de Contexto, que contém valores que serão enviadas com todos os dados de telemetria.TelemetryClient has a Context property, which contains values that are sent along with all telemetry data. Normalmente, eles são definidos pelos módulos padrão de telemetria, mas você pode também defini-las por conta própria.They are normally set by the standard telemetry modules, but you can also set them yourself. Por exemplo:For example:

telemetry.Context.Operation.Name = "MyOperationName";

Se você definir qualquer um desses valores por conta própria, considere remover a linha relevante de ApplicationInsights.config, de modo que não haja confusão entre os seus valores e os valores padrão.If you set any of these values yourself, consider removing the relevant line from ApplicationInsights.config, so that your values and the standard values don't get confused.

  • Componente: o aplicativo e sua versão.Component: The app and its version.
  • Dispositivo: dados sobre o dispositivo onde o aplicativo está sendo executado.Device: Data about the device where the app is running. (Em aplicativos Web, esse é o servidor ou dispositivo cliente do qual a telemetria é enviada).(In web apps, this is the server or client device that the telemetry is sent from.)
  • InstrumentationKey: o recurso de Application insights no Azure em que a telemetria é exibida.InstrumentationKey: The Application Insights resource in Azure where the telemetry appears. Normalmente, escolhido no Applicationinsights.config.It's usually picked up from ApplicationInsights.config.
  • Local: a localização geográfica do dispositivo.Location: The geographic location of the device.
  • Operação: em aplicativos Web, a solicitação HTTP atual.Operation: In web apps, the current HTTP request. Em outros tipos de aplicativos, você pode definir isso para agrupar eventos juntos.In other app types, you can set this to group events together.
    • ID: um valor gerado que correlaciona eventos diferentes, de modo que, quando você inspeciona qualquer evento na pesquisa de diagnóstico, você pode encontrar itens relacionados.ID: A generated value that correlates different events, so that when you inspect any event in Diagnostic Search, you can find related items.
    • Nome: um identificador, geralmente a URL da solicitação HTTP.Name: An identifier, usually the URL of the HTTP request.
    • 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.SyntheticSource: If not null or empty, a string that indicates that the source of the request has been identified as a robot or web test. Por padrão, ela é excluída dos cálculos no Metrics Explorer.By default, it is excluded from calculations in Metrics Explorer.
  • Propriedades: propriedades que são enviadas com todos os dados de telemetria.Properties: Properties that are sent with all telemetry data. Pode ser substituído nas chamadas individuais de Track*.It can be overridden in individual Track* calls.
  • Sessão: a sessão do usuário.Session: The user's session. A ID é definida para um valor gerado, que é alterado quando o usuário ficar inativo por um tempo.The ID is set to a generated value, which is changed when the user has not been active for a while.
  • Usuário: informações do usuário.User: User information.

limitesLimits

Há alguns limites no número de métricas e eventos por aplicativo, ou seja, por chave de instrumentação.There are some limits on the number of metrics and events per application, that is, per instrumentation key. Os limites dependem do plano de preços que você escolher.Limits depend on the pricing plan that you choose.

RecursoResource Limite padrãoDefault limit ObservaçãoNote
Total de dados por diaTotal data per day 100 GB100 GB Você pode reduzir os dados ao definir um limite.You can reduce data by setting a cap. Caso precise de mais dados, é possível aumentar o limite até 1.000 GB.If you need more data, you can increase the limit in the portal, up to 1,000 GB. Para capacidades maiores que 1.000 GB, envie um email para AIDataCap@microsoft.com .For capacities greater than 1,000 GB, send email to AIDataCap@microsoft.com.
LimitaçãoThrottling 32.000 eventos/segundo32,000 events/second O limite é medido em um minuto.The limit is measured over a minute.
Retenção de dadosData retention 30-730 dias30 - 730 days Este recurso destina-se a Pesquisa, Análise e Metrics Explorer.This resource is for Search, Analytics, and Metrics Explorer.
Retenção de resultados detalhados do Teste de disponibilidade de várias etapasAvailability multi-step test detailed results retention 90 dias90 days Esse recurso fornece resultados detalhados de cada etapa.This resource provides detailed results of each step.
Tamanho máximo do item de telemetriaMaximum telemetry item size 64 kB64 kB
Máximo de itens de telemetria por loteMaximum telemetry items per batch 64 k64 K
Tamanho dos nomes de propriedade e métricaProperty and metric name length 150150 Veja esquemas de tipo.See type schemas.
Tamanho da cadeia de caracteres do valor da propriedadeProperty value string length 8.1928,192 Veja esquemas de tipo.See type schemas.
Comprimento da mensagem de rastreamento e de exceçãoTrace and exception message length 32.76832,768 Veja esquemas de tipo.See type schemas.
Contagem de testes de disponibilidade por aplicativoAvailability tests count per app 100100
Retenção de dados do criador de perfilProfiler data retention 5 dias5 days
Dados do criador de perfil enviados por diaProfiler data sent per day 10 GB10 GB

Para obter mais informações, consulte sobre preços e cotas no Application Insights.For more information, see About pricing and quotas in Application Insights.

Para evitar atingir o limite de taxa de dados, use amostragem.To avoid hitting the data rate limit, use sampling.

Para determinar por quanto tempo os dados são mantidos, confira Retenção e privacidade de dados.To determine how long data is kept, see Data retention and privacy.

Documentos de ReferênciaReference docs

Código do SDKSDK code

PerguntasQuestions

  • Que exceções podem ser lançadas por chamadas Track_()?What exceptions might Track_() calls throw?

    Nenhum.None. Você não precisa encapsulá-las em cláusulas try-catch.You don't need to wrap them in try-catch clauses. Se o SDK encontrar problemas, ele registrará mensagens em log na saída do console de depuração e (se elas passarem despercebidas) na Pesquisa de Diagnóstico.If the SDK encounters problems, it will log messages in the debug console output and--if the messages get through--in Diagnostic Search.

  • Há uma API REST para obter dados do portal?Is there a REST API to get data from the portal?

    Sim, a API de acesso a dados.Yes, the data access API. Outras maneiras de extrair dados incluem exportar do Analytics para o Power BI e a exportação contínua.Other ways to extract data include export from Analytics to Power BI and continuous export.

Próximas etapasNext steps