설치

Sophonz Browser SDK를 CDN 또는 NPM으로 웹 프론트엔드 프로젝트에 설치하는 방법을 안내합니다.

Sophonz Browser SDK는 OpenTelemetry Native 기반으로 동작합니다. VanillaJS, React, Vue, Next.js 등 웹 프론트엔드 프레임워크에서 웹 성능 지표를 수집하기 위한 에이전트 설치 및 설정 방법을 설명합니다.

프론트엔드 모니터링

웹 프론트엔드 성능 모니터링은 사용자 경험을 개선하고 웹 애플리케이션의 성능을 최적화하는 데 중요한 역할을 합니다. Sophonz를 사용하면 표준화된 방식으로 성능 데이터를 수집하고 분석할 수 있습니다.

수집된 데이터를 바탕으로 다음과 같은 최적화를 수행할 수 있습니다:

느린 API 호출 식별 및 최적화
클라이언트 사이드 렌더링 성능 개선
자주 발생하는 오류 해결

주요 기능

네트워크 요청 자동 계측

XMLHttpRequest 및 Fetch API: 네트워크 요청 및 응답의 상세 추적
WebSocket (beta): 실시간 양방향 통신 계측
요청/응답 메타데이터: HTTP 메서드, 상태 코드, 헤더, 타이밍 정보 자동 수집

페이지 로드 성능 추적

Document Load (@sophonz/instrumentation-document-load)
- Navigation Timing API를 통한 초기 페이지 로드 성능 측정
- Server-Timing 헤더 파싱 및 백엔드 타이밍 정보 수집
- TraceParent 추출을 통한 분산 추적 지원
- 리소스 타이밍 정보 수집 (이미지, 스크립트, 스타일시트 등)
Post Document Load (@sophonz/instrumentation-post-doc-load-resource)
- Performance Observer를 통한 동적 리소스 추적
- Mutation Observer를 통한 <head> 변경 감지
- SPA 라우트 전환 후 로드되는 리소스 자동 계측
- URL-to-Context 매핑을 통한 컨텍스트 보존

사용자 상호작용 및 이벤트

User Interaction: 클릭, 마우스 이벤트, 드래그, 키보드 입력 등 자동 추적
User Event (@sophonz/user-event)
- 비즈니스 로직의 시작과 완료 지점을 명시적으로 추적
- OpenTelemetry 컨텍스트 전파를 통한 자동 그룹화
- 이벤트 중 발생하는 모든 계측(fetch, console, exception 등)을 단일 트레이스로 연결
- 저장소를 통한 이벤트 지속성 (페이지 새로고침 지원)

SPA (Single Page Application) 지원

Route Change (@sophonz/instrumentation-route)
- History API 기반 클라이언트 사이드 라우팅 자동 추적
- pushState, replaceState, popstate, hashchange 이벤트 감지
- React Router, Vue Router, Angular Router, Next.js 등 모든 라우팅 라이브러리 호환
- 라우트 전환 시 발생하는 리소스 로딩 자동 연결
- 사용자 이벤트와의 자동 컨텍스트 연결

에러 및 예외 추적

Browser Exception (@sophonz/instrumentation-browser-exception)
- Uncaught exceptions 자동 수집
- Unhandled promise rejections 추적
- Document error events (이미지/스크립트 로드 실패 등)
- console.error() 패칭 및 스택 트레이스 수집
- 에러 발생 시 활성 컨텍스트 자동 보존
- Span/Log 상관관계 (span.id, trace.id)를 통한 추적

성능 모니터링

Web Vitals: LCP, FID, CLS, FCP, TTFB 자동 수집
Long Tasks: 자동 컨텍스트 연결을 통한 브라우저 메인 스레드 블로킹 감지
세션 분석: 세션 ID를 통한 사용자 행동 패턴 분석

컨텍스트 관리

자동 컨텍스트 유지: Timer, Promise, async/await, 이벤트, Observer 등에서 자동 컨텍스트 전파
SophonzContextManager: OpenTelemetry Context API를 확장한 고급 컨텍스트 관리
분산 추적: 프론트엔드와 백엔드 간 TraceParent 전파

페이지 상태 추적

Visibility: 페이지 가시성 변경 자동 계측
Connectivity: 네트워크 연결 상태 변경 자동 계측

사용자 정의 및 확장

커스텀 속성: 사용자 ID, 지역, 비즈니스 메타데이터 추가
수동 계측: 커스텀 로그, 커스텀 에러, 사용자 이벤트 수동 추적
세션 리플레이 (beta): DOM 변경, 사용자 입력, 스크린샷 캡처

크로스 플랫폼 지원

Mobile SDK 연동: Sophonz Android/iOS SDK와 연동하여 네이티브-웹뷰 컨텍스트 자동 연결
레거시 브라우저: IE11, Chrome 52, Edge Legacy 79, Safari 11, Firefox 57 이상 지원

빠른 설치

CDN을 통한 설치

웹사이트에서 Sophonz로 계측을 시작하는 가장 쉬운 방법은 아래 코드를 <head></head> 태그 내부에 추가하는 방법입니다.

특정 버전

특정 버전을 사용하기 위한 설치 코드는 아래와 같습니다. {{VERSION}} 부분을 사용하려는 버전으로 대체하세요.

<script
  src="https://cdn.sophonz.com/release/npm/@browser-sdk/{{VERSION}}/index.js"
  integrity="{{VERSION_SRI_HASH_INTEGRITY}}"
  crossorigin="anonymous">
</script>
<script>
    window.SophonzSDK.init({
      collectorUrl: '{{SOPHONZ_TRACES_COLLECTOR_URL}}',
      appName: '{{NAME_OF_YOUR_WEB_SERVICE}}',
      appVersion: '{{VERSION_OF_YOUR_WEB_SERVICE}}',
      appKey: '{{KEY_OF_YOUR_WEB_SERVICE}}'
      project: '{{SERVICE_NAMESPACE}}',
      deploymentEnvironment: '{{DEPLOYMENT_ENVIRONMENT}}',
    });
</script>

collectorUrl, appName, appKey, appVersion을 올바르게 제공하면 웹사이트가 준비되며 다른 필수 작업은 필요하지 않습니다. 수집된 추적 정보를 지정된 Sophonz 수집기로 전송합니다.

NPM을 통한 설치

https://www.npmjs.com/package/@sophonz/browser-sdk

NPM Last Update NPM Unpacked Size npm bundle size NPM Downloads NPM Type Definitions

다른 옵션은 프로젝트 내에서 이 라이브러리를 번들로 묶고 초기화하는 것입니다. 프로젝트 디렉토리 내에서 npm install @sophonz/browser-sdk를 실행하세요.

에이전트는 다른 기능보다 우선적으로 초기화되어야 관련 정보들을 수집할 수 있습니다.

import SophonzSDK from '@sophonz/browser-sdk';
 
SophonzSDK.init({
  collectorUrl: '{{SOPHONZ_TRACES_COLLECTOR_URL}}',
  appName: '{{NAME_OF_YOUR_WEB_SERVICE}}',
  appVersion: '{{VERSION_OF_YOUR_WEB_SERVICE}}',
  appKey: '{{KEY_OF_YOUR_WEB_SERVICE}}',
  project: '{{SERVICE_NAMESPACE}}',
  deploymentEnvironment: '{{DEPLOYMENT_ENVIRONMENT}}',
});