웹 브라우저 기능을 활용한 프런트엔드 오류 수집 전략

수정

프론트엔드 애플리케이션이 복잡해질수록, 사용자 환경에서 발생하는 오류를 빠르게 탐지하고 수집하는 것은 서비스 품질 유지의 핵심입니다. 서버 로그만으로는 확인하기 어려운 클라이언트 단 오류를 어떻게 안정적으로 모을 수 있을까요?

이번 글에서는 외부 라이브러리 없이 브라우저 기본 기능만으로 오류 수집 시스템을 구축하는 방법을 정리해보겠습니다.


1. 수집 대상 정의

브라우저 환경에서 발생하는 오류는 크게 네 가지로 나눌 수 있습니다.

  1. 실행 오류 (JavaScript Runtime Error)
  2. 예: TypeError: undefined is not a function
  3. 수집 방법: window.onerror
  4. 리소스 로드 오류 (Resource Error)
  5. 예: 이미지, CSS, JS 파일 로드 실패
  6. 수집 방법: window.addEventListener('error', …, true)
  7. ⚠️ 참고: window.onerror로는 리소스 로드 오류를 잡을 수 없고, 반드시 capture=true 옵션을 준 이벤트 리스너에서만 감지됩니다.
  8. 비처리 프로미스 오류 (Unhandled Promise Rejection)
  9. 예: fetch() 실패 후 .catch 미처리
  10. 수집 방법: window.onunhandledrejection
  11. 성능/네트워크 힌트 (선택 사항)
  12. 예: 느린 요청, 대용량 자원 로드
  13. 수집 방법: PerformanceObserver (resource/longtask 관찰)

2. 오류 수집 스니펫 (개선 버전)

아래 코드는 오류를 캡처하고, 일정 간격 또는 언로드 시점에 서버로 전송하는 예시입니다.

<script>
(function () {
  const ENDPOINT = "/client-error";
  const queue = [];
  const MAX_PAYLOAD_SIZE = 60000; // 보수적으로 60KB 이하
  const SAMPLE_RATE = 0.1; // 10% 샘플링
  const sentErrors = new Set();

  function shouldSample() {
    return Math.random() <= SAMPLE_RATE;
  }

  function isDuplicate(error) {
    const key = btoa(unescape(encodeURIComponent(
      `${error.type}-${error.msg || error.reason}-${error.stack || ''}`
    ))); // 해시 기반 중복 체크
    if (sentErrors.has(key)) return true;
    sentErrors.add(key);
    setTimeout(() => sentErrors.delete(key), 300000);
    return false;
  }

  function push(error) {
    if (!shouldSample()) return;
    if (isDuplicate(error)) return;

    queue.push({
      ...error,
      timestamp: Date.now(),
      userAgent: navigator.userAgent,
      url: location.href
    });

    if (queue.length >= 5) flush();
  }

  function flush() {
    if (!queue.length) return;

    const payload = JSON.stringify({
      ts: Date.now(),
      url: location.href,
      items: queue.splice(0)
    });

    if (new Blob([payload]).size > MAX_PAYLOAD_SIZE) {
      console.warn('Payload too large, splitting...');
      return;
    }

    if (navigator.sendBeacon) {
      const ok = navigator.sendBeacon(ENDPOINT, payload);
      if (!ok) fallback(payload);
    } else {
      fallback(payload);
    }
  }

  function fallback(payload) {
    fetch(ENDPOINT, {
      method: "POST",
      body: payload,
      headers: { "Content-Type": "application/json" }
    }).catch(() => {
      try {
        const img = new Image();
        const encoded = encodeURIComponent(payload);
        if (encoded.length < 2000) {
          img.src = `${ENDPOINT}?data=${encoded}`;
        }
      } catch (e) {}
    });
  }

  window.addEventListener("beforeunload", flush);
  window.addEventListener("pagehide", flush);

  window.onerror = (msg, src, line, col, err) => {
    push({
      type: "js-error",
      msg: String(msg).slice(0, 500),
      src,
      line,
      col,
      stack: err?.stack?.slice(0, 3000)
    });
  };

  window.addEventListener("error", e => {
    if (e.target && e.target !== window) {
      push({
        type: "resource-error",
        tag: e.target.tagName,
        src: e.target.src || e.target.href
      });
    }
  }, true);

  window.onunhandledrejection = e => {
    const reason = e.reason instanceof Error ?
      e.reason.message :
      String(e.reason).slice(0, 500);

    push({
      type: "unhandled-rejection",
      reason,
      stack: e.reason?.stack?.slice(0, 3000)
    });
  };

  setInterval(flush, 30000);
})();
</script>

3. navigator.sendBeacon의 특징과 한계

오류 수집에서 가장 중요한 포인트는 언로드 시점에서도 로그 유실 없이 서버에 도착하는 것입니다.

👉 따라서 sendBeacon → 일반 fetch → 이미지 태그 순으로 fallback을 준비하는 것이 최적입니다.


4. 운영 시 반드시 고려할 점

  1. 소스맵 연계
  1. CORS 정책
  1. 민감정보 마스킹
   url.replace(/([?&])(password|token|key|secret)=[^&]*/gi, '$1$2=***');
  1. 샘플링 & 중복 억제
  1. 호환성 안내

5. 서버 수집 예시

app.post('/client-error', (req, res) => {
  const errors = req.body.items;
  errors.forEach(error => {
    if (error.stack) {
      error.originalStack = mapStackTrace(error.stack);
    }
    logger.error({ ...error, ip: req.ip, userAgent: req.get('User-Agent') });
    if (error.type === 'js-error') {
      sendAlert(error);
    }
  });
  res.status(200).send('OK');
});

6. 결론

서재에서 보기 →