Files
pages/docs/design/ja/seheweit.md
T
Anya Tokugawa d5d21b7841
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s
Refactor architecture into eight components and consolidate reliability work
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.
2026-11-01 15:23:31 +09:00

105 lines
8.2 KiB
Markdown

# 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・本番展開は別段階とする。