Node.js

ClickStack용 Node.js SDK - ClickHouse Observability Stack

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: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack의 경우 생략
    service: 'my-service'
});

import

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

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack의 경우 생략
    service: 'my-service'
});

이렇게 하면 Node.js 애플리케이션의 트레이싱, 메트릭, 로그가 자동으로 수집됩니다.

​

로그 수집 설정

기본적으로 console.* 로그는 자동으로 수집됩니다. winston이나 pino 같은 로거를 사용하는 경우, 로그를 ClickStack으로 전송하려면 로거에 transport를 추가해야 합니다. 다른 종류의 로거를 사용한다면, 문의하거나 해당하는 경우 플랫폼 통합(예: 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으로 설정하거나 init 함수에 consoleCapture: false를 전달하여 이 기능을 비활성화할 수 있습니다.

​

오류 수집 설정

ClickStack SDK는 전체 스택 트레이스와 코드 컨텍스트를 포함해 애플리케이션에서 처리되지 않은 예외와 오류를 자동으로 기록할 수 있습니다.

이를 활성화하려면 애플리케이션의 오류 처리 미들웨어 끝부분에 다음 코드를 추가하거나, recordException 함수를 사용해 예외를 수동으로 기록해야 합니다.

Express

const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack의 경우 생략
    service: 'my-service'
});
const app = express();

// 라우트 등을 추가합니다.

// 모든 라우트를 추가한 후,
// 다른 오류 처리 미들웨어를 정의하기 전에 이것을 추가합니다
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: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Managed 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

​

고급 계측 구성

​

콘솔 로그 수집

기본적으로 ClickStack SDK는 콘솔 로그를 수집합니다. HDX_NODE_CONSOLE_CAPTURE 환경 변수를 0으로 설정하면 이 기능을 비활성화할 수 있습니다.

copy

export HDX_NODE_CONSOLE_CAPTURE=0

​

사용자 정보 또는 메타데이터 추가

지정한 속성이나 식별자(예: 사용자 ID 또는 이메일)와 관련된 모든 이벤트에 쉽게 태그를 지정하려면 setTraceAttributes 함수를 호출하면 됩니다. 이 함수를 호출한 이후 현재 트레이스와 연결된 모든 로그/스팬에는 지정한 속성이 태그로 추가됩니다. 이 함수는 해당 요청/트레이스 내에서 가능한 한 이른 시점에 호출하는 것이 좋습니다(예: Express 미들웨어 스택에서 가능한 한 이른 시점).

이 방법을 사용하면 나중에 검색할 수 있도록 모든 로그/스팬에 올바른 식별자가 자동으로 태그되므로, 식별자를 직접 태그하고 전파할 필요가 없습니다.

userId, userEmail, userName, teamName은 세션 UI에 해당 값을 채워 넣으며, 생략해도 됩니다. 이 외의 추가 값도 지정하여 이벤트 검색에 사용할 수 있습니다.

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

app.use((req, res, next) => {
  // 요청에서 사용자 정보를 가져옵니다...

  // 현재 트레이스에 사용자 정보를 연결합니다
  HyperDX.setTraceAttributes({
    userId,
    userEmail,
  });

  next();
});

trace 속성을 사용하려면 HDX_NODE_BETA_MODE 환경 변수를 1로 설정하거나 init 함수에 betaMode: true를 전달해 베타 모드를 활성화하십시오.

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 documentation을 참조하십시오.

​

자동 계측 라이브러리

SDK는 다음 라이브러리를 자동으로 계측(trace)합니다:

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

​

다른 설치 방법

​

ClickStack OpenTelemetry CLI로 애플리케이션 실행

또는 opentelemetry-instrument CLI나 Node.js의 --require 플래그를 사용하면 코드 변경 없이 애플리케이션을 자동 계측할 수 있습니다. CLI를 설치하면 자동 계측을 지원하는 라이브러리와 프레임워크를 더 폭넓게 사용할 수 있습니다.

NPX 사용

Managed ClickStack

Managed ClickStack에서는 HYPERDX_API_KEY를 생략할 수 있습니다.

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

사용자 지정 엔트리 포인트 (예: Nodemon, ts-node 등)

Managed ClickStack

Managed 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

코드 가져오기

// 애플리케이션에서 가장 먼저 로드되는 파일의 최상단에 이를 import하십시오
// 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 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