> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

# Next.js

export const ClickStackIntegrates = ({signals = []}) => {
  const list = Array.isArray(signals) ? signals : String(signals).split(",");
  const supported = list.map(s => String(s).trim().toLowerCase());
  const pillStyle = {
    display: "inline-flex",
    alignItems: "center",
    padding: "0.125rem 0.625rem",
    borderRadius: "9999px",
    fontSize: "0.8125rem",
    fontWeight: 500,
    lineHeight: 1.6,
    color: "#161517",
    backgroundColor: "#faff69",
    border: "1px solid rgba(0, 0, 0, .1)",
    marginRight: "0.5rem"
  };
  return <div style={{
    margin: "0 0 1.25rem"
  }}>
      <span style={{
    marginRight: "0.5rem"
  }}>이 가이드에서 통합하는 항목:</span>
      {supported.includes("logs") && <span style={pillStyle}>로그</span>}
      {supported.includes("metrics") && <span style={pillStyle}>메트릭</span>}
      {supported.includes("traces") && <span style={pillStyle}>트레이스</span>}
    </div>;
};

ClickStack은 Next 13.2+의
[Next.js 서버리스 함수](https://nextjs.org/docs/pages/building-your-application/optimizing/open-telemetry#manual-opentelemetry-configuration)에서
네이티브 OpenTelemetry 트레이스를 수집할 수 있습니다.

<ClickStackIntegrates signals={['logs', 'traces']} />

<Note>
  세션 리플레이 또는 브라우저 측 모니터링이 필요하다면, 대신 [브라우저 통합](/ko/clickstack/ingesting-data/sdks/browser)을 설치하세요.
</Note>

<h2 id="installing">
  설치하기
</h2>

<h3 id="enable-instrumentation-hook">
  instrumentation hook 활성화(v15 이하 필수)
</h3>

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

**예시:**

```javascript theme={null}
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;
```

<h3 id="install-sdk">
  ClickHouse OpenTelemetry SDK 설치하기
</h3>

<Tabs>
  <Tab title="NPM">
    ```shell theme={null}
    npm install @hyperdx/node-opentelemetry 
    ```
  </Tab>

  <Tab title="Yarn">
    ```shell theme={null}
    yarn add @hyperdx/node-opentelemetry 
    ```
  </Tab>
</Tabs>

<h3 id="create-instrumentation-files">
  instrumentation 파일 만들기
</h3>

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

```javascript theme={null}
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { init } = await import('@hyperdx/node-opentelemetry');
    init({
      apiKey: '<YOUR_INGESTION_API_KEY>', // optionally configure via `HYPERDX_API_KEY` env var
      service: '<YOUR_SERVICE_NAME>', // optionally configure via `OTEL_SERVICE_NAME` env var
      additionalInstrumentations: [], // optional, default: []
    });
  }
}
```

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

<h3 id="configure-environment-variables">
  환경 변수 구성
</h3>

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

<Tabs>
  <Tab title="Managed ClickStack">
    ```sh copy theme={null}
    OTEL_SERVICE_NAME=<YOUR_SERVICE_NAME> \
    OTEL_EXPORTER_OTLP_ENDPOINT=<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>
    npm run dev
    ```
  </Tab>

  <Tab title="ClickStack 오픈 소스">
    ```sh copy theme={null}
    HYPERDX_API_KEY=<YOUR_INGESTION_API_KEY> \
    OTEL_SERVICE_NAME=<YOUR_SERVICE_NAME> \
    OTEL_EXPORTER_OTLP_ENDPOINT=<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>
    npm run dev
    ```
  </Tab>
</Tabs>

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