フロントエンド開発者のためのクライアントサイドロギング

このガイドには、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使うことをためらわないでください~/lib/logger。しかし ~/lib/logger、監視システムに実際に送信される~/lib/loggerメッセージの制御を検討して ~/lib/loggerください。

まとまりのあるロギングモジュールは、様々なエントリーポイントで一貫してこれらの副作用を制御するのに役立ちます。