브라우저 JS

ClickStack용 브라우저 SDK - ClickHouse 관측성 스택

ClickStack 브라우저 SDK를 사용하면 프런트엔드 애플리케이션을 계측해 이벤트를 ClickStack으로 전송할 수 있습니다. 이를 통해 네트워크 요청과 예외를 백엔드 이벤트와 함께 단일 타임라인에서 확인할 수 있습니다.

또한 세션 리플레이 데이터를 자동으로 캡처하고 연관시키므로, 애플리케이션을 사용하는 동안 사용자가 보고 있던 내용을 시각적으로 단계별로 따라가며 디버깅할 수 있습니다.

이 가이드에서는 다음 항목을 통합합니다:

• 콘솔 로그
• 세션 리플레이
• XHR/Fetch/WebSocket 요청
• 예외

​

시작하기

패키지 import

패키지 import로 설치(권장)

다음 명령으로 브라우저 패키지를 설치합니다.

npm install @hyperdx/browser

ClickStack 초기화

import HyperDX from '@hyperdx/browser';

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack에서는 생략
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // 프런트엔드 요청과 백엔드 요청의 트레이스를 연결하도록 설정
    consoleCapture: true, // 콘솔 로그 수집(기본값: false)
    advancedNetworkCapture: true, // HTTP 요청/응답의 전체 헤더와 본문 수집(기본값: false)
});

스크립트 태그

스크립트 태그로 설치(대안)

NPM으로 설치하는 대신 스크립트 태그로 스크립트를 포함해 사용할 수도 있습니다. 이렇게 하면 전역 변수 HyperDX가 제공되며, NPM 패키지와 동일한 방식으로 사용할 수 있습니다.

현재 사이트를 번들러로 빌드하지 않는 경우 이 방법을 권장합니다.

<script src="//www.unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
<script>
  window.HyperDX.init({
    url: 'http://localhost:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack에서는 생략
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // 프런트엔드 요청과 백엔드 요청의 트레이스를 연결하도록 설정
  });
</script>

​

옵션

• apiKey - ClickStack 수집 API Key입니다.
• service - HyperDX UI에 이벤트가 표시될 서비스 이름입니다.
• tracePropagationTargets - 프론트엔드와 백엔드 trace를 연결하기 위해 HTTP 요청과 대조할 regex 패턴 목록입니다. 패턴 중 하나와 일치하는 모든 요청에 추가 traceparent header를 추가합니다. 백엔드 API 도메인(예: api.yoursite.com)으로 설정해야 합니다.
• consoleCapture - (선택 사항) 모든 콘솔 로그를 수집합니다(기본값 false).
• advancedNetworkCapture - (선택 사항) 전체 요청/응답 headers 및 본문을 수집합니다(기본값 false).
• url - (선택 사항) OpenTelemetry collector URL이며, 자체 호스팅 인스턴스에서만 필요합니다.
• maskAllInputs - (선택 사항) 세션 리플레이에서 모든 입력 필드를 마스킹할지 여부입니다(기본값 false).
• maskAllText - (선택 사항) 세션 리플레이에서 모든 텍스트를 마스킹할지 여부입니다(기본값 false).
• disableIntercom - (선택 사항) Intercom 통합을 비활성화할지 여부입니다(기본값 false)
• disableReplay - (선택 사항) 세션 리플레이를 비활성화할지 여부입니다(기본값 false)

​

추가 구성

​

사용자 정보 또는 메타데이터 추가

사용자 정보를 추가하면 HyperDX UI에서 세션과 이벤트를 검색하거나 필터링할 수 있습니다. 이는 클라이언트 세션 중 언제든지 호출할 수 있습니다. 현재 클라이언트 세션과 이 호출 이후에 전송되는 모든 이벤트는 사용자 정보와 연결 됩니다.

userEmail, userName, teamName은 세션 UI에 해당 값을 표시하는 데 사용되지만 생략할 수도 있습니다. 그 외의 추가 값도 지정할 수 있으며, 이벤트를 검색하는 데 사용할 수 있습니다.

HyperDX.setGlobalAttributes({
  userId: user.id,
  userEmail: user.email,
  userName: user.name,
  teamName: user.team.name,
  // 기타 사용자 정의 속성...
});

​

React error boundary 오류 자동 수집

React를 사용하는 경우, 에러 바운더리(error boundary) 컴포넌트를 attachToReactErrorBoundary 함수에 전달하면 React error boundary 내에서 발생하는 오류를 자동으로 수집할 수 있습니다.

// ErrorBoundary를 가져옵니다 (예시로 react-error-boundary를 사용합니다)
import { ErrorBoundary } from 'react-error-boundary';

// ErrorBoundary 컴포넌트에 연결하여 해당 컴포넌트의 모든 인스턴스에서 발생하는
// 오류를 캡처합니다.
HyperDX.attachToReactErrorBoundary(ErrorBoundary);

​

사용자 지정 액션 보내기

특정 애플리케이션 이벤트(예: 회원 가입, 제출 등)를 명시적으로 추적하려면 이벤트 이름과 선택적 메타데이터를 함께 지정해 addAction 함수를 호출할 수 있습니다.

예시:

HyperDX.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});

​

네트워크 캡처 동적으로 활성화하기

네트워크 캡처를 동적으로 활성화하거나 비활성화하려면 필요에 따라 enableAdvancedNetworkCapture 또는 disableAdvancedNetworkCapture 함수를 호출하면 됩니다.

HyperDX.enableAdvancedNetworkCapture();

​

CORS 요청에 대한 리소스 타이밍 활성화

프런트엔드 애플리케이션이 다른 도메인으로 API 요청을 보내는 경우, 선택적으로 Timing-Allow-Origin헤더가 요청과 함께 전송되도록 설정할 수 있습니다. 이렇게 하면 ClickStack이 PerformanceResourceTiming을 통해 DNS 조회, 응답 다운로드 등 요청에 대한 세부적인 리소스 타이밍 정보를 수집할 수 있습니다.

cors 패키지와 함께 express를 사용 중이라면, 다음 스니펫을 사용하여 헤더를 활성화할 수 있습니다:

var cors = require('cors');
var onHeaders = require('on-headers');

// ... 나머지 코드

app.use(function (req, res, next) {
  onHeaders(res, function () {
    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
    if (allowOrigin) {
      res.setHeader('Timing-Allow-Origin', allowOrigin);
    }
  });
  next();
});
app.use(cors());