Codexにobservability計装を任せる前に決めること

3行まとめ

Trace

道筋。

Metric

傾向。

Log

証拠。

Alert

検知。

observabilityは、ログを増やすことではなく、判断できる材料を置くことです。

• Codexにobservability計装を任せる時は、trace、metric、log、alertをまとめて「ログ追加」と呼ばず、何を判断したいかから決めます。
• telemetryにはPII、secret、raw payload、高cardinality属性を入れないよう、redaction、属性名、粒度、保持期間をreviewします。
• alertは鳴らして終わりではなく、dashboard、runbook、owner、確認query、改善feedbackまでセットで設計します。

Codexに「ログを足して」「メトリクスを入れて」と頼むと、差分はすぐ出ます。console.logが増える。timerが入る。errorをcatchして送る。spanを作る。dashboardの項目を足す。けれど、障害時に本当に役立つかは別です。

observabilityは、データを増やすことではありません。誰が、何を見て、どの判断をするための材料なのかを決める作業です。問いがないままtelemetryを増やすと、費用、ノイズ、PIIリスク、alert疲れだけが増えます。

この記事では、Codexにobservability計装を任せる前に決めることを整理します。障害後のログ調査は公開済みのCodexにログ調査を頼む前に決めることで扱いました。ここでは、実装時に何を計測するかに絞ります。

この記事でわかること

SLO

目標。

PII

除外。

Cardinality

粒度。

Runbook

対応。

telemetryは、見る人と対応手順まで決めると使える形になります。

• observability計装をCodexへ頼む前に決める6項目
• trace、metric、logの使い分け
• OpenTelemetryのsemantic conventionsをreviewで見る理由
• Datadogなどでlogとtraceを相関させる時の注意
• PII、secret、高cardinality属性を入れない設計
• alert、dashboard、runbookを同時に作る考え方
• Codexへそのまま渡せる依頼packet
• reviewで止めるべき計装差分

この記事は、特定vendorの完全な設定手順ではありません。OpenTelemetry、Datadog、Sentry、Grafana、CloudWatch、New Relicなどで実装は変わります。ここでは、Codexへ依頼する前の共通チェックに絞ります。

前提知識

項目	内容	見方
OTel		標準。
Semconv		属性。
Logs		相関。
Datadog		連携。

trace、metric、logは相互に補完する材料です。

observabilityでは、trace、metric、logを組み合わせて見ます。

OpenTelemetryのDocsでは、semantic conventionsがtrace、metrics、logs、resourcesなどで共通の属性名や意味を定めるものとして説明されています。DatadogのDocsでは、trace IDやspan ID、env、service、versionなどをlogへ入れることでlogとtraceの相関を改善する考え方が説明されています。

trace、metric、logは役割が違う

traceはrequestやjobの流れを追うものです。metricは傾向や閾値を見るものです。logは後から読む証拠です。

この3つを混ぜると、logでlatency分布を見ようとしたり、metricで個別原因を追おうとしたり、traceにpayloadを詰めたりします。Codexへは、どのsignalを足すのかを明記します。

まず問いを決める

計装前に決めるべきなのは、「どのデータを出すか」ではなく「何を判断したいか」です。

たとえば「外部APIが遅いのか、自分たちの処理が遅いのかを分けたい」「queue滞留で通知が遅れているか知りたい」「billing jobの失敗率をSLOで見たい」のように書きます。

計装前に決める6項目

項目	内容	見方
Question		問い。
Signal		信号。
Fields		属性。
PII		除外。
Alert		通知。
Owner		担当。

何を知りたいかを決めずに計装すると、読まれないデータが増えます。

Codexへ頼む前に、6項目を決めます。

項目	決めること	曖昧なまま起きること
question	何を判断したいか	使わないlogが増える
signal	trace、metric、log、event	役割が混ざる
fields	属性名と粒度	検索できない
redaction	PII、secret、payload	情報漏えいになる
alert	閾値、通知先、抑制	alert疲れになる
owner	誰が見るか	鳴っても対応されない

Codexは既存コードに計装を足せますが、SLO、運用体制、保持期間、費用上限、個人情報の扱いは知らないため、人間が渡します。

signalを選ぶ

処理の流れを見たいならtrace。傾向や閾値を見たいならmetric。個別の証拠を残したいならlog。状態変化を履歴にしたいならevent。目的ごとに選びます。

fieldsを固定する

属性名を毎回ばらばらにすると検索できません。service.name、deployment.environment、http.route、error.typeのように、標準や社内命名へ寄せます。

reviewで見ること

reviewでは、PII、secret、raw payload、email、phone、full URL query、user input、cardinalityが高すぎるIDやtagが入っていないかを見ます。

traceは処理の道筋を見る

1. 1Entry

   入口。

2. 2Span

   処理。

3. 3External

   外部。

4. 4Error

   失敗。

5. 5Link

   相関。

traceは、遅い場所や失敗した依存先を追うために使います。

traceは、1つのrequestやjobがどこを通ったかを見るためのものです。

たとえば、checkout APIが遅い時に、認証、DB read、外部決済API、メールqueue投入のどこで時間を使ったかを見ます。HTTP request、DB query、queue job、external API callをspanとして分けると、遅い場所が見えます。

spanを増やしすぎない

細かすぎるspanは読みにくくなります。関数1つごとにspanを作るのではなく、運用上の判断が変わる単位で作ります。

trace contextをつなぐ

外部API、queue、worker、background jobをまたぐ場合は、trace contextをつなぎます。つながらないと、request側とworker側をtimestampで手作業照合することになります。

注意点

span attributeにraw request bodyやtokenを入れないでください。traceは便利ですが、共有されやすい画面に出ることもあります。

metricは傾向とSLOを見る

項目	内容	見方
Latency		遅延。
Error		失敗。
Rate		量。
Saturation		逼迫。

metricは個別の証拠ではなく、傾向と閾値を見る材料です。

metricは、個別の証拠ではなく、傾向を見るためのものです。

latency、error rate、request rate、queue depth、retry count、saturation、success ratio、p95/p99などを見ます。SLOやalertの材料になるのはmetricです。

metric名とlabelを決める

metricは名前とlabelが命です。payment_request_durationのような名前だけでなく、provider、operation、environmentなどのlabelを決めます。

ただし、user ID、request ID、email、raw pathなどをlabelにするとcardinalityが爆発します。

SLOとつなげる

metricは「見たい数字」ではなく「判断する数字」にします。p95 latencyが何msを超えたら影響ありか。error rateが何%を超えたらincidentか。queue depthがどれくらいで対応が必要かを決めます。

条件

Codexへは、metricを足すだけでなく、unit、aggregation、label、alert候補、dashboard表示まで書かせます。

logは証拠として残す

Event

出来事。

Context

文脈。

Reason

理由。

Safe

伏せる。

logは検索できる証拠ですが、payload丸ごと保存ではありません。

logは、後から読む証拠です。

「何が起きたか」「なぜその分岐に入ったか」「外部APIが何を返したか」「どのjobが失敗したか」を残します。ただし、payloadを丸ごと残すものではありません。

structured logにする

可能ならstructured logにします。messageだけではなく、operation、status、error_type、attempt、duration_ms、correlation_id、trace_idをfieldとして持ちます。

levelを分ける

debug、info、warn、errorを分けます。正常系をerrorで出すとalertが汚れます。失敗をinfoにすると見逃します。

reviewで見ること

console.log(error)でerror objectを丸ごと出していないか、request headerやauthorizationを出していないか、user inputをそのまま出していないかを見ます。

alertとdashboardを同時に設計する

1. Detect

   検知。

2. Route

   通知。

3. Inspect

   確認。

4. Runbook

   対応。

5. Review

   改善。

alertは鳴らすことより、誰が何を見るかを決めることが大事です。

alertは、鳴らすことより、鳴った後に何を見るかが大事です。

alertだけ作ってdashboardがないと、通知を受けた人が調査を始められません。dashboardだけ作ってalertがないと、誰も見ていない画面になります。runbookがないと、初動が人によって変わります。

alertの条件

alertには、閾値、window、通知先、重要度、抑制条件、対応owner、runbook linkを入れます。

dashboardの条件

dashboardには、関連metric、trace sample、error log、deploy marker、feature flag、外部provider status、直近変更を入れます。

評価基準

alertを見た人が、5分以内に「影響範囲」「原因候補」「次に見る画面」を判断できるなら、良い設計です。

redactionとcardinalityをreviewする

項目	内容	見方
PII		除外。
Secret		禁止。
User ID		注意。
Path		正規化。
Tag		粒度。

属性は便利ですが、入れ方を間違えると費用とリスクが増えます。

telemetryは便利ですが、入れすぎると危険です。

PIIやsecretが入ると情報管理の問題になります。cardinalityが高すぎる属性をlabelにすると、費用や性能に影響します。raw URL、email、user ID、request ID、order ID、free textをmetric labelへ入れるのは避けます。

PIIとsecretを入れない

email、phone、address、token、cookie、API key、authorization header、session ID、raw payloadはtelemetryに入れません。必要ならhashや分類値へ置き換えます。

pathやerrorを正規化する

/users/123/orders/456をそのままlabelにすると高cardinalityになります。/users/:userId/orders/:orderIdのようにroute patternへ正規化します。

Codexへ渡す依頼packet

項目	内容	見方
Question		問い。
Signal		信号。
Fields		属性。
Tests		確認。
Owner		担当。

packet化すると、Codexの計装差分をreviewしやすくなります。

Codexへは、次のようなpacketで渡します。

目的:
  外部決済API呼び出しが遅い時に、自社処理とprovider遅延を分けて見たい。

signal:
  trace: checkout requestからpayment provider callまでspanをつなぐ。
  metric: provider別のdurationとerror rateを出す。
  log: provider call失敗時だけstructured logを残す。

fields:
  service, environment, operation, provider, status, error_type, duration_ms, trace_id。

禁止:
  email、user name、card情報、token、raw request body、raw response bodyをtelemetryへ入れない。
  metric labelへuser_idやrequest_idを入れない。

alert:
  provider error rateが5分で5%を超えたらwarn。
  p95 latencyが10分続けて閾値超過したらpage候補。

tests:
  success、timeout、429、5xxでtrace、metric、logが出ることを確認する。

review:
  span粒度、metric label、redaction、dashboard、runbook linkを見る。

このpacketがあると、Codexは「ログを増やす」ではなく「判断できるtelemetryを足す」方向に進みやすくなります。

よくある失敗

Log all

丸ごと。

No trace

相関なし。

High card

粒度過多。

No owner

担当なし。

計装の失敗は、障害時に初めて読みにくさとして返ってきます。

payloadを丸ごとlogに入れる

調査しやすそうに見えますが、PIIやsecretが混ざる可能性があります。必要なfieldだけ残します。

metric labelへIDを入れる

user ID、request ID、order IDをlabelにするとcardinalityが増えすぎます。metricには分類値を入れ、個別調査はtraceやlogへ寄せます。

alertを増やすだけでownerがない

誰が見るか決まっていないalertは、結局無視されます。owner、通知先、runbookを決めます。

traceとlogが相関しない

trace IDやcorrelation IDがないと、障害時に画面を行き来して手作業で探すことになります。trace/log correlationを入れます。

dashboardがリリースとつながっていない

deploy markerやversionがないと、直近変更との関係が見えません。service、version、environmentを入れます。

FAQ

項目	内容	見方
Trace?		流れ。
Metric?		傾向。
Log?		証拠。
Alert?		対応。

迷ったら、そのtelemetryで次の行動が変わるかを見ます。

trace、metric、logのどれを足せばよいですか

処理の流れを見たいならtrace、傾向や閾値を見たいならmetric、個別の証拠を残したいならlogです。迷ったら、障害時にどの判断をしたいかから選びます。

OpenTelemetryを使うべきですか

vendorをまたいで共通の考え方で計装したい場合は有力です。ただし、既存stack、SDK対応、collector運用、sampling、費用を見て判断します。

logは多いほど良いですか

違います。読まれないlog、検索できないlog、PIIを含むlog、高費用のlogは逆効果です。必要な証拠をstructuredに残します。

alert閾値はCodexに決めさせてよいですか

仮置きはできますが、最終判断はSLO、traffic、運用体制、過去のincidentで決めます。Codexには候補と根拠、未確定項目を出させます。

dashboardまで作らせるべきですか

可能なら作らせます。alertだけでは初動に困るため、dashboard、query、runbook linkまでセットでreviewします。

次に読むなら

参照した主な情報源

• OpenTelemetry: Semantic Conventions
• OpenTelemetry: Semantic Conventions 1.41.0
• OpenTelemetry Specification
• Datadog Docs: Correlate Logs and Traces
• Datadog Docs: Correlate OpenTelemetry Traces and Logs

更新履歴

1. 2026.06.01

   初版。

observabilityの仕様やprovider機能は変わるため、導入時に公式Docsを確認します。

• 2026.06.01: 初版公開。Codexへobservability計装を任せる前のtrace、metric、log、alert、redaction、cardinalityを整理しました。