ログ・アラート ガイドライン

どの会社でもログやアラートのガイドラインというのを書いているなぁという感じなので、もうここでまとめて参照させたい、という意図で公開してみる。

ログ

ログレベル

基本的には以下の４つで利用することを推奨。

MonoLogの場合は他にもNOTICE ALERT CRITICAL EMERGENCY のログレベルがあるが、使い分けが難しく運用しきれない可能性が高いため、まずは上記の４つで運用する。細かく分けないと厳しいケースが出てきたら改めて検討する。

ログの出力内容

• [MUST] 個人情報を載せないように注意する
  • アクセスログにはクエリパラメータも載るのでURL設計にも注意する（例えば ?name=山田太郎 のようにクエリパラメータに個人情報が載らないようにする）
• [MUST] バッチ処理など長めの処理は障害発生時に「どこまで成功したのか」がわかりづらいため、INFOログを適度に残しておく。
• [SHOULD] ログ出力のコスト（CPU/IOや転送料金など）が増えたり、本質的なログが見えづらくなることもあるので、Webアプリケーションなどログが増えそうな箇所には不要なログはできるだけ載せない。
• [SHOULD] アプリケーションログを出力した場所（クラス、ファイル名、行番号）も入れておくと障害時に追いやすい
• [SHOULD] Exceptionのエラーログはスタックトレースも残す
  • スタックトレースに引数の値が載らないように設定する。PHPの場合は以下のような感じでiniを設定する。

zend.exception_ignore_args = On
zend.exception_string_param_max_len = 0

• [SHOULD] アプリケーションログにはトレースIDを入れておくと１リクエスト単位でまとめてログを確認できるので追いやすいので推奨
  • 分散システムの場合は必須。
  • DatadogやNewRelicが自動でつけてくれたりする。

ログフォーマット

外部ツール連携性が高いので構造化ログ（JSONL）にする。

Laravelログの例

{
    "message": "some message",
    "context": {},
    "level": 200,
    "level_name": "INFO",
    "channel": "production",
    "datetime": "2024-11-26T16:08:19.585601+09:00",
    "extra": {
        "platform": "laravel",
        "url": "/home",
        "ip": "x.x.x.x",
        "http_method": "GET",
        "server": "example.com",
        "referrer": "https://example.com/referrer",
        "file": "/var/www/html/app/Models/Hoge.php",
        "line": 123,
        "class": "App\\Models\\Hoge",
        "callType": "->",
        "function": "fuga",
        "uid": "8a1d991"
    }
}

ログ出力場所

コンテナ化している場合はCloudWatch Logsに連携する。アプリケーションでは標準出力に出せばOK。

アラート

どんなアラートを出すか

「どこ」で「何」 が発生したか。次に行うアクションはなにか？ を書くと良い。 特にアクションは大事で、内容はwikiに書いてそのURLを記載するだけでも良い。

アラートの意味を早く正確に把握できるように、とにかく認知負荷を下げるようなアラート文言を入れておくと良い。

どこに通知するか

Slackなどのチームで見れるようなChatツールに通知しておくと良い。メールだと気づかない…。通知するときは必要に応じてメンションできると良い。

何を使って通知するか

Slackであれば

• SlackのAPI(incoming webhookなど)を直接叩く
• Sentryなどのエラー管理ツール経由

といった選択肢がありそう。

Sentryは意図しないエラー（想定外のException）が発生したときに送信しておくと良い。意図しないエラー内容を確認し、不具合であれば修正するし、WARNINGレベルのエラーなどスルーしても良い内容であれば、そのように修正してSentryに通知されなようにするので、エラー管理ツールとして機能する。

一方で、想定内のエラーで一部手動のオペレーションが必要なのでSlack通知する、といったものはSentry管理にしないほうが良く、SlackのAPIを直接叩くほうが良いだろう。Sentryの設定によっては2回目以降の同じエラーは通知されなかったり、そもそもエラーというより「手動オペレーションが必要」というただの通知なので性質が違う。

オオカミ少年アラートに注意する

アラートが来たときに、ちゃんと精査してスルーしてOKなのか（INFO）、連続して発生していたらヤバいのか（WARNING）、不具合で修正が必要なのか（ERROR）を把握し、対応する必要がある。

もし、INFOレベルなのに通知されていたらオオカミ少年アラート化し、チームの認知負荷が上がる。オンボーディングも「このエラーは無視して良いですよ」みたいな意味不明な暗黙的な運用が発生してしまう。

また、大量のエラーに埋もれてしまって、新規のエラーを見逃してしまう可能性もある。

参考資料

• 今さら聞けないログの基本と設計指針
• ログ設計指針