@imqa/instrumentation-browser-exception

개요

@imqa/instrumentation-browser-exception은 IMQA 모니터링 시스템에서 웹 애플리케이션의 Error와 예외를 캡처합니다. 이 스키마는 OpenTelemetry 형식을 사용하여 클라이언트 측 Error를 추적하도록 설계되었습니다.

스키마 구조

스키마는 JSON 문서로, JSON Schema Draft 2020-12 사양을 따릅니다. Error Telemetry 데이터의 구조화된 형식을 정의합니다.

Error 범위

Error 범위는 애플리케이션 실행 중 발생하는 Error와 예외를 캡처합니다.

범위 정의

"scope": {
  "name": "@imqa/errors",
  "version": "1"
}

Error 스팬

Error 스팬은 사용자 상호작용 중 발생하는 Error를 캡처합니다:

• traceId: 트레이스의 고유 식별자
• spanId: 스팬의 고유 식별자
• parentSpanId: 부모 스팬의 식별자
• name: Error 타입 (예: "console.error")
• kind: 스팬의 타입 (1 = INTERNAL)
• startTimeUnixNano: 에포크 이후의 시작 시간 (나노초)
• endTimeUnixNano: 에포크 이후의 종료 시간 (나노초)
• status: 결과 상태 (2 = ERROR)

Error 스팬 속성

Error 스팬은 다음과 같은 속성을 포함합니다:

| 속성 | 타입 | 설명 | |-----------|------|-------------| | location.href | string | 현재 페이지 URL | | environment | string | 환경 이름 | | deployment.environment | string | 배포 환경 | | screen.name | string | 화면/페이지 이름 | | screen.type | string | 화면/페이지 타입 | | session.id | string | 사용자 세션 식별자 | | url.full | string | 요청 전체 URL (예: "https://example.com/articles/4?s=1&t1" ) | | component | string | 컴포넌트 (Error) | | span.type | string | 스팬 타입 (Error) | | error | boolean | Error 플래그 | | exception.type | string | 예외 타입 | | exception.message | string | Error 메시지 | | exception.stacktrace | string | Error 스택 트레이스 | | error.stack | string | Error 스택 트레이스 |

Error 이벤트

Error 스팬은 다음과 같은 추가 정보를 포함할 수 있는 예외 이벤트를 포함할 수 있습니다:

| 이벤트 속성 | 타입 | 설명 | |-----------------|------|-------------| | exception.message | string | Error 메시지 | | exception.parsed_stacktrace | string | 파싱된 스택 트레이스의 JSON 표현 | | exception.type | string | 예외 타입 |

다른 스키마와의 관계

Error는 종종 다른 Telemetry 데이터와 관련이 있습니다:

1. Error는 클릭과 같은 사용자 상호작용에 의해 트리거될 수 있습니다
2. Error는 싱글 페이지 애플리케이션의 라우트 변경 중 발생할 수 있습니다
3. Error 스팬은 일반적으로 트리거된 사용자 상호작용이나 라우트 변경 스팬을 연결하는 부모 SpanId를 포함합니다

사용 방법

계측 설정

(boolean, 선택)

브라우저에서 발생하는 오류 계측을 활성화하거나 비활성화합니다. true로 설정하면 전역 오류 핸들러가 활성화되어 애플리케이션에서 발생하는 오류가 자동으로 계측됩니다.

[!WARNING] 이 기능은 브라우저에서 발생하는 오류를 계측합니다. 따라서, 서버 혹은 엣지 환경(SSR을 사용하는 경우)에서 발생하는 오류는 계측되지 않습니다. 서버 측에서 발생하는 오류를 계측하려면 별도의 서버측 에이전트를 사용해야 합니다. 이는 IMQA에서 제공하는 기능이 아닙니다.

기타

유효한 Error Telemetry 객체는 다음과 같은 내용을 포함합니다:

• 서비스, 브라우저 및 환경을 식별하는 리소스 정보
• 발생한 예외를 상세히 설명하는 Error 스팬
• 스택 트레이스 및 기타 진단 정보
• 관련 사용자 상호작용 또는 라우트 변경 스팬을 연결하는 링크

데이터는 다양한 Telemetry 수집 및 분석 도구와 호환되는 OpenTelemetry 프로토콜 형식을 따릅니다.

라이센스

Copyright (c) 2024-2025 ONYCOM CO., LTD. All rights reserved.