UUIDv7/ULIDから障害時刻を復元する実践ログ調査

障害対応で最初に詰まりやすいのは、「いつ壊れたか」を正確に特定できない点である。アプリログが欠けていたり、時刻フォーマットが混在していたり、タイムゾーンが統一されていなかったりすると、初動で判断を誤りやすい。こうした状況でも、IDがUUIDv7またはULIDであれば、ID本体から発行時刻を復元できる。

本記事では、UUIDv7/ULIDから時刻を復元し、一次切り分けを進める実務手順を示す。対象は「すでに生成済みのIDは大量に残っている一方で、時刻付きログが不完全」という現場である。

時刻復元は、下記ツールを使ってブラウザ内で完結できる。

サイト内の時刻復元ツール紹介

本サイトには、障害調査でそのまま使える時刻復元ツールがある。用途に応じて次のように使い分けると、調査の迷いが減る。

UUID v7 Timestamp Extractor

URL: UUID v7 Timestamp Extractor
向いている用途: UUIDv7中心のシステムで、失敗IDが集中した時間ウィンドウ（対象時間帯）を素早く把握したい場合。
できること: UUID v7 から UTC と任意タイムゾーン時刻を復元し、version/variant なども同時に確認できる。

ULID Timestamp Extractor

URL: ULID Timestamp Extractor
向いている用途: フロントや外部連携でULIDを採用しており、障害の時系列を復元したい場合。
できること: ULID先頭の時刻情報を復元し、UTC と業務タイムゾーンを並べて確認できる。

UUID v7 Generator / ULID Generator（検証用）

URL: UUID v7 Generator, ULID Generator
向いている用途: 復元値が正しいかを再現確認したい場合、モノトニック生成の挙動を検証したい場合。
使い方: 任意時刻でIDを生成し、Timestamp Extractorに再入力して往復確認する。

運用上は、まず Extractor で障害の対象時間帯を特定し、次に Generator で再現検証する流れが最も効率的である。

この手法が有効な条件

次の3条件を満たす場合、時刻復元は特に高い効果を発揮する。

主キーやイベントIDとして UUIDv7/ULID を使っている。
障害期間のログが部分欠損している。
どの処理系で詰まったかを数分で絞り込みたい。

一方で、UUIDv4やランダムトークンしか残っていない場合は、この手法を適用できない。

まず押さえる前提

UUIDv7 と ULID はどちらも先頭側にUNIXエポックミリ秒を持つ。
復元できるのは「IDが生成された時刻」であり、「DBコミット時刻」や「外部送信完了時刻」ではない。
同一ミリ秒内に多数生成されたIDは、順序が処理実行順と一致しない場合がある。

この3点を取り違えると、原因調査の優先順位を誤りやすい。

実践手順（一次切り分け）

1. 影響範囲のIDを抽出する

まず、障害に関連するIDを可能な限り集める。例として、注文処理で失敗したID群をCSVに並べる。

id
0194b7f0-7f3a-79d0-8a45-2b4f0c3a912e
0194b7f0-80b1-7b0d-9b6a-1017f0de88a1
01JNW3N9ZSC8M6A0W5C2EJ8P4V
01JNW3NA2J4PK9M2J5X1R3M9TP

2. IDを種別ごとに分ける

ID形式が混在している場合は、UUIDv7とULIDを分離する。最初は厳密な正規化よりも、形式判定を優先すればよい。

UUIDv7: 8-4-4-4-12 の16進、version nibble が 7
ULID: 26文字の Crockford Base32

3. 時刻を復元し、UTCと業務TZの両方で見る

復元時は必ず UTC と業務タイムゾーン（例: Asia/Tokyo）を同時表示する。障害初動では、時差の取り違えが最も起きやすいためである。

4. 5分窓で集計して異常スパイクを見る

復元した時刻を5分単位で集計すると、障害の開始点やピークが見えやすくなる。ログ本文が欠けていても、ID由来の時系列から異常密度を観測できる。

5. インフラ系ログと突き合わせる

復元して得られた対象時間帯を起点に、まず次のログを優先して照合する。

API Gateway / LB の 5xx 増加
DB接続エラー急増
バッチ再実行やリトライ嵐

ここまで進めると、「アプリ起因か、下流起因か」を短時間で切り分けられる。

具体例：30分調査を10分に圧縮したパターン

実際の調査では、次の順で進めると所要時間を短縮しやすい。

失敗ID 2,000件を抽出。
UUIDv7/ULID時刻を一括復元。
09:35〜09:42（JST）に失敗が集中していると判明。
同時間帯のLBログで upstream timeout が増加していると確認。
アプリ改修調査を止め、接続プール設定へ調査軸を切り替え。

この段階のポイントは、根本原因を即断することではなく、「次にどこを疑うべきか」という調査優先順位を正しく置くことである。

落とし穴と回避策

落とし穴1: 生成時刻と業務イベント時刻を同一視する

ID生成が先で、処理完了が後になる設計では、数秒〜数十秒のズレが自然に発生する。監査用途では、必ずアプリ側イベント時刻と突き合わせるべきである。

落とし穴2: 同一ms内の順序を過信する

モノトニック実装でも、並列処理やキュー経由の再整列により、最終順序は崩れうる。厳密な順序保証が必要なら、別のシーケンス項目を持つべきである。

落とし穴3: タイムゾーン変換の誤り

障害報告はローカル時刻、クラウドログはUTCで記録されることが多い。復元時点で両方を固定表示する運用にすると、時刻解釈の事故を防げる。

落とし穴4: クライアント時計ずれを無視する

クライアント生成IDでは、端末時計のずれがそのままID時刻に反映される。NTP非同期端末が混在する環境では、「時刻の絶対値」ではなく「分布の塊」を見るべきである。

実務チェックリスト

UUIDv7/ULIDの採番箇所をシステム境界ごとに棚卸ししたか。
生成時刻と業務時刻を別カラムで持っているか。
調査時に UTC と業務TZを同時表示する運用になっているか。
同一ms多発時の順序保証をIDに依存していないか。
失敗IDをすぐ抽出できるクエリ/導線を準備しているか。

まとめ

UUIDv7/ULIDは、単に「IDを振るための形式」として扱うだけでは価値を十分に引き出せない。障害時に時刻復元へ使える設計にしておけば、ログが欠けた状況でも初動の切り分け速度を上げられる。

結論として、UUIDv7/ULIDは主キー戦略であると同時に、障害調査の観測点でもある。平時から復元手順を定型化しておくことで、インシデント時の混乱を着実に減らせる。