Next.js

ClickStack용 Next.js SDK - ClickHouse 관측성 스택

ClickStack은 Next 13.2+의 Next.js 서버리스 함수에서 네이티브 OpenTelemetry 트레이스를 수집할 수 있습니다.

이 가이드에서는 다음을 통합합니다:

• 콘솔 로그
• 트레이스

세션 리플레이 또는 브라우저 측 모니터링이 필요하다면, 대신 브라우저 통합을 설치하세요.

​

설치하기

​

instrumentation hook 활성화(v15 이하 필수)

시작하려면 next.config.js에서 experimental.instrumentationHook = true;를 설정해 Next.js instrumentation hook을 활성화해야 합니다.

예시:

const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
  // otel 패키지 경고 무시
  // https://github.com/open-telemetry/opentelemetry-js/issues/4173#issuecomment-1822938936
  webpack: (
    config,
    { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack },
  ) => {
    if (isServer) {
      config.ignoreWarnings = [{ module: /opentelemetry/ }];
    }
    return config;
  },
};

module.exports = nextConfig;

​

ClickHouse OpenTelemetry SDK 설치하기

NPM

npm install @hyperdx/node-opentelemetry 

Yarn

yarn add @hyperdx/node-opentelemetry 

​

instrumentation 파일 만들기

Next.js 프로젝트 루트에 instrumentation.ts(또는 .js) 파일을 만들고, 아래 내용을 추가하십시오:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { init } = await import('@hyperdx/node-opentelemetry');
    init({
      apiKey: '<YOUR_INGESTION_API_KEY>', // `HYPERDX_API_KEY` 환경 변수로 설정 가능 (선택 사항)
      service: '<MY_SERVICE_NAME>', // `OTEL_SERVICE_NAME` 환경 변수로 설정 가능 (선택 사항)
      additionalInstrumentations: [], // 선택 사항, 기본값: []
    });
  }
}

이렇게 하면 Next.js가 서버리스 함수가 호출될 때마다 OpenTelemetry instrumentation을 불러올 수 있습니다.

​

환경 변수 구성

OpenTelemetry를 통해 트레이스를 ClickStack으로 직접 전송하는 경우, 스팬이 OTel collector로 전송되도록 다음 환경 변수를 설정하여 Next.js 서버를 시작해야 합니다:

Managed ClickStack

copy

OTEL_SERVICE_NAME=<MY_SERVICE_NAME> \
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-otel-collector:4318
npm run dev

ClickStack 오픈 소스

copy

HYPERDX_API_KEY=<YOUR_INGESTION_API_KEY> \
OTEL_SERVICE_NAME=<MY_SERVICE_NAME> \
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-otel-collector:4318
npm run dev

Vercel에 배포하는 경우, 위의 모든 환경 변수가 배포 환경에 맞게 구성되어 있는지 확인하세요.