Codexにログ調査を頼む前に決めること

3行まとめ

Source

出所。

Time

時刻。

Redact

除外。

Evidence

証拠。

ログ調査では、長さより出どころと時刻の揃い方が重要です。

• Codexにログ調査を頼む時は、長いログ全文ではなく、source、timestamp、相関ID、deploy window、再現条件を揃えたlog packetを渡します。
• secret、顧客情報、内部URL、tokenは渡す前にredactionし、必要な手がかりだけを残します。
• 調査結果は、fact、hypothesis、missing、next actionに分けて受け取ると、要約で終わらず次の作業へつなげやすくなります。

ログは、AIに読ませたくなる情報の代表です。CIが落ちた。productionでerrorが増えた。browser consoleに警告が出た。support ticketに「たまに失敗する」と書かれている。こうした時、Codexにログを渡せば、原因候補を出してくれます。

ただし、ログを丸ごと渡すだけでは、調査が安定しません。長いログには、同じようなエラー、関係ないwarning、secretに近い値、古い実行、別ユーザーの情報、timezoneのずれが混ざります。Codexがきれいに要約しても、どの事実からどの仮説へ進んだのかが追いにくくなります。

この記事では、Codexにログ調査を頼む前に、どんな形でログを渡すかを整理します。障害後のポストモーテムは、公開済み記事のCodexで障害ポストモーテムを下書きする前に決めることで扱いました。ここでは、ポストモーテムより前の「調査開始時に渡すlog packet」に絞ります。

この記事でわかること

Source

種類。

ID

相関。

Secret

除外。

Next

次手。

Codexへ渡す前に、ログを判断材料として扱える形へ整えます。

• ログ調査でsourceを分ける理由
• CI log、app log、browser log、customer signalの扱い方
• timestamp、timezone、request id、deploy windowの揃え方
• Codexへ渡す前にredactionする情報
• log packetに入れるsummary、evidence、question、stop condition
• 調査結果をfact、hypothesis、missing、next actionに分ける方法
• GitHub Actionsでlogs、artifacts、job summaryを証跡として残す考え方
• よくある失敗と避け方

ログ調査の目的は、もっともらしい原因説明を作ることではありません。次に確認すべきことを狭くすることです。

前提知識

項目	内容	見方
Log		時系列。
Artifact		保存物。
Trace		経路。
Signal		報告。

ログは強い手がかりですが、単独で原因を断定しないようにします。

OpenTelemetryのLogs documentationでは、ログは既存のlogging frameworkと連携し、contextual attributesを付けたり、他のsignalsと相関させたりできるものとして説明されています。GitHub Actionsのworkflow logs documentationでは、workflow runのsummaryやjob logsを確認でき、artifacts documentationではbuild logなどのfileを後から見るために保存できると説明されています。

Codex側では、OpenAIのCodex Use Casesに、bug triage、alert monitoring、CI/CD、log sourceやteam scriptを扱うCLI作成などの用途が示されています。つまり、ログ調査はCodexに向いた作業です。ただし、ログには機密や個人情報が混ざるため、渡し方を設計する必要があります。

logは事実そのものではない

ログは強い手がかりですが、事実そのものではありません。

たとえば、timeout と出ていても、原因がnetworkとは限りません。DB lock、queue詰まり、認証失敗、retryの増加、外部API制限、deploy直後のwarmupなど、別の原因でtimeoutに見えることがあります。

Codexには、ログの行を根拠として扱わせますが、原因断定は別にします。

logsとartifactsを分ける

logsは時系列の記録です。artifactsは、実行後に残すfileや成果物です。

GitHub Actionsでは、workflow runのlogを見られる一方で、build結果、test report、coverage、screenshot、core dump、追加のlog fileなどはartifactとして保存できます。調査では、標準logだけでなく、後から見返せるartifactも重要です。

traceやmetricsとの違い

traceは、requestがどのserviceや処理を通ったかを見るのに向いています。metricsは、error rate、latency、throughputなどの傾向を見るのに向いています。logsは、個別eventの文脈を見るのに向いています。

Codexに渡す時は、logだけで原因を決めさせるのではなく、必要ならtrace id、metricの変化、deploy時刻を添えます。

まずsourceを分ける

項目	内容	見方
CI		実行。
App		動作。
Browser		画面。
Customer		報告。

sourceが混ざると、同じエラーに見えても意味が変わります。

ログ調査の最初は、sourceを分けることです。

同じ error でも、CI log、app log、browser log、customer signalでは意味が違います。sourceを混ぜたまま渡すと、Codexは時系列をきれいに並べても、原因候補を絞りにくくなります。

CI log

CI logは、build、test、lint、typecheck、deploy jobなどの実行記録です。

見るべきものは、workflow名、run id、job名、step名、失敗時刻、失敗command、直前の変更、retry有無です。GitHub Actionsなら、workflow run summary、job log、artifact、commit SHA、pull request番号を一緒に見ます。

Codexへ渡す時は、失敗したstepの前後だけでなく、依存install、cache restore、test shard、環境変数の有無も短く添えます。

app log

app logは、アプリケーションが出している記録です。

error level、message、request id、user idの扱い、endpoint、status code、duration、exception type、deploy versionなどを見ます。OpenTelemetryの考え方に寄せるなら、severity、body、attributes、resource情報を分けます。

ただし、user idやpayloadには機密が含まれることがあります。Codexに渡す前に、必要な識別子だけを匿名化します。

browser log

browser logは、frontendの調査に使います。

console error、network error、failed request、CORS、hydration warning、source map、performance issueなどです。ブラウザ側のlogは、画面操作、URL、viewport、login state、network conditionとセットで見ます。

browser logだけでは、server側の原因かclient側の原因か分かりません。request idやresponse headerが取れるなら、app logとつなげます。

customer signal

customer signalは、support ticket、問い合わせ、スクリーンショット、録画、status page反応、SNSの報告などです。

これはログではありませんが、調査の入口になります。顧客情報をそのまま渡さず、時刻、操作、影響、画面名、error文言、再現頻度へ分解します。

時刻と相関IDを揃える

1. 1Time

   時刻。

2. 2ID

   識別子。

3. 3Deploy

   変更。

4. 4Result

   結果。

timestamp、request id、deploy windowを揃えると仮説を絞れます。

ログ調査で一番効くのは、時刻と相関IDです。

長いログを読むより、同じ出来事へ紐づく行を集めるほうが調査は速くなります。

timezone

timezoneは必ず書きます。

CIはUTC、アプリはJST、browserはユーザーのlocal time、monitoringはworkspace設定、support ticketは受付時刻ということがあります。時刻がずれると、関係ないdeployや別のincidentを原因に見てしまいます。

Codexへ渡すpacketには、時刻の基準を1つ決めます。例: 「以下はすべてUTC」「顧客報告はJST、app logはUTC」のように書きます。

request id

request idやtrace idがあるなら、最優先で使います。

request idがあれば、browser、gateway、app、worker、DB周辺のlogをつなげられます。なければ、時刻、endpoint、status code、user segment、deploy versionなどで近似します。

Codexには、「同じrequest idの行だけでまず仮説を出す」「request idがない行は補助情報として扱う」と指示します。

deploy window

deploy windowは、変更が入った時間帯です。

エラーがdeploy直後に増えたとしても、deployが原因とは限りません。ただし、原因候補の優先順位は変わります。commit SHA、release version、feature flag、config change、migration、dependency updateを添えます。

deploy windowを入れると、Codexが「この変更とこのerror pathが関係しそう」と絞りやすくなります。

渡す前にredactionする

Secret

鍵。

PII

個人。

URL

内部。

Token

認証。

必要な手がかりだけを残し、機密や顧客情報は渡す前に除外します。

ログをAIに渡す前に、redactionします。

redactionは、単に伏せ字にする作業ではありません。調査に必要な関係性を残しながら、渡してはいけない情報を除外する作業です。

secret

secretは渡しません。

API key、access token、refresh token、cookie、session id、署名付きURL、private key、password、Authorization headerなどです。abcd... のように一部だけ残すのも避けます。

必要なら、TOKEN_REDACTED_1 のようなラベルに置き換えます。同じtokenらしき値が複数行に出ている場合は、同じラベルで置き換えると相関は残せます。

customer data

顧客情報も渡しません。

氏名、メールアドレス、電話番号、住所、会社名、契約ID、決済情報、自由記述の問い合わせ本文などです。調査に必要な場合は、属性へ落とします。

例: enterprise customer、paid plan、new user、region=jp のように、原因調査に必要な範囲だけ残します。

internal URL

内部URLも注意します。

社内admin URL、非公開dashboard、ticket URL、storage URL、private repo URL、staging hostなどです。必要なら、hostを internal-dashboard.example のように抽象化し、pathやqueryを削ります。

最小化

redactionと同じくらい大事なのが最小化です。

関係ない10万行を渡すより、失敗時刻の前後5分、同じrequest id、同じjob step、同じcustomer segmentへ絞ります。足りなければ追加で渡します。

Codexへ渡すlog packet

項目	内容	見方
Summary		概要。
Evidence		根拠。
Question		問い。
Stop		停止。

ログ全文より、問いと証拠を分けたpacketのほうが調査が安定します。

Codexへ渡すlog packetは、ログの添付ではなく調査依頼です。

目的、範囲、証拠、問い、停止条件を入れます。

summary

summaryには、何が起きたかを短く書きます。

例: 「main branchのCIでunit testだけが失敗する」「checkout後の決済画面で一部ユーザーだけtimeoutする」「deploy後にbrowser console errorが増えた」。

summaryは、原因ではなく現象にします。

evidence

evidenceには、確認済みの根拠を入れます。

ログ行、workflow run URL、artifact名、request id、時刻、commit SHA、再現手順、screenshot、metric変化などです。長いログ全文は別fileへ置き、packetには参照しやすい要点を入れます。

questions

questionsには、Codexに答えてほしい問いを書きます。

「原因は何ですか」だけだと広すぎます。代わりに、「失敗している最初のstepはどれか」「同じrequest idで最初にerrorになったserviceはどれか」「deploy前後で新しく出たerrorはどれか」のように絞ります。

stop condition

stop conditionには、止める条件を書きます。

例: 「secretらしき値が出たら調査を止める」「追加logが必要なら推測で原因断定しない」「外部dashboardへのアクセスが必要なら依頼する」。

調査結果の受け取り方

項目	内容	見方
Fact		事実。
Hypothesis		仮説。
Missing		不足。
Action		次。

要約ではなく、確認済みと仮説を分けた結果を受け取ります。

Codexからの返答は、要約ではなく分類で受け取ります。

おすすめは、fact、hypothesis、missing、next actionです。

fact

factは、ログから確認できる事実です。

「21:03 UTCにjob Xのstep Yがexit code 1で失敗」「request id Aではgatewayは200だがworkerでtimeout」「deploy version 2026.05.31-3以降にerrorが出ている」のように書きます。

factには、根拠行やURLを付けます。

hypothesis

hypothesisは、原因候補です。

仮説は事実ではありません。Codexには、仮説ごとに根拠と反証方法を出させます。

「cache不整合の可能性」「feature flagの対象条件の可能性」「DB connection pool枯渇の可能性」のように出し、次に何を見るかを添えます。

missing

missingは、足りない情報です。

追加で必要なlog、artifact、trace、metric、再現手順、権限、commit diffなどです。missingがあるのに原因断定している場合は、レビューで止めます。

next action

next actionは、次にやることです。

追加logを取る、該当commitを見る、再現testを書く、rollback判断へ進む、feature flagを確認する、ownerに質問する。actionにはownerと確認方法を入れます。

GitHub Actionsで残す証跡

1. Run

   実行。

2. Log

   記録。

3. Artifact

   保存。

4. Summary

   要約。

CIの調査では、ログとartifactを後で追える場所へ残します。

CIのログ調査では、GitHub Actions上に証跡を残すと後から追いやすくなります。

workflow logだけに頼ると、必要なfileやreportが消えたり、長い出力に埋もれたりします。

logs

workflow run logsでは、job、step、command outputを確認できます。

Codexへ渡す場合は、失敗したstepの前後、run URL、job名、commit SHAをまとめます。すべてのlogを貼るより、必要な範囲をartifactに保存するほうが扱いやすいこともあります。

artifacts

artifactsは、workflow run後に残したいfileを保存するのに使います。

test report、coverage、screenshot、browser trace、build log、core dump、generated outputなどです。Codexに調査させるなら、artifact名、保存場所、どのjobで作ったかをpacketに入れます。

job summary

job summaryは、人が見る要約に向いています。

失敗したtest、代表log、artifact link、再現command、次の確認を短く載せます。Codexの調査結果も、PR commentだけでなくjob summaryへ残すと、CI run単位で追えます。

よくある失敗

Full dump

丸投げ。

No time

時刻なし。

Secret

混入。

No ask

問いなし。

長いログだけを渡しても、原因調査ではなく要約で終わりがちです。

よくある失敗は、ログを全部渡すことです。

全部渡せば見落としが減るように見えますが、実際には関係ない情報が増え、機密混入リスクも上がります。

1つ目は、sourceを混ぜることです。CI、app、browser、supportの情報を同じ時系列へ入れる前に、出どころを分けます。

2つ目は、timezoneを書かないことです。時刻がずれると、原因候補が変わります。

3つ目は、secretや顧客情報を伏せずに渡すことです。これは調査効率以前の問題です。

4つ目は、問いを立てないことです。問いがないログ調査は、要約で終わりやすくなります。

FAQ

項目	内容	見方
全部渡す?		絞る。
何分?		窓。
secret?		除外。
原因?		仮説。

迷ったら、誰が同じ証拠で再確認できるかを見ます。

ログはどのくらい渡せばいいですか

まずは、失敗時刻の前後、同じrequest id、同じjob stepに絞ります。

足りなければ追加します。最初から全期間のログを渡すより、調査の問いごとに追加するほうが安全です。

secretが混ざっているか不安な時はどうしますか

渡す前に止めます。

Authorization header、cookie、token、署名付きURL、customer payloadを探し、redactionします。不安が残る場合は、ログそのものではなく、抽象化した表へ変換します。

Codexに原因断定まで任せてよいですか

原因候補の整理までは任せやすいです。

ただし、原因断定は、fact、反証、追加確認、owner reviewを通して行います。特にproduction incident、security、billing、data lossでは、人間が判断します。

ログ基盤が整っていない場合はどうしますか

まず、request id、timestamp、deploy versionを出せるようにします。

完璧なobservability基盤を待つ必要はありません。最低限、同じ出来事を追える識別子と時刻を揃えるだけでも、Codexへ渡す材料はかなり良くなります。

参照した主な情報源

• Codex Use Cases | OpenAI Developers
• Codex | OpenAI
• Using workflow run logs | GitHub Docs
• Workflow artifacts | GitHub Docs
• Logs | OpenTelemetry

次に読むなら

更新履歴

1. 2026.05.31

   初版。

ログ基盤やCIの仕様は、導入時に公式docsで見直します。

• 2026.05.31 初版公開。