🔍 Next.js에서 OpenTelemetry로 관측성(Observability) 구축하기

 

🔍 Next.js에서 OpenTelemetry로 관측성(Observability) 구축하기

Next.js는 기본적으로 SSR과 동적 기능을 지원하기 때문에 복잡한 서비스 구조에서 성능 추적과 오류 진단이 필수입니다. 이때 표준화된 오픈소스인 OpenTelemetry를 활용하면 로그, 메트릭, 트레이스를 통합적으로 수집하고 시각화할 수 있습니다.

---

✅ OpenTelemetry란?

OpenTelemetry(OTel)는 다음 세 가지를 하나로 추적할 수 있는 표준 프레임워크입니다.

• 📈 메트릭 (Metrics)
• 🔍 트레이스 (Traces)
• 🪵 로그 (Logs)

서버와 클라이언트의 경계를 넘나드는 요청 흐름을 추적할 수 있어 성능 병목과 오류 발생 지점을 빠르게 파악할 수 있습니다.

---

✅ 기본 설정 방법 (@vercel/otel 사용)

1. 패키지 설치

npm install @vercel/otel

2. 루트 디렉토리에 instrumentation.ts 생성

import { registerOTel } from '@vercel/otel';

export function register() {
  registerOTel({ serviceName: 'next-app' });
}

3. next.config.js 설정

module.exports = {
  experimental: {
    instrumentationHook: true,
  },
};

instrumentation.ts는 반드시 루트에 있어야 하고, Next.js 14+ 이상부터 지원됩니다.

---

✅ 고급 설정 (수동 설정)

더 세부적인 트레이싱이나 외부 수집 서버 연동이 필요할 경우 수동 설정이 필요합니다.

설치

npm install @opentelemetry/sdk-node \
             @opentelemetry/exporter-trace-otlp-http \
             @opentelemetry/resources \
             @opentelemetry/semantic-conventions

설정 예시

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';

export function register() {
  const sdk = new NodeSDK({
    resource: new Resource({
      [SemanticResourceAttributes.SERVICE_NAME]: 'next-app',
    }),
    traceExporter: new OTLPTraceExporter({
      url: 'http://localhost:4318/v1/traces',
    }),
  });

  sdk.start();
}

---

✅ 주요 스팬 목록

반응형

Next.js에서 기본적으로 생성되는 스팬 예시는 다음과 같습니다:

• render route (app) /about
• fetch GET https://api.example.com
• getServerSideProps /dashboard
• executing api route /api/user

---

✅ 사용자 정의 스팬 추가

import { trace } from '@opentelemetry/api';

export default async function handler(req, res) {
  const tracer = trace.getTracer('custom');
  const span = tracer.startSpan('fetch-user-data');

  try {
    await fetchUser();
    res.status(200).json({ ok: true });
  } catch (e) {
    span.recordException(e);
    res.status(500).json({ error: 'fail' });
  } finally {
    span.end();
  }
}

---

✅ 자동 계측

자동으로 fetch, fs, http 등 주요 라이브러리를 계측하려면 다음 설정을 추가합니다.

npm install @opentelemetry/auto-instrumentations-node

import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  instrumentations: [getNodeAutoInstrumentations()],
});

---

✅ Vercel 환경에서의 활용

• @vercel/otel 사용 시, Vercel 플랫폼에서 손쉽게 활성화 가능
• NEXT_OTEL_VERBOSE=1 환경 변수로 디버깅 로그 활성화 가능

---

✅ 요약

항목 간편 설정 (@vercel/otel) 수동 설정

설정 난이도	매우 쉬움	다소 복잡
Edge 지원 여부	O	X
세부 제어 가능성	제한적	매우 높음
자동 계측	기본 제공	직접 설정 필요
배포 플랫폼	Vercel 최적화	어디서든 사용 가능

---

 

Next.js, OpenTelemetry, Observability, 메트릭, 트레이스, 서비스 모니터링, 로그 분석, 성능 최적화, Vercel, Full Stack Observability

---