dpdpdndn 블로그

FE-01-otel-instrumentation-bootstrap

NEW2 min read

[FE-01] web OTel 계측 부트스트랩 (instrumentation.ts + 설정)

작업 내용 (설계 의도)

변경 사항

근거: design-fe-web.md “시스템 역할 경계” · “계측 config 계약”. FR-10.

Next 서버 런타임에 OpenTelemetry를 등록하는 선행 부트스트랩. 세 파일이 인과적으로 결합돼 함께 있어야 계측이 로드되므로 한 티켓으로 묶는다.

  • package.json(수정): @vercel/otel·@opentelemetry/api 추가.
  • next.config.mjs(수정): experimental.instrumentationHook: true(Next 14.2 필요).
  • instrumentation.ts(신규, web 루트): registerOTel({ serviceName: OTEL_SERVICE_NAME|'sports-web', attributes: { 'deployment.environment': APP_ENV|'local' } }), OTLP endpoint = OTEL_EXPORTER_OTLP_ENDPOINT. 미설정 시 no-op(앱 정상 부팅).
  • lib/server/otel-resource.ts(신규): APP_ENV→deployment.environment 매핑·service.name 산출(단위 테스트 대상).

롤백: 의존성·instrumentation.ts revert(단일 PR). endpoint 언셋으로 즉시 no-op.

의존

  • 없음

다이어그램

클래스 의존

flowchart LR
    Config["next.config instrumentationHook"] --> Instr["instrumentation.ts"]
    Resource["otel-resource.ts"] --> Instr
    Instr -->|registerOTel| Runtime["Next 서버 런타임"]

테스트 케이스

  • @vercel/otel이 설치되고 빌드가 성공한다.
  • otel-resource가 APP_ENV=dev를 deployment.environment=dev로 매핑한다.
  • APP_ENV 미설정 시 local 기본값을 반환한다.
  • OTEL_EXPORTER_OTLP_ENDPOINT 미설정 시 register가 예외 없이 no-op으로 완료된다.
  • experimental.instrumentationHook가 next.config에 설정돼 있다.

그래프 뷰