# Seheweit のリソース収集と履歴契約 2026-11-01、リソース収集と履歴の期間・保持ルールを `internal/seheweit` に初期分離した。 現在値APIとバックグラウンド監視は同じ収集実装を使う。Seheweitは観測を担当し、 ジョブの実行制御・認可・DBトランザクション・表示は呼出し元に残す。 これで採用した8部品の初期分離が揃うが、各部品の後続機能が完了したことは意味しない。 [コンポーネント命名](component-names.md) と [システム拡張](../system-extensions.md) を併読する。 ## 責務と接続 | 部品 | 責務 | | --- | --- | | `seheweit.Collect` | Go runtime、load average、プロセスI/O、Document Rootの容量を型付きSnapshotへ収集 | | `seheweit.ParseProcessIO` | 実ストレージ読み書きの累積値と、プロセス単位の識別子・取得可否 | | `seheweit.Window` / `RetentionCutoff` | 期間・bucket幅・保持境界。SQLやDB接続は持たない | | server | 管理権限の検査、キュー状態の読込、実行中worker数、HTTP応答、監視handlerの登録 | | store | 既存SQLiteへの保存・期限切れ削除・履歴query。schemaの所有は移さない | | Dregarnuhr | 監視イベントの実行時刻・claim・worker制御。観測結果から仕事を勝手に停止しない | | 設定画面 | ライブ値・履歴グラフ・実行中ジョブの表示、I/O差分速度の計算 | server/store → seheweit の一方向依存とする。Seheweitからserver/store/DBは参照しない。 文書内容・認証情報・ジョブpayload・外部カレンダーを読まない。 ネットワーク接続、shell、ディレクトリ再帰走査、独自の定期loopは追加しない。 Queueは呼出し元から渡す観測値だけであり、停止・再開・再試行のコールバックではない。 ## 収集値と互換性 `Snapshot` のJSONは既存の `timestamp_ms`、`io`、`cpu`、`memory`、`storage`、`queue` を維持する。 従来のmapを型付きstructへ置換し、背景保存時のtimestamp型assertionをなくす。 旧 `processIOCounters` はalias、parserは委譲とし、取得ロジックを二重に持たない。 | 観測値 | 意味と制限 | | --- | --- | | CPU | Go runtimeの論理CPU数と `/proc/loadavg` の先頭3値。CPU使用率やcgroup上限ではない | | メモリ | Go heap、Go system bytes、GC回数、goroutine数。RSSやホスト全体の使用量ではない | | 容量 | Document Rootに対するStatfs。使用量は従来のtotal−Bavailで、予約領域も含む | | I/O | `/proc/self/io` のread_bytes/write_bytes。rchar/wcharやデバイスIOPSとは別 | | キュー | queued/running件数、プロセス内active worker数、paused。履歴ジョブ全件は取得しない | procファイルの読込は各16KiBまで。超過・読込失敗時は部分データを採用しない。 Statfsの失敗、非正のblock size、BavailがBlocksを上回る値、乗算overflowは容量0へ落とす。 符号なし減算で巨大な使用量を作らない。絶対Pathへの解決失敗時も空Pathへ上書きしない。 I/O取得失敗は `available=false`。プロセスIDはプロセス起動ごとのランダムUUIDを共有し、 collectorの呼出しごとには変えない。PID 1の再利用と、同一プロセス内の複数呼出しを区別する。 既存のブラウザ計算は、再起動・カウンタ減少・時刻逆転・欠測・JS安全整数超過を速度0にせず欠測にする。 並行収集では可変の共有Snapshotを使わない。 容量失敗時の0、load取得失敗時の空文字、キュー読込失敗時のゼロ値は既存互換のfallbackである。 I/O以外の取得失敗を正常値と区別するavailability契約は後続とする。 各情報源は順番に採取し、DB・runtime・OSを跨ぐ同一瞬間のsnapshotではない。 ## 背景保存と履歴 イベントID `builtin.resource.sample`、型 `resource.sample`、既定60秒、許可範囲30〜86400秒、 priority 100とmax attempts 1を維持する。設定済みのenabledとintervalは起動時に上書きしない。 画面のライブ更新既定1秒と、背景の永続化既定60秒は別の周期である。 保存は `resource_samples` の既存schemaを使う。job_uuidの一意性で同一jobの重複登録を防ぎ、 挿入と7日より古い行の削除を同一transactionに置く。既存行のpayloadをretryで上書きしない。 保持境界は今回の採取timestampから7日前。境界と同じtimestampは残す。 retryで挿入を無視しても、その採取時刻で清掃する既存動作は維持する。 `SaveResourceSampleContext` は取消contextをBeginTx・各SQLへ渡す。 監視handlerは取消済みなら収集を始めず、保存時もcontextを引き継ぐ。 read-only Storeでは保存を拒否する。旧 `SaveResourceSample` はBackground contextで委譲する。 清掃失敗時には挿入もrollbackし、半端な成功を返さない。 contextはDB待機を中断できるが、実行中のStatfs等を強制停止する仕組みではない。 履歴APIは `GET /_/api/v1/queue/resources/history?hours=1|24|168` のまま。 UIの期間既定1時間と選択の記憶、APIの未指定・不正値時の24時間fallbackは変えない。 内部Windowは1〜168時間へ制限し、幅は期間/360か最低1分、epoch基準でbucketを切る。 期間両端を含み、最大361点を返す。空履歴は `[]`、retention_daysは7を維持する。 bucket代表は既存SQLの `MAX(id)`、つまり最後に挿入された行である。 時刻の順序が逆転した入力では最大timestampの行とは限らず、平均・最大値・ピークでもない。 期間はtimestamp索引で絞るが、361という上限は返却点数であり走査行数の固定上限ではない。 現在値GETは収集だけ、履歴GETは読込だけで、どちらも保存や補間を行わない。 ブラウザを閉じても背景イベントは止まらず、監視無効化・キュー停止では新規採取を止める。 ## 権限と配置 既存queue APIの管理権限を維持し、新しい公開endpointやDomain間共有を追加しない。 応答は引き続き `Cache-Control: no-store`。リソースはインスタンス全体の情報なので、 個々の文書の公開権限とは分けて扱う。URI・設定キー・schema・保存済みJSONの移行は不要。 追加コンテナや監視サービス、外部送信先の導入も行わない。 ## 後続TODO - [ ] 各情報源のavailability・診断コード・取得時刻を追加し、旧履歴とUIを互換移行する。DB失敗を空キューに見せない。 - [ ] foreground多重要求の短時間共有と収集予算を設ける。runtime読込や遅いマウントのStatfsを計測し、画面要求を待たせない。 - [ ] キュー状態読込へのcontext伝播と一貫性、観測API専用のinstance_operator権限を整理する。 - [ ] 大量履歴の保持清掃を分割し、粒度別rollup・平均/最大/欠測数・容量予算を設計する。返却点数の制限だけで走査負荷は保証しない。 - [ ] component/provider別の件数・失敗・待機時間・実行時間を低cardinalityで追加する。共有GoプロセスのCPU/RAMを根拠なく按分しない。 - [ ] cgroup、デバイスI/O、外部adapterプロセスを独立scopeで観測する。現在のprocess I/Oと混合しない。 - [ ] HAのinstance UUID・boot ID・node別収集・集約を定義する。現行process_idは永続instance identityではない。 - [ ] SNMPv3 collectorを任意機能として追加する。接続先・OID許可、秘密管理、timeout、再試行、counter resetを別途検証する。 ## 検証と反映 合成counter・注入clock・一時DB・localhostのブラウザfixtureで、wire互換、収集失敗、容量の異常値、 I/O識別、並行収集、保持境界、idempotence、rollback、取消、read-only拒否、認可、設定保持を検証する。 実行記録は [コンポーネント検証記録](component-names.md#検証記録) に記載する。 本番DBや取り込み済み外部カレンダーにアクセスせず、commit・push・本番展開は別段階とする。