Поделиться через


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

Примечание.

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

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

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

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

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

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

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

Примечание.

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

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

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

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

    Снимок экрана: обзор и строка подключения Application Insights.

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

    npm install applicationinsights --save
    

    Примечание.

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

Перед загрузкой других пакетов загрузите библиотеку 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();

Загрузчик пакета 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или br deflate.
  • Ответ не содержит текущих конечных точек 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 для исправления обезьян некоторых из этих библиотек. Эту функцию можно отключить, задав переменную среды 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 события трассировки Application Insights на основе включенияsetAutoCollectConsole. winston Остальные создают события зависимостей 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().
  • Запросы API собственных наборов не отслеживаются классическими приложениями Application Insights; Требуется отслеживание зависимостей вручную.
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.)

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

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

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

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

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

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