계측

Browser SDK가 내장한 14개 계측이 각각 무엇을 수집하고 어떤 스팬을 만드는지, Web Vitals가 내보내는 속성, 그리고 활성화·비활성화 방법을 정리합니다.

Browser SDK는 14개의 계측을 내장합니다. 각 계측은 브라우저 API 하나를 감싸고, 스팬에 고유한 app.span.type 값을 붙입니다. 대시보드와 세션 타임라인은 이 값으로 데이터를 분류하므로, 어떤 계측이 어떤 타입을 사용하는지가 곧 쿼리 기준이 됩니다.

기본 상태

공통 속성

socketio의 send 스팬과 userJourney를 제외한 모든 계측이 스팬에 다음을 붙입니다.

앱과 브라우저를 식별하는 값(service.name, service.version, sophonz.browser.name, os.name 등)은 스팬이 아니라 리소스 속성으로 한 번만 실립니다.

네트워크

fetch

window.fetch 호출을 가로채 클라이언트 스팬을 만듭니다. 스팬 이름은 HTTP GET처럼 메서드를 따릅니다.

응답 상태와 크기, 요청 URL(url.full, http.url)을 기록하고, tracePropagationTargets에 해당하는 요청에는 traceparent 헤더를 주입해 백엔드 트레이스와 연결합니다. 응답에 Server-Timing: traceparent가 있으면 서버 스팬 ID를 link.spanId로 함께 남깁니다.

advancedNetworkCapture를 활성화하면 요청·응답 헤더와 본문도 담습니다.

(boolean 또는 SophonzFetchInstrumentationConfig, 선택)

Fetch API 계측을 활성화하거나 비활성화합니다. true로 설정하면 Fetch 요청이 자동으로 계측됩니다. SophonzFetchInstrumentationConfig을 제공하여 Fetch 계측의 세부 설정을 조정할 수 있습니다.

자세한 계측 정보는 @sophonz/instrumentation-fetch 참조

type SophonzFetchInstrumentationConfig = {
  advancedNetworkCapture?: () => boolean;
  clearTimingResources?: boolean;
  propagateTraceHeaderCorsUrls?: web.PropagateTraceHeaderCorsUrls;
  ignoreUrls?: Array<string | RegExp>;
  applyCustomAttributesOnSpan?: FetchCustomAttributeFunction;
  ignoreNetworkEvents?: boolean;
  measureRequestSize?: boolean;
}

• advancedNetworkCapture: 고급 네트워크 캡처를 활성화합니다. 기본값은 false입니다.
• clearTimingResources: 타이밍 리소스를 초기화합니다. 기본값은 false입니다.
• propagateTraceHeaderCorsUrls: CORS 요청에 Trace Header를 전파할 URL 목록을 지정합니다.
• ignoreUrls: 계측하지 않을 URL 패턴을 지정합니다. 정규식이나 문자열 배열로 설정할 수 있습니다.
• applyCustomAttributesOnSpan: Span에 사용자 정의 속성을 추가하는 함수입니다. 기본값은 undefined입니다.
• ignoreNetworkEvents: 네트워크 이벤트를 무시합니다. 기본값은 false입니다.
• measureRequestSize: 요청 크기를 측정합니다. 기본값은 false입니다.

xhr

XMLHttpRequest를 같은 방식으로 감쌉니다. 스팬 이름과 속성, 전파 규칙은 fetch와 동일하고 app.span.type만 xhr입니다. jQuery나 axios처럼 XHR을 사용하는 라이브러리는 별도 설정 없이 여기에 잡힙니다.

(boolean 또는 SophonzXMLHttpRequestInstrumentationConfig, 선택)

XMLHttpRequest 계측을 활성화하거나 비활성화합니다. true로 설정하면 XMLHttpRequest 요청이 자동으로 계측됩니다.

자세한 계측 정보는 @sophonz/instrumentation-xml-http-request 참조

interface XMLHttpRequestInstrumentationConfig extends InstrumentationConfig {
    clearTimingResources?: boolean;
    propagateTraceHeaderCorsUrls?: PropagateTraceHeaderCorsUrls;
    ignoreUrls?: Array<string | RegExp>;
    applyCustomAttributesOnSpan?: XHRCustomAttributeFunction;
    ignoreNetworkEvents?: boolean;
    measureRequestSize?: boolean;
    advancedNetworkCapture?: () => boolean;
}

• clearTimingResources: 타이밍 리소스를 초기화합니다. 기본값은 false입니다.
• propagateTraceHeaderCorsUrls: CORS 요청에 Trace Header를 전파할 URL 목록을 지정합니다.
• ignoreUrls: 계측하지 않을 URL 패턴을 지정합니다.
• applyCustomAttributesOnSpan: Span에 사용자 정의 속성을 추가하는 함수입니다. 기본값은 undefined입니다.
• ignoreNetworkEvents: 네트워크 이벤트를 무시합니다. 기본값은 false입니다.
• measureRequestSize: 요청 크기를 측정합니다. 기본값은 false입니다.
• advancedNetworkCapture: 고급 네트워크 캡처를 활성화합니다. 기본값은 false입니다.

websocket

기본값은 비활성화입니다. websocket으로 활성화하면 connect 스팬을 만들고, 이후 메시지 송수신과 오류를 스팬 이벤트로 남깁니다.

(boolean 또는 SophonzWebSocketInstrumentationConfig, 선택)

WebSocket 계측을 활성화하거나 비활성화합니다. true로 설정하면 WebSocket 연결 이벤트가 자동으로 계측됩니다.

interface SophonzWebSocketInstrumentationConfig extends InstrumentationConfig {
  ignoreUrls?: (string | RegExp)[];
}

• ignoreUrls: 계측하지 않을 URL 패턴을 지정합니다.

socketio

기본값은 비활성화입니다. socketio로 활성화하면 Socket.IO 클라이언트의 connect, disconnect, emit 등을 추적합니다. send 스팬에는 화면·세션 속성이 붙지 않습니다.

(boolean 또는 SocketIoClientInstrumentationConfig, 선택)

Socket.io 클라이언트 계측을 활성화하거나 비활성화합니다. true로 설정하면 Socket.io 클라이언트의 이벤트가 자동으로 계측됩니다.

interface SocketIoClientInstrumentationConfig
  extends InstrumentationConfig {
  target?: string | SocketIOClient;
}

• target: Socket.io 클라이언트의 타겟 객체를 지정합니다. 기본값은 undefined입니다.

페이지 수명주기

document

최초 문서 로드를 documentLoad, documentFetch, resourceFetch 스팬으로 기록합니다. DNS·연결·TTFB 같은 내비게이션 타이밍이 스팬 이벤트로 들어가고, First Paint와 First Contentful Paint도 여기에 실립니다.

resourceFetch는 문서가 불러온 하위 리소스 하나마다 하나씩 생기며, url.full은 그 리소스의 주소입니다.

(boolean 또는 SophonzDocLoadInstrumentationConfig, 선택)

문서 로드 계측을 활성화하거나 비활성화합니다. true로 설정하면 문서 로드 이벤트가 계측됩니다. SophonzDocLoadInstrumentationConfig을 제공하여 계측의 세부 설정을 조정할 수 있습니다.

interface SophonzDocLoadInstrumentationConfig
  extends InstrumentationConfig {
  ignoreUrls?: (string | RegExp)[];
}

• ignoreUrls: 계측하지 않을 URL 패턴을 지정합니다. 정규식이나 문자열 배열로 설정할 수 있으며, 부분 일치 또는 정확히 일치하는 URL은 계측되지 않습니다.

자세한 계측 정보는 @sophonz/instrumentation-document-load 참조

postload

문서 로드가 끝난 뒤 발생하는 리소스 요청을 추적합니다. 지연 로딩되는 이미지나 코드 스플리팅된 청크처럼 초기 로드에 포함되지 않는 것들이 대상입니다.

(boolean 또는 SophonzPostDocLoadResourceInstrumentationConfig, 선택)

문서 로드 후 리소스 계측을 활성화하거나 비활성화합니다. true로 설정하면 문서가 완전히 로드된 후 리소스 로딩 이벤트가 자동으로 계측됩니다. 이 계측은 SPA 형태의 웹에서 컴포넌트 단위의 리소스 계측에 유용합니다.

@sophonz/instrumentation-post-document-load 문서 참조

interface SophonzPostDocLoadResourceInstrumentationConfig
  extends InstrumentationConfig {
  allowedInitiatorTypes?: string[];
  ignoreUrls?: (string | RegExp)[];
}

• allowedInitiatorTypes: 계측할 요청의 이니시에이터 타입을 지정합니다. 기본값은 ["script", "link"]입니다.
• ignoreUrls: 계측하지 않을 URL 패턴을 지정합니다.

visibility

visibilitychange 이벤트를 받아 탭이 보이거나 숨겨진 구간을 스팬으로 남깁니다. 사용자가 실제로 화면을 보고 있던 시간을 재는 근거가 됩니다.

(boolean 또는 InstrumentationConfig, 선택)

페이지 가시성 계측을 활성화하거나 비활성화합니다. true로 설정하면 페이지의 가시성 상태(포그라운드/백그라운드 변화)가 자동으로 계측됩니다.

자세한 계측 정보는 @sophonz/instrumentation-visibility 참조

export interface InstrumentationConfig {
    enabled?: boolean;
}

connectivity

online/offline 이벤트로 네트워크 연결 상태 변화를 기록합니다. 오프라인 구간에서 발생한 오류를 해석할 때 쓰입니다.

(boolean 또는 InstrumentationConfig, 선택)

네트워크 연결 상태 계측을 활성화하거나 비활성화합니다. true로 설정하면 네트워크 상태(온라인/오프라인 변화)가 자동으로 계측됩니다.

자세한 계측 정보는 @sophonz/instrumentation-connectivity 참조

export interface InstrumentationConfig {
    enabled?: boolean;
}

longtask

메인 스레드를 50ms 이상 붙잡은 작업을 longtask 스팬으로 남깁니다. 입력 지연의 원인을 좁힐 때 쓰며, longtask.name과 longtask.duration을 함께 기록합니다.

(boolean 또는 InstrumentationConfig, 선택)

브라우저 장시간 작업 계측을 활성화하거나 비활성화합니다. true로 설정하면 긴 시간 동안 실행되는 작업이 자동으로 계측됩니다.

자세한 계측 정보는 @sophonz/instrumentation-browser-longtask 참조

export interface InstrumentationConfig {
    enabled?: boolean;
}

• enabled: 계측을 활성화할지 여부를 설정합니다. 기본값은 true입니다.

상호작용

interactions

클릭·제출 같은 사용자 이벤트를 event 타입으로, 라우트 변경을 route 타입 (routeChange 스팬)으로 남깁니다. 이벤트 스팬에는 대상 요소의 텍스트·태그·ID·클래스가 target_element_* 속성으로 들어갑니다.

instrumentations로 세부 설정이 가능한 유일한 계측입니다.

SophonzSDK.init({
  // ...
  instrumentations: {
    interactions: { events: { click: true, submit: false } },
  },
});

(boolean 또는 SophonzUserInteractionInstrumentationConfig, 선택)

사용자 상호작용 계측을 활성화하거나 비활성화합니다. true로 설정하면 클릭, 입력 등 사용자 상호작용 이벤트가 자동으로 계측됩니다. SophonzUserInteractionInstrumentationConfig을 통해 상호작용 계측의 세부 설정을 커스터마이즈할 수 있습니다.

자세한 계측 정보는 @sophonz/instrumentation-user-interaction 참조

interface SophonzUserInteractionInstrumentationConfig extends InstrumentationConfig {
    eventNames?: EventName[];
    shouldPreventSpanCreation?: ShouldPreventSpanCreation;
    events?: UserInteractionEventsConfig;
    captureText?: boolean;
    captureId?: boolean;
}

• eventNames: 계측할 이벤트 목록을 지정합니다. 기본값은 DEFAULT_AUTO_INSTRUMENTED_EVENTS입니다.
  • 포인터 이벤트: click, dblclick, mousedown, mouseup
  • Form 이벤트: submit, reset, change
  • Drag & Drop: dragend, drop
  • 미디어 이벤트: ended, pause, play
• shouldPreventSpanCreation: Span이 생성될 때 호출되는 콜백 함수입니다. true를 반환하면 Span 기록을 방지합니다.
• events: 사용자 상호작용 이벤트를 설정합니다. UserInteractionEventsConfig 인터페이스를 사용하여 세부 설정을 지정할 수 있습니다.
• captureText: (boolean, 기본값: true) false로 설정하면 모든 이벤트 span attribute에서 target_element_text 값을 포함하지 않으며, Operation Name 폴백에서 innerText를 제외합니다.
• captureId: (boolean, 기본값: true) false로 설정하면 모든 이벤트 span attribute에서 target_element_id 값을 포함하지 않으며, Operation Name 폴백에서 id를 제외합니다.

type UserInteractionEventsConfig = {
  [type: string]: boolean;
};
const DEFAULT_AUTO_INSTRUMENTED_EVENTS: UserInteractionEventsConfig = {
  // pointer
  click: true,
  dblclick: true,
  mousedown: true,
  mouseup: true,
 
  // form
  submit: true,
  reset: true,
  change: true,
 
  // drag & drop
  dragend: true,
  drop: true,
 
  // media
  ended: true,
  pause: true,
  play: true,
};

Ignore 설정

특정 요소를 계측 대상에서 제외하려면 HTML 요소에 data-sophonz="ignore" 속성을 추가합니다. 해당 요소에서 발생하는 이벤트는 span과 trace가 생성되지 않습니다.

<button data-sophonz="ignore">민감한 버튼</button>
<input data-sophonz="ignore" type="text" placeholder="개인정보 입력" />

Operation Name 폴백 로직

사용자 상호작용 이벤트의 Operation Name은 다음 우선순위로 결정됩니다:

설정 예시

SophonzSDK.init({
  collectorUrl: 'https://in.sophonz.ai',
  appName: 'my-frontend-app',
  appVersion: '1.0.0',
  appKey: '<YOUR_APP_KEY_HERE>',
  instrumentations: {
    interactions: {
      captureText: true,   // innerText 수집 여부 (기본값: true)
      captureId: true,     // id 수집 여부 (기본값: true)
      events: {
        click: true,
        dblclick: true,
        submit: true,
        change: true,
        mousedown: false,  // 비활성화
        mouseup: false,    // 비활성화
      }
    }
  }
});

userJourney

기본값은 비활성화입니다. userJourney로 활성화하면 사용자의 화면 이동 경로를 이어 붙여 기록합니다. 고유한 app.span.type을 쓰지 않고, 공통 화면·세션 속성도 붙지 않습니다.

오류와 로그

errors

처리되지 않은 예외와 거부된 Promise를 error 타입 스팬으로 남깁니다. 스택 트레이스가 함께 실리며, 소스맵을 업로드해 두면 대시보드에서 원본 위치로 복원됩니다.

(boolean 또는 SophonzErrorInstrumentationConfig, 선택)

브라우저에서 발생하는 오류 계측을 활성화하거나 비활성화합니다. true로 설정하면 전역 오류 핸들러가 활성화되어 애플리케이션에서 발생하는 오류가 자동으로 계측됩니다. SophonzErrorInstrumentationConfig 객체를 제공하여 오류 계측의 세부 설정을 커스터마이즈할 수 있습니다.

interface SophonzErrorInstrumentationConfig extends InstrumentationConfig {
  /**
   * Whether to capture console.error calls as exceptions.
   * @default true
   */
  captureConsoleError?: boolean;
  /**
   * A callback function for adding custom attributes to the span/log when an error is recorded.
   * @param error - The error object or string that is being recorded.
   * @returns Attributes to add to the span and log.
   */
  applyCustomAttributes?: (error: Error | string | Event) => Attributes;
}

• captureConsoleError: console.error 호출을 exception으로 캡처할지 여부를 설정합니다. 기본값은 true입니다.
  • true (기본값): console.error 호출이 exception으로 캡처됨
  • false: console.error 계측이 비활성화되어 exception으로 캡처되지 않음
• applyCustomAttributes: 에러가 기록될 때 span/log에 커스텀 속성을 추가하는 콜백 함수입니다. 에러 객체를 인자로 받아 추가할 속성 객체를 반환합니다.

applyCustomAttributes 사용 예시:

SophonzSDK.init({
  // ... 기본 설정
  instrumentations: {
    errors: {
      applyCustomAttributes: (error) => {
        if (error instanceof Error) {
          return {
            'error.category': error.name === 'TypeError' ? 'type-error' : 'general',
            'error.component': 'frontend',
          };
        }
        return {};
      },
    },
  },
});

자세한 계측 정보는 @sophonz/instrumentation-browser-exception 참조

console

기본값은 비활성화입니다. consoleCapture로 활성화하면 console.debug/info/warn/error 호출을 log 타입으로 수집합니다. 콘솔 인자가 그대로 전송되므로 민감한 값을 찍는 코드가 있다면 데이터 편집 설정을 함께 확인하세요.

(boolean 또는 SophonzConsoleInstrumentationConfig, 선택)

콘솔 계측을 활성화하거나 비활성화합니다. true로 설정하면 기본 콘솔 계측이 활성화됩니다. SophonzConsoleInstrumentationConfig 객체를 제공하여 콘솔 계측의 세부 설정을 커스터마이즈할 수 있습니다.

interface SophonzConsoleInstrumentationConfig
  extends InstrumentationConfig {
  betaMode: boolean;
  loggerOptions: LoggerOptions;
  contextManager?: MutableAsyncLocalStorageContextManager;
}

• betaMode: 콘솔 계측의 베타 모드를 활성화합니다. 기본값은 false입니다.
• loggerOptions: 콘솔 계측의 로거 옵션을 설정합니다. LoggerOptions 인터페이스를 사용하여 세부 설정을 지정할 수 있습니다.
• contextManager: MutableAsyncLocalStorageContextManager를 사용하여 비동기 컨텍스트를 관리합니다. AsyncHooksContextManager 참조

Web Vitals

webvitals

LCP, CLS, INP, FCP, TTFB를 webvitals 타입으로 수집하고, Google의 Core Web Vitals를 OpenTelemetry browser.web_vital 시맨틱 컨벤션으로 내보냅니다.

(boolean 또는 InstrumentationConfig, 선택)

Web Vitals 계측을 활성화하거나 비활성화합니다. 기본값은 켜짐이고, 최상위 webVitals 옵션으로도 끌 수 있습니다.

interface InstrumentationConfig {
  enabled?: boolean;
}

• enabled: 계측을 활성화할지 여부를 설정합니다. 기본값은 true입니다.

web-vital.*가 browser.web_vital.*로 대체되었습니다

속성 이름, 소문자 지표 값, 아래의 요구 수준은 OpenTelemetry 브라우저 이벤트 컨벤션과 브라우저 속성 레지스트리를 따릅니다. 둘 다 Development 단계라 상위 명세에서 더 바뀔 수 있습니다.

Span은 바뀌지 않았고 app.span.type = "webvitals"도 그대로입니다. Span 타입으로 웹 바이탈을 선택하는 쿼리는 영향을 받지 않습니다.

전송되는 신호

하나의 지표가 보고되면 최대 세 가지 신호가 만들어집니다.

이벤트

컨벤션은 browser.web_vital을 이벤트, 즉 로그 레코드로 정의하며 이벤트 이름을 정확히 browser.web_vital로 지정하도록 요구합니다.

• eventName은 browser.web_vital입니다. 속성이 아니라 로그 레코드의 네이티브 필드입니다.
• 레코드는 아래의 Span에 바인딩되므로 동일한 Trace ID와 Span ID를 가집니다.
• 속성: browser.web_vital.name, .value, .delta, .id, .rating, 값이 있을 때의 .navigation_type, 그리고 app.screen.name.
• session.id와 sophonz.browser.device는 레코드에 중복해서 붙이지 않습니다. 리소스 속성이라 SDK가 보내는 모든 로그 레코드에 이미 포함되어 있습니다.

Span

세션 타임라인이 app.span.type으로 데이터를 선택하므로 Span도 함께 전송됩니다.

• Span 이름: @sophonz/instrumentation-webvitals
• 시작 시각과 종료 시각이 같은 0초 Span입니다.
• 속성: app.span.type = "webvitals", 6개의 browser.web_vital.* 속성, 그리고 SDK의 모든 Span이 공통으로 갖는 화면 이름, 화면 타입, 세션 ID, url.full.

히스토그램

지표 값을 기록하는 webvitals 메트릭 계기입니다.

• 속성: app.span.type, browser.web_vital.name, browser.web_vital.delta, browser.web_vital.rating, 값이 있을 때의 browser.web_vital.navigation_type
• browser.web_vital.id는 제외했습니다. 측정마다 고유한 값이라 포함하면 데이터 포인트마다 별도의 시계열이 만들어집니다.

속성

수집하는 지표

cls, fcp, inp, lcp, ttfb를 수집하며, 각 지표는 페이지 로드당 한 번만 보고됩니다.

FID는 수집하지 않습니다. INP로 대체된 지표입니다.

집계

Google은 Core Web Vitals 기준값(LCP 2.5초, INP 200ms, CLS 0.1)을 페이지 조회의 75번째 백분위수로 정의합니다. 백분위수는 합성되지 않으므로, 화면별 백분위수를 다시 합치지 말고 원본 이벤트에서 p75를 계산해야 합니다.

지표는 페이지 로드당 한 번 보고되지만 bfcache 복원과 SPA 라우트 전환은 새 browser.web_vital.id를 만들어냅니다. 이 ID로 묶은 뒤 마지막 값을 취하면 중복이 제거됩니다.

browser.web_vital.rating은 비율로 집계됩니다. good 비율은 어떤 기준으로 묶어도 합산할 수 있습니다.

instrumentations로 켜고 끄기

init()의 instrumentations 객체로 계측을 개별로 끄거나 설정할 수 있습니다.

SophonzSDK.init({
  // ...
  instrumentations: {
    longtask: false,                                   // 끄기
    interactions: { events: { click: true, submit: false } },  // 세부 설정
  },
});

동작 규칙은 세 가지입니다.

• false를 지정하면 해당 계측이 비활성화됩니다.
• 객체를 지정하면 SDK가 설정하는 값에 병합됩니다. 예를 들어 fetch에 객체를 지정해도 propagateTraceHeaderCorsUrls와 캡처 콜백은 SDK 값이 유지되고, 명시한 필드만 바뀝니다.
• 아무것도 주지 않으면 SDK 기본값 그대로입니다.

consoleCapture·webVitals·websocket·socketio·userJourney처럼 최상위 옵션이 따로 있는 계측은 양쪽 중 하나라도 false이면 비활성화됩니다. 한쪽에서 비활성화한 것을 다른 쪽이 조용히 되살리지 않습니다.