사용자 정의 로그 수집

브라우저 에이전트는 웹 애플리케이션이 직접 임의의 로그 메시지를 수집하도록 logger 인터페이스를 제공합니다. 자연어 수준의 메시지에 레벨과 컨텍스트, 오류 정보를 함께 담아 전송하면 WhaTap 콘솔에서 검색·필터링할 수 있습니다. 사용자 정의 이벤트 수집이 이벤트의 수행 시간과 결과를 다루는 데 비해, 사용자 정의 로그는 애플리케이션 동작 중 발생하는 메시지를 레벨별로 기록하는 데 사용합니다.

노트

사용자 정의 로그는 브라우저 에이전트 3.0 이상에서만 동작합니다. 이전 버전이라면 본 기능을 사용하기 전에 에이전트를 업그레이드하세요.

주의

로그 모니터링은 과금 대상 기능입니다. 활성화한 날부터 15일 동안 무료로 체험할 수 있고, 이후에는 수집한 로그 기준으로 요금이 부과됩니다.

사전 준비

WhaTap 콘솔에서 다음 값을 발급받으세요.

Item	Description
액세스 키	프로젝트 액세스 키(projectAccessKey)
프로젝트 코드	숫자형 프로젝트 코드(pcode)
수집기 주소	데이터를 받는 수집기 URL(proxyBaseUrl)

주의

proxyBaseUrl이 비어 있으면 모든 로그가 폐기됩니다. 반드시 설정하세요.

활성화

사용자 정의 로그를 사용하려면 다음 두 가지를 설정해야 합니다.

1. 로그 설정: 로그 설정 화면에서 로그 모니터링 활성화 토글을 켜세요. 로그 모니터링이 켜져야 로그가 수집되며, 토글을 끄면 로그를 더 이상 저장하지 않습니다.
2. 사용자 정의 로그 옵션 설정: 브라우저 에이전트는 기본적으로 비동기로 로드됩니다. WhaTap 콘솔에서 발급되는 표준 설치 스니펫을 그대로 사용하고, config 객체에 enableCustomLog: true를 추가하세요.

<script>
  (function (w, h, _a, t, a, b) {
    w = w[a] = w[a] || {
      config: {
        projectAccessKey: 'YOUR_ACCESS_KEY',
        pcode: 12345,
        sampleRate: 100,
        proxyBaseUrl: 'https://your-collector.example.com/',
        enableCustomLog: true,   // 사용자 정의 로그 활성화
        env: 'prod',
        version: '1.0.0'
      }
    };
    a = h.createElement(_a);
    a.async = 1;
    a.src = t;
    t = h.getElementsByTagName(_a)[0];
    t.parentNode.insertBefore(a, t);
  })(window, document, 'script',
     'https://repo.whatap-browser-agent.io/rum/v3/whatap-browser-agent.js',
     'WhatapBrowserAgent', '');
</script>

설정 옵션

Option	Type	Required	Description
projectAccessKey	string	필수	WhaTap 콘솔에서 발급받은 액세스 키
pcode	number	필수	프로젝트 코드
proxyBaseUrl	string	필수	수집기 베이스 URL. 미설정 시 로그 미전송
enableCustomLog	boolean	필수	true로 지정해야 활성화(기본값 false)
env	string	선택	환경 구분(예: prod, staging, dev). 기본값 default_env
version	string	선택	애플리케이션 버전. 배포별 로그 구분에 사용. 기본값 default_version

노트

logger 인터페이스는 에이전트 스크립트가 다운로드·실행된 이후에만 노출됩니다. 페이지 로드 매우 이른 시점의 호출은 무시될 수 있습니다. 안전한 호출 방법은 비동기 로드와 안전한 호출을 참고하세요.

주의

사용자 정의 로그는 세션의 샘플링 결정을 따릅니다. sampleRate로 인해 현재 세션이 수집 대상에서 제외되면 해당 세션의 사용자 정의 로그도 전송되지 않습니다. 모든 세션의 로그를 수집하려면 sampleRate: 100(기본값)을 유지하세요.

인터페이스

logger 인터페이스는 window의 WhatapBrowserAgent 객체에 포함되어 있습니다.

Typescript

window.WhatapBrowserAgent.logger.debug(message, context, error);
window.WhatapBrowserAgent.logger.info (message, context, error);
window.WhatapBrowserAgent.logger.warn (message, context, error);
window.WhatapBrowserAgent.logger.error(message, context, error);
window.WhatapBrowserAgent.logger.log  (message, context, status, error);

Argument	Type	Required	Description
message	string	필수	로그 본문. 최대 8KB
context	object	선택	추가 메타. 검색·필터에 사용
error	Error 또는 유사 객체	선택	스택과 함께 보낼 때 사용

• 모든 메서드는 동기적이며 반환값이 없습니다.
• 호출 즉시 내부에 적재하며, 약 1초 뒤 묶어서 전송합니다.
• 인자를 잘못 넘기더라도 예외를 던지지 않아 애플리케이션 동작에 영향이 없습니다.
• logger.log()는 세 번째 인자로 status('debug' | 'info' | 'warn' | 'error')를 받으며, 잘못된 값은 'info'로 처리됩니다.

사용 방법

기본 호출

window.WhatapBrowserAgent.logger.info('checkout button clicked');

컨텍스트 함께 보내기

두 번째 인자에 객체를 넘기면 WhaTap 콘솔에서 검색·필터에 활용할 수 있습니다.

window.WhatapBrowserAgent.logger.info('checkout step', {
  step: 'shipping',
  cartItems: 3,
  isPremiumUser: true
});

context에는 문자열, 숫자, 불리언만 그대로 전송됩니다. 객체·배열·null·undefined·함수는 자동으로 제외되므로, 중첩 값은 평탄화하거나 문자열로 직렬화하세요.

// 무시됨: user가 객체
window.WhatapBrowserAgent.logger.info('login', {
  user: { id: 42, name: 'jihoon' }
});

// 평탄화
window.WhatapBrowserAgent.logger.info('login', {
  userId: 42,
  userName: 'jihoon'
});

// 직렬화
window.WhatapBrowserAgent.logger.info('login', {
  userJson: JSON.stringify({ id: 42, name: 'jihoon' })
});

오류 함께 보내기

세 번째 인자에 Error 객체나 catch한 값을 그대로 전달하면 name, message, stack이 함께 전송됩니다.

try {
  riskyOperation();
} catch (e) {
  window.WhatapBrowserAgent.logger.error(
    'riskyOperation failed',
    { feature: 'checkout' },
    e
  );
}

• Error 인스턴스: name, message, stack을 그대로 추출
• 일반 객체: name / message / stack 속성이 있으면 사용
• 그 외(문자열·숫자 등): 문자열로 변환되어 message에 들어감

로그 레벨

레벨	권장 용도
debug	개발 중 상세 추적. 운영 환경에서는 사용을 자제
info	정상 흐름 이벤트(페이지 진입, 비즈니스 마일스톤)
warn	복구된 비정상 상황(재시도 성공, 폴백 사용)
error	사용자 경험에 영향을 준 실패(결제 실패, 데이터 누락)

WhaTap 콘솔은 레벨을 색상으로 구분해 표시합니다.

활용 패턴

결제 흐름 추적

const log = window.WhatapBrowserAgent.logger;

log.info('checkout:start', { cartId, items: cartItems.length, total });

try {
  const result = await pay(cartId);
  log.info('checkout:success', { cartId, paymentId: result.id });
} catch (e) {
  log.error('checkout:fail', { cartId, gateway: 'PG_X' }, e);
}

전역 오류 보강

기본 오류 수집과 별개로 컨텍스트를 덧붙여 보낼 수 있습니다.

window.addEventListener('error', (event) => {
  window.WhatapBrowserAgent.logger.error(
    'uncaught: ' + event.message,
    { filename: event.filename, line: event.lineno },
    event.error
  );
});

전송 동작

• 마지막 호출 이후 약 1초간 추가 호출이 없으면 묶어서 전송합니다.
• 첫 호출 이후 5초가 지나면 강제로 전송합니다.
• 짧은 시간에 500건 또는 약 512KB가 누적되면 즉시 전송합니다.
• 메시지 1건은 최대 8KB까지 전송되며, 그 이상은 잘립니다.

대부분의 경우 별도 처리 없이 그대로 사용해도 충분합니다.

주의사항

주의	이유
개인정보 직접 전송 금지	주민등록번호·카드번호·전화번호 등은 호출 측에서 마스킹한 뒤 전송하세요
루프 안 무조건 호출 금지	단위 시간당 호출이 과도하면 네트워크 부하를 유발할 수 있습니다
8KB 초과 메시지	자동으로 잘립니다. 큰 페이로드는 context 필드로 분할하세요
객체·배열을 context에 그대로 전달 금지	무시됩니다. 평탄화하거나 문자열로 직렬화하세요

비동기 로드와 안전한 호출

페이지가 막 열리는 시점에 logger.*를 호출해야 한다면 logger 존재 여부를 먼저 확인하세요.

function safeLog(level, message, context, error) {
  const agent = window.WhatapBrowserAgent;
  if (agent && agent.logger && typeof agent.logger[level] === 'function') {
    agent.logger[level](message, context, error);
  }
  // 로드 전이라면 무시됩니다.
}

safeLog('info', 'app boot', { route: location.pathname });

팁

사용자 이벤트(클릭, 폼 제출 등) 시점의 호출은 보통 에이전트 로드가 끝난 뒤이므로 별도 방어가 필요 없습니다. 위 패턴은 페이지 부팅 코드에서만 사용하세요.

문제 해결

증상	원인 / 조치
window.WhatapBrowserAgent.logger가 undefined	(1) 에이전트가 3.0 미만 버전 (2) 비동기 로드가 아직 끝나지 않음 (3) CSP·광고 차단 등으로 스크립트 차단
콘솔에 Custom log call was dropped 경고	enableCustomLog가 false입니다. config에 enableCustomLog: true를 추가하세요. 이 경고는 최초 1회만 출력됩니다
호출해도 네트워크 요청이 없음	enableCustomLog: true 누락, proxyBaseUrl 미설정, 또는 설정보다 호출이 먼저 실행됨
401 / 403 응답	액세스 키 또는 pcode 오류
특정 세션의 로그가 전부 누락	sampleRate로 해당 세션이 수집 대상에서 제외됨. 모든 세션을 수집하려면 sampleRate: 100으로 설정하세요
일부 로그만 누락	짧은 시간에 500건 또는 약 512KB 초과분이 즉시 전송됩니다(정상 동작)
메시지가 잘려서 도착	단일 메시지 8KB 상한. 초과분은 자동으로 잘립니다

전송된 로그는 WhaTap 콘솔의 분석 > 사용자 세션 로그 검색 메뉴에서 확인할 수 있습니다. status, message, context 키, error.message 등으로 검색·필터링하세요.