이 가이드는 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();
    });
};

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

클라이언트 측 로깅은 프론트엔드 옵저버빌리티와 밀접하게 관련됩니다. 사용자에게 영향을 주는 문제에 빠르게 대응할 수 있도록, 예상하지 못한 오류는 모니터링 시스템이 관측하게 해야 합니다. 여러 이유로 모든 로그를 모니터링 시스템에 보내기는 어렵습니다. ~/lib/logger 사용을 주저할 필요는 없지만, ~/lib/logger에 전달된 메시지 중 어떤 것을 실제로 모니터링 시스템에 보낼지는 함께 고려합니다.

응집도 있는 로깅 모듈은 여러 진입점에서 이러한 부수 효과를 일관되게 제어하는 데 도움이 됩니다.