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', // Managed ClickStack의 경우 생략
    service: 'my-service'
});

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
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으로 설정하거나 init 함수에 consoleCapture: false를 전달하여 이 기능을 비활성화할 수 있습니다.

오류 수집 설정

ClickStack SDK는 전체 스택 트레이스와 코드 컨텍스트를 포함해 애플리케이션에서 처리되지 않은 예외와 오류를 자동으로 기록할 수 있습니다. 이를 활성화하려면 애플리케이션의 오류 처리 미들웨어 끝부분에 다음 코드를 추가하거나, recordException 함수를 사용해 예외를 수동으로 기록해야 합니다.

Express
Koa
수동

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

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)합니다:

다른 설치 방법

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

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

NPX 사용
사용자 지정 엔트리 포인트 (예: Nodemon, ts-node 등)
코드 가져오기

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

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

Managed ClickStackManaged 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에서 발생하는 예외를 자동으로 수집하거나 예외를 수동으로 처리하려면 위의 오류 수집 설정 섹션의 안내를 따르십시오.

자동 계측 라이브러리

다음 라이브러리는 위 설치 방법을 통해 자동으로 계측되어 추적됩니다:

​시작하기

​HyperDX OpenTelemetry 계측 패키지 설치

​SDK 초기화

​로그 수집 설정

​오류 수집 설정

​문제 해결

​고급 계측 구성

​콘솔 로그 수집

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

​Google Cloud Run

​자동 계측 라이브러리

​다른 설치 방법

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

​예외 캡처 활성화

​자동 계측 라이브러리

시작하기

HyperDX OpenTelemetry 계측 패키지 설치

SDK 초기화

로그 수집 설정

오류 수집 설정

문제 해결

고급 계측 구성

콘솔 로그 수집

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

Google Cloud Run

자동 계측 라이브러리

다른 설치 방법

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

예외 캡처 활성화

자동 계측 라이브러리