@rlawncks125/otel-web

Nuxt 3/4에서 브라우저 OpenTelemetry SDK를 자동으로 설치하는 모듈입니다.

bun add @rlawncks125/otel-web

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@rlawncks125/otel-web'],
})

이 설정만으로 client plugin, Vue/Nuxt 오류 수집, $observability 타입이 등록됩니다. 운영에서는 인증 수집 게이트웨이 URL과 공개 수집 키를 함께 설정하세요.

개인정보 보호를 위해 히트맵 좌표 수집은 기본적으로 꺼져 있습니다. trace, metric, 오류 수집은 기본적으로 활성화됩니다. 히트맵이 필요할 때만 otelWeb.hitmap.use: true와 동의 저장 위치를 명시하세요.

환경별 값은 다음 환경변수로 설정할 수 있습니다.

NUXT_PUBLIC_OTEL_SERVICE_NAME=my-nuxt-web
NUXT_PUBLIC_OTEL_ENDPOINT=https://observe.example.com/api/ingest
NUXT_PUBLIC_OTEL_API_KEY=otel_pk_example
NUXT_PUBLIC_OTEL_TRACE_SAMPLE_RATE=1
NUXT_PUBLIC_APP_VERSION=1.0.0
NUXT_PUBLIC_APP_ENVIRONMENT=production

사용자 동의를 저장한 위치와 승인 값을 지정하면 값이 정확히 일치할 때만 SDK가 시작됩니다. 값이 없거나 거부 값이면 trace, metric, log, 히트맵 좌표를 전혀 보내지 않습니다.

export default defineNuxtConfig({
  modules: ['@rlawncks125/otel-web'],
  frontendObservability: {
    otlpEndpoint: 'https://observe.example.com/api/ingest',
    apiKey: 'otel_pk_public_ingest_key',
    consent: {
      storage: 'localStorage', // localStorage | sessionStorage | cookie
      key: 'analytics-consent',
      grantedValue: 'accepted',
    },
  },
})

같은 설정을 NUXT_PUBLIC_OTEL_CONSENT_STORAGE, NUXT_PUBLIC_OTEL_CONSENT_KEY, NUXT_PUBLIC_OTEL_CONSENT_GRANTED_VALUE 환경변수로도 지정할 수 있습니다. 브라우저 키는 비밀키가 아니므로 서버 게이트웨이에서 허용 Origin과 service.name도 함께 검증해야 합니다. 동의를 런타임에 바꾼 뒤에는 페이지를 다시 로드해 SDK를 초기화하세요.

otelWeb 그룹 설정

히트맵과 OTLP 설정을 나눠서 관리하려면 다음 형태를 사용할 수 있습니다.

export default defineNuxtConfig({
  modules: ['@rlawncks125/otel-web'],
  otelWeb: {
    hitmap: {
      use: true,
      storage: 'local',
      key: 'hitmap-approval',
      grantedValue: 'granted',
    },
    otel: {
      endpoint: 'https://observe.example.com/api/ingest',
      apiKey: 'otel_pk_public_ingest_key',
      serviceName: 'shop-web',
      traceSampleRate: 0.2,
    },
  },
})

• hitmap.use: false: 클릭·터치 좌표만 수집하지 않습니다. trace, metric, 오류 수집은 계속 동작합니다.
• hitmap.use: true와 storage/key: 저장된 값이 grantedValue와 일치해야 SDK가 시작됩니다.
• storage: local, session, cookie를 사용하며 localStorage, sessionStorage도 허용합니다.
• otel.endpoint: 공통 base URL이며 SDK가 /v1/traces, /v1/metrics, /v1/logs를 붙입니다.
• 신호별 주소가 다르면 otel.trace, otel.metric, otel.log에 /v1/...까지 포함된 전체 URL을 입력합니다. traces, metrics, logs 복수형도 같은 별칭으로 사용할 수 있습니다.

요청하신 철자를 그대로 사용할 수 있도록 hitmap을 지원하며, heatmap도 동일한 별칭으로 사용할 수 있습니다. 기존 frontendObservability 평면 설정은 하위 호환을 위해 계속 지원됩니다.

환경변수와 config 매핑

모든 환경변수 설정은 nuxt.config.ts에서도 설정할 수 있습니다. 둘 다 있으면 환경변수 → otelWeb → 기존 frontendObservability → 기본값 순서로 적용됩니다.

| 환경변수 | otelWeb 설정 | 설명 | | --- | --- | --- | | NUXT_PUBLIC_OTEL_ENABLED | enabled | 모듈 전체 활성화 (true/false) | | NUXT_PUBLIC_OTEL_SERVICE_NAME | otel.serviceName | OTel service.name | | NUXT_PUBLIC_OTEL_SERVICE_VERSION | otel.serviceVersion | 서비스 버전 | | NUXT_PUBLIC_APP_VERSION | otel.serviceVersion | 기존 버전 변수 별칭 | | NUXT_PUBLIC_OTEL_ENVIRONMENT | otel.environment | 배포 환경 | | NUXT_PUBLIC_APP_ENVIRONMENT | otel.environment | 기존 환경 변수 별칭 | | NUXT_PUBLIC_OTEL_ENDPOINT | otel.endpoint | 공통 OTLP base URL | | NUXT_PUBLIC_OTEL_TRACE_ENDPOINT | otel.trace | trace 전체 exporter URL | | NUXT_PUBLIC_OTEL_METRIC_ENDPOINT | otel.metric | metric 전체 exporter URL | | NUXT_PUBLIC_OTEL_LOG_ENDPOINT | otel.log | log 전체 exporter URL | | NUXT_PUBLIC_OTEL_API_KEY | otel.apiKey | 공개 수집 키 | | NUXT_PUBLIC_OTEL_TRACE_SAMPLE_RATE | otel.traceSampleRate | 0~1 trace sampling 비율 | | NUXT_PUBLIC_OTEL_METRIC_EXPORT_INTERVAL_MS | otel.metricExportIntervalMs | metric 전송 주기(ms) | | NUXT_PUBLIC_OTEL_PROPAGATE_TRACE_HEADERS_TO | otel.propagateTraceHeadersTo | 쉼표 구분 URL 목록 / 문자열 배열 | | NUXT_PUBLIC_OTEL_DEBUG | otel.debug | SDK 진단 로그 | | NUXT_PUBLIC_OTEL_HITMAP_USE | hitmap.use | 좌표 수집 활성화 | | NUXT_PUBLIC_OTEL_HEATMAP_USE | heatmap.use | 올바른 철자의 별칭 | | NUXT_PUBLIC_OTEL_CONSENT_STORAGE | hitmap.storage | local, session, cookie | | NUXT_PUBLIC_OTEL_CONSENT_KEY | hitmap.key | 동의 저장 키 | | NUXT_PUBLIC_OTEL_CONSENT_GRANTED_VALUE | hitmap.grantedValue | 승인으로 판단할 정확한 값 |

Boolean 환경변수에는 true/false, 1/0, yes/no, on/off를 사용할 수 있습니다. NUXT_PUBLIC_* 값과 공개 수집 키는 브라우저 번들에서 확인할 수 있으므로 비밀키를 넣으면 안 됩니다.

기본값은 otelWeb.enabled: true, hitmap.use: false, otel.traceSampleRate: 1, otel.metricExportIntervalMs: 15000, otel.debug: false입니다.

세부 설정이 필요한 경우에만 frontendObservability를 추가합니다.

export default defineNuxtConfig({
  modules: ['@rlawncks125/otel-web'],
  frontendObservability: {
    metricExportIntervalMs: 5_000,
    propagateTraceHeadersTo: ['https://api.example.com'],
  },
})