Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
8.2 KiB
Seheweit のリソース収集と履歴契約
2026-11-01、リソース収集と履歴の期間・保持ルールを internal/seheweit に初期分離した。
現在値APIとバックグラウンド監視は同じ収集実装を使う。Seheweitは観測を担当し、
ジョブの実行制御・認可・DBトランザクション・表示は呼出し元に残す。
これで採用した8部品の初期分離が揃うが、各部品の後続機能が完了したことは意味しない。
コンポーネント命名 と システム拡張 を併読する。
責務と接続
| 部品 | 責務 |
|---|---|
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拒否、認可、設定保持を検証する。 実行記録は コンポーネント検証記録 に記載する。 本番DBや取り込み済み外部カレンダーにアクセスせず、commit・push・本番展開は別段階とする。