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

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

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

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

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

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

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

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

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

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

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

При использовании AzureFunctions версии 2 и более поздней или веб-заданий Azure версии 3 и более поздней — выполняйте инструкции, изложенные в этом документе.

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"});

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

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

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

GetMetric

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

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.Value = 42.3;
telemetryClient.TrackMetric(sample);

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

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

Настраиваемые метрики в аналитике

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

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

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

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

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

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

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. Выбор рассматриваемого интервала за вами.

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

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

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

Дополнительные сведения о корреляции см. в статье Корреляция данных телеметрии в 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.

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

В службе аналитики 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.

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

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

В службе аналитики 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 агент Java Application Insights выполняет автоматический сбор и отправку журналов на портал.

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

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

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

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

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

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

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

Примечание

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

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 см. раздел Подавление определенных данных телеметрии, собираемых автоматически.

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

В службе аналитики 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 в приложении, которое завершает работу.

C#

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

Java

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

Node.js

telemetry.flush();

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

Желательно использовать в действии завершения работы для приложения метод flush().

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

В веб-приложении пользователи (по умолчанию) идентифицируются по файлам 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 класс в .NET Core SDK упрощает настройку параметров JavaScript, необходимого для введения имени пользователя в качестве идентификатора проверки подлинности для каждой трассировки, отправляемой Application Insights JavaScript SDK. Если это свойство установлено как истина, имя пользователя из поля пользователь в ASP.NET Core печатается вместе с телеметрией со стороны, поэтому добавлять appInsights.setAuthenticatedUserContext вручную нет необходимости, т. к. данные уже вводятся SDK для ASP.NET Core. Идентификатор проверки подлинности также отправляется на сервер, где SDK в .NET Core идентифицирует его и будет использовать для любой телеметрии со стороны сервера, как подробно описано в Справочнике по JavaScript API. Между тем, в приложения 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*(). Это может привести к отправке телеметрии с неверной конфигурацией.

Пользовательские измерения и свойства в службе аналитики

В службе аналитики пользовательские метрики и свойства приводятся в атрибутах 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 можно написать код. Будут обрабатываться данные, отправляемые из модулей стандартной телеметрии, таких как коллекция запросов HTTP и коллекция зависимостей.

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

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

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

Подробнее.

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

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

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-запрос в веб-приложениях. В приложениях других типов для этого значения можно задать значение "Группировать события совместно".
    • ID: сгенерированное значение, которое устанавливает зависимость между различными событиями, чтобы при проверке любого события в Diagnostic Search, вы могли найти связанные элементы.
    • Name: идентификатор, обычно URL-адрес HTTP-запроса.
    • SyntheticSource: если эта строка не пустая и не имеет значение null, она означает, что источник запроса был определен как программа-робот или веб-тест. По умолчанию он исключается из вычислений в обозревателе метрик.
  • Session: сеанс пользователя. Для Id задается созданное значение, которое изменяется, если пользователь был неактивным в течение некоторого времени.
  • User: информация о пользователе.

Ограничения

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

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

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

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

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

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

Код пакета SDK

Вопросы

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

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

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

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

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