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

Вставьте несколько строк кода в свое приложение, чтобы узнать, как пользователи его используют, или чтобы диагностировать неполадки. Вы можете отправлять телеметрию из устройств и классических приложений, веб-клиентов и веб-серверов. Используйте основной API телеметрии Application Insights, чтобы отправлять пользовательские события и метрики, а также собственные версии стандартной телеметрии. Этот же API используется стандартными сборщиками данных Application Insights.

Примечание.

Поддержка приема ключей инструментирования будет завершена 31 марта 31, 2025 г. Прием ключей инструментирования будет и дальше осуществляться, но мы больше не будем предоставлять обновления или поддержку для этой функции. Перейдите на строки подключения, чтобы использовать новые возможности.

Сводные данные API

Этот основной API используется на всех платформах, за некоторыми исключениями, например GetMetric (только в .NET).

Способ	Используется для
TrackPageView	Страницы, экраны, панели или формы.
TrackEvent	Действия пользователя и другие события. Используется для отслеживания поведения пользователя или мониторинга производительности.
GetMetric	Нулевые и многомерные метрики, централизованное агрегирование, только в C#.
TrackMetric	Измерения производительности, не связанные с конкретными событиями, например, измерение длины очереди.
TrackException	Регистрация исключений для диагностики. Отслеживайте исключения, связанные с другими событиями, и изучайте трассировку стека.
TrackRequest	Регистрация частоты и длительности запросов к серверу для анализа производительности.
TrackTrace	Журнал сообщения диагностики ресурсов. Можно также использовать журналы сторонних приложений.
TrackDependency	Регистрация длительности и частоты вызовов внешних компонентов, от которых зависит приложение.

Вы можете прикрепить свойства и метрики к большинству этих вызовов телеметрии.

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

Если у вас еще нет ссылки на пакет SDK Application Insights, выполните указанные ниже действия.

• Добавьте пакет SDK Application Insights в свой проект:

  • проект ASP.NET;
  • проект ASP.NET Core
  • проект Java;
  • проект Node.js;
  • JavaScript на каждой веб-странице.

• В программный код устройства или веб-сервера необходимо добавить:

  C#.using Microsoft.ApplicationInsights;

  Visual Basic:Imports Microsoft.ApplicationInsights

  Java:import com.microsoft.applicationinsights.TelemetryClient;

  Node.js.var applicationInsights = require("applicationinsights");

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

Получите экземпляр TelemetryClient (без использования JavaScript на веб-страницах).

Для приложений ASP.NET Core и приложений не на основе HTTP/Worker для .NET/.NET Core получите экземпляр TelemetryClient из контейнера внедрения зависимостей, в соответствии с инструкциями, изложенными в их документации.

Если вы используете Функции Azure версии 2 или веб-задания Azure версии 3+, см. статью Мониторинг Функций Azure.

C#

private TelemetryClient telemetry = new TelemetryClient();

Если отображается сообщение о том, что этот метод устарел, дополнительные сведения см. на странице microsoft/ApplicationInsights-dotnet#1152.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

Метод TelemetryClient является потокобезопасным.

Для проектов ASP.NET и Java автоматически фиксируются входящие HTTP-запросы. Возможно, вам потребуется создать дополнительные экземпляры TelemetryClient для других модулей приложения. Например, у вас может быть один экземпляр TelemetryClient в классе промежуточного ПО для отчетов о событиях бизнес-логики. Вы можете задать свойства, такие как UserId и DeviceId, для идентификации компьютера. Эти данные прикрепляются ко всем событиям, отправляемым экземпляром.

C#

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

Java

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

В проектах Node.js вы можете использовать new applicationInsights.TelemetryClient(instrumentationKey?) для создания нового экземпляра. Этот подход рекомендуется использовать только для сценариев, требующих изолированной конфигурации из отдельного экземпляра defaultClient.

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

В Application Insights пользовательское событие — это точка данных, которую можно отобразить как агрегированное значение в обозревателе метрик, а также как отдельные значения на вкладке поиска по журналу диагностики. (Оно не связано с MVC и другими "событиями" платформы.)

Вставьте вызовы TrackEvent в код для подсчета различных событий: Например, вам может потребоваться отслеживать, как часто пользователи выбирают определенную функцию. Или, возможно, вам потребуется узнать, как часто они достигают определенных целей или делают определенные типы ошибок.

Например, отправляйте событие в игровом приложении при каждом выигрыше пользователя:

JavaScript

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

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

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

Пользовательские события в Log Analytics

Телеметрические данные представлены в таблице customEvents на вкладке Журналы Application Insights или в сведениях об использовании. События могут поступать из trackEvent(..) или подключаемого модуля вызова автоматического сбора аналитики.

Если действует выборка, свойство itemCount имеет значение больше 1. Например, itemCount==10 означает, что из 10 вызовов к trackEvent() процесс выборки передал только один. Для правильного подсчета пользовательских событий используйте код customEvents | summarize sum(itemCount).

Примечание.

itemCount имеет минимальное значение, равное 1; сама запись представляет собой вводные данные.

GetMetric

Дополнительные сведения об эффективном использовании вызова GetMetric() для записи предварительно агрегированных локально показателей и метрик для приложений .NET и .NET Core см. в статье Сбор пользовательских метрик в .NET и .NET Core.

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

Примечание.

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric не является предпочтительным способом для отправки метрик. Метрики всегда нужно предварительно агрегировать в течение определенного периода перед отправкой. Используйте одну из перегрузок GetMetric(..), чтобы получить объект метрики для доступа к возможностям предварительного агрегирования пакета SDK.

При применении вами собственной логики предварительного агрегирования вы можете использовать метод TrackMetric() для отправки сводных показателей. Если приложению требуется каждый раз отправлять отдельный элемент телеметрии без агрегирования в течение определенного периода, скорее всего, у вас уже есть вариант использования телеметрии события. См. раздел TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Application Insights может создать диаграмму метрик, не привязанных к определенным событиям. Например, можно отслеживать длину очереди через регулярные промежутки времени. Благодаря метрикам отдельные измерения менее интересны, чем вариации и тенденции, и поэтому статистические диаграммы полезны.

Для отправки метрик в Application Insights можно использовать API TrackMetric(..). Отправить метрику можно двумя способами.

• Отдельное значение. Каждый раз при выполнении измерения в приложении вы отправляете соответствующее значение в Application Insights.

  Например, предположим, что имеется метрика, описывающая число элементов в контейнере. В течение некоторого периода времени вы сначала помещаете три элемента в контейнер, а затем удаляете два элемента. Соответственно, вам нужно вызвать TrackMetric дважды. Сначала необходимо передать значение 3, а затем — значение -2. Application Insights сохраняет для вас оба значения.

• Агрегирование. При работе с метриками отдельные измерения редко представляют интерес. Вместо этого обычно важна сводка того, что произошло за определенный период времени. Такая сводка называется агрегированием.

  В приведенном выше примере сумма агрегированной метрики за период времени равна 1, а число значений метрики — 2. При использовании агрегирования TrackMetric вызывается только один раз для каждого периода времени с отправкой агрегированных значений. Это рекомендуемый подход, так как он может значительно снизить затраты и улучшить производительность благодаря отправке меньшего числа точек данных в Application Insights. При этом собирается вся важная информация.

Примеры отдельных значений

Отправка значения одной метрики

JavaScript

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

C#

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

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

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

Пользовательские метрики в Log Analytics

Данные телеметрии доступны в таблице customMetrics в службе аналитики Application Insights. Каждая строка представляет собой вызов trackMetric(..) в приложении.

• valueSum — это сумма измерений. Чтобы получить среднее значение, разделите текущее значение на значение valueCount.
• valueCount — число измерений, агрегированных в этот вызов trackMetric(..).

Примечание.

valueCount имеет минимальное значение, равное 1; сама запись представляет собой вводные данные.

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

В устройстве или приложении веб-страницы телеметрия просмотров страницы отображается по умолчанию при загрузке каждого экрана или страницы. Но это можно изменить, чтобы отслеживать количество просмотров страницы в дополнительное или другое время. Например, в приложении, на котором отображаются вкладки или панели, может потребоваться отслеживать страницу всякий раз, когда пользователь открывает новую панель.

Данные о пользователе и сеансе отправляются в качестве свойств вместе с количеством просмотров страниц, поэтому диаграммы для пользователей и сеансов активируются при наличии телеметрии по количеству просмотров страницы.

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

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Если у вас есть несколько вкладок на различных HTML-страницах, можно также указать URL-адрес:

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

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

По умолчанию время, отображаемое как Время загрузки страницы, отсчитывается от момента отправки запроса браузером до вызова события загрузки страницы в браузере.

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

• Задайте явную длительность вызова trackPageView: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
• Используйте вызовы времени просмотра страницы startTrackPage и stopTrackPage.

JavaScript

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

...

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

Имя, используемое в качестве первого параметра, связывает вызовы start и stop. По умолчанию используется имя текущей страницы.

Полученные длительности загрузки страниц, отображаемые в обозревателе метрик, являются производными интервала между вызовами start и stop. Выбор рассматриваемого интервала за вами.

Телеметрия страниц в Log Analytics

В Log Analytics две таблицы содержат данные по операциям в браузере:

• pageViews — содержит данные об URL-адресе и заголовке страницы.
• browserTimings — содержит данные по производительности клиента, например время, затраченное на обработку входящих данных.

Чтобы узнать, сколько времени требуется браузеру на обработку различных страниц, используйте следующий код:

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

Чтобы определить популярность различных браузеров, используйте следующий код:

pageViews
| summarize count() by client_Browser

Чтобы связать просмотры страниц с вызовами AJAX, выполните объединение с зависимостями:

pageViews
| join (dependencies) on operation_Id

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

TrackRequest используется пакетом SDK для ведения журнала HTTP-запросов.

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

Мы рекомендуем отправлять телеметрию запросов так, чтобы запрос выступал в качестве контекста операции.

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

Вы можете коррелировать элементы телеметрии между собой. Для этого свяжите их с контекстом операции. Стандартный модуль отслеживания запросов делает это для исключений и других событий, отправляемых во время обработки HTTP-запроса. В службе поиска и службе аналитики можно легко найти все события, связанные с запросом при помощи его идентификатора операции.

Дополнительные сведения о корреляции см. в статье Корреляция данных телеметрии в Application Insights.

Если вы отслеживаете телеметрию вручную, проще всего выполнить ее корреляцию с помощью этого шаблона:

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

Элементы телеметрии, о которых поступают сведения в пределах операции, становятся дочерними элементами такой операции. Контексты операции могут быть вложенными.

В колонке поиска контекст операции используется для создания списка Связанные элементы.

Дополнительные сведения об отслеживании пользовательских операций см. в статье Отслеживание пользовательских операций с помощью пакета SDK Application Insights для .NET.

Запросы в Log Analytics

В службе аналитики Application Insights запросы приводятся в таблице requests.

Если действует выборка, свойство itemCount имеет значение больше 1. Например, itemCount==10 означает, что из 10 вызовов к trackRequest() процесс выборки передал только один. Чтобы получить правильное число запросов и среднюю длительность, разбитую по именам запросов, используйте следующий код:

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

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

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

• определить их количество (для указания на частоту возникновения проблемы);
• проверить отдельные значения.

Отчеты содержат данные по трассировкам стеков.

C#

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

Java

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

JavaScript

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

Node.js

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

Пакеты SDK регистрируют многие исключения автоматически, поэтому не всегда нужно явно вызвать метод TrackException:

• ASP.NET: написание кода для регистрации исключений.
• Java EE: исключения регистрируются автоматически.
• JavaScript: исключения регистрируются автоматически. Если вы хотите отключить автоматическую коллекцию, добавьте строку в скрипт загрузчика пакета SDK JavaScript (Web), который вы вставляете на веб-страницы:

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

Исключения в Log Analytics

В службе аналитики Application Insights исключения приводятся в таблице exceptions.

Если действует выборка, свойство itemCount имеет значение больше 1. Например, itemCount==10 означает, что из 10 вызовов к trackException() процесс выборки передал только один. Чтобы получить правильное число исключений, разбитое по типам исключений, используйте следующий код:

exceptions
| summarize sum(itemCount) by type

Большая часть важных сведений о стеке уже извлечена в отдельные переменные, однако вы можете разобрать структуру details, чтобы получить дополнительные сведения. Так как это динамическая структура, результат следует привести к требуемому типу. Например:

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

Чтобы связать исключения с соответствующими запросами, используйте соединение:

exceptions
| join (requests) on operation_Id

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

Используйте TrackTrace для диагностики неполадок, отправляя цепочку отслеживания в Application Insights. Вы можете отправлять блоки диагностических данных и проверять их с помощью поиска по журналу диагностики.

В .NET адаптеры журнала используют этот API для отправки журналов сторонних поставщиков на портал.

В Java агент Application Insights для Java выполняет автоматический сбор и отправку журналов на портал.

C#

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

Java

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

Node.js

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

JavaScript на стороне клиента или браузера

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

Зарегистрируйте событие диагностики, например вход в метод или выход из него.

Параметр	Описание
message	Диагностические данные. Могут содержать не только имя.
properties	Сопоставление строки со строкой. Дополнительные данные, используемые для фильтрации исключений на портале. Значение по умолчанию: empty.
severityLevel	Поддерживаемые значения: SeverityLevel.ts.

Вы можете выполнять поиск содержимого сообщения, но (в отличие от значений свойств) не можете фильтровать его.

Ограничения по размеру message гораздо выше, чем ограничение для свойств. Преимуществом TrackTrace является возможность добавления в сообщения относительно длинных данных, например данных POST.

Вы также можете настроить для сообщения уровень серьезности. Как и для других данных телеметрии, вы можете добавлять значения свойства, используемые для фильтрации или поиска различных наборов трассировки. Например:

C#

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

Java

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

В колонке Поиск вы сможете легко отфильтровать все сообщения с определенной степенью серьезности, относящиеся к определенной базе данных.

Трассировки в Log Analytics

В службе аналитики Application Insights вызовы к TrackTrace приводятся в таблице traces.

Если действует выборка, свойство itemCount имеет значение больше 1. Например, itemCount==10 означает, что из 10 вызовов к trackTrace() процесс выборки передал только один. Для правильного подсчета вызовов трассировки используйте код traces | summarize sum(itemCount).

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

Используйте вызов TrackDependency для отслеживания времени отклика и процента успешных попыток вызовов во внешнюю часть кода. Результаты отображаются в диаграммах зависимостей на портале. Указанный ниже фрагмент кода необходимо добавить в позицию, откуда выполняется вызов зависимости.

Примечание.

Для .NET и .NET Core в качестве альтернативного варианта вы можете использовать метод (расширение) TelemetryClient.StartOperation, который заполняет свойства DependencyTelemetry, необходимые для корреляции, а также другие свойства, такие как время начала и продолжительность, чтобы вам не пришлось создавать пользовательский таймер, как в примерах ниже. Дополнительные сведения см. в разделе об отслеживании исходящих зависимостей в статье Отслеживание пользовательских операций с помощью пакета SDK Application Insights для .NET.

C#

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

Java

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

Node.js

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

Помните, что серверные пакеты SDK включают модуль зависимостей, который автоматически обнаруживает и отслеживает определенные вызовы зависимостей, например вызовы к базам данных и интерфейсам REST API. Для работы модуля необходимо установить агент на сервере.

В Java многие вызовы зависимостей могут отслеживаться автоматически с помощью агента Java для Application Insights.

Используйте этот вызов, если необходимо отследить вызовы, которые не отслеживаются автоматически.

Чтобы отключить стандартный модуль отслеживания зависимостей в C#, измените файл ApplicationInsights.config и удалите ссылку на DependencyCollector.DependencyTrackingTelemetryModule. Для Java см. раздел Подавление определенных данных телеметрии, собираемых автоматически.

Зависимости в Log Analytics

В службе аналитики Application Insights вызовы к trackDependency приводятся в таблице dependencies.

Если действует выборка, свойство itemCount имеет значение больше 1. Например, itemCount==10 означает, что из 10 вызовов к trackDependency() процесс выборки передал только один. Чтобы получить правильное число зависимостей, разбитое по конечным компонентам, используйте следующий код:

dependencies
| summarize sum(itemCount) by target

Чтобы связать зависимости с соответствующими запросами, используйте соединение:

dependencies
| join (requests) on operation_Id

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

Обычно SDK отправляет данные через фиксированные интервалы (как правило, 30 сек) или если буфер заполнен (как правило, максимальный объем буфера составляет 500 элементов). В некоторых случаях может потребоваться очистить буфер, например если вы используете пакет SDK в приложении, которое завершает работу.

.NET

При использовании Flush() рекомендуется следующий шаблон:

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

При использовании FlushAsync() рекомендуется следующий шаблон:

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

В процессе завершения работы приложения рекомендуется всегда проводить очистку, чтобы гарантировать, что данные телеметрии не будут потеряны.

Java

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

Node.js

telemetry.flush();

Эта функция является асинхронной для канала телеметрии сервера.

Примечание.

Пакеты SDK для Java и JavaScript автоматически сбрасываются при завершении работы приложения.

Пользователи, прошедшие проверку подлинности

В веб-приложении пользователи по умолчанию идентифицируются по файлам cookie. Пользователь может быть учтен более одного раза при доступе к приложению с другого компьютера или браузера либо при удалении файлов cookie.

Если пользователи входят в ваше приложение, более точное их количество можно узнать, указав идентификатор пользователя, прошедшего аутентификацию, в коде браузера.

JavaScript

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

Например, в веб-приложении MVC ASP.NET.

Razor

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

Нет необходимости использовать фактическое учетное имя пользователя. Нужен только уникальный идентификатор этого пользователя. В нем не должно быть пробелов или символов ,;=|.

Идентификатор пользователя также задается в файле cookie сеанса и отправляется на сервер. Если установлен серверный пакет SDK, идентификатор пользователя, прошедшего проверку подлинности, отправляется как часть свойств контекста телеметрии клиента и сервера. Затем можно выполнить фильтрацию и поиск.

Если приложение группирует пользователей по учетным записям, вы также можете передать идентификатор учетной записи. Применяются те же ограничения по символам.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

В обозревателе метрик можно создать диаграмму для отображения количества пользователей, прошедших проверку подлинности, а также учетных записей пользователей.

Кроме того, можно выполнить поиск точек данных клиентов с определенными именами пользователей и учетными записями.

Примечание.

Класс EnableAuthenticationTrackingJavaScript в ApplicationInsightsServiceOptions в пакете SDK для .NET Core упрощает настройку параметров JavaScript, необходимых для введения имени пользователя в качестве идентификатора проверки подлинности для каждой трассировки, отправляемой пакетом SDK для JavaScript в Application Insights.

Если для этого свойства задано значение true, имя пользователя ASP.NET Core выводится вместе с телеметрией на стороне клиента. По этой причине добавление appInsights.setAuthenticatedUserContext вручную больше не потребуется, так как он уже внедрен пакетом SDK для ASP.NET Core. Идентификатор проверки подлинности также отправляется на сервер, где пакет SDK в .NET Core идентифицирует его и будет использовать для любой телеметрии на стороне сервера, как описано в справочнике по API JavaScript.

В приложения JavaScript, которые работают иначе, чем ASP.NET Core MVC (например, веб-приложения SPA), вам придется добавить appInsights.setAuthenticatedUserContext вручную.

Фильтрация, поиск и сегментация данных с помощью свойств

Вы можете прикрепить свойства и результаты измерений к своим событиям, а также метрикам, просмотрам страниц, исключениям и другим данным телеметрии.

Свойства — это строковые значения, которые можно использовать для фильтрации телеметрии в отчетах об использовании. Например, если приложение содержит несколько игр, можно к каждому событию присоединять имя игры, чтобы видеть, какие игры наиболее популярны.

Максимальная длина строки составляет 8192 символов. Если вы хотите отправлять крупные блоки данных, используйте параметр сообщения TrackTrace.

Метрики являются числовыми значениями, которые могут быть представлены в графическом виде. Например, вам нужно будет посмотреть, постепенно ли увеличиваются зарабатываемые игроками очки. Графы можно сегментировать по свойствам, отправленным с событием, чтобы получать отдельные графы или набор графов для разных игр.

Для правильного отображения значения метрик должны быть больше или равны 0.

Количество используемых свойств, значений свойств и метрик ограничено .

JavaScript

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

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

C#

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

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

Node.js

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Visual Basic

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

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

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

Java

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

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

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

Примечание.

Убедитесь, что вы не указываете в свойствах личные сведения.

Альтернативный способ настройки свойств и метрик

Для удобства вы можете собирать параметры события в отдельный объект:

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*(). Это может приводить к отправке телеметрии с неверной конфигурацией.

Пользовательские измерения и свойства в Log Analytics

В Log Analytics пользовательские метрики и свойства приводятся в атрибутах customMeasurements и customDimensions каждой записи телеметрии.

Например, если вы добавили свойство game в телеметрию запросов, следующий запрос подсчитывает число различных значений свойства game и показывает среднее значение пользовательской метрики score:

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

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

• При извлечении значения из JSON customDimensions или customMeasurements, тип будет динамическим, поэтому вам нужно привести его к tostring или todouble.
• С учетом возможности выборки следует использовать sum(itemCount), а не count().

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

Иногда требуется отобразить на диаграмме продолжительность выполнения действия. Например, может потребоваться определить, сколько времени нужно пользователям для выбора решений в игре. Чтобы получить эти сведения, используйте параметр измерения.

C#

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

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

Java

long startTime = System.currentTimeMillis();

// Perform timed action

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

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

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

Свойства по умолчанию для настраиваемой телеметрии

Если требуется задать значения свойств по умолчанию для некоторых записываемых пользовательских событий, это можно сделать в экземпляре TelemetryClient. Они прикреплены к каждому элементу телеметрии, отправляемому из этого клиента.

C#

using Microsoft.ApplicationInsights.DataContracts;

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

Visual Basic

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

Java

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

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

gameTelemetry.TrackEvent("WinGame");

Node.js

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

Вызовы отдельных данных телеметрии могут переопределить значения по умолчанию в словарях свойства.

Для веб-клиентов JavaScript используйте инициализаторы телеметрии JavaScript.

Чтобы добавить свойства для всей телеметрии, включая данные из модулей стандартной коллекции, реализуйте ITelemetryInitializer.

Выборка, фильтрация и обработка телеметрии

См. статью "Фильтрация и предварительная обработка данных телеметрии" в пакете SDK для приложений Аналитика.

Отключение данных телеметрии

Чтобы динамически остановить и запустить сбор и передачу данных телеметрии:

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Для отключения выбранных стандартных сборщиков данные, например счетчиков производительности, HTTP-запросов или зависимостей, удалите или закомментируйте соответствующие строки в файле ApplicationInsights.config. Вы можете сделать это, если хотите отправить данные собственного запроса TrackRequest.

Node.js

telemetry.config.disableAppInsights = true;

Чтобы отключить выбранные стандартные сборщики, например счетчики производительности, HTTP-запросы или зависимости, свяжите методы конфигурации с кодом инициализации пакета SDK во время инициализации.

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

Чтобы отключить эти сборщики после инициализации, используйте объект конфигурации applicationInsights.Configuration.setAutoCollectRequests(false).

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

Во время отладки полезно передавать телеметрию через конвейер, чтобы результаты можно было увидеть немедленно. Кроме того, вы можете получать другие сообщения, которые помогают отслеживать любые проблемы с телеметрией. Отключите этот режим в рабочей среде, так как он может замедлить работу приложения.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Для Node.js вы можете включить режим разработчика, включив ведение внутреннего журнала через setInternalLogging и установив для maxBatchSize значение 0 (это означает, что ваши данные телеметрии должны отправляться по мере сбора).

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

Настройка ключа инструментирования для выбранной пользовательской телеметрии

C#

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

Ключ динамического инструментирования

Во избежание смешивания телеметрии из среды разработки, тестовой и рабочей среды вы можете создавать отдельные ресурсы Application Insights и менять их ключи в зависимости от среды.

Вместо получения ключа инструментирования из файла конфигурации можно задать его в коде. Задайте ключ в методе инициализации, таком как global.aspx.cs, в службе ASP.NET:

C#

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

JavaScript

appInsights.config.instrumentationKey = myKey;

На веб-странице может потребоваться задать его, используя состояние веб-сервера, а не внедрить его в сценарий. Например, на веб-странице, созданной в приложении ASP.NET.

JavaScript в Razor

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

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

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

Класс TelemetryContext

TelemetryClient включает свойство Context, содержащее несколько значений, которые отправляются вместе со всеми данными телеметрии. Как правило, их задают модули стандартной телеметрии, но их также можно задать самостоятельно. Например:

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

Если задать эти значения самостоятельно, мы советуем удалить соответствующую строку из файла ApplicationInsights.config, чтобы не перепутать собственные значения и стандартные значения.

• Component: приложение и его версия.
• Device: данные об устройстве, на котором выполняется приложение. (В веб-приложениях это сервер или клиентское устройство, с которых отправляется телеметрия.)
• InstrumentationKey: ресурс Application Insights в Azure, на котором отображаются данные телеметрии. Оно обычно принимается из ApplicationInsights.config.
• Location: географическое расположение устройства.
• Operation: текущий HTTP-запрос в веб-приложениях. В приложениях других типов для этого значения можно задать значение "Группировать события".
  • Идентификатор — это сгенерированное значение, которое устанавливает зависимость между различными событиями, чтобы при проверке любого события в поиске по журналу диагностики вы могли найти связанные элементы.
  • Name: идентификатор, обычно URL-адрес HTTP-запроса.
  • SyntheticSource: если эта строка не пустая и не имеет значение null, она означает, что источник запроса был определен как программа-робот или веб-тест. По умолчанию он исключается из вычислений в обозревателе метрик.
• Session: сеанс пользователя. Для идентификатора задается созданное значение, которое изменяется, если пользователь был неактивным в течение некоторого времени.
• User: информация о пользователе.

Ограничения

Число метрик и событий, используемых в приложении (то есть на ключ инструментирования), ограничено. Ограничения зависят от выбранного ценового плана.

Ресурс	Ограничение по умолчанию	Максимальный лимит	Примечания.
Общий объем данных в день	100 ГБ	Обратитесь в службу поддержки.	Можно задать ограничение для уменьшения данных. Если требуется больше данных, на портале можно увеличить граничное значение до 1000 ГБ. Если требуется объем более 1000 ГБ, отправьте сообщение электронной почты на адрес AIDataCap@microsoft.com.
Регулирование	32 000 событий в секунду	Обратитесь в службу поддержки.	Ограничение измеряется каждую минуту.
Журналы хранения данных	От 30 до 730 дней	730 дней	Этот ресурс предназначен для журналов.
Метрики хранения данных	90 дней	90 дней	Этот ресурс предназначен для обозревателя метрик.
Хранение подробных результатов многошагового теста доступности	90 дней	90 дней	Этот ресурс предоставляет подробные результаты каждого шага.
Максимальный размер элемента телеметрии	64 КБ	64 КБ
Максимальное количество элементов телеметрии на пакет	64 000	64 000
Длина имен свойств и метрик	150	150	См. схемы типов.
Длина строки значения свойства	8,192	8,192	См. схемы типов.
Длина сообщения трассировки и исключения	32,768	32,768	См. схемы типов.
Количество тестов доступности на ресурс приложения Аналитика	100	100
Хранение данных профилировщика и моментальных снимков	Две недели	Обратитесь в службу поддержки. Максимальный срок хранения данных — шесть месяцев.
Отправляемые данные профилировщика в день	Без ограничений	Без ограничений.
Объем отправляемых в сутки данных моментальных снимков	30 моментальных снимков в день на отслеживаемое приложение	Без ограничений.	Количество моментальных снимков, собираемых для каждого приложения, можно изменить в конфигурации.

Дополнительные сведения см. в разделе Выставление счетов для Application Insights.

Чтобы избежать превышения ограничения на скорость передачи данных, используйте выборку.

Сведения о том, как определить, как долго хранятся данные, см. в статье Сбор и хранение данных в Application Insights.

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

• Справочник по .NET
• Справочник по Java
• Справочник по JavaScript

Код пакета SDK

• .NET
• Пакеты Windows Server
• пакет SDK для Java
• Пакет SDK для Node.js
• Пакет SDK для JavaScript

Часто задаваемые вопросы

В этом разделы приводятся ответы на часто задаваемые вопросы.

Почему отсутствуют данные телеметрии?

Обе telemetryChannels потеряют буферизованную телеметрию, если она не очищается до завершения работы приложения.

Чтобы избежать потери данных, смыть telemetryClient при завершении работы приложения.

Дополнительные сведения см. в разделе "Очистка данных".

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

Нет. Вам не нужно помещать их в предложения try-catch. Если пакет SDK сталкивается с проблемами, он добавляет в журнал сообщения, которые отображаются в консоли отладки и, если сообщения проходят, — в поиске по журналу диагностики.

Существует ли REST API для получения данных из портала?

Да, API доступа к данным. Другие способы извлечения данных включают Power BI , если вы перешли на ресурс на основе рабочей области или непрерывный экспорт , если вы все еще находитесь на классическом ресурсе.

Почему мои вызовы к пользовательским событиям и API метрик игнорируются?

Пакет SDK Аналитика приложения несовместим с автоинструментацией. Если включена автоинструментация, вызовы Track() и другие пользовательские события и API метрик будут игнорироваться.

Отключите автоинструментацию в портал Azure на вкладке "Приложение Аналитика" страницы Служба приложений или задайте значение ApplicationInsightsAgent_EXTENSION_VERSIONdisabled.

Почему счетчики в результатах поиска и на диаграммах метрик не совпадают?

Выборка уменьшает количество элементов телеметрии (например, запросов и пользовательских событий), отправляемых из приложения на портал. В поиске отображается количество полученных элементов. На диаграммах метрик, на которых приводится число событий, вы видите количество исходных событий, которые произошли.

Каждый переданный itemCount элемент содержит свойство, показывющее количество исходных событий, которые представляет элемент. Чтобы наблюдать за выборкой в операции, этот запрос можно выполнить в Log Analytics:

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

Как можно настроить оповещение о событии?

Оповещения Azure настраиваются только для метрик. Создайте пользовательскую метрику, пороговое значение которой будет нарушаться при наступлении события. Затем настройте оповещение для метрики. Вы получаете уведомление всякий раз, когда метрика пересекает пороговое значение в любом направлении. Вы не получите уведомление до первого пересечения, независимо от того, является ли начальное значение высоким или низким. Задержка в течение нескольких минут всегда возникает.

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

• Поиск событий и журналов