2016/09/26

2W1Hなエラーログの実例

前に エラーメッセージは 2W1H がいいんじゃないか というエントリーを書いたらけっこう反響があった。

2W1Hなログ

ログのエラーメッセージの中身が足りない場面が多いから、インターフェースで縛って What, Why, How を書くのはどうかというものでした。

$c->log->error(
    what => 'What happened?',
    why  => 'Why did this happen?',
    how  => 'How can we support this?',
    info => Dumper($some, $information),
);

How が書けるならそもそも実装で回避できるだろ、とか what => 'Unknown error ocurred.', why => 'Please investigate why, and fix somehow.' という身も蓋もないコメントがブクマに付いてて面白いなと思った。まあ、それが現実というものです。実装で回避できるのが一番良いし、人はどこまでもダークサイドに落ちる。とはいえ、より良いエラーログのために、この2W1Hはまあまあ良さげなのではないかというコメントもあった。しかし、具体的にどういう場面でどういうエラーを吐きたいのかが想像付きにくかったかなと思ったので、今回はそういうのを書いておく。

なお、この2W1H方式は、開発者もしくは運用者向けのエラーメッセージを想定していました。エンドユーザ向けには、ユーザ操作で回避できる問題とそうでない場面でアプローチ違ってきたりしますし、また別の解があると思われます。

2W1Hなログの具体例

ファイルを読むとき、ファイルの存在チェックをしますよね。いきなり読みに行く人もいるかもしれませんが、存在チェックぐらいしましょう。もっと丁寧ならサイズがゼロで無いかも見るかもしれませんが、それは読んでから見ても同じな気がするので気にしないことにします。いずれにしろ、以下のようにファイルの存在チェックをしたら、ファイルが無い場合の 2W1Hログです。

if (-e $some_file) {
    $data = slurp($some_file);
}
else {
    $c->log->error(
        what => "Could not read $some_file",
        why  => "Not exists $some_file",
        how  => "Ask Team Hoge. $some_file made by Hoge component.",
    );
}

この how => "Ask Team Hoge. $some_file made by Hoge component." が、開発者/運用者が本当に欲しかった情報なはず。大抵は what/why の情報しか書かれない。そこから、how にたどり着くところが秘伝と化す。2W1Hが良いと思ったのはこういうことでした。

とはいっても、普通、運用担当者は運用しているサービス全体のコードを grep くらいできるはずなので、このような取っ掛かりが無くてもファイル名さえ分かればどのコンポーネントがファイル生成をミスっているか瞬時に見つけられる気はするのだけれど、開発者同士でマイクロサービス全盛の昨今、コンポーネント間の切り分けが著しい場合、さらに常日頃はこのファイルが無い場面など起き得ない場合など、howに書かれた情報を知りうるのはこのコードを最初に書いた人だけかもしれないような場面でたぶんありがたい。忘れたころに役に立つ。はず。

そんな風に思いませんか?

2W1H 全部書くってのはやり過ぎかも

この 2W1H なログは、実戦投入しているわけではなく思いつきで書いたものだったので、改めて具体的に考えてみると、2W1H全部書かされるのは冗長で嫌だなと我ながら思った。まあでも、上の例のように本当に欲しい情報にたどり着きやすいインターフェースではあるなという気がして、捨てるには惜しい感じがする。なのできっと whatもwhyもhowもまあオプショナルでいいけど、情報を 2W1Hで勘案してログを書くためのインターフェースとして使ってみるという程度が現実的かもしれない。シンプルな一行メッセージであっても、レビューが十分に機能していて、本当に欲しいログメッセージが書けているかが事前に十分に考慮されるならこういうインターフェースは必要ないかもしれないし(そもそもファイルの存在確認などしない場面も多い気がするという見も蓋もない現実もあるだろうし)。とはいえ、インターフェースがこうなってる方が開発者が書きやすいというのは縛りとしてあった方が良いかもしれない。

サイト内検索