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

Статья
01/31/2024

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

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

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

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

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

Примечание.

В следующей документации используется классический API приложения Аналитика. Долгосрочный план приложения Аналитика заключается в сборе данных с помощью OpenTelemetry. Дополнительные сведения см. в разделе "Включить Azure Monitor OpenTelemetry" для приложений .NET, Node.js, Python и Java.

Начать

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

Необходимые компоненты

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

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

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

Примечание.

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

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

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

Скопируйте строку подключения ресурса из нового ресурса. Application Insights использует строку подключения для сопоставления данных с ресурсом Azure. Прежде чем пакет SDK сможет использовать строку подключения, необходимо указать строку подключения в переменной среды или в коде.
Добавьте клиентскую библиотеку Node.js в зависимости приложения через package.json. Из корневой папки приложения выполните следующую команду:
```
npm install applicationinsights --save
```
Примечание.

Если вы используете TypeScript, не устанавливайте отдельные пакеты typeings. Пакет NPM содержит встроенные вводимые элементы.
Загрузите явным образом библиотеку в код. Так как пакет SDK внедряет инструментирование во многие другие библиотеки, вам необходимо загрузить библиотеку как можно раньше, даже до выполнения других инструкций require.
```
let appInsights = require('applicationinsights');
```
Кроме того, можно предоставить строка подключения с помощью переменной APPLICATIONINSIGHTS_CONNECTION_STRINGсреды, а не передавать ее вручную setup() или new appInsights.TelemetryClient()в нее. Это позволит хранить строки подключения вне выделенного исходного кода, и вы можете указать различные строки подключения для разных сред. Чтобы осуществить настройку вручную, вызовите appInsights.setup('[your connection string]');.

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

Вы можете использовать пакет SDK, не отправляя данные телеметрии. Для этого задайте appInsights.defaultClient.config.disableAppInsights = true.
Запустите автоматический сбор и отправку данных, вызвав appInsights.start();.

Примечание.

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

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

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

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

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

Нет данных.

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

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

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

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


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

Примечание.

Если строка подключения задана в переменной среды APPLICATIONINSIGHTS_CONNECTION_STRING, .setup() можно вызвать без аргументов. Это позволяет легко использовать разные строки подключения для разных сред.

Перед загрузкой других пакетов загрузите библиотеку require("applicationinsights") приложений Аналитика как можно раньше в скриптах. Этот шаг необходим для того, чтобы библиотека 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 подробных сведений и дополнительных аргументов.

Примечание.

По умолчанию setAutoCollectConsole настроено исключение вызовов console.log и других методов консоли. Будут собираться только вызовы поддерживаемых сторонних средств ведения журнала (например, winston и bunyan). Это поведение можно изменить, чтобы включить вызовы методов console с помощью setAutoCollectConsole(true, true).

Образец

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

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

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

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

Примечание.

Доступно как общедоступная предварительная версия. Дополнительные условия использования Предварительных версий Microsoft Azure

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

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

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

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

Ответ имеет код 200состояния.
Метод ответа : GET.
Ответ сервера имеет Content-Type html.
Ответ сервера содержит как теги, так <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. По умолчанию приложение Аналитика используется diagnostic-channel-publishers для исправления обезьян некоторых из этих библиотек. Эту функцию можно отключить, задав переменную среды 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,,pgwinston и pg-pool. Сведения о том, какая версия этих пакетов исправлена, см. в разделе README для издателей диагностических каналов.

Исправления bunyanсоздают console события трассировки приложения Аналитика на основе включенияsetAutoCollectConsole. winston Остальная часть создает события зависимостей приложения Аналитика на основе включенияsetAutoCollectDependencies.

Динамические метрики

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

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

Примечание.

Возможность отправлять расширенные собственные метрики была добавлена в версию 1.4.0.

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

npm install applicationinsights-native-metrics

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

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

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

По умолчанию пакет SDK отправляет заголовки, понятные другими приложениями или службами, инструментируемыми с помощью пакета SDK для приложений Аналитика. Вы можете включить отправку и получение заголовков контекста трассировки W3C в дополнение к существующим заголовкам ИИ. Таким образом, вы не будете нарушать корреляцию с существующими устаревшими службами. Включение заголовков W3C позволяет приложению коррелировать с другими службами, которые не инструментируются с помощью приложения Аналитика, но они применяют этот стандарт 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:

Примечание.

По умолчанию отслеживаются все запросы. Чтобы отключить автоматическую коллекцию, вызовите .setAutoCollectRequests(false) перед вызовом start().

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

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

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

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

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

Можно создать несколько ресурсов 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().

Свойство	Описание
connectionString	Идентификатор ресурса Application Insights.
endpointUrl	Конечная точка приема данных, в которую отправляются полезные данные телеметрии.
quickPulseHost	Узел Live Metrics Stream, на который отправляются данные телеметрии динамических метрик.
proxyHttpUrl	Прокси-сервер для HTTP-трафика ПАКЕТА SDK. (Необязательно. Значение по умолчанию извлекается из `http_proxy` переменной среды.)
proxyHttpsUrl	Прокси-сервер для трафика HTTPS пакета SDK. (Необязательно. Значение по умолчанию извлекается из `https_proxy` переменной среды.)
httpAgent	Http. Агент, используемый для HTTP-трафика ПАКЕТА SDK. (Необязательно. Значение по умолчанию не определено.)
httpsAgent	Https. Агент, используемый для трафика HTTPS пакета SDK. (Необязательно. Значение по умолчанию не определено.)
maxBatchSize	Максимальное количество элементов телеметрии для включения в полезные данные в конечную точку приема. (Значение по умолчанию — `250`.)
maxBatchIntervalMs	Максимальное время ожидания полезных данных до maxBatchSize. (Значение по умолчанию — `15000`.)
disableAppInsights	Флаг, указывающий, отключена ли передача телеметрии. (Значение по умолчанию — `false`.)
samplingPercentage	Процент отслеживаемых элементов телеметрии, которые должны передаваться. (Значение по умолчанию — `100`.)
correlationIdRetryIntervalMs	Время ожидания перед повторным повтором получения идентификатора для корреляции между компонентами. (Значение по умолчанию — `30000`.)
correlationHeaderExcludedDomains	Список доменов, которые следует исключить из внедрения заголовка корреляции между компонентами. (По умолчанию. См. Config.ts.)

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

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

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

Начать

Необходимые компоненты

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

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

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

Нет данных.

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

Переход с версий до версии 0.22

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

Образец

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

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

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

Динамические метрики

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

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

API TelemetryClient

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

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

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

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

Очистка

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

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

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

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

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

Дополнительные ресурсы