Мониторинг приложений и служб Node.js с помощью Application Insights (классический API)

Application Insights отслеживает компоненты после развертывания, чтобы обнаружить проблемы с производительностью и другие проблемы. Application Insights можно использовать для служб Node.js, размещенных в центре обработки данных, на виртуальных машинах Azure, в веб-приложениях и даже в других общедоступных облаках.

Чтобы получить, сохранить и изучить данные мониторинга, включите пакет SDK в код. Затем настройте соответствующий ресурс Application Insights в Azure. Пакет SDK отправляет данные в этот ресурс для дальнейшего анализа и исследования.

Клиентская библиотека Node.js может автоматически отслеживать входящие и исходящие HTTP-запросы, исключения и некоторые системные метрики. Начиная с версии 0.20 клиентская библиотека также может отслеживать некоторые распространенные пакеты сторонних поставщиков, такие как MongoDB, MySQL и Redis.

Все события, связанные с входящим HTTP-запросом, коррелируют для быстрого устранения неполадок.

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

Начало работы

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

Предварительные условия

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

Настройка ресурса Application Insights

1. Войдите на портал Azure.
2. Создайте ресурс Application Insights.

Настройка клиентской библиотеки Node.js

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

1. Скопируйте строку подключения ресурса из нового ресурса. Application Insights использует строку подключения для сопоставления данных с ресурсом Azure. Прежде чем пакет SDK сможет использовать строку подключения, необходимо указать строку подключения в переменной среды или в коде.

   

2. Добавьте клиентскую библиотеку Node.js в зависимости приложения через package.json. Из корневой папки приложения выполните следующую команду:

   npm install applicationinsights --save
   

   Примечание.

   Если вы используете TypeScript, не устанавливайте отдельные пакеты типов. Пакет NPM содержит встроенные вводимые элементы.

3. Явно загрузите библиотеку в вашем коде. Так как пакет SDK внедряет инструментирование во многие другие библиотеки, вам необходимо загрузить библиотеку как можно раньше, даже до выполнения других инструкций require.

   let appInsights = require('applicationinsights');
   

4. Кроме того, можно предоставить строку подключения с помощью переменной среды APPLICATIONINSIGHTS_CONNECTION_STRING, вместо того чтобы передавать ее вручную в setup() или new appInsights.TelemetryClient(). Это позволит хранить строки подключения вне выделенного исходного кода, и вы можете указать различные строки подключения для разных сред. Чтобы осуществить настройку вручную, вызовите appInsights.setup('[your connection string]');.

   Дополнительные параметры конфигурации приведены в указанных ниже разделах.

   Вы можете использовать пакет SDK, не отправляя данные телеметрии. Для этого задайте appInsights.defaultClient.config.disableAppInsights = true.

5. Запустите автоматический сбор и отправку данных, вызвав appInsights.start();.

Отслеживание работы приложения

Пакет SDK автоматически собирает данные телеметрии для среды выполнения Node.js и некоторых распространенных модулей сторонних поставщиков. Используйте приложение для создания этих данных.

Затем на портале Azure перейдите к ресурсу Application Insights, созданному ранее. На временной шкале обзора найдите первые несколько точек данных. Для просмотра более подробных данных выбирайте различные компоненты на диаграммах.

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

Нет данных.

Так как пакет SDK пакетирует данные для отправки, может возникнуть задержка перед появлением элементов на портале. Если данные в ресурсе не отображаются, попробуйте сделать следующее:

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

Базовое использование

Для встроенной коллекции HTTP-запросов, событий популярных сторонних библиотек, необработанных исключений и метрик системы:

let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

Перед загрузкой других пакетов загрузите библиотеку require("applicationinsights") Application Insights как можно раньше в скриптах. Этот шаг необходим для того, чтобы библиотека Application Insights могла подготовить пакеты для дальнейшего отслеживания. При возникновении конфликтов с другими библиотеками, выполняющими аналогичные подготовительные действия, попробуйте загрузить библиотеку Application Insights позже.

Из-за способа, используемого JavaScript для обработки обратных вызовов, требуются дополнительные действия, чтобы отследить запрос для внешних зависимостей и более поздних обратных вызовов. По умолчанию это дополнительное отслеживание включено. Отключите его, вызвав setAutoDependencyCorrelation(false) , как описано в разделе конфигурации пакета SDK.

Переход с версий более ранних, чем 0.22

Существуют критические изменения между выпусками, предшествующими версии 0.22, и последующими. Эти изменения призваны обеспечить согласованность с другими пакетами SDK Application Insights и позволяют использовать будущие возможности расширения.

Как правило, можно выполнить миграцию с помощью следующих действий:

• Замените ссылки на appInsights.client ссылками на appInsights.defaultClient.
• Замените ссылки на appInsights.getClient() ссылками на new appInsights.TelemetryClient().
• Замените все аргументы в методах client.track* на один объект, содержащий аргументы в виде именованных свойств. См. встроенные подсказки типов в вашей интегрированной среде разработки или TelemetryTypes для ожидаемого объекта каждого типа телеметрии.

Если вы обращаетесь к функциям конфигурации SDK без их связывания с appInsights.setup(), теперь вы можете найти эти функции по appInsights.Configurations. Например, appInsights.Configuration.setAutoCollectDependencies(true). Ознакомьтесь с изменениями конфигурации по умолчанию в следующем разделе.

Конфигурация пакета SDK

Объект appInsights предоставляет множество методов конфигурации. Эти методы со значениями по умолчанию перечислены в следующем фрагменте кода.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

Чтобы полностью сопоставить события в сервисе, задайте .setAutoDependencyCorrelation(true). При включении этой опции SDK может отслеживать контекст в асинхронных обратных вызовах в Node.js.

Просмотрите их описания в подсказках типов встроенной среды разработки или в файле applicationinsights.ts для получения подробной информации и просмотра необязательных дополнительных аргументов.

Распределенная трассировка

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

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

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

Включите распределённую трассировку через Application Insights с помощью автоинструментирования или пакетов SDK.

Агенты Application Insights и пакеты SDK для .NET, .NET Core, Java, Node.jsи JavaScript поддерживают собственную распределенную трассировку.

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

Любые технологии также можно отслеживать вручную с помощью вызова TrackDependency в TelemetryClient.

Модель данных для корреляции телеметрии

Application Insights определяет модель данных для корреляции распределенной телеметрии. Для связывания телеметрии с логической операцией каждый элемент телеметрии имеет поле operation_Idконтекста. Каждый элемент телеметрии в распределенной трассировке использует этот идентификатор. Таким образом, даже если вы теряете данные телеметрии из одного слоя, вы по-прежнему можете связать данные телеметрии, сообщаемые другими компонентами.

Распределенная логическая операция обычно состоит из набора небольших операций, обрабатываемых одним из компонентов. Запрос телеметрии определяет эти операции. Каждый элемент телеметрии запроса имеет свой собственный id идентификатор, определяющий его уникально и глобально. И все элементы телеметрии (например, трассировки и исключения), связанные с запросом, должны установить operation_parentId в значение запроса id.

Телеметрия зависимостей представляет каждую исходящую операцию, например вызов HTTP к другому компоненту. Он также определяет свой собственный id, который глобально уникален. Запрос телеметрии, инициированный этим вызовом зависимости, использует это id в качестве operation_parentId.

Вы можете создать представление распределенной логической операции с помощью operation_Id, operation_parentId, request.id и dependency.id. Эти поля также определяют порядок причинно-следственных вызовов телеметрии.

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

Если количество элементов хранилища большое, вам потребуется указание о том, где искать дальше. Модель данных Application Insights определяет два поля для решения этой проблемы: request.source и dependency.target. Первое поле определяет компонент, инициирующий запрос зависимостей. Второе поле определяет, какой компонент вернул ответ вызова зависимостей.

Сведения о запросах из нескольких разрозненных экземпляров см. в статье "Запрос данных в рабочих областях Log Analytics, приложениях и ресурсах в Azure Monitor".

Example

Рассмотрим пример. Приложение под названием "Цены акций" показывает текущую рыночную цену акций с помощью внешнего API с именем Stock. Приложение "Цены на акции" имеет страницу с именем "Фондовая страница", которая открывается в веб-браузере клиента с помощью GET /Home/Stock. Приложение запрашивает API stock с помощью http-вызова GET /api/stock/value.

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

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

В результатах все элементы телеметрии имеют общий корень operation_Id. При вызове Ajax на странице новый уникальный идентификатор (qJSXU) назначается телеметрии зависимостей, а идентификатор pageView используется как operation_ParentId. Затем запрос сервера использует идентификатор Ajax в качестве operation_ParentId.

При вызове GET /api/stock/value внешней службы необходимо знать идентификацию сервера, чтобы можно было соответствующим образом установить поле dependency.target. Если внешняя служба не поддерживает мониторинг, target устанавливается в имя узла службы. Например, stock-prices-api.com. Но если служба идентифицирует себя путем возврата предопределенного заголовка HTTP, target содержит удостоверение службы, позволяющее Application Insights создавать распределенную трассировку путем запроса телеметрии из этой службы.

Заголовки корреляции с помощью W3C TraceContext

Application Insights переходит в контекст трассировки W3C, который определяет:

• traceparent: содержит глобальный уникальный идентификатор операции и уникальный идентификатор вызова.
• tracestate: содержит контекст трассировки для конкретной системы.

Последняя версия пакета SDK Application Insights поддерживает протокол Trace-Context, но может потребоваться принять его. (Поддерживается обратная совместимость с предыдущим протоколом корреляции, поддерживаемым пакетом SDK Application Insights.)

Протокол HTTP корреляции, также называемый Request-Id, устарел. Этот протокол определяет два заголовка:

• Request-Id: несет глобально уникальный идентификатор вызова.
• Correlation-Context: содержит коллекцию пар "имя-значение" свойств распределенной трассировки.

Application Insights также определяет расширение для протокола HTTP корреляции. Он использует Request-Context пары "имя-значение" для распространения коллекции свойств, используемых непосредственным вызывающим или вызываемой стороной. Пакет SDK Application Insights использует этот заголовок для задания полей dependency.target и request.source.

Модели данных W3C Trace-Context и Application Insights сопоставляются следующим образом:

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

Образец

По умолчанию пакет SDK отправляет все собранные данные в службу Application Insights. Если вы хотите включить выборку для уменьшения объема данных, установите поле samplingPercentage в объекте config клиента. Параметр samplingPercentage 100 (по умолчанию) означает, что все данные будут отправлены, и 0 означает, что ничего не будет отправлено.

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

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

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

Несколько ролей для приложений с несколькими компонентами

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

Используйте следующий код, чтобы задать RoleName поле:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

Загрузчик пакета SDK для браузера

Автоматическое веб-инструментирование можно включить для Node.js сервера с помощью внедрения скрипта загрузчика JavaScript SDK (Web) через настройки конфигурации.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

или путем задания переменной APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = trueсреды.

Веб-инструментирование включено в ответах сервера узлов, когда выполняются все следующие требования:

• Ответ имеет код состояния 200.
• Метод ответа : GET.
• Ответ сервера содержит HTML в тэге Content-Type.
• Ответ сервера содержит как тег <head>, так и тег </head>.
• Если ответ сжимается, он должен иметь только один Content-Encoding тип, а тип кодирования должен быть одним из gzipили brdeflate.
• Ответ не содержит текущих конечных точек CDN для веб-инструментирования /backup. (текущие и резервные точки веб-инструментирования CDN здесь)

Конечная точка CDN веб-инструментирования может быть изменена, задав переменную среды APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints". Строку подключения веб-инструментов можно изменить путем установки переменной среды APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

Автоматическое инструментирование сторонних компонентов

Для отслеживания контекста в асинхронных вызовах некоторые изменения требуются в сторонних библиотеках, таких как MongoDB и Redis. По умолчанию Application Insights использует diagnostic-channel-publishers для monkey-patching некоторых из этих библиотек. Эту функцию можно отключить, задав переменную среды APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL.

Отдельные патчи можно отключить, установив переменную среды APPLICATION_INSIGHTS_NO_PATCH_MODULES на список пакетов, разделенных запятыми. Например, используйте APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis для предотвращения исправления console и redis пакетов.

В настоящее время инструментируется девять пакетов: bunyan, console, mongodb, mongodb-core, mysql, redis, winston, pg и pg-pool. Информация о том, какая версия этих пакетов обновлена, см. в README для diagnostic-channel-publishers.

Патчи bunyan, winston и console создают события трассировки в Application Insights в зависимости от того, включён ли setAutoCollectConsole. Остальные создают события зависимостей Application Insights в зависимости от того, включен ли setAutoCollectDependencies.

Метрики в реальном времени

Чтобы включить отправку динамических метрик из приложения в Azure, используйте setSendLiveMetrics(true). В настоящее время фильтрация динамических метрик на портале не поддерживается.

Расширенные метрики

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

npm install applicationinsights-native-metrics

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

• Сборка мусора. Количество времени ЦП, затраченного на каждый тип сборки мусора, и количество событий каждого типа.
• Цикл событий. Сколько тактов произошло и сколько времени ЦП было суммарно затрачено.
• Куча и вне кучи: сколько памяти вашего приложения используется в куче или вне кучи.

Режимы распределенной трассировки

По умолчанию пакет SDK отправляет заголовки, понятные другими приложениями или службами, инструментируемыми с помощью пакета SDK Application Insights. Вы можете включить отправку и получение заголовков контекста трассировки W3C в дополнение к существующим заголовкам искусственного интеллекта (ИИ). Таким образом, вы не нарушите совместимость с существующими устаревшими службами. Включение заголовков W3C позволяет приложению сопоставляться с другими службами, которые не инструментируются с Application Insights, но применяют этот стандарт W3C.

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

API TelemetryClient

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

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

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

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

С помощью следующего кода можно отслеживать зависимости:

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

Пример утилиты, которая использует trackMetric, чтобы измерять, сколько времени занимает планирование цикла событий.

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

Добавление пользовательского свойства во все события

С помощью следующего кода можно добавить пользовательское свойство во все события:

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

Отслеживание HTTP-запросов GET

Используйте следующий код, чтобы вручную отслеживать HTTP-запросы GET:

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

Кроме того, можно отслеживать запросы с помощью trackNodeHttpRequest метода:

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

Отслеживание времени запуска сервера

С помощью следующего кода можно отслеживать время запуска сервера:

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

Смыв

По умолчанию данные телеметрии буферизуются на 15 секунд перед отправкой на сервер приема данных. Если ваше приложение имеет короткий срок жизни, например, средство CLI, может потребоваться вручную сбросить буферизованную телеметрию при завершении работы приложения, используя appInsights.defaultClient.flush().

Если SDK обнаруживает, что ваше приложение аварийно завершает работу, он вызывает функцию очистки для вас с помощью appInsights.defaultClient.flush({ isAppCrashing: true }). При использовании параметра очистки isAppCrashing предполагается, что приложение находится в аномальном состоянии и не подходит для отправки телеметрии. Вместо этого пакет SDK сохраняет все буферизованные данные телеметрии в постоянное хранилище и позволяет приложению завершить работу. При повторном запуске приложения пытается отправить данные телеметрии, сохраненные в постоянном хранилище.

Фильтрация и предварительная обработка телеметрии

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

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

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

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

Filtering

Этот метод обеспечивает прямой контроль над включенными или исключенными из потока телеметрии. Фильтрация может использоваться для исключения отправляемых телеметрических данных в Application Insights. Фильтрацию можно использовать с фильтрацией выборок или отдельно.

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

ITelemetryProcessor и ITelemetryInitializer

Какова разница между процессорами телеметрии и инициализаторами телеметрии?

• Есть некоторые пересечения в том, как их можно использовать. Их можно использовать для добавления или изменения свойств телеметрии, хотя мы рекомендуем использовать инициализаторы для этой цели.
• Инициализаторы телеметрии всегда выполняются перед процессорами телеметрии.
• Инициализаторы телеметрии могут вызываться несколько раз. По соглашению они не задают какое-либо свойство, которое уже было задано.
• Процессоры телеметрии позволяют полностью заменить или отменить элемент телеметрии.
• Все зарегистрированные инициализаторы телеметрии вызываются для каждого элемента телеметрии. Для процессоров телеметрии пакет SDK гарантирует вызов первого процессора телеметрии. Независимо от того, вызываются ли остальные процессоры телеметрии или не определяются предыдущими процессорами телеметрии.
• Инициализаторы телеметрии используются для дополнения телеметрии большим количеством свойств или переопределения существующих. Используйте обработчик телеметрии для фильтрации телеметрии.

Добавление и изменение свойств

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

Например, Application Insights для веб-пакета собирает данные телеметрии о HTTP-запросах. По умолчанию он отмечает любой запрос с кодом >=400 как ошибочный. Если вместо этого вы хотите рассматривать 400 как успешный, можно предоставить инициализатор телеметрии, который задает свойство успешности.

Если вы предоставляете инициализатор телеметрии, он вызывается всякий раз, когда вызывается любой из методов Track*(). Этот инициализатор включает Track() методы, вызываемые стандартными модулями телеметрии. По соглашению эти модули не задают никаких свойств, которые уже были заданы инициализатором. Инициализаторы телеметрии вызываются перед вызовом процессоров телеметрии, поэтому любые обогащения, выполненные инициализаторами, видны процессорам.

Предварительная обработка данных с помощью обработчиков телеметрии

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

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

Если обработчик телеметрии возвращает значение false, этот элемент телеметрии не отправляется.

Все обработчики телеметрии получают данные телеметрии и их конверт для проверки и изменения. Они также получают объект контекста. Содержимое этого объекта определяется параметром contextObjects при вызове метода отслеживания для отслеживания телеметрии вручную. Для автоматически собираемых данных телеметрии этот объект заполняется доступными данными запроса и постоянным содержимым запроса, предоставленными appInsights.getCorrelationContext() (если включена автоматическая корреляция зависимостей).

Тип TypeScript для обработчика данных телеметрии:

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

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

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

Добавьте имя облачной роли и экземпляр облачной роли

Задайте имя облачной роли с помощью прямых тегов контекста:

var appInsights = require("applicationinsights");
appInsights.setup('INSTRUMENTATION_KEY').start();
appInsights.defaultClient.context.tags["ai.cloud.role"] = "your role name";
appInsights.defaultClient.context.tags["ai.cloud.roleInstance"] = "your role instance";

Задайте имя облачной роли с помощью обработчика телеметрии:

var appInsights = require("applicationinsights");
appInsights.setup('INSTRUMENTATION_KEY').start();

appInsights.defaultClient.addTelemetryProcessor(envelope => {
    envelope.tags["ai.cloud.role"] = "your role name";
    envelope.tags["ai.cloud.roleInstance"] = "your role instance"
});

Использование нескольких строк подключения

Можно создать несколько ресурсов Application Insights и отправить каждому из них разные данные, используя соответствующие строки подключения.

Например:

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

Расширенные параметры конфигурации

Объект клиента содержит свойство config с множеством необязательных параметров для расширенных сценариев. Чтобы задать их, используйте:

client.config.PROPERTYNAME = VALUE;

Эти свойства зависят от клиента, поэтому можно настроить appInsights.defaultClient отдельно от клиентов, созданных с помощью new appInsights.TelemetryClient().

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

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

Сводка по API

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

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

Предварительные условия

Если у вас еще нет ссылки на пакет SDK Application Insights:

1. Добавьте пакет SDK Application Insights в проект.

2. В коде устройства или веб-сервера включите следующее:

   • .NET
   • Node.js

   using Microsoft.ApplicationInsights;
   

Получить экземпляр TelemetryClient

Получите экземпляр TelemetryClient:

private TelemetryClient telemetry = new TelemetryClient();

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

var telemetry = applicationInsights.defaultClient;

TrackEvent

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

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

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

telemetry.TrackEvent("WinGame");

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

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

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

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

GetMetric

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

TrackMetric

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

telemetry.TrackPageView("GameReviewPage");

Данные телеметрии страниц в 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

Серверный SDK использует TrackRequest для записи HTTP-запросов.

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

Рекомендуемый способ отправки телеметрии запроса — когда запрос выступает в качестве контекста операции.

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

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

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

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here uses 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.

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, telemetry item is sent.

Наряду с настройкой контекста операции, StartOperation создает элемент телеметрии того типа, который вы указываете. Он отправляет элемент телеметрии, когда вы завершаете операцию или при явном вызове StopOperation. Если вы используете RequestTelemetry в качестве типа телеметрии, его длительность задается в интервал времени между запуском и остановкой.

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

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

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

Запросы в Log Analytics

В Application Insights Analytics запросы отображаются в requests таблице.

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

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

TrackException

Отправка исключений в Application Insights:

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

Отчеты включают трассировки стека.

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

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

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

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

В Application Insights Analytics в таблице отображаются 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. Вы можете отправлять блоки диагностических данных и проверять их в поиске диагностики.

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

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

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

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

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

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

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

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

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

В Application Insights Analytics вызовы TrackTrace отображаются в таблице traces.

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

TrackDependency

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

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

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. Для работы модуля необходимо установить агент на сервере.

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

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

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

В Application Insights AnalyticstrackDependency вызовы отображаются в dependenciesтаблице.

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

dependencies
| summarize sum(itemCount) by target

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

dependencies
| join (requests) on operation_Id

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

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

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

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

telemetry.flush();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например, если вы добавите свойство, названное "игра", в телеметрию запроса, этот запрос подсчитывает количество различных значений "игра" и показывает среднее значение пользовательской метрики "очко".

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

Обратите внимание, что:

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

События синхронизации

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

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

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

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

using Microsoft.ApplicationInsights.DataContracts;

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

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

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

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

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

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

Для динамической остановки и запуска коллекции и передачи данных телеметрии:

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

telemetry.config.disableAppInsights = true;

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

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

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

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

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

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

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

Динамическая строка подключения

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

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

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

TelemetryContext

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

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

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

• Компонент: приложение и его версия.
• Устройство: данные об устройстве, на котором работает приложение. В веб-приложениях телеметрия отправляется с сервера или клиентского устройства.
• Ключ инструментария: ресурс Application Insights в Azure, где отображается телеметрия. Обычно он загружается из ApplicationInsights.config.
• Расположение: географическое расположение устройства.
• Операция: в веб-приложениях текущий HTTP-запрос. В других типах приложений можно задать это значение для группирования событий вместе.
  • Идентификатор: это созданное значение, которое сопоставляет различные события, чтобы при проверке любого события в Диагностическом Поиске можно было найти связанные элементы.
  • Имя: идентификатор, как правило, URL-адрес HTTP-запроса.
  • SyntheticSource: если значение не равно null или пусто, строка, указывающая, что источник запроса был определен как робот или веб-тест. По умолчанию он исключен из вычислений в обозревателе метрик.
• Сеанс: сеанс пользователя. Идентификатор имеет созданное значение, которое изменяется, когда пользователь не был активным в течение некоторого времени.
• Пользователь: сведения о пользователе.

Limits

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

Для получения дополнительной информации о ценах и квотах, смотрите выставление счетов Application Insights.

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

Сведения о том, сколько времени хранятся данные, см. в разделе "Хранение и конфиденциальность данных".

Устранение неполадок

Сведения об устранении неполадок, включая сценарии "без данных" и настройку журналов, см. в статье "Устранение неполадок мониторинга Application Insights" Node.js приложений и служб.

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

• Чтобы просмотреть часто задаваемые вопросы (вопросы и ответы), см. следующие сведения:
  • вопросы и ответы оNode.js
  • Часто задаваемые вопросы о API Application Insights для пользовательских событий и метрик
• Отслеживайте данные телеметрии на портале.
• Узнайте, как использовать Log Analytics и записывать запросы аналитики по данным телеметрии.