이 가이드에는 GitLab 프론트엔드 개발을 위한 클라이언트 측 로깅의 모범 사례가 포함되어 있습니다.

브라우저 콘솔에 로그를 남길 시기#

불필요하게 브라우저 콘솔에 로그를 남기지 않는 것이 좋습니다. 지나치게 많은 콘솔 로그는 읽고, 파싱하고, 처리하기 어렵기 때문입니다. 그러나 시스템에서 의도치 않은 이벤트가 발생할 때는 가시성을 확보해야 합니다. 런타임 중에 발생 가능하지만 예상치 못한 예외가 발생하면, 해당 예외의 세부 정보를 로그로 남겨야 합니다. 이러한 로그는 이슈를 생성하는 최종 사용자나 문제를 진단하는 기여자에게 매우 유용한 컨텍스트를 제공할 수 있습니다.

catch(e)가 존재하고 e가 예상치 못한 것이라면, 세부 정보를 로그로 남기세요.

오류가 예상치 못한 것인지 판단하는 방법#

때로는 잡힌 예외가 표준 운영의 일부일 수 있습니다. 예를 들어, 서드파티 라이브러리는 특정 입력에 따라 예외를 던질 수 있습니다. 이러한 예외를 우아하게 처리할 수 있다면, 그것은 예상된 예외입니다. 불필요하게 로그를 남기지 마세요. 예를 들면:

try {
  // Here, we call a method based on some user input.
  // `doAThing` will throw an exception if the input is invalid.
  const userInput = getUserInput();
  doAThing(userInput);
} catch (e) {
  if (e instanceof FooSyntaxError) {
    // To handle a `FooSyntaxError`, we just need to instruct the user to change their input.
    // This isn't unexpected, and is part of standard operations.
    setUserMessage(`Try writing better code. ${e.message}`);
  } else {
    // We're not sure what `e` is, so something unexpected and bad happened...
    logError(e);
    setUserMessage('Something unexpected happened...');
  }
}

오류를 로그로 남기는 방법#

GitLab에서 런타임 오류를 일관되게 로그로 남기는 방법을 캡슐화한 유용한 ~/lib/logger 모듈이 있습니다. 이 모듈에서 logError를 임포트하여 일반적으로 console.error를 사용하는 것처럼 사용하세요. 스택 추적 및 기타 세부 정보가 로그에 캡처될 수 있도록 실제 Error 객체를 전달하세요:

// 1. Import the logger module.
import { logError } from '~/lib/logger';

export const doThing = () => {
  return foo()
    .then(() => {
      // ...
    })
    .catch(e => {
      // 2. Use `logError` like you would `console.error`.
      logError('An unexpected error occurred while doing the thing', e);

      // We may or may not want to present that something bad happened to the end user.
      showThingFailed();
    });
};

프론트엔드 옵저버빌리티와의 관계#

클라이언트 측 로깅은 프론트엔드 옵저버빌리티(Frontend observability)와 밀접하게 관련되어 있습니다. 예상치 못한 오류가 모니터링 시스템에 의해 관찰되어 사용자 대면 이슈에 빠르게 대응할 수 있기를 원합니다. 여러 가지 이유로, 모든 로그를 모니터링 시스템에 전송하는 것은 실행하기 어렵습니다. ~/lib/logger 사용을 주저하지 말되, ~/lib/logger에 전달된 메시지 중 실제로 모니터링 시스템에 전송되는 것을 제어하는 것을 고려하세요.

통합된 로깅 모듈은 다양한 진입점에서 이러한 사이드 이펙트를 일관되게 제어하는 데 도움이 됩니다.