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

Статья
12/05/2022
Чтение занимает 13 мин

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 можно ознакомиться далее в этой статье.

Примечание

Доступна предварительная версия предложения Node.js на основе OpenTelemetry. Подробнее.

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

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

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

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

Автоматическое внедрение веб-фрагментов (предварительная версия)

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

Для сервера узла с конфигурацией задайте значение enableAutoWebSnippetInjectiontrue. Кроме того, можно задать для переменной среды значение APPLICATIONINSIGHTS_WEB_SNIPPET_ENABLED = true. Автоматическое внедрение веб-фрагментов доступно в пакете SDK для Application Insights Node.js версии 2.3.0 или более поздней версии. Дополнительные сведения см. в статье Application Insights Node.js GitHub Readme.

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

Для отслеживания контекста в асинхронных вызовах требуются некоторые изменения в сторонних библиотеках, таких как MongoDB и Redis. По умолчанию Application Insights будет использовать 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 ,winstonpg и pg-pool. Сведения о том, какая именно версия этих пакетов является исправленной, см. в файле сведений diagnostic-channel-publishers.

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

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

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

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

Примечание

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

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

Примечание

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

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

Проверка подключения между узлом приложения и службой приема

Пакеты SDK и агенты Application Insights отправляют данные телеметрии для приема в качестве вызовов REST к конечным точкам приема. Вы можете проверить подключение веб-сервера или хост-компьютера приложения к конечным точкам службы приема с помощью необработанных клиентов REST из Команд PowerShell или curl. См. статью Устранение неполадок с телеметрией отсутствующих приложений в Azure Monitor Application Insights.

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

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

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

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

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

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

Нет данных

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

Миграция с версий до 0.22

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

Дискретизация

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

Автоматическое внедрение веб-фрагментов (предварительная версия)

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

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

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

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

API TelemetryClient

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

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

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

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

Очистка

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

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

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

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

Проверка подключения между узлом приложения и службой приема

Дальнейшие действия

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

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