@rlawncks125/otel-web-core

브라우저 OpenTelemetry trace·metric·error log, 자체 오류 추적과 UX 세션 이벤트를 한 번에 초기화하는 SDK입니다. 외부 오류 추적 서비스 없이 session.id로 페이지 이동·클릭·폼 활동·오류를 연결하며 DOM 텍스트와 입력값은 수집하지 않습니다.

import { frontendObservabilityOptionsFromEnv, initFrontendObservability } from '@rlawncks125/otel-web-core'

export const observability = initFrontendObservability({
  serviceName: 'shop-web',
  serviceVersion: '1.4.0',
  environment: 'production',
  otlpEndpoint: 'https://otel.example.com',
  apiKey: 'otel_pk_public_ingest_key',
  traceSampleRate: 0.2,
  propagateTraceHeadersTo: [/^https:\/\/api\.example\.com/],
  privacy: {
    elementNameAttribute: 'data-observe-name',
    captureInteractionCoordinates: true,
    captureFormInteractions: true,
  },
  consent: {
    storage: 'localStorage',
    key: 'analytics-consent',
    grantedValue: 'accepted',
  },
})

환경변수 기반 앱은 helper를 사용할 수 있습니다. OTEL_*뿐 아니라 Vite의 VITE_OTEL_*, PUBLIC_OTEL_*, NEXT_PUBLIC_OTEL_* 접두사를 인식합니다.

const observability = initFrontendObservability(
  frontendObservabilityOptionsFromEnv(import.meta.env),
)

지원 값은 OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION, OTEL_ENVIRONMENT, OTEL_ENDPOINT, OTEL_TRACE_ENDPOINT, OTEL_METRIC_ENDPOINT, OTEL_LOG_ENDPOINT, OTEL_API_KEY, OTEL_TRACE_SAMPLE_RATE, OTEL_CONSENT_STORAGE, OTEL_CONSENT_KEY, OTEL_CONSENT_GRANTED_VALUE입니다. 신호별 endpoint는 /v1/traces 같은 전체 URL입니다. 동의 값이 없거나 일치하지 않으면 enabled: false인 no-op handle을 반환하고 네트워크 exporter나 이벤트 listener를 만들지 않습니다. 동의 후 다시 초기화할 수 있습니다.

브라우저에 들어가는 apiKey는 사용자에게 보이는 공개 수집 키입니다. 이것만으로 신뢰하지 말고 수집 게이트웨이에서 정확한 Origin과 허용 service.name, 요청 크기, rate limit을 함께 검사하세요.

Nuxt에서는 직접 초기화하는 대신 @rlawncks125/otel-web을 modules에 추가하면 client-only 초기화와 타입 등록이 자동 처리됩니다. 의미 있는 UI 이름은 텍스트 대신 data-observe-name="checkout" attribute로 지정하고, 제외할 영역은 data-observe-ignore를 사용합니다.

captureInteractionCoordinates는 클릭/터치의 화면·문서 좌표를 0–1 비율과 뷰포트 크기로 기록합니다. data-observe-name이 있는 요소에서는 요소 사각형 안의 상대 좌표(ui.target.offset_x_ratio, ui.target.offset_y_ratio)도 함께 기록하므로, 서로 다른 화면 너비에서 발생한 이벤트를 기준 스크린샷의 같은 요소 위에 투영할 수 있습니다. DOM 텍스트, 입력값, query string은 좌표 span에 포함하지 않습니다. 좌표 수집이 불필요한 앱은 이 값을 false로 설정하세요.

좌표 수집 기본값은 false입니다. 히트맵을 사용할 때만 privacy.captureInteractionCoordinates: true와 동의 설정을 명시하세요.

click(키보드 활성화 포함), 디바운스된 input, change, submit을 자동 수집합니다. 폼 이벤트에는 필드 값이나 DOM 텍스트가 포함되지 않으며 password/contenteditable 영역은 기본 제외됩니다.

처리되지 않은 error와 unhandledrejection은 자동 수집됩니다. 직접 처리한 예외도 observability.captureException(error)로 보내면 browser.unhandled_error span과 Loki용 OTLP error log, 예외 stack, 자체 event ID가 생성됩니다. 같은 브라우저 탭의 navigation/interaction/error 신호에는 session.id와 session.sequence가 붙어 오류 직전 행동 흐름을 재구성할 수 있습니다.

Nuxt의 렌더링/라이프사이클 오류까지 포함하려면 client plugin에서 vue:error와 app:error hook을 captureException에 연결하세요. 저장소의 Nuxt 예제에는 이 연결이 포함되어 있습니다.