Node.js

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

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

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

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

NPM
Yarn

npm install @hyperdx/node-opentelemetry

yarn add @hyperdx/node-opentelemetry

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

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

require
import

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

HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    apiKey: '<YOUR_INGESTION_API_KEY>', // Не указывайте для Управляемого ClickStack
    service: 'my-service'
});

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

HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    apiKey: '<YOUR_INGESTION_API_KEY>', // Не указывайте для Управляемого ClickStack
    service: 'my-service'
});

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

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

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

Winston
Pino
console.log

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

    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', { // Отправлять журналы уровня info и выше
          detectResources: true,
        }),
      ],
    });

    export default logger;

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

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

const logger = pino(
    pino.transport({
    mixin: HyperDX.getPinoMixinFunction,
    targets: [
        HyperDX.getPinoTransport('info', { // Отправлять журналы уровня info и выше
        detectResources: true,
        }),
    ],
    }),
);

export default logger;

По умолчанию методы console.* поддерживаются без дополнительной настройки.Вы можете отключить это, установив переменную окружения HDX_NODE_CONSOLE_CAPTURE в 0 или передав consoleCapture: false в функцию init.

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

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

Express
Koa
Вручную

const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    apiKey: '<YOUR_INGESTION_API_KEY>', // Не указывайте для Управляемого ClickStack
    service: 'my-service'
});
const app = express();

// Добавьте здесь маршруты и т. д.

// Добавьте это после всех маршрутов,
// но до объявления любых других middleware обработки ошибок
HyperDX.setupExpressErrorHandler(app);

app.listen(3000);

const Koa = require("koa");
const Router = require("@koa/router");
const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    apiKey: '<YOUR_INGESTION_API_KEY>', // Не указывайте для Управляемого ClickStack
    service: 'my-service'
});

const router = new Router();
const app = new Koa();

HyperDX.setupKoaErrorHandler(app);

// Добавьте здесь маршруты и т. д.

app.listen(3030);

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

function myErrorHandler(error, req, res, next) {
    // Это можно использовать в любом месте приложения
    HyperDX.recordException(error);
}

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

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

export OTEL_LOG_LEVEL=debug

Расширенная настройка инструментирования

Сбор логов консоли

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

copy

export HDX_NODE_CONSOLE_CAPTURE=0

Добавление информации о пользователе или метаданных

Чтобы пометить все события, связанные с определённым атрибутом или идентификатором (например, ID пользователя или email), можно вызвать функцию setTraceAttributes, которая после вызова добавит указанные атрибуты ко всем журналам/спанам, связанным с текущей трассировкой. Эту функцию рекомендуется вызывать как можно раньше в рамках конкретного запроса/трассировки (например, как можно раньше в стеке middleware Express). Это удобный способ гарантировать, что все журналы/спаны будут автоматически помечены нужными идентификаторами для последующего поиска, вместо того чтобы вручную добавлять метки и самостоятельно передавать идентификаторы. userId, userEmail, userName и teamName заполнят интерфейс сеансов соответствующими значениями, но их можно не указывать. Также можно задать любые другие дополнительные значения и использовать их для поиска событий.

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

app.use((req, res, next) => {
  // Получаем информацию о пользователе из запроса...

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

Использование NPX
Пользовательская точка входа (например, Nodemon, ts-node и т. д.)
Импорт кода

Управляемый ClickStackДля Управляемого ClickStack HYPERDX_API_KEY можно не указывать.

HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' npx opentelemetry-instrument index.js

Управляемый ClickStackДля Управляемого ClickStack HYPERDX_API_KEY можно не указывать.

HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' ts-node -r '@hyperdx/node-opentelemetry/build/src/tracing' index.js

// Импортируйте это в самом начале первого файла, загружаемого в вашем приложении
// API key по-прежнему нужно указать через переменную окружения `HYPERDX_API_KEY`
import { initSDK } from '@hyperdx/node-opentelemetry';

initSDK({
    consoleCapture: true, // необязательно, по умолчанию: true
    additionalInstrumentations: [], // необязательно, по умолчанию: []
});

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

Включение перехвата исключений

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

HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1

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

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

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

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

Возможности

Управление ClickStack

Руководства

Партнёры по интеграции

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

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

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

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

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

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

Расширенная настройка инструментирования

Сбор логов консоли

Добавление информации о пользователе или метаданных

Google Cloud Run

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

Альтернативный способ установки

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

Включение перехвата исключений

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

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

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

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

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

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

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

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

​Сбор логов консоли

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

​Google Cloud Run

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

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

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

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

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

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

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

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

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

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

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

Расширенная настройка инструментирования

Сбор логов консоли

Добавление информации о пользователе или метаданных

Google Cloud Run

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

Альтернативный способ установки

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

Включение перехвата исключений

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