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

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

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

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

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

Образец

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

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

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

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

Часто задаваемые вопросы

Как отключить корреляцию телеметрии?

Чтобы отключить корреляцию телеметрии, используйте correlationHeaderExcludedDomains свойство в конфигурации. Дополнительные сведения см. в ApplicationInsights-node.js.

Как настроить требуемый уровень журнала?

Чтобы настроить требуемый уровень журнала, который будет использовать Application Insights, используйте APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL переменную среды. Поддерживаемые значения: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE и ALL. Дополнительные сведения см. в ApplicationInsights-node.js.

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

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

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

• Мониторьте телеметрию на портале
• Пишите запросы аналитики по вашей телеметрии