Node.js

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({
    apiKey: 'YOUR_INGESTION_API_KEY',
    service: 'my-service'
});

import

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

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

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

Настройка сбора логов

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

Winston

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

    export default logger;

Pino

Если вы используете pino в качестве логгера, вам необходимо добавить в него следующий транспорт и указать 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({
    apiKey: 'YOUR_INGESTION_API_KEY',
    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({
    apiKey: 'YOUR_INGESTION_API_KEY',
    service: 'my-service'
});

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

HyperDX.setupKoaErrorHandler(app);

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

app.listen(3030);

Manual

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.

export HDX_NODE_CONSOLE_CAPTURE=0

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

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

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

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

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

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

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

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

Импорт кода

// Импортируйте это в самом верху первого файла, который загружается в вашем приложении
// Ключ API по-прежнему указывается через переменную окружения `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 Functions
• 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