API Application Insights для пользовательских событий и метрикApplication Insights API for custom events and metrics

Вставьте несколько строк кода в свое приложение, чтобы узнать, как пользователи его используют, или чтобы диагностировать неполадки.Insert a few lines of code in your application to find out what users are doing with it, or to help diagnose issues. Вы можете отправлять телеметрию из устройств и классических приложений, веб-клиентов и веб-серверов.You can send telemetry from device and desktop apps, web clients, and web servers. Используйте основной API телеметрии Azure Application Insights, чтобы отправлять пользовательские события и метрики, а также собственные версии стандартной телеметрии.Use the Azure Application Insights core telemetry API to send custom events and metrics, and your own versions of standard telemetry. Этот же API используется стандартными сборщиками данных Application Insights.This API is the same API that the standard Application Insights data collectors use.

Сводные данные APIAPI summary

Этот основной API используется на всех платформах, за некоторыми исключениями, например GetMetric (только в .NET).The core API is uniform across all platforms, apart from a few variations like GetMetric(.NET only).

МетодMethod Используется дляUsed for
TrackPageView Страницы, экраны, колонки или формы.Pages, screens, blades, or forms.
TrackEvent Действия пользователя и другие события.User actions and other events. Используется для отслеживания поведения пользователя или мониторинга производительности.Used to track user behavior or to monitor performance.
GetMetric Нулевые и многомерные метрики, централизованное агрегирование, только в C#.Zero and multi-dimensional metrics, centrally configured aggregation, C# only.
TrackMetric Измерения производительности, не связанные с конкретными событиями, например, измерение длины очереди.Performance measurements such as queue lengths not related to specific events.
TrackException Регистрация исключений для диагностики.Logging exceptions for diagnosis. Отслеживайте исключения, связанные с другими событиями, и изучайте трассировку стека.Trace where they occur in relation to other events and examine stack traces.
TrackRequest Регистрация частоты и длительности запросов к серверу для анализа производительности.Logging the frequency and duration of server requests for performance analysis.
TrackTrace Сообщения журнала диагностики ресурсов.Resource Diagnostic log messages. Можно также использовать журналы сторонних приложений.You can also capture third-party logs.
TrackDependency Регистрация длительности и частоты вызовов внешних компонентов, от которых зависит приложение.Logging the duration and frequency of calls to external components that your app depends on.

Вы можете прикрепить свойства и метрики к большинству этих вызовов телеметрии.You can attach properties and metrics to most of these telemetry calls.

Перед началом работыBefore you start

Если у вас еще нет ссылки на пакет SDK Application Insights, выполните указанные ниже действия.If you don't have a reference on Application Insights SDK yet:

Получение экземпляра TelemetryClientGet a TelemetryClient instance

Получите экземпляр TelemetryClient (без использования JavaScript на веб-страницах).Get an instance of TelemetryClient (except in JavaScript in webpages):

Для приложений ASP.NET Core и не HTTP/Worker для приложений .NET и .NET Core рекомендуется получить экземпляр TelemetryClient из контейнера внедрения зависимостей, как описано в соответствующей документации.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.

Если вы используете Азурефунктионс v2 + или веб-задания Azure v3 + – следуйте этому документу: 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();

Для всех, кто видит этот метод, — это устаревшие сообщения. Дополнительные сведения см. в Microsoft/ApplicationInsights-DotNet # 1152 .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 является потокобезопасным.TelemetryClient is thread-safe.

Для проектов ASP.NET и Java автоматически фиксируются входящие HTTP-запросы.For ASP.NET and Java projects, incoming HTTP Requests are automatically captured. Возможно, потребуется создать дополнительные экземпляры TelemetryClient для другого модуля вашего приложения.You might want to create additional instances of TelemetryClient for other module of your app. Например, у вас может быть один экземпляр TelemetryClient в классе промежуточного ПО для отчетов о событиях бизнес-логики.For instance, you may have one TelemetryClient instance in your middleware class to report business logic events. Можно задать свойства, такие как идентификатор пользователя (UserId) и идентификатор устройства (DeviceId), для идентификации компьютера.You can set properties such as UserId and DeviceId to identify the machine. Эти данные прикрепляются ко всем событиям, отправляемым экземпляром.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("...");

В проектах Node.js для создания экземпляра можно использовать команду new applicationInsights.TelemetryClient(instrumentationKey?). Но эта команда рекомендуется, только если требуется конфигурация, отдельная от единственного экземпляра defaultClient.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.

TrackEvent (Отслеживание событий)TrackEvent

В Application Insights пользовательское событие — это точка данных, которую можно отобразить как суммарное значение в обозревателе метрик, а также как отдельные значения на вкладке поиска по журналу диагностики.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. (Оно не связано с MVC и другими "событиями" платформы.)(It isn't related to MVC or other framework "events.")

Вставьте вызовы TrackEvent в код для подсчета различных событий:Insert TrackEvent calls in your code to count various events. как часто пользователи выбирают определенный компонент, как часто они достигают определенных целей, а также как часто возникают те или иные ошибки.How often users choose a particular feature, how often they achieve particular goals, or maybe how often they make particular types of mistakes.

Например, отправляйте событие в игровом приложении при каждом выигрыше пользователя: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"});

Пользовательские события в службе аналитикиCustom events in Analytics

Данные телеметрии доступны в customEvents таблице на вкладке Application Insights журналов или в процессе использования.The telemetry is available in the customEvents table in Application Insights Logs tab or Usage Experience. События могут поступать trackEvent(..) или щелкнуть подключаемый модуль автоматической коллекции аналитики.Events may come from trackEvent(..) or Click Analytics Auto-collection Plugin.

Если действует выборка, свойство itemCount имеет значение больше 1.If sampling is in operation, the itemCount property shows a value greater than 1. Например, itemCount==10 означает, что из 10 вызовов trackEvent() процесс выборки передал только один.For example itemCount==10 means that of 10 calls to trackEvent(), the sampling process only transmitted one of them. Чтобы получить правильное количество пользовательских событий, необходимо использовать код, такой как customEvents | summarize sum(itemCount) .To get a correct count of custom events, you should therefore use code such as customEvents | summarize sum(itemCount).

GetMetricGetMetric

Чтобы узнать, как эффективно использовать вызов методаической метрики () для отслеживания локальных предварительно агрегированных метрик для приложений .NET и .NET Core, посетите документацию по функции Intel.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.

TrackMetric (Отслеживание метрик)TrackMetric

Примечание

Microsoft. ApplicationInsights. TelemetryClient. TrackMetric не является предпочтительным методом отправки метрик.Microsoft.ApplicationInsights.TelemetryClient.TrackMetric is not the preferred method for sending metrics. Метрики всегда нужно предварительно агрегировать в течение определенного периода перед отправкой.Metrics should always be pre-aggregated across a time period before being sent. Используйте одну из перегрузок GetMetric(..), чтобы получить объект метрики для доступа к возможностям предварительного агрегирования пакета SDK.Use one of the GetMetric(..) overloads to get a metric object for accessing SDK pre-aggregation capabilities. При реализации собственной логики предварительной обработки можно использовать метод TrackMetric () для отправки итоговых статистических выражений.If you are implementing your own pre-aggregation logic, you can use the TrackMetric() method to send the resulting aggregates. Если приложению требуется каждый раз отправить отдельный элемент телеметрии без агрегирования в течение определенного периода, скорее всего, у вас уже есть вариант использования телеметрии события; см. метод 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).

Application Insights может создать диаграмму метрик, не привязанных к определенным событиям.Application Insights can chart metrics that are not attached to particular events. Например, можно отслеживать длину очереди через регулярные промежутки времени.For example, you could monitor a queue length at regular intervals. Благодаря метрикам отдельные измерения менее интересны, чем вариации и тенденции, и поэтому статистические диаграммы полезны.With metrics, the individual measurements are of less interest than the variations and trends, and so statistical charts are useful.

Для отправки метрик в Application Insights можно использовать API TrackMetric(..).In order to send metrics to Application Insights, you can use the TrackMetric(..) API. Отправить метрику можно двумя способами.There are two ways to send a metric:

  • Отдельное значение.Single value. Каждый раз при выполнении измерения в приложении вы отправляете соответствующее значение в Application Insights.Every time you perform a measurement in your application, you send the corresponding value to Application Insights. Например, предположим, что имеется метрика, описывающая число элементов в контейнере.For example, assume that you have a metric describing the number of items in a container. В течение некоторого периода времени вы сначала помещаете три элемента в контейнер, а затем удаляете два элемента.During a particular time period, you first put three items into the container and then you remove two items. Соответственно, TrackMetric вызывается дважды: сначала передается значение 3, а затем значение -2.Accordingly, you would call TrackMetric twice: first passing the value 3 and then the value -2. Application Insights сохраняет оба значения от вашего имени.Application Insights stores both values on your behalf.

  • Агрегирование.Aggregation. При работе с метриками отдельные измерения редко представляют интерес.When working with metrics, every single measurement is rarely of interest. Вместо этого обычно важна сводка того, что произошло за определенный период времени.Instead a summary of what happened during a particular time period is important. Такая сводка называется агрегированием.Such a summary is called aggregation. В приведенном выше примере сумма агрегированной метрики за период времени равна 1, а число значений метрики — 2.In the above example, the aggregate metric sum for that time period is 1 and the count of the metric values is 2. При использовании агрегирования TrackMetric вызывается только один раз для каждого периода времени и отправляются агрегированные значения.When using the aggregation approach, you only invoke TrackMetric once per time period and send the aggregate values. Это рекомендуемый подход, так как он может значительно снизить затраты и потери производительности благодаря отправке меньшего числа точек данных в Application Insights. При этом собирается вся важная информация.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.

ПримерыExamples

Отдельные значенияSingle values

Отправка значения одной метрики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});

Настраиваемые метрики в аналитикеCustom metrics in Analytics

Данные телеметрии доступны в таблице customMetrics в службе аналитики Application Insights.The telemetry is available in the customMetrics table in Application Insights Analytics. Каждая строка представляет собой вызов trackMetric(..) в приложении.Each row represents a call to trackMetric(..) in your app.

  • valueSum — это сумма измерений.valueSum - This is the sum of the measurements. Чтобы получить среднее значение, разделите текущее значение на значение valueCount.To get the mean value, divide by valueCount.
  • valueCount — число измерений, агрегированных в этот вызов trackMetric(..).valueCount - The number of measurements that were aggregated into this trackMetric(..) call.

Просмотры страницPage views

В устройстве или приложении веб-страницы телеметрия просмотров страницы отображается по умолчанию при загрузке каждого экрана или страницы.In a device or webpage app, page view telemetry is sent by default when each screen or page is loaded. Однако это можно изменить, чтобы отслеживать количество просмотров страницы в дополнительное или другое время.But you can change that to track page views at additional or different times. Например, в приложении, которое отображает вкладки или колонки, может потребоваться отслеживать страницу каждый раз, когда пользователь открывает новую колонку.For example, in an app that displays tabs or blades, you might want to track a page whenever the user opens a new blade.

Данные о пользователе и сеансе отправляются в качестве свойств вместе с количеством просмотров страниц, поэтому диаграммы для пользователей и сеансов активируются при наличии телеметрии по количеству просмотров страницы.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.

Пользовательские данные о просмотре страницыCustom page views

JavaScriptJavaScript

appInsights.trackPageView("tab1");

C#C#

telemetry.TrackPageView("GameReviewPage");

Visual BasicVisual Basic

telemetry.TrackPageView("GameReviewPage")

JavaJava

telemetry.trackPageView("GameReviewPage");

Если у вас есть несколько вкладок на различных HTML-страницах, можно также указать URL-адрес:If you have several tabs within different HTML pages, you can specify the URL too:

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

Время просмотра страницTiming page views

По умолчанию время, отображаемое как Время загрузки страницы, отсчитывается от момента отправки запроса браузером до вызова события загрузки страницы в браузере.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.

Вместо этого вы можете выбрать один из таких вариантов:Instead, you can either:

  • Задайте явную длительность вызова trackPageView: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.Set an explicit duration in the trackPageView call: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Используйте вызовы времени просмотра страницы startTrackPage и 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);

Имя, используемое в качестве первого параметра, связывает вызовы start и stop.The name that you use as the first parameter associates the start and stop calls. По умолчанию используется имя текущей страницы.It defaults to the current page name.

Полученные длительности загрузки страниц, отображаемые в обозревателе метрик, являются производными интервала между вызовами start и stop.The resulting page load durations displayed in Metrics Explorer are derived from the interval between the start and stop calls. Выбор рассматриваемого интервала за вами.It's up to you what interval you actually time.

Телеметрия страниц в службе аналитикиPage telemetry in Analytics

В службе аналитики две таблицы содержат данные по операциям в браузере.In Analytics two tables show data from browser operations:

  • Таблица pageViews содержит данные по URL-адресу и названию страницы.The pageViews table contains data about the URL and page title
  • Таблица browserTimings содержит данные по производительности клиента, например время, затраченное на обработку входящих данных.The browserTimings table contains data about client performance, such as the time taken to process the incoming data

Чтобы узнать, сколько времени требуется браузеру на обработку различных страниц, используйте следующий код:To find how long the browser takes to process different pages:

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

Чтобы установить популярность различных браузеров, используйте следующий код:To discover the popularities of different browsers:

pageViews
| summarize count() by client_Browser

Чтобы связать просмотры страниц с вызовами AJAX, выполните объединение с зависимостями:To associate page views to AJAX calls, join with dependencies:

pageViews
| join (dependencies) on operation_Id 

TrackRequest (Отслеживание запросов)TrackRequest

TrackRequest используется в серверном пакете SDK, чтобы регистрировать HTTP-запросы.The server SDK uses TrackRequest to log HTTP requests.

Его можно также вызвать самостоятельно, чтобы смодулировать запросы в контексте, в котором отсутствует выполняющийся модуль веб-службы.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.

Мы рекомендуем отправлять телеметрию запроса, выступающего в качестве контекста операции.However, the recommended way to send request telemetry is where the request acts as an operation context.

Контекст операцииOperation context

Вы можете коррелировать элементы телеметрии между собой. Для этого свяжите их с контекстом операции.You can correlate telemetry items together by associating them with operation context. Стандартный модуль отслеживания запросов делает это для исключений и других событий, отправляемых во время обработки HTTP-запроса.The standard request-tracking module does this for exceptions and other events that are sent while an HTTP request is being processed. В службе Поиск и службе Analytics можно легко найти все события, связанные с запросом при помощи его идентификатора операции.In Search and Analytics, you can easily find any events associated with the request using its operation ID.

Дополнительные сведения о корреляции см. в статье Корреляция данных телеметрии в Application Insights.See Telemetry correlation in Application Insights for more details on correlation.

Если вы отслеживаете телеметрию вручную, проще всего выполнить ее корреляцию с помощью этого шаблона: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.

Наряду с определением контекста операции StartOperation создает элемент телеметрии указанного вами типаAlong with setting an operation context, StartOperation creates a telemetry item of the type that you specify. и отправляет его при удалении операции или при явном вызове StopOperation.It sends the telemetry item when you dispose the operation, or if you explicitly call StopOperation. При использовании типа телеметрии RequestTelemetry ее длительность задается как временной интервал между запуском и остановкой.If you use RequestTelemetry as the telemetry type, its duration is set to the timed interval between start and stop.

Элементы телеметрии, о которых поступают сведения в пределах операции, становятся дочерними элементами такой операции.Telemetry items reported within a scope of operation become 'children' of such operation. Контексты операции могут быть вложенными.Operation contexts could be nested.

В области поиска контекст операции используется для создания списка связанных элементов :In Search, the operation context is used to create the Related Items list:

Связанные элементы

Дополнительные сведения об отслеживании пользовательских операций см. в статье Отслеживание пользовательских операций с помощью пакета SDK Application Insights для .NET.See Track custom operations with Application Insights .NET SDK for more information on custom operations tracking.

Запросы в аналитикеRequests in Analytics

В службе аналитики Application Insights запросы приводятся в таблице requests.In Application Insights Analytics, requests show up in the requests table.

Если действует выборка, свойство itemCount будет иметь значение больше 1.If sampling is in operation, the itemCount property will show a value greater than 1. Например, itemCount==10 означает, что из 10 вызовов trackRequest() процесс выборки передал только один.For example itemCount==10 means that of 10 calls to trackRequest(), the sampling process only transmitted one of them. Чтобы получить правильное число запросов и среднюю длительность, разбитую по именам запросов, используйте следующий код: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

TrackException (Отслеживание исключений)TrackException

Отправляйте исключения в Application Insights, чтобы:Send exceptions to Application Insights:

Отчеты содержат данные по трассировкам стеков.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});
}

Пакеты SDK перехватывают многие исключения автоматически, поэтому не всегда нужно явно вызвать метод TrackException.The SDKs catch many exceptions automatically, so you don't always have to call TrackException explicitly.

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

Исключения в службе аналитикиExceptions in Analytics

В службе аналитики Application Insights исключения приводятся в таблице exceptions.In Application Insights Analytics, exceptions show up in the exceptions table.

Если действует выборка, свойство itemCount имеет значение больше 1.If sampling is in operation, the itemCount property shows a value greater than 1. Например, itemCount==10 означает, что из 10 вызовов trackException() процесс выборки передал только один.For example itemCount==10 means that of 10 calls to trackException(), the sampling process only transmitted one of them. Чтобы получить правильное число исключений, разбитое по типам исключений, используйте следующий код:To get a correct count of exceptions segmented by type of exception, use code such as:

exceptions
| summarize sum(itemCount) by type

Большая часть важных сведений о стеке уже извлечена в отдельные переменные, однако вы можете разобрать структуру details, чтобы получить дополнительные сведения.Most of the important stack information is already extracted into separate variables, but you can pull apart the details structure to get more. Так как это динамическая структура, результат следует привести к требуемому типу.Since this structure is dynamic, you should cast the result to the type you expect. Например:For example:

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

Чтобы связать исключения с соответствующими запросами, используйте соединение:To associate exceptions with their related requests, use a join:

exceptions
| join (requests) on operation_Id

TrackTrace (Отслеживание трассировки)TrackTrace

Используйте TrackTrace для диагностики неполадок, отправляя навигационную цепочку в Application Insights.Use TrackTrace to help diagnose problems by sending a "breadcrumb trail" to Application Insights. Вы можете отсылать блоки диагностических данных и проверять их в поискепо журналу диагностики.You can send chunks of diagnostic data and inspect them in Diagnostic Search.

В .NET адаптеры журнала используют этот API для отправки журналов сторонних производителей на портал.In .NET Log adapters use this API to send third-party logs to the portal.

В Java для стандартных средств ведения журнала, например Log4J и Logback, используются аппендеры Application Insights Log4J или Logback, позволяющие отправлять журналы сторонних производителей на портал.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 на стороне клиента или браузераClient/Browser-side JavaScript

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

Зарегистрируйте событие диагностики, например вход в метод или выход из него.Log a diagnostic event such as entering or leaving a method.

ПараметрParameter ОписаниеDescription
message Диагностические данныеDiagnostic data. Могут содержать не только имя.Can be much longer than a name.
properties Преобразование строки в строку: дополнительные данные, используемые для фильтрации исключений на портале.Map of string to string: Additional data used to filter exceptions in the portal. Значение по умолчанию: empty.Defaults to empty.
severityLevel Поддерживаемые значения: северитилевел. TSSupported values: SeverityLevel.ts

Вы можете выполнять поиск содержимого сообщения, но (в отличие от значений свойств) не можете фильтровать его.You can search on message content, but (unlike property values) you can't filter on it.

Ограничения по размеру message гораздо выше, чем ограничение для свойств.The size limit on message is much higher than the limit on properties. Преимуществом TrackTrace является возможность добавления в сообщения относительно длинных данных,An advantage of TrackTrace is that you can put relatively long data in the message. например данных POST.For example, you can encode POST data there.

Кроме того, вы можете настроить для сообщения уровень серьезности.In addition, you can add a severity level to your message. Как и для других данных телеметрии, вы можете добавлять значения свойства, используемые для фильтрации или поиска различных наборов трассировки.And, like other telemetry, you can add property values to help you filter or search for different sets of traces. Например: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);

В колонке Поиск вы сможете легко отфильтровать все сообщения с определенной степенью серьезности, относящиеся к определенной базе данных.In Search, you can then easily filter out all the messages of a particular severity level that relate to a particular database.

Трассировки в службе аналитикиTraces in Analytics

В службе аналитики Application Insights вызовы TrackTrace приводятся в таблице traces.In Application Insights Analytics, calls to TrackTrace show up in the traces table.

Если действует выборка, свойство itemCount имеет значение больше 1.If sampling is in operation, the itemCount property shows a value greater than 1. Например, itemCount==10 означает, что из 10 вызовов trackTrace() процесс выборки передал только один.For example itemCount==10 means that of 10 calls to trackTrace(), the sampling process only transmitted one of them. Чтобы получить правильное количество вызовов трассировки, следует использовать такой код, как traces | summarize sum(itemCount).To get a correct count of trace calls, you should use therefore code such as traces | summarize sum(itemCount).

TrackDependency (Отслеживание зависимостей)TrackDependency

Используйте вызов TrackDependency для отслеживания времени отклика и процента успешных попыток вызовов во внешнюю часть кода.Use the TrackDependency call to track the response times and success rates of calls to an external piece of code. Результаты отображаются в диаграммах зависимостей на портале.The results appear in the dependency charts in the portal. Приведенный ниже фрагмент кода должен быть добавлен везде, где выполняется вызов зависимости.The code snippet below needs to be added wherever a dependency call is made.

Примечание

Для .NET и .NET Core можно также использовать TelemetryClient.StartOperation метод (расширение), который заполняет DependencyTelemetry свойства, необходимые для корреляции, и другие свойства, такие как время начала и длительность, поэтому вам не нужно создавать пользовательский таймер, как в приведенных ниже примерах.For .NET and .NET Core you can alternatively use the TelemetryClient.StartOperation (extension) method that fills the DependencyTelemetry properties that are needed for correlation and some other properties like the start time and duration so you don't need to create a custom timer as with the examples below. Дополнительные сведения см. в разделе об отслеживании исходящих зависимостей вэтой статье.For more information consult this article's section on outgoing dependency tracking.

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

Помните, что серверные пакеты SDK включают модуль зависимостей, который автоматически обнаруживает и отслеживает определенные вызовы зависимостей, например вызовы к базам данных и интерфейсам REST API.Remember that the server SDKs include a dependency module that discovers and tracks certain dependency calls automatically--for example, to databases and REST APIs. Для работы модуля необходимо установить агент на сервере.You have to install an agent on your server to make the module work.

В Java некоторые вызовы зависимостей могут автоматически отслеживаться с помощью агента Java.In Java, certain dependency calls can be automatically tracked using Java Agent.

Используйте этот вызов, если необходимо отследить вызовы, которые не отслеживаются автоматически, или если вы не хотите устанавливать агент.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.

Чтобы отключить стандартный модуль отслеживания зависимостей в C#, измените файл ApplicationInsights.config и удалите ссылку на DependencyCollector.DependencyTrackingTelemetryModule.To turn off the standard dependency-tracking module in C#, edit ApplicationInsights.config and delete the reference to DependencyCollector.DependencyTrackingTelemetryModule. В Java не следует устанавливать агент Java, если не требуется автоматически собирать данные стандартных зависимостей.In Java, please do not install java agent if you do not want to collect standard dependencies automatically.

Зависимости в службе аналитикиDependencies in Analytics

В службе аналитики Application Insights вызовы trackDependency приводятся в таблице dependencies.In Application Insights Analytics, trackDependency calls show up in the dependencies table.

Если действует выборка, свойство itemCount имеет значение больше 1.If sampling is in operation, the itemCount property shows a value greater than 1. Например, itemCount==10 означает, что из 10 вызовов trackDependency() процесс выборки передал только один.For example itemCount==10 means that of 10 calls to trackDependency(), the sampling process only transmitted one of them. Чтобы получить правильное число зависимостей, разбитое по конечным компонентам, используйте следующий код:To get a correct count of dependencies segmented by target component, use code such as:

dependencies
| summarize sum(itemCount) by target

Чтобы связать зависимости с соответствующими запросами, используйте соединение:To associate dependencies with their related requests, use a join:

dependencies
| join (requests) on operation_Id

Очистка данныхFlushing data

Как правило, пакет SDK отправляет данные через фиксированные интервалы (обычно 30 с) или каждый раз, когда буфер полон (обычно 500 элементов).Normally, the SDK sends data at fixed intervals (typically 30 secs) or whenever buffer is full (typically 500 items). Однако в некоторых случаях может потребоваться очистить буфер, например, при использовании пакета SDK в приложении, которое завершает работу.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();

Эта функция является асинхронной для канала телеметрии сервера.The function is asynchronous for the server telemetry channel.

Желательно использовать в действии завершения работы для приложения метод flush().Ideally, flush() method should be used in the shutdown activity of the Application.

Прошедшие проверку пользователиAuthenticated users

В веб-приложении пользователи (по умолчанию) определяются файлами cookie.In a web app, users are (by default) identified by cookies. Пользователь может быть учтен более одного раза при доступе к приложению с другого компьютера или браузера либо при удалении файлов cookie.A user might be counted more than once if they access your app from a different machine or browser, or if they delete cookies.

Если пользователи входят в ваше приложение, более точное их количество можно узнать, указав идентификатор пользователя, прошедшего аутентификацию, в коде браузера.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);
    ...
}

Например, в веб-приложении MVC ASP.NET.In an ASP.NET web MVC application, for example:

RazorRazor

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

Нет необходимости использовать фактическое учетное имя пользователя.It isn't necessary to use the user's actual sign-in name. Нужен только уникальный идентификатор этого пользователя.It only has to be an ID that is unique to that user. В нем не должно быть пробелов или символов ,;=|.It must not include spaces or any of the characters ,;=|.

Идентификатор пользователя также задается в файле cookie сеанса и отправляется на сервер.The user ID is also set in a session cookie and sent to the server. Если установлен серверный пакет SDK, идентификатор пользователя, прошедшего проверку подлинности, отправляется как часть свойств контекста телеметрии клиента и сервера.If the server SDK is installed, the authenticated user ID is sent as part of the context properties of both client and server telemetry. Затем можно выполнить фильтрацию и поиск.You can then filter and search on it.

Если приложение группирует пользователей по учетным записям, вы также можете передать идентификатор учетной записи (с аналогичными ограничениями знаков).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);

В обозревателе метрик можно создать диаграмму для отображения количества пользователей, прошедших проверку подлинности, а также учетных записей пользователей.In Metrics Explorer, you can create a chart that counts Users, Authenticated, and User accounts.

Кроме того, можно выполнять поиск точек данных клиента с помощью конкретных имен пользователей и учетных записей.You can also Search for client data points with specific user names and accounts.

Фильтрация, поиск и сегментация данных с помощью свойствFiltering, searching, and segmenting your data by using properties

Вы можете прикрепить свойства и результаты измерений к своим событиям, а также метрикам, просмотрам страниц, исключениям и другим данным телеметрии.You can attach properties and measurements to your events (and also to metrics, page views, exceptions, and other telemetry data).

Свойства — это строковые значения, которые можно использовать для фильтрации телеметрии в отчетах об использовании.Properties are string values that you can use to filter your telemetry in the usage reports. Например, если приложение содержит несколько игр, можно к каждому событию присоединять имя игры, чтобы видеть, какие игры наиболее популярны.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.

В каждой строке может отображаться до 8192 событий.There's a limit of 8192 on the string length. (Если вы хотите отправлять большие блоки данных, используйте параметр сообщения TrackTrace.)(If you want to send large chunks of data, use the message parameter of TrackTrace.)

Метрики являются числовыми значениями, которые могут быть представлены в графическом виде.Metrics are numeric values that can be presented graphically. Например, вам нужно будет посмотреть, постепенно ли увеличиваются зарабатываемые игроками очки.For example, you might want to see if there's a gradual increase in the scores that your gamers achieve. Графы можно сегментировать по свойствам, отправленным с событием, чтобы получать отдельные графы или набор граф для разных игр.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.

Чтобы значения метрик отображались правильно, они должны быть больше или равны 0.For metric values to be correctly displayed, they should be greater than or equal to 0.

Количество используемых свойств, значений свойств и метрик ограничено .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);

Примечание

Постарайтесь не указывать в свойствах личные сведения.Take care not to log personally identifiable information in properties.

Альтернативный способ настройки свойств и метрикAlternative way to set properties and metrics

Для удобства вы можете собирать параметры события в отдельный объект: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);

Предупреждение

Не используйте один и тот же экземпляр элемента телеметрии (в этом примере event) для многократного вызова Track*().Don't reuse the same telemetry item instance (event in this example) to call Track*() multiple times. Это может привести к отправке телеметрии с неверной конфигурацией.This may cause telemetry to be sent with incorrect configuration.

Пользовательские измерения и свойства в службе аналитикиCustom measurements and properties in Analytics

В службе аналитики пользовательские метрики и свойства приводятся в атрибутах customMeasurements и customDimensions каждой записи телеметрии.In Analytics, custom metrics and properties show in the customMeasurements and customDimensions attributes of each telemetry record.

Например, если вы добавили свойство game в телеметрию запросов, следующий запрос подсчитывает число различных значений свойства game и показывает среднее значение пользовательской метрики score: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)

Обратите внимание на указанные ниже моменты.Notice that:

  • При извлечении значения из JSON customDimensions или customMeasurements оно имеет динамический тип, поэтому его необходимо привести к tostring или 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.
  • С учетом возможности выборки следует использовать sum(itemCount), а не count().To take account of the possibility of sampling, you should use sum(itemCount), not count().

События времениTiming events

Иногда требуется отобразить на диаграмме продолжительность выполнения действия.Sometimes you want to chart how long it takes to perform an action. Например, может потребоваться определить, сколько времени нужно пользователям для выбора решений в игре.For example, you might want to know how long users take to consider choices in a game. Для этого можно использовать параметр измерения.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);

Свойства по умолчанию для настраиваемой телеметрииDefault properties for custom telemetry

Если для некоторых создаваемых пользовательских событий требуется задать значения свойств по умолчанию, можно сделать это в экземпляре 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. Они прикреплены к каждому элементу телеметрии, отправляемой из этого клиента.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"});

Вызовы отдельных данных телеметрии могут переопределить значения по умолчанию в словарях свойства.Individual telemetry calls can override the default values in their property dictionaries.

Для веб-клиентов JavaScript используйте инициализаторы телеметрии JavaScript.For JavaScript web clients, use JavaScript telemetry initializers.

Чтобы добавить свойства для всей телеметрии, включая данные из модулей стандартной коллекции, реализуйте ITelemetryInitializer.To add properties to all telemetry, including the data from standard collection modules, implement ITelemetryInitializer.

Выборка, фильтрация и обработка данных телеметрииSampling, filtering, and processing telemetry

Для обработки телеметрии перед отправкой из пакета SDK можно написать код.You can write code to process your telemetry before it's sent from the SDK. Будут обрабатываться данные, отправляемые из модулей стандартной телеметрии, таких как коллекция запросов HTTP и коллекция зависимостей.The processing includes data that's sent from the standard telemetry modules, such as HTTP request collection and dependency collection.

Добавьте свойства в телеметрию, реализовав ITelemetryInitializer.Add properties to telemetry by implementing ITelemetryInitializer. Например, можно добавить номера версий или значения, вычисленные на основе других свойств.For example, you can add version numbers or values that are calculated from other properties.

Используя фильтрацию, можно изменить или отменить телеметрию перед ее отправкой из пакета SDK. Для этого реализуйте ITelemetryProcessor.Filtering can modify or discard telemetry before it's sent from the SDK by implementing ITelemetryProcessor. Вы сможете управлять тем, какие данные отправляются, а какие отклоняются. Однако при этом необходимо учитывать влияние на метрики.You control what is sent or discarded, but you have to account for the effect on your metrics. В зависимости от способа отклонения элементов можно потерять возможность перехода между связанными элементами.Depending on how you discard items, you might lose the ability to navigate between related items.

Выборка представляет собой упакованное решение для сокращения объема данных, отправляемых из приложения на портал.Sampling is a packaged solution to reduce the volume of data that's sent from your app to the portal. На отображаемые метрики выборка не влияет.It does so without affecting the displayed metrics. Возможность диагностировать проблемы путем перехода между связанными элементами, такими как исключения, запросы и просмотры страниц, также не затрагивается.And it does so without affecting your ability to diagnose problems by navigating between related items such as exceptions, requests, and page views.

Подробнее.Learn more.

Отключение телеметрииDisabling telemetry

Чтобы динамически остановить и запустить сбор и передачу данных телеметрии: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);

Чтобы Отключить выбранные стандартные компоненты, например счетчики производительности, HTTP-запросы или зависимости, удалите или закомментируйте соответствующие строки в ApplicationInsights.config. Это можно сделать, например, если вы хотите отправить собственные данные 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;

Чтобы отключить выбранные стандартные сборщики, например счетчики производительности, HTTP-запросы или зависимости, свяжите методы конфигурации с кодом инициализации пакета 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();

Чтобы отключить эти сборщики после инициализации, используйте объект конфигурации applicationInsights.Configuration.setAutoCollectRequests(false).To disable these collectors after initialization, use the Configuration object: applicationInsights.Configuration.setAutoCollectRequests(false)

Режим разработчикаDeveloper mode

Во время отладки полезно передавать телеметрию через конвейер, чтобы результаты можно было увидеть немедленно.During debugging, it's useful to have your telemetry expedited through the pipeline so that you can see results immediately. Кроме того, вы можете получать дополнительные сообщения, которые помогают трассировать любые проблемы с телеметрией.You also get additional messages that help you trace any problems with the telemetry. Отключите этот режим в рабочей среде, так как он может замедлить работу приложения.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

Для Node.js можно включить режим разработчика, включив внутреннее ведение журнала с помощью setInternalLogging и установив значение maxBatchSize 0, что приводит к отправке данных телеметрии сразу после сбора.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;

Установка ключа инструментирования для выбранной пользовательской телеметрииSetting the instrumentation key for selected custom telemetry

C#C#

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

Динамический ключ инструментированияDynamic instrumentation key

Чтобы не смешивать данные телеметрии из сред разработки, тестирования и рабочей среды, можно создать отдельные ресурсы Application Insights и изменить их ключи в зависимости от среды.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.

Вместо получения ключа инструментирования из файла конфигурации можно задать его в коде.Instead of getting the instrumentation key from the configuration file, you can set it in your code. Задайте ключ в методе инициализации, таком как global.aspx.cs, в службе 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;

На веб-странице может потребоваться задать его, используя состояние веб-сервера, а не внедрить его в сценарий.In webpages, you might want to set it from the web server's state, rather than coding it literally into the script. Например, на веб-странице, созданной в приложении ASP.NET.For example, in a webpage generated in an ASP.NET app:

JavaScript в 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 включает свойство Context, содержащее несколько значений, которые отправляются вместе со всеми данными телеметрии.TelemetryClient has a Context property, which contains values that are sent along with all telemetry data. Как правило, их задают модули стандартной телеметрии, но их также можно задать самостоятельно.They are normally set by the standard telemetry modules, but you can also set them yourself. Например:For example:

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

Если задать эти значения самостоятельно, мы советуем удалить соответствующую строку из файла ApplicationInsights.config, чтобы не перепутать собственные значения и стандартные значения.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.

  • Component: приложение и его версия.Component: The app and its version.
  • Device: данные об устройстве, на котором выполняется приложение.Device: Data about the device where the app is running. (В веб-приложениях это сервер или клиентское устройство, с которых отправляется телеметрия.)(In web apps, this is the server or client device that the telemetry is sent from.)
  • InstrumentationKey: ресурс Application Insights в Azure, в котором отображается телеметрии.InstrumentationKey: The Application Insights resource in Azure where the telemetry appears. Обычно этот ресурс получают из файла ApplicationInsights.config.It's usually picked up from ApplicationInsights.config.
  • Location: географическое расположение устройства.Location: The geographic location of the device.
  • Operation: текущий HTTP-запрос в веб-приложениях.Operation: In web apps, the current HTTP request. В приложениях других типов для этого значения можно задать значение "Группировать события совместно".In other app types, you can set this to group events together.
    • ID: созданное значение, которое сопоставляет различные события, чтобы при проверке любого события в поиске по журналу диагностики можно было найти связанные элементы.ID: A generated value that correlates different events, so that when you inspect any event in Diagnostic Search, you can find related items.
    • Name: идентификатор, обычно URL-адрес HTTP-запроса.Name: An identifier, usually the URL of the HTTP request.
    • SyntheticSource: если эта строка не пустая и не имеет значение null, она означает, что источник запроса был определен как программа-робот или веб-тест.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. По умолчанию он исключается из вычислений в обозревателе метрик.By default, it is excluded from calculations in Metrics Explorer.
  • Свойства: свойства, которые отправляются со всеми данными телеметрии.Properties: Properties that are sent with all telemetry data. Это значение можно переопределить в отдельных вызовах Track*.It can be overridden in individual Track* calls.
  • Session: сеанс пользователя.Session: The user's session. Для Id задается созданное значение, которое изменяется, если пользователь был неактивным в течение некоторого времени.The ID is set to a generated value, which is changed when the user has not been active for a while.
  • Пользователь: сведения о пользователе.User: User information.

ОграниченияLimits

Число метрик и событий, используемых в приложении (то есть на ключ инструментирования), ограничено.There are some limits on the number of metrics and events per application, that is, per instrumentation key. Ограничения зависят от выбранного ценового плана.Limits depend on the pricing plan that you choose.

РесурсResource Ограничение по умолчаниюDefault limit ПримечаниеNote
Общий объем данных в деньTotal data per day 100 ГБ100 GB Объем данных можно сократить, задав ограничение.You can reduce data by setting a cap. Если требуется больше данных, на портале можно увеличить граничное значение до 1000 ГБ.If you need more data, you can increase the limit in the portal, up to 1,000 GB. Если требуется объем более 1000 ГБ, отправьте сообщение электронной почты на адрес AIDataCap@microsoft.com.For capacities greater than 1,000 GB, send email to AIDataCap@microsoft.com.
РегулированиеThrottling 32 000 событий в секунду32,000 events/second Ограничение измеряется каждую минуту.The limit is measured over a minute.
Хранение данныхData retention 30–730 дней30 - 730 days Этот ресурс используется для поиска, аналитики и обозревателя метрик.This resource is for Search, Analytics, and Metrics Explorer.
Хранение подробных результатов многошагового теста доступностиAvailability multi-step test detailed results retention 90 дней90 days Этот ресурс предоставляет подробные результаты каждого шага.This resource provides detailed results of each step.
Максимальный размер элемента телеметрииMaximum telemetry item size 64 КБ64 kB
Максимальное количество элементов телеметрии на пакетMaximum telemetry items per batch 64 00064 K
Длина имен свойств и метрикProperty and metric name length 150150 См. схемы типов.See type schemas.
Длина строки значения свойстваProperty value string length 81928,192 См. схемы типов.See type schemas.
Длина сообщения трассировки и исключенияTrace and exception message length 32,76832,768 См. схемы типов.See type schemas.
Количество тестов доступности для одного приложенияAvailability tests count per app 100100
Хранение данных профилировщикаProfiler data retention 5 дней5 days
Отправляемые данные профилировщика в деньProfiler data sent per day 10 ГБ10 GB

Дополнительные сведения см. в статье Управление ценами и квотами для Application Insights.For more information, see About pricing and quotas in Application Insights.

Чтобы избежать превышения ограничения на скорость передачи данных, используйте выборку.To avoid hitting the data rate limit, use sampling.

Сведения о том, как определить, как долго хранятся данные, см. в статье Сбор и хранение данных в Application Insights.To determine how long data is kept, see Data retention and privacy.

Справочная документацияReference docs

Код пакета SDKSDK code

ВопросыQuestions

  • Какие исключения могут создаваться при вызовах Track_()?What exceptions might Track_() calls throw?

    Отсутствует.None. Вам не нужно помещать их в предложения try-catch.You don't need to wrap them in try-catch clauses. Если пакет SDK сталкивается с проблемами, он добавляет в журнал сообщения, которые отображаются в консоли отладки и, если сообщения проходят, — в поиске по журналу диагностики.If the SDK encounters problems, it will log messages in the debug console output and--if the messages get through--in Diagnostic Search.

  • Существует ли REST API для получения данных из портала?Is there a REST API to get data from the portal?

    Да, API доступа к данным.Yes, the data access API. К другим способам извлечения данных относятся экспорт из Analytics в Power BI и непрерывный экспорт.Other ways to extract data include export from Analytics to Power BI and continuous export.

Следующие шагиNext steps