Перейти к основному содержимому
Перейти к основному содержимому

Node.js

ClickStack использует стандарт OpenTelemetry для сбора телеметрических данных (журналы, метрики, трассировки и исключения). Трассировки автоматически генерируются с помощью автоматического инструментирования, поэтому ручное инструментирование не требуется для получения ценности от трассировки.

Этот гид охватывает:

  • Журналы
  • Метрики
  • Трассировки
  • Исключения

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

Установка пакета инструментирования HyperDX OpenTelemetry​

Используйте следующую команду для установки пакета ClickStack OpenTelemetry.

npm install @hyperdx/node-opentelemetry

Инициализация SDK​

Чтобы инициализировать SDK, вам нужно вызвать функцию init в начале точки входа вашего приложения.

const HyperDX = require('@hyperdx/node-opentelemetry');

HyperDX.init({
    apiKey: 'YOUR_INGESTION_API_KEY',
    service: 'my-service'
});

Это автоматически захватит трассировку, метрики и журналы вашего приложения на Node.js.

Настройка сбора журналов​

По умолчанию журналы console.* собираются автоматически. Если вы используете логгер такой как winston или pino, вам нужно будет добавить транспорт к вашему логгеру, чтобы отправить журналы в ClickStack. Если вы используете другой тип логгера, свяжитесь с нами или изучите одно из наших интеграций платформы, если это применимо (например, Kubernetes).

Если вы используете winston в качестве вашего логгера, вам нужно будет добавить следующий транспорт к вашему логгеру.

import winston from 'winston';
import * as HyperDX from '@hyperdx/node-opentelemetry';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.Console(),
    HyperDX.getWinstonTransport('info', { // Send logs info and above
      detectResources: true,
    }),
  ],
});

export default logger;

Настройка сбора ошибок​

SDK ClickStack может автоматически захватывать необработанные исключения и ошибки в вашем приложении с полным стек-трейсом и контекстом кода.

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

const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    apiKey: 'YOUR_INGESTION_API_KEY',
    service: 'my-service'
});
const app = express();

// Add your routes, etc.

// Add this after all routes,
// but before any and other error-handling middlewares are defined
HyperDX.setupExpressErrorHandler(app);

app.listen(3000);

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

Если у вас возникли проблемы с SDK, вы можете включить подробное логирование, установив переменную окружения OTEL_LOG_LEVEL в debug.

export OTEL_LOG_LEVEL=debug

Расширенная конфигурация инструментирования​

Захват консольных журналов​

По умолчанию SDK ClickStack будет захватывать консольные журналы. Вы можете отключить это, установив переменную окружения HDX_NODE_CONSOLE_CAPTURE в 0.

export HDX_NODE_CONSOLE_CAPTURE=0

Присоединение информации о пользователе или метаданных​

Чтобы легко пометить все события, связанные с данным атрибутом или идентификатором (например, идентификатор пользователя или электронная почта), вы можете вызвать функцию setTraceAttributes, которая пометит каждый журнал/спан, связанный с текущей трассировкой, после вызова с объявленными атрибутами. Рекомендуется вызывать эту функцию как можно раньше в пределах данного запроса/трассировки (например, как можно раньше в стеке промежуточного программного обеспечения Express).

Это удобный способ убедиться, что все журналы/спаны автоматически помечены правильными идентификаторами для дальнейшего поиска, вместо того чтобы вручную помечать и передавать идентификаторы самим.

userId, userEmail, userName и teamName будут заполнять интерфейс сессий соответствующими значениями, но могут быть опущены. Любые другие дополнительные значения могут быть указаны и использованы для поиска событий.

import * as HyperDX from '@hyperdx/node-opentelemetry';

app.use((req, res, next) => {
  // Get user information from the request...

  // Attach user information to the current trace
  HyperDX.setTraceAttributes({
    userId,
    userEmail,
  });

  next();
});

Убедитесь, что вы включили бета-режим, установив переменную окружения HDX_NODE_BETA_MODE в 1 или передав betaMode: true в функцию init, чтобы включить атрибуты трассировки.

export HDX_NODE_BETA_MODE=1

Google Cloud Run​

Если вы запускаете свое приложение на Google Cloud Run, Cloud Trace автоматически вставляет заголовки выборки в входящие запросы, в настоящее время ограничивая трассировки до выборки 0.1 запроса в секунду для каждой инстанции.

Пакет @hyperdx/node-opentelemetry по умолчанию перезаписывает скорость выборки на 1.0.

Чтобы изменить это поведение или настроить другие установки OpenTelemetry, вы можете вручную настроить переменные окружения OTEL_TRACES_SAMPLER=parentbased_always_on и OTEL_TRACES_SAMPLER_ARG=1, чтобы достигнуть того же результата.

Чтобы узнать больше и заставить трассировку конкретных запросов, пожалуйста, обратитесь к документации Google Cloud Run.

Автоинструментированные библиотеки​

Следующие библиотеки будут автоматически инструментированы (трассированы) SDK:

Альтернативная установка​

Запуск приложения с помощью ClickStack OpenTelemetry CLI​

В качестве альтернативы, вы можете автоинструментировать ваше приложение без каких-либо изменений в коде, используя CLI opentelemetry-instrument или используя флаг Node.js --require. Установка CLI открывает более широкий спектр автоинструментированных библиотек и фреймворков.

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' npx opentelemetry-instrument index.js

Переменная окружения OTEL_SERVICE_NAME используется для идентификации вашего сервиса в приложении HyperDX, это может быть любое имя, которое вы хотите.

Включение захвата исключений​

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

HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1

После этого, чтобы автоматически захватывать исключения из Express, Koa или вручную ловить исключения, следуйте инструкциям в разделе Настройка сбора ошибок выше.

Автоинструментированные библиотеки​

Следующие библиотеки будут автоматически инструментированы (трассированы) с помощью вышеуказанных методов установки: