トラブルシューティング (症状 → 診断 → 修正)

各エントリは同じ形式に従います: 目にする症状、それが何かを確認する方法、そして修正です。引用されているログ行はエンジンの実際の文字列なので、grep で検索できます。より詳細な runbook が存在する場合、エントリはそれを再導出するのではなく、関連ページへリンクします。

初回起動とセットアップ

セットアップトークンを見逃した

再起動しても 再表示はされません (トークンのハッシュのみが、データディレクトリの setup.token に保存されます)。まだユーザーが存在しないあいだは、復旧は安全です: エンジンを停止し、setup.token を削除して起動します — 新しいトークンが発行され、表示されます。これはユーザーが存在しないインストールでのみ機能するため、乗っ取りの経路にはなりません。トークンは stdout のみ に出力されます (systemd では journal、 Docker/Kubernetes ではコンテナログ) — ログファイルには決して出力されません。

`=== FIRST-BOOT SETUP ===` が一度も表示されない

そのデータディレクトリにはすでにユーザーが存在します — 初回起動ではありません。既存の管理者でログインするか、本当に新規で始めたい場合は、新しい --data-dir を使ってください。

エンジンが初回起動時に鍵について警告する

generated a new audit signing key; back it up path=/var/lib/olivares/audit-signing.key
generated a local TLS certificate; clients must trust it, or pin it with --pin-sha256=<pin_sha256> (that value, verbatim) cert=/var/lib/olivares/tls.crt cert_fingerprint_sha256=d38567e8…378c4e7f pin_sha256=JsdrhrY77Me8miAmobJsqamE3NDWIOSBrDTwbHkyCD0

どちらも意図的なもので、最初のものが後で問題になります: 強制されたエスクローは存在しません — 今すぐ audit-signing.key をボックス外にコピーし、公開鍵 (GET /v1/audit/pubkey) をボックス外でピン留めしてください。さもないと、将来ホストが侵害された際に、自分自身の ledger を証明できなくなります (バックアップと復元)。

TLS の行は 2 つ のダイジェストを出力し、両者は交換できません。 cert_fingerprint_sha256 は証明書のダイジェストで、ブラウザーが表示するものです。 pin_sha256 はリーフ証明書の SPKI のダイジェストであり、--pin-sha256 が比較するのはこちらだけです。その値をそのままコピーしてください:

olivares status --server https://127.0.0.1:8443 \
  --pin-sha256 JsdrhrY77Me8miAmobJsqamE3NDWIOSBrDTwbHkyCD0

代わりに証明書フィンガープリントをピン留めしても、不正なフラグ値としては失敗しません。形式として正しい 32 バイトのダイジェストなので、接続が試みられたうえで TLS SPKI pin mismatch で拒否され、そのエラーが本来使うべき値を示します。 curl --pinnedpubkey sha256//… を使う場合は、末尾の = パディングを補ってください。エンジンは意図的にパディングなしの base64 を出力します（ログ上で引用符が付かず、コピー＆ペーストで壊れないため）が、curl はパディング付きの形式を要求します。

ホストインストールの診断

生成 CLI リファレンスは olivares doctor を次のように記述します: diagnose this host installation without printing secrets （CLI）。フラグは --data-dir, --mode (auto | user | system), --init (auto | systemd | openrc | launchd), --config, --unit, --binary, --server, --timeout, --ca-cert, --audit-tenant, --check-updates です。この表を追加のヘルプ文として扱わないでください。それが生成コマンドです。

`agentops-layout` check

olivares doctor は agentops-layout という検査を報告します（CHANGELOG.md [26.9.0]、cmd/olivares/cmd_doctor.go doctorAgentOpsCheck）。サブコマンドではありません。所有マニフェストが記録するネイティブ AgentOps レイアウトを測ります: 管理 drop-in はその mode で存在し、記録された claude HOME、トークンディレクトリ、ワークスペースを名付ける必要があります。runtime env は設定 mode 付きで存在する必要があります（値は読まれません）。ワークスペースはディレクトリでなければなりません（docs/RELEASE-INSTALLER.md）。

検査が返すステータス:

Status	When
`not_applicable`	no readable manifest; malformed manifest; or the manifest records no AgentOps files (`dropin`, `runtime-env`, `workspace_dir` all empty)
`fail`	drop-in does not reference a recorded token (`$dataDir/claude-home`, `$dataDir/run`, or `workspace_dir`); workspace path is absent or is not a directory
`unknown`	drop-in or workspace is not readable
`pass`	drop-in, runtime-env (values not read) and workspace directory agree with the record

マニフェストが AgentOps ファイルを少なくとも 1 つ記録するまで Required は false です。その後検査は required です。エンジンが印刷する修復文字列には rerun install-agentops.sh; the managed drop-in and the recorded layout disagree と recreate the recorded workspace or rerun install-agentops.sh with OLIVARES_WORKSPACE_DIR が含まれます。

テキストも -o json もキー名とパスを含み、設定値は含みません（docs/RELEASE-INSTALLER.md）。

ソースと access map

map が空である

まず、何かが結線されているかを確認します。エンジンは起動時に明示的にそう述べます:

ingest: no observation sources configured (OLIVARES_SOURCES_CONFIG.sources is empty); no connector will ingest — the estate runs on no live traffic

ソース設定を指定するとエンジンが起動しない

OLIVARES_SOURCES_CONFIG が、存在しないファイル、読み取れないファイル、または無効な JSON ファイルを指定している場合、olivares serve は終了コード 1 で終了します。refusing to start instead of silently omitting operator configuration を含む起動エラー load sources operator config: OLIVARES_SOURCES_CONFIG を探してください。サービスやコンテナから見たパスを確認し、実行ユーザーがファイルを読み取れることを確かめ、JSON を検証して再起動してください。このファイルエラーは起動を阻止するため、エンジンが空の map で動作し続けることはありません。

起動が成功すると、ソースごとに ingest: wired source … kind=… と表示されます。構築に失敗したソースは、その理由とともに ingest: failed to register in-process source; not wired を出力します。

pgAudit は結線されているが edge が届かない

ほぼすべてのケースを 3 つの原因がカバーし、いずれも設計上のものです (pgAudit ガイド):

サーバーが UTC でログを記録していない。 UTC 以外のゾーン略称を持つレコードは、誤ったタイムスタンプを付けるのではなく スキップ されます — log_timezone = 'UTC' を設定してください。
csvlog はバッチであり、tail ではない。 follow は jsonlog にのみ適用されます。 csvlog ソースは継続的にではなく、各実行時に ingest します。
監査対象のクラスがオフになっている — pgaudit.log に read, write が含まれているか確認してください。

すべてが drift として表示される

新規インストールでは想定どおりです: grant が一切宣言されていないため、観測されたすべてのアクセスは正直なところ「予期しない」ものです。これはバグではなく、開始状態です — 意図する grant を宣言してトリアージしてください。

可用性

`/readyz` が 503 を返す

ボディを読んでください。503 は ready ではなく、成功でもありません。/livez が 200 のままなのはプロセスが生きていることだけを意味し、/pod-readyz が 200 のままなのは pod の健全性（ストア到達）だけを意味します。リーダーシップ検査も初回起動の能力プローブもありません。どちらも、/readyz をコンテナの readinessProbe として配線するデフォルト Helm chart やフラットマニフェストのロールアウトを解除しません。

{"status":"unavailable","store":"down"} — ストアに到達できません。SQLite の場合: ディスク満杯、PVC の問題、ファイルパーミッション。Postgres の場合: 到達性と認証情報。 liveness は意図的に通り続ける ため (プロセスは生きている)、ストア障害で再起動ループに陥るものはありません。ストアを修正した後も詰まったままなら、 pod/サービスを手動で再起動してください。
{"status":"standby","store":"up","leader":false} — HA standby が正直に応答しています。エラーではありません: Service はリーダーへルーティングし、standby は設計どおり drain します。すべての レプリカが standby を報告する場合、リーダー選出が詰まっています — Postgres の advisory-lock 接続を確認してください。
{"status":"setup_blocked","store":"up","leader":true,"setup_required":true,"code":"cross_tenant_admin_pool_not_configured"} — PostgreSQL の初回起動が組織を権威ある形で列挙できません。 NOSUPERUSER BYPASSRLS の管理ロールと --admin-dsn をプロビジョニングしてください（Kubernetes 上の Postgres）。ボディには固定の対処が入ります。その前提が直るまで、デフォルトの readiness プローブは pod を Not Ready のままにします。これを隠すためにプローブを差し替えてはいけません。
{"status":"setup_unavailable","store":"up","leader":true,"code":"setup_state_unavailable"} — このノードはインストールがセットアップ済みかを観測できませんでした。値が未知のため setup_required は省略されます。これは既知の空インストールではありません。
{"status":"setup_unavailable","store":"up","leader":true,"setup_required":true,"code":"setup_probe_unavailable"} — インストールは未セットアップと分かっていますが、初回起動の能力プローブが管理プール拒否以外の理由で失敗しました。タイムアウトは空のエステートの証拠ではありません。

200 {"status":"ok",…,"setup_required":true} は別の観測です: 初回セットアップを試せます。POST /v1/setup は権限検査を繰り返します。その 200 は可用性予算を消費しません。これらの 503 は消費します。

pod が死んだのに何も引き継がれない

デフォルトの単一レプリカ トポロジーでは自動フェイルオーバーはありません — 復旧は StatefulSet の再スケジューリングと RWO ボリュームの再アタッチです (Multi-Attach エラーに注意。ボリュームは復旧をその AZ に固定します)。自動フェイルオーバーは HA トポロジー (Postgres + レプリカ + 共有署名鍵) の特性です。永続化を無効にして本番を運用してはいけません: emptyDir は再スケジューリングのたびに署名鍵を失います。

パフォーマンス

Ingest レイテンシの p99 が上昇している (バックプレッシャー)

バスは ドロップせずブロックします — olivares_ingest_duration_seconds の p99 上昇は、データ損失ではなく、サブスクライバーが飽和していることを示す設計どおりのシグナルです。原因を直接特定します:

olivares_eventbus_queue_depth / olivares_eventbus_queue_capacity > 0.9

サブスクライバーごとのラベルが遅いモジュールを指し示します。 olivares_eventbus_publish_blocked_total はバックプレッシャーイベントをカウントします。よくある根本原因は ストアの書き込みスループット (SQLite の単一ライター上限) です — これはチューニングのつまみではなく、容量の修正です (Postgres に移行するか、書き込み増幅を減らす)。遅い出力コネクター (webhook、SIEM) を同期サブスクライバーにしてはいけません。

分散バスを有効にしている場合 (OLIVARES_BUS_CONFIG)、ノード間ブリッジが 最大 1 回 (at-most-once) であることを忘れないでください: 飽和したブリッジは olivares_eventbus_bridge_pending_messages を満たし、その後 リモートイベントをドロップ します。これは olivares_eventbus_bridge_dropped_total でカウントされます — 増加があればアラートを発し、olivares_eventbus_bridge_connected == 0 になったら呼び出してください。

ログインが「locked out」で失敗する

olivares_auth_login_attempts_total{outcome="locked_out"} の上昇は、繰り返しの失敗の後にスロットルが試行を拒否したことを意味します。自身の繰り返しの失敗でロックされたアカウントか、失敗が続くクライアントアドレスがすでに試していたアカウントです。履歴のきれいなアカウントが、同じアドレスからの他者の失敗でロックされることはありません。代わりに 1 秒待ちます。いずれも自動的に解除されます。上限を引き上げるのではなく、失敗の発生源を調査してください。

証跡

ledger が検証に失敗する

まず、何を実行したかを把握してください: デフォルトの audit verify は チェーンが失敗しても 0 で終了します (結果は JSON レポートに含まれます) — 自動化では --strict を使うか、レポートをパースしなければなりません:

olivares audit verify --tenant $TENANT --data-dir /var/lib/olivares --strict \
  --pubkey <BASE64-PINNED-OFF-BOX>

ボックス外 の公開鍵をピン留めしてください: ピンがない場合、検証器は (侵害された可能性のある) ホストから読み取った鍵を信頼します — 参考のチェックとしては問題ありませんが、改ざんの証拠としては不十分です。次に reason フィールドで分類します:

Reason	クラス	対応
`hash-mismatch`, `prev-mismatch`, `head-mismatch`, `tail-truncated`	改ざんまたは切り詰め	SEV1 として扱う: ボックスを保全し、ボックス外のチェックポイントと突き合わせる
`checkpoint-sig-invalid`, `checkpoint-link-mismatch`, `event-sig-invalid`	改ざんまたは誤った鍵	鍵管理の取り違えを証明できない限り SEV1
`seq-gap`	削除または復元の不整合	改ざんと騒ぐ前にボックス外のチェックポイントと比較する
`event-sig-missing`	署名が有効化される前のレガシーレコードの可能性	有効化境界で `--from` を使って範囲を限定する。境界より前の不在は想定どおり

素朴な walk は通過するが、ピン留めしたボックス外のチェックポイントと一致しない復元済みバックアップは、復元アノマリーのケースです — その比較こそがピンが存在する理由です。

`olivares_audit_checkpoint_age_seconds` が増え続ける

チェックポイントの書き込みが停止しています (デフォルトの間隔は 1h。 OlivaresAuditCheckpointStale は 2h で発火します)。エンジンログでチェックポイントのエラーを、ストアの書き込み可能性を確認してください — 増えているあいだ、あなたの改ざん証跡のアンカーは古くなっていきます。

通知とシンク

宛先が何も受信しない

不明な kind を持つ宛先は スキップされ、ログに記録されます (notify: destination has unknown connector kind; skipped — kind のスペルを確認してください)。イベンティングのシンクについては、POST …/subscriptions/{id}/test が観察できる配信を送り、エンドポイントは HTTPS でなければなりません (SIEM へプッシュする)。

症状がここになく、エンジン自身のメッセージでも説明がつかない場合、それはドキュメントのバグです — そのログ行を添えて報告してください。