Node.js

SDK для Node.js для ClickStack — стек обсервабилити ClickHouse

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

​

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

​

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

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

NPM

npm install @hyperdx/node-opentelemetry 

Yarn

yarn add @hyperdx/node-opentelemetry 

​

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

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

require

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

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

import

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

Если вы используете 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

Если вы используете 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.log

По умолчанию методы console.* поддерживаются без дополнительной настройки.

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

​

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

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

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

Express

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);

Koa

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 будет автоматически инструментировать (трассировать) следующие библиотеки:

• dns
• express
• graphql
• hapi
• http
• ioredis
• knex
• koa
• mongodb
• mongoose
• mysql
• mysql2
• net
• pg
• pino
• redis
• winston

​

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

​

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

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

Использование NPX

Управляемый ClickStack

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

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

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

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

​

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

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

• amqplib
• функции AWS Lambda
• aws-sdk
• bunyan
• cassandra-driver
• connect
• cucumber
• dataloader
• dns
• express
• fastify
• generic-pool
• graphql
• grpc
• hapi
• http
• ioredis
• knex
• koa
• lru-memoizer
• memcached
• mongodb
• mongoose
• mysql
• mysql2
• nestjs-core
• net
• pg
• pino
• redis
• restify
• socket.io
• winston