アプリのログ出力 — レベルの決め方とリクエストIDで1件を追う

アプリのログ出力。複数のログにある同じリクエストIDを虫眼鏡で追うイメージ。

ログは、障害が起きてから足すものではありません。起きたときには、もう手遅れです。

再現しない不具合を調べるとき、手元にあるのはそのとき残った文字だけです。何も出していなければ、推測するしかありません。逆に、全部出していると1日で数GBになり、肝心の1行が埋もれます。

この記事では、前の回で作った API にログを入れて、レベルで出し分け、あとから1件の処理だけを追える状態にします。集めて画面で見る仕組み(Loki など)は後の回で、ここでは「何を、どう出すか」だけを決めます。

対象レベル: 初級〜中級 / 区分: 必修

目次

この記事でわかること

  • ログレベルが「重要度」ではなく「誰が、いつ見るか」で決まること
  • console.log のままだと、あとで機械に読ませられないこと
  • 1件の処理を横断して追うための IDの付け方
  • ログに書いてはいけない値と、その避け方
  • 出しすぎると、費用と見落としの両方が増えること

この記事でやること

  1. いまの出力を見て、あとから追えないことを確かめる
  2. レベルを4つに決めて、環境変数で出す量を変える
  3. 1行1件の JSON で出す(構造化ログ)
  4. リクエストごとの ID を付けて、1件の処理だけを抜き出す
  5. わざとパスワードを渡して、出ないことを確かめる

先に知る言葉

この記事で初めて出てくる言葉です。 詳しくは用語集にもまとめてあります。

言葉意味
ログレベル誰がいつ見るかで分ける区分。error/warn/info/debug
構造化ログ1 行 1 件をJSON など機械が読める形で出すこと
標準出力 / 標準エラー出力プログラムの2 つの出口。 分けておくと後で振り分けられる
requestId1 回の処理に振る番号。混ざった行から 1 件だけ抜き出せる
マスキング秘密の値を出さない・伏せること

前提と作業場所

VM の中(Ubuntu Server)で打ちます。 前の回で作った ~/server がある前提です。データベースには触りません。

作業前にコピーを取ります。

bash
$ cd ~/server
$ cp -r . ~/server-backup-before-logging

いまの出力では追えない

よくあるのは、こういう行です。

console.log("タスクを取得");
console.log(task);
console.log("完了");

出力はこうなります。

タスクを取得
{ id: 1, title: '買い物', done: false }
完了

ここから分かることが、ほとんどありません。

  • いつ出たのか(時刻が無い)
  • 誰のリクエストか(同時に10人来たら、行が混ざって区別できない)
  • どこで出たのか(同じ文言が複数箇所にあると特定できない)
  • 重要なのか(全部同じ見た目)

とくに致命的なのが2つ目です。 サーバーは同時に複数の処理を進めるので、1件の処理の行は、他の行と交互に並びます。 時刻順に読んでも、話が繋がりません。

レベルを決める — 誰がいつ見るか

レベルは4つで足ります。「どれくらい重大か」ではなく、「誰が、いつ見るか」で決めます。

レベル意味誰がいつ見るか
error処理が失敗した。 人の対応が要るすぐ。通知を飛ばす対象
warn失敗はしていないが、普通ではない翌営業日。増え方を見る
info何が起きたかの記録。 正常系調べるときに遡って読む
debug開発中に中身を見るため本番では出さない

基準は「これが出たら、人は何かするか」です。何もしないなら error ではありません。

error を出しすぎると、誰も見なくなります。 実際、1日に数千件出ている error は、全員が無視するようになります。そうなった時点で、通知の仕組みは死んでいます。

迷いやすい例

起きたことレベル理由
利用者が入力を間違えた(400)info か warn想定内。 直すのは利用者で、こちらは何もしない
DB に繋がらない(500)error人が動かないと直らない
外部 API が1回だけ失敗し、再試行で成功warn今回は困っていない。増えたら困る
存在しない URL への要求(404)info単発なら日常。大量なら別の話

1行1件の JSON で出す

人が読む形と、機械が読む形は違います。ログは、最終的に機械が検索します。

bash
$ nano ~/server/logger.js
// logger.js — 1行1件の JSON で出す
const LEVELS = { error: 0, warn: 1, info: 2, debug: 3 };
const threshold = LEVELS[process.env.LOG_LEVEL] ?? LEVELS.info;

function write(level, message, fields = {}) {
  if (LEVELS[level] > threshold) return;   // 設定より細かいものは出さない
  const line = {
    time: new Date().toISOString(),
    level,
    message,
    ...fields
  };
  const out = level === "error" ? process.stderr : process.stdout;
  out.write(JSON.stringify(line) + "\n");
}

export const log = {
  error: (m, f) => write("error", m, f),
  warn:  (m, f) => write("warn",  m, f),
  info:  (m, f) => write("info",  m, f),
  debug: (m, f) => write("debug", m, f)
};

大事なのは3つです。

  • 1件が1行。 改行で区切れるので、あとで機械が1件ずつ読める
  • 値をメッセージに混ぜない。 { taskId: 42 } のように別のキーで持つ
  • error だけ標準エラー出力へ。 分けておくと、あとで別のファイルに振り分けられる

2つ目が効いてきます。「タスク42を取得しました」と1つの文字列にすると、42 で検索することはできても、「100 以上の ID」では探せません。 キーで分けておけば、あとから条件を付けられます。

1件の処理を追えるようにする

ここが、この記事でいちばん効く部分です。リクエストごとに ID を1つ振り、その処理から出る全部の行に付けます。

bash
$ nano ~/server/request-log.js
// request-log.js — 1リクエストに1つ ID を振る
import { randomUUID } from "node:crypto";
import { log } from "./logger.js";

export function requestLog(req, res, next) {
  req.id = randomUUID().slice(0, 8);
  const started = Date.now();

  res.on("finish", () => {
    log.info("request", {
      requestId: req.id,
      method: req.method,
      path: req.path,
      status: res.statusCode,
      ms: Date.now() - started
    });
  });

  next();
}

res.on("finish") は「応答を返し終わったとき」に呼ばれます。ここで書けば、結果(ステータス)と所要時間まで含めて1行に残せます。

組み込みます。ルートより前に置きます(後ろだと、ルートの中で req.id が使えません)。

bash
$ nano ~/server/index.js
import { requestLog } from "./request-log.js";
import { log } from "./logger.js";

app.use(requestLog);          // ルートより前

app.get("/api/tasks/:id", async (req, res, next) => {
  try {
    const id = Number(req.params.id);
    log.debug("タスクを取得する", { requestId: req.id, taskId: id });
    const task = await findTask(id);
    if (!task) {
      log.info("タスクが無い", { requestId: req.id, taskId: id });
      return res.status(404).json({ error: { code: "task_not_found" } });
    }
    res.json(task);
  } catch (e) {
    log.error("取得に失敗", { requestId: req.id, taskId: req.params.id, err: e.message });
    next(e);
  }
});

// 練習用のログイン窓口(認証はしない。ログに何を出すかだけを確かめる)
// 本文の JSON を読むため express.json() を通す(index.js で express を import している前提)
app.post("/api/login", express.json(), (req, res) => {
  log.info("ログイン", { requestId: req.id, user: req.body.user });   // 必要な項目だけ名指しで出す
  res.status(204).end();
});

すべての行に requestId が付いています。 これで、混ざった行の中から1件だけを抜き出せます。

動かして、追ってみる

bash
$ cd ~/server
$ node index.js > ~/server/app.log 2>&1 &
$ sleep 1
$ curl -s -o /dev/null http://localhost:3000/api/tasks/1
$ curl -s -o /dev/null http://localhost:3000/api/tasks/999999

出た行を見ます。

bash
$ tail -n 4 ~/server/app.log
{"time":"2026-09-09T01:22:10.412Z","level":"info","message":"request","requestId":"3f9a1c22","method":"GET","path":"/api/tasks/1","status":200,"ms":8}
{"time":"2026-09-09T01:22:10.930Z","level":"info","message":"タスクが無い","requestId":"7c4e8b10","taskId":999999}
{"time":"2026-09-09T01:22:10.933Z","level":"info","message":"request","requestId":"7c4e8b10","method":"GET","path":"/api/tasks/999999","status":404,"ms":5}

1件だけを抜き出せます。

bash
$ grep "7c4e8b10" ~/server/app.log

これが目的でした。 何十人分の行が混ざっていても、1つの ID で、その処理だけが並びます。

機械に読ませることもできます。

bash
$ grep '"level":"info"' ~/server/app.log | jq -r 'select(.ms > 5) | "\(.path) \(.ms)ms"'
/api/tasks/1 8ms

jq が無ければ sudo apt install -y jq で入ります。1行1件の JSON にしておいたから、こう書けます。 人向けの文章だったら、この抽出はできません。

出す量を切り替える

debug は本番で出しません。環境変数で切り替えます。

kill %1
LOG_LEVEL=debug node index.js > ~/server/app.log 2>&1 &
sleep 1
curl -s -o /dev/null http://localhost:3000/api/tasks/1
grep debug ~/server/app.log | tail -n 1

debug の行が出ます。環境変数を外せば、同じコードのまま出なくなります。 コードを書き換えて回る必要はありません。

書いてはいけない値

わざと危ない値を、上で足した /api/login に渡して確かめます。

bash
$ curl -s -o /dev/null -X POST http://localhost:3000/api/login -H "Content-Type: application/json" -d '{"user":"sato","password":"himitsu"}'
$ grep -i "himitsu" ~/server/app.log

1行も出なければ合格です。 出てしまう典型は、受け取った本文をまるごと出しているときです。

log.info("ログイン", { body: req.body });   // これをやると入る

必要な項目だけを、名指しで出します。

log.info("ログイン", { requestId: req.id, user: req.body.user });

出してはいけないものの目安です。

種類例代わりに出すもの
認証に使えるものパスワード、トークン、cookie出さない
個人を特定できるもの氏名、住所、電話、メール利用者 ID
決済に関わるものカード番号下4桁のみ、または出さない
受け取った本文まるごとreq.body必要な項目だけ名指し

ログは消しにくい場所に残ります。 集約先、バックアップ、外部サービス。1度出したら、全部から消すのは現実的ではありません。 出さないことでしか守れません。

出しすぎの害

量は費用に直結します。 ログを外部サービスへ送る構成では、たいてい取り込んだ量で課金されます。

それ以上に効くのが見落としです。info が毎秒何百行も出ていると、その中の error は見つかりません。「全部出しておけば安心」は、実際には「何も見ていない」と同じになります。

目安として、正常系は「1リクエストに1行」から始めてください。足りなければ足せます。最初から全部出すより、足すほうが簡単です。

つまずいたところ

複数のリクエストの行が混ざって、まったく追えませんでした。 時刻順に読んでも別の処理の行が挟まり、話が繋がりません。requestId を入れた日から、調査の時間が桁で変わりました。

console.log(req.body) でパスワードを出していました。 気づいたのは、ログを集約サービスへ送り始めたあとでした。すでに送った分は消せず、資格情報を作り直すことになりました。

error を出しすぎて、通知を全員がミュートしました。 想定内の入力ミスまで error にしていたためです。「人が何かするか」で決めるようにしてから、通知が機能を取り戻しました。

後片づけ

bash
$ jobs
$ kill %1 2>/dev/null
$ rm -f ~/server/app.log
$ rm -rf ~/server-backup-before-logging

ログファイルは消しても構いません。 書き戻したい場合は、消す前に cp -r ~/server-backup-before-logging/. ~/server/ で戻せます。

まとめ

  • レベルは「誰がいつ見るか」で決める。人が何もしないなら error ではない
  • 1行1件の JSONで出す。値はメッセージに混ぜず、キーで持つ
  • requestId を全部の行に付ける。 混ざった行から1件を抜き出せる
  • 本文をまるごと出さない。 必要な項目だけを名指しで出す
  • 出しすぎは費用と見落としの両方を増やす。正常系は1リクエスト1行から

参考リンク

次に読む

この記事は 【第5段階】バックエンドとデータベース の 8 / 29 本目です。

記事
← 前の記事APIのエラー設計 — 4xxと5xxの分け方と、返す本文の決め方
→ 次の記事パスワードは保存しない — セッションとJWT

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次