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

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

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

Примечание

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

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

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

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

    Screenshot displaying Application Insights overview and connection string.

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

Примечание

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

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

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

Миграция из версий, предшествующих 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.

Для получения подробных сведений о дополнительных вторичных аргументах изучите их описания в подсказках IDE для встроенных типов или в 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. Для сервера узла с конфигурацией задайте для параметра enableAutoWebSnippetInjection значение true или задайте переменную среды APPLICATIONINSIGHTS_WEB_SNIPPET_ENABLED = true. Автоматическое внедрение веб-фрагментов доступно в пакете SDK для Application Insights Node.js версии 2.3.0 или более поздней версии. Дополнительные сведения см. в разделе Файл сведений Application Insights Node.js GitHub.

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

Чтобы отслеживать контекст для асинхронных вызовов, необходимо внести ряд изменений в сторонних библиотеках, таких как 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, winston, pg и pg-pool. Точные сведения о том, какие версии этих пакетов исправлены, см. в файле README diagnostic-channel-publishers.

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

Интерактивные метрики

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

Примечание

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

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.Agent, используемый для HTTP-трафика пакета SDK (необязательный, по умолчанию не определен).
httpsAgent Агент http.Agent, используемый для HTTPS-трафика пакета SDK (необязательный, по умолчанию не определен).
maxBatchSize Максимальное число элементов телеметрии, включаемых в полезные данные, передаваемые в конечную точку приема данных (по умолчанию 250).
maxBatchIntervalMs Максимальное время ожидания достижения полезными данными размера maxBatchSize (по умолчанию 15000).
disableAppInsights Флаг, показывающий, отключена ли передача телеметрии (по умолчанию false).
samplingPercentage Процент отслеживаемых элементов телеметрии, которые должны быть переданы (по умолчанию 100).
correlationIdRetryIntervalMs Время ожидания перед повторной попыткой получения идентификатора для корреляции между компонентами (по умолчанию 30000).
correlationHeaderExcludedDomains Список доменов, исключаемых из вставки заголовка корреляции между компонентами (по умолчанию см. Config.ts).

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