Node.js - ClickHouse Documentation

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: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Не указывайте для Управляемого ClickStack
    service: 'my-service'
});

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

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    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: 'http://your-otel-collector:4318',
    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: 'http://your-otel-collector:4318',
    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_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' npx opentelemetry-instrument index.js

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

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_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 или вручную перехватывать их, следуйте инструкциям в разделе Настройка сбора ошибок выше.

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

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

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

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

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

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

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

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

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

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

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

​Google Cloud Run

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Google Cloud Run

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

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

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

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

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