HyperDX: Client Session (RUM)

HyperDX - Clickstack은 클라이언트 수준의 녹화 기능도 제공한다. RUM(Real User Monitoring)이라고도 불리는 그 기능이다.
브라우저 환경과 React Native 기반의 앱 환경만을 지원한다.

hyperdx를 셋업하고 들어가면, Client Sessions이라는 탭이 있다.

여기서 clickhouse에 저장되어있는 리플레이 데이터를 조회하고, 재생해볼 수 있는 것이다.

브라우저에 에이전트 셋업하기

설정은 그렇게 어렵지는 않은 편이다.
모듈 하나 깔고

npm i @hyperdx/browser

이런 식으로 초기화 처리만 해주면 된다.

'use client';

import HyperDX from '@hyperdx/browser';

const isEnabled =
  typeof window !== 'undefined' && process.env.NEXT_PUBLIC_HYPERDX_ENABLED === 'true';

if (isEnabled) {
  HyperDX.init({
    url: 'https://clickhouse-otel-exporter.도메인.co',
    // Managed ClickStack 은 ingestion key 불필요 — env 미설정 시 빈 값
    apiKey: process.env.NEXT_PUBLIC_HYPERDX_API_KEY ?? '',
    service: process.env.NEXT_PUBLIC_HYPERDX_SERVICE_NAME ?? 'test-app',

    tracePropagationTargets: [/\/api\//i, /https:\/\/.*\.도메인\.ai/i],

    consoleCapture: true,
    advancedNetworkCapture: true,
  });
}

엔드포인트는 otel collector의 엔드포인트를 넣으면 되고, API Key도 otel collector의 엔드포인트를 넣으면 된다. 로그/트레이스와 동일한 인증/API 경로를 사용한다.
그리고 이 Ingestion Key는 불가피하게 클라이언트 수준에서 노출된다. 감안해야 한다.

https://clickhouse.com/docs/use-cases/observability/clickstack/sdks/browser

관측

위 과정을 거쳐 세팅을 하고 돌려서 제대로 쌓았다면, 대시보드에서 조회가 가능해진다.

각각의 세션 단위로 누적이 되고 (브라우저 세션 단위)

개별 세션을 클릭하면, 어떤 행동을 했는지를 비디오로 보고, 어떤 API를 썼고, 어떤 로그가 찍혔는지 등을 전부 훔쳐볼 수 있다.

영상 퀄리티 조정

고화질 영상을 원하는지, 뚝뚝 끊겨도 작게 저장되면 충분한지에 따라서 수집 옵션을 커스텀할 수 있다.
sampling이라는 옵션이다.

    sampling: {
      mousemove: 50, // 마우스 이동을 50ms 간격으로만 기록 (false면 아예 안 기록)
      scroll: 150, // 스크롤 이벤트 throttle (ms)
      input: 'last', // 타이핑 중간값 버리고 최종값만
      media: 800, // 오디오/비디오 상태 기록 간격
      mouseInteraction: { MouseUp: false, MouseDown: false }, // 이벤트 종류별 on/off
      canvas: 15, // 캔버스 녹화 FPS (recordCanvas 켰을 때만 의미)
    },

User Attribute 설정

따로 세션에 대한 설정을 하지 않는다면, 그건 그냥 익명 세션으로만 누적이 된다.
그래서 가능하면 해당 유저에 대한 속성을 고정해서 식별 가능하도록 만드는 것이 일반적인 패턴이다.

이런 식으로 이메일이나 닉네임 등을 붙여주면 우리가 대시보드에서 볼 때도 그 이름으로 보인다.

세션 샘플링

당연하지만 이건 디스크를 무식하게 먹는 기능이다.
그래서 실서비스 환경에서는 샘플링을 넣어서 일정 확률로 수집을 하도록 하는 편이 좋다.

아래는 간단한 예시 코드다.

// app/hyperdx-init.tsx 게이팅에 추가하는 형태
const SAMPLE_RATE = 0.2; // 20%

function isSampled(): boolean {
  const KEY = 'hdx-sampled';
  const TTL = 4 * 60 * 60 * 1000; // HyperDX 세션 최대 길이(4h)와 맞춤

  const stored = localStorage.getItem(KEY);
  if (stored) {
    const { value, expires } = JSON.parse(stored);
    if (Date.now() < expires) return value;
  }
  const value = Math.random() < SAMPLE_RATE;
  localStorage.setItem(KEY, JSON.stringify({ value, expires: Date.now() + TTL }));
  return value;
}

if (isEnabled && isSampled()) {
  HyperDX.init({ ... });
}

보안 및 마스킹

필요하다면 API나 콘솔로그를 전부 수집해서 쌓을 수 있는데, 경우에 따라서는 패스워드 같은 민감한 값은 수집하지 않도록 조정을 해야할 수 있다. 따로 설정을 하지 않는다면 무작정 다 넣기 때문이다.

일단 DOM 수준에서는 기본적인 마스킹을 해준다.
maskAllInputs가 input 태그 내의 값을 마스킹해주긴 하는데, 문제는 위처럼 request body로 수집되는 것이다.

이 경우 일부 민감한 URL만 수집 대상에서 제외하거나, 아예 body 수집 자체를 비활성화해야한다.

참조
https://clickhouse.com/docs/use-cases/observability/clickstack/sdks/browser