ログは、障害が起きてから足すものではありません。起きたときには、もう手遅れです。
再現しない不具合を調べるとき、手元にあるのはそのとき残った文字だけです。何も出していなければ、推測するしかありません。逆に、全部出していると1日で数GBになり、肝心の1行が埋もれます。
この記事では、前の回で作った API にログを入れて、レベルで出し分け、あとから1件の処理だけを追える状態にします。集めて画面で見る仕組み(Loki など)は後の回で、ここでは「何を、どう出すか」だけを決めます。
対象レベル: 初級〜中級 / 区分: 必修
この記事でわかること
- ログレベルが「重要度」ではなく「誰が、いつ見るか」で決まること
console.logのままだと、あとで機械に読ませられないこと- 1件の処理を横断して追うための IDの付け方
- ログに書いてはいけない値と、その避け方
- 出しすぎると、費用と見落としの両方が増えること
この記事でやること
- いまの出力を見て、あとから追えないことを確かめる
- レベルを4つに決めて、環境変数で出す量を変える
- 1行1件の JSON で出す(構造化ログ)
- リクエストごとの ID を付けて、1件の処理だけを抜き出す
- わざとパスワードを渡して、出ないことを確かめる
先に知る言葉
この記事で初めて出てくる言葉です。 詳しくは用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| ログレベル | 誰がいつ見るかで分ける区分。error/warn/info/debug |
| 構造化ログ | 1 行 1 件をJSON など機械が読める形で出すこと |
| 標準出力 / 標準エラー出力 | プログラムの2 つの出口。 分けておくと後で振り分けられる |
| requestId | 1 回の処理に振る番号。混ざった行から 1 件だけ抜き出せる |
| マスキング | 秘密の値を出さない・伏せること |
前提と作業場所
VM の中(Ubuntu Server)で打ちます。 前の回で作った ~/server がある前提です。データベースには触りません。
作業前にコピーを取ります。
いまの出力では追えない
よくあるのは、こういう行です。
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 で出す
人が読む形と、機械が読む形は違います。ログは、最終的に機械が検索します。
// 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つ振り、その処理から出る全部の行に付けます。
// 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 が使えません)。
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件だけを抜き出せます。
動かして、追ってみる
出た行を見ます。
{"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件だけを抜き出せます。
これが目的でした。 何十人分の行が混ざっていても、1つの ID で、その処理だけが並びます。
機械に読ませることもできます。
/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 に渡して確かめます。
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 にしていたためです。「人が何かするか」で決めるようにしてから、通知が機能を取り戻しました。
後片づけ
ログファイルは消しても構いません。 書き戻したい場合は、消す前に cp -r ~/server-backup-before-logging/. ~/server/ で戻せます。
まとめ
- レベルは「誰がいつ見るか」で決める。人が何もしないなら
errorではない - 1行1件の JSONで出す。値はメッセージに混ぜず、キーで持つ
requestIdを全部の行に付ける。 混ざった行から1件を抜き出せる- 本文をまるごと出さない。 必要な項目だけを名指しで出す
- 出しすぎは費用と見落としの両方を増やす。正常系は1リクエスト1行から
参考リンク
次に読む
この記事は 【第5段階】バックエンドとデータベース の 8 / 29 本目です。
| 記事 | |
|---|---|
| ← 前の記事 | APIのエラー設計 — 4xxと5xxの分け方と、返す本文の決め方 |
| → 次の記事 | パスワードは保存しない — セッションとJWT |
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。

コメント