あなたが削ったそのログは、私たちが欲しかったコンテキストだった

株式会社サポーターズでエンジニアをしている、ちゅうこです。

あなたも、オープンソースソフトウェア(以下、OSS)やプロダクトに対して、バグやエラーを報告したり、開発時に質問をしたりする ことがあると思います。

そんなとき、 あなたが不要だと思って削除してしまったログの中に、問題解決への糸口が眠っている ことがあります。

質問や報告を投げるときは、ぜひ本記事で述べるポイントを覚えていて欲しいです。

経緯

私は、とあるOSSのコア開発者 として関わっています。開発者グループのDiscordに参加し、 日々、多くの開発者からの質問に回答 しています。

最近、ある開発者が「アプリケーションが自分の環境で動作しない」と質問してきました。しかし、提出されたログはただHTTPステータスコード500を示す情報とDockerの起動失敗に関するログだけでした。

提出する情報が多いほど、問題解決に近づく可能性が高まる

エラーやバグ報告の情報量に基づいてカテゴリを分ける ならば、以下のように考えられるでしょう。

カテゴリ1. 「実行したらエラーが出ました」のみの情報

カテゴリ2. 実行手順を含めた情報

カテゴリ3. 実行手順とそれに対応するログを含めた情報

カテゴリ4. 実行手順、ログ、そして実行環境やOSの詳細を含めた情報

この例でいえば、提出された情報はカテゴリ2のものでした。

問題の切り分けや解決に繋がる判断に必要な情報が不足 していました。

これが何を意味するかというと、 あなたが提出する情報が多ければ多いほど問題の解決に近づく可能性が高まる ということです。

どのツールを使ったのか、どのような問題が起きたのか、実行手順は何だったのか、使用しているミドルウェアのバージョンやOSなどの詳細が不明では問題解決は難しいです。

つまり、 起きた問題よりも「あなたの手順や環境」を詳しく知ることが、私たちが問題を解決する上で重要 なのです。

言い換えれば、 あなたがどのような行動を取ったかが、私たちが問題を理解し解決するための最も重要な情報源 となります。

質問者にやってほしいこと

最初に起動手順や準備のプロセス、実行手順や使用環境を示してほしいというのが、私の期待です。

なぜかというと 前提から何かが間違っている可能性もあるから です。

  • 開発者が想定した起動方法をしたのか
  • 必要なファイルを適切に認識しているのか
  • Dockerを使っているのであれば、ボリュームマウントは適切にされているのか

上記のように、実行手順や使用環境の情報がないと問題解決は難しくなります。

これは、 全体の情景を可能な限り理解するための情報が欠けることで、原因の特定が困難になるから です。

質問や報告に入れてほしい情報

質問をサポートする開発者として、次のような情報があると質問に答えやすいです。

  • CLIの実行コマンドログ

  • アプリケーションのエラーログ

  • ミドルウェアのログ

  • 利用するOS、アプリケーション、ミドルウェアのバージョン

  • 実行またはファイル配置パスに日本語や全角スペースが含まれているのか

CLI プロンプトのユーザ名など隠すべき情報がある場合は、それらを隠した状態で情報を提出してよいです。また、 開発者が用意したテンプレートがあれば、それに沿うのがよい でしょう。

まとめ

あなたが親切心で削った報告内容の一部は、本当に不要だったかもしれません。

しかし、その中には解決への糸口が含まれていることもあります。

私たちがプロダクトを改善し、あなたがスムーズに問題を解決できるように、どうか情報を削らないでください。