Skip to content

Assessments and history

Assessments are explicit, read-only captures of VM, host, cluster, datastore, and snapshot state. They are stored locally in SQLite and never sent back to vCenter.

Capture and inspect

vsfleet capture run --all-contexts
vsfleet capture run --all-contexts --browse-datastores
vsfleet capture run --all-contexts \
  --label nightly --note "pre-change baseline" --pin
vsfleet capture list
vsfleet describe capture latest
vsfleet describe vm billing --history --all-observations

Label recurring baselines and pin those you want to keep. Retention cleanup preserves pinned runs; use capture update <run> --unpin before removing one.

Compare runs

vsfleet capture diff previous latest
vsfleet capture diff nightly latest \
  --fail-on moved,vanished \
  --max-snapshot-age 30d \
  --require-complete

Diffs compare vCenters collected successfully in both runs, so an outage does not appear as VM deletion. Exit code 2 means a requested drift-policy violation; execution and selector errors return 1.

Policy flags are command-line only. A scheduled job records its policy in the invocation:

vsfleet capture run --all-contexts --label nightly
vsfleet capture diff nightly latest \
  --fail-on appeared,vanished,moved \
  --fail-on snapshot-created,snapshot-removed \
  --max-snapshot-age 30d --require-complete -o json > drift.json

Use --include-runtime when volatile power, guest, IP, VMware Tools, storage, VM state (configuration status, last power-on, change version, the guest OS VMware Tools reports) or host state (configuration status, quarantine, boot time) fields should participate in a diff.

Imports and live captures

An RVTools import records fewer fields than a live capture, and records some differently, so comparing the two reports differences between the sources rather than changes to the estate. VM history follows a VM a live capture has seen through live captures only; a VM known only from imports is followed through those. capture diff with no capture, or one, picks a capture of the same kind. Naming an import and a live capture still compares them, with a warning.

vsfleet analyze snapshots --older-than 30d
vsfleet analyze churn
vsfleet analyze snapshots --trend --older-than 30d
vsfleet analyze capacity --trend --kind all
vsfleet describe capture latest

analyze snapshots measures each age at the capture it reads, not today, and its first line names that capture and its date.

Trends show estate totals, then context and resource detail, for a window of captures: from --from, or the start of history, up to --run, or the most recent. They use complete assessments by default; --include-partial includes partial runs.

Scope stored evidence

--context scopes reports, diffs, exports, VM history and every analyze command. Without it, an analysis covers every context the capture recorded, because its questions cross vCenters. Names come from the ledger, without current configuration, and match case-insensitively after trimming whitespace.

  • Blank names or names absent from every selected run return exit code 1.
  • A context on only one side of a diff produces a coverage warning, without inferred appeared/vanished changes.
  • A diff compares each VM once per vCenter, however many contexts reach that vCenter. When both captures recorded some of the same contexts, only those are compared; when they share none, as after a rename, all of them are.
  • latest, previous and a date pick among the captures that recorded every scoped context, so a newer capture of another vCenter does not hide them. An ID or label names its capture regardless. describe capture and capture diff resolve their arguments the same way.
  • capture diff with no capture, or one, only pairs captures that share a context, because a pair that shares none compares nothing. With no capture it takes the newest such pair, passing over a newer capture that has no earlier capture to compare with, and fails if there is no such pair. Naming two captures compares them regardless, with coverage warnings.
  • VM history judges a gap only by the captures of the scoped contexts. A capture through another context, even of the same vCenter, is not reported as vanished.
  • Trends skip runs that did not record the context. --limit counts contributing runs only.
  • A successful empty collection counts as zero; a failed collection produces a coverage warning.

Metadata and maintenance commands reject --context.

Capacity attribution and projection

vsfleet analyze capacity --since 30d --top 5
vsfleet analyze capacity --min-free 10 --min-free-bytes 500Gi -o json

Capacity growth uses used bytes (capacity - free) and records datastore resizes separately. Contributors have an evidence level:

Level Basis
exact Complete browse file-size deltas mapped through VM disk backing paths
inferred Committed-storage delta for a VM on one datastore
split Per-disk provisioned-capacity deltas for a VM spanning datastores

Unresolved files remain file contributors. unattributed is the residual that makes contributors sum to datastore growth.

Projection fits used bytes to usable history by linear least squares. It is unknown with fewer than three points, under a day of history, non-shrinking free space, or incomplete coverage. Sparse history, a weak fit, partial runs, resizes, or pruning-like gaps produce low-confidence.

Shared backing identities merge datastores across vCenters; local datastores stay context-scoped. JSON and stderr report missing coverage.

Retention and recovery

vsfleet capture prune --older-than 90d          # dry-run
vsfleet capture prune --older-than 90d --execute
vsfleet db backup ./history-backup.db
vsfleet db restore ./history-backup.db --force
vsfleet db doctor
vsfleet capture delete <run> --force

Capture, prune, backup, and restore use a fenced lease that permits one writer at a time. Listing, diffing, and the TUI do not take it. Backups are consistent SQLite snapshots; restore makes a safety copy before replacing the database. Restoring into a capture database that holds no data yet needs no --force; replacing existing history does.

The database defaults to <user-config-dir>/vsfleet/history.db. Override it with --db <path> or VSFLEET_DB. It may contain operational inventory, so protect it using normal host disk and backup controls.

VM performance history

See vm performance history for collection, missing samples, and sizing signals.

Health and orphan checks

See health and orphan checks for health findings and orphan-disk evidence.

Inventory exports

See inventory exports for XLSX and CSV workflows, worksheet coverage, and compatibility.

Migration and capacity planning

See migration and capacity planning for migration readiness, dependencies, sizing, and decommission blockers.

Tags and custom attributes

See tags and custom attributes for metadata exports and saved report definitions.

Sharing inventory

See sharing inventory for scoped export profiles and pseudonymization.