VersionLog の運用

このページは、VersionLog を有効にしたエンジンを本番運用する場合や、復旧、サイドカー、保持処理、並列キューの挙動を診断したい場合に読むページです。

運用時に見る値

VersionLog の状態は主に AkkEngine::stats().vlog から確認します。統計は best-effort の診断スナップショットであり、トランザクションとして一貫した読み取りではありません。

フィールド	意味	対応
recoveryDurationMicros	直近の復旧処理の所要時間です。	起動時間の悪化を追い、セグメント数とエントリ数と比較します。
recoveredSegmentCount, recoveredEntryCount	復旧処理が受け入れたセグメント数とエントリ数です。	予期しない減少は、保持処理、永続化済み末尾の切り詰め、復旧失敗を疑います。
segmentCount, activeSegmentBytes	現在のセグメント数とアクティブセグメントのサイズです。	履歴ストレージが増えすぎる場合は segmentBytes と保持設定を調整します。
sidecarFallbackCount	.akvidx を使えず、正本であるセグメント走査にフォールバックした問い合わせ数です。	増え続ける場合、正しさは保たれますが読み取りが走査に劣化している可能性があります。
sidecarRebuildFailures	可能な範囲で試みたサイドカー書き込みが失敗した回数です。	権限、ディスク容量不足、ウイルス対策ソフトやファイルロック、ファイルシステムエラーを確認します。
retentionPrunedSegments	保持処理が削除できた閉じたセグメント数です。	保持処理が進んでいるかを見る値です。
retentionBaseEntriesWritten	削除前に書いた合成ベースエントリ数です。	値が大きい場合、多数の有効キーが保持境界を跨いでいます。
parallelLaneCount	有効な PARALLEL レーン数です。	解決後のレーン数を確認します。
parallelPendingWrites, parallelPendingBytes	まだ永続化されていないレーン上の作業量です。	高止まりする場合、ストレージが追いついていないか未処理バイト上限が小さすぎます。
parallelQueueRejects	未処理バイト上限により拒否された書き込み数です。	継続的に増える場合はアラート対象です。

保守ツール

akkaradb_vlog_tool 実行ファイルは、正本である VersionLog セグメントを検証し、派生サイドカーインデックスを再構築できます。

akkaradb_vlog_tool validate --log <path> [--json]
akkaradb_vlog_tool rebuild-indexes --log <path> [--json]

どちらのコマンドも通常の即時復旧経由でログを開きます。.akvlog セグメントを検証し、必要に応じて .akvidx サイドカーを書き直します。基準パスも兄弟セグメントも存在しない場合、新しい空ログは作らず失敗します。

終了コード	意味
0	復旧が完了しました。
1	検証またはオープンに失敗しました。
2	rebuild-indexes で復旧は完了したが、サイドカー再生成の失敗がありました。

監視プロセスやスクリプトで読む場合は --json を使います。

復旧失敗の扱い

復旧失敗時の VersionLog: エラーにはファイルパスが含まれ、可能な場合はバイトオフセットとシーケンス番号も含まれます。セグメントファイルが正本です。

データセットを意図的に破棄する、またはバックアップから復元する場合を除き、.akvlog や .akvtail を削除しないでください。.akvidx サイドカーは派生ファイルなので、削除や再生成が可能です。

バックアップの考え方

ファイルシステムレベルのバックアップでは、VersionLog とエンジンの WAL、SST、Manifest、Blob を同じ時点の組として保存します。

*.akvlog
*.akvtail
wal/
sstable/
manifest.akmf
blobs/

.akvidx サイドカーは起動と読み取りの高速化には有用ですが、正本ではなく再構築できます。