»Consul Snapshot Inspect

Command: consul snapshot inspect

The snapshot inspect command is used to inspect an atomic, point-in-time snapshot of the state of the Consul servers which includes key/value entries, service catalog, prepared queries, sessions, and ACLs. The snapshot is read from the given file.

Typically this is used with Consul self-contained Snapshot files obtained using the consul snapshot command or Snapshot API. If the file provided is named state.bin however, the command will assume it is a raw raft snapshot in a Consul server data directory and will attempt to read it directly. The state.bin file must still be in the same directory as it's associated meta.json file. This is useful for debugging data on live servers without making a complete new snapshot via the CLI or API first.

The following fields are displayed when inspecting a snapshot:

ID - A unique ID for the snapshot, only used for differentiation purposes.
Size - The size of the snapshot, in bytes.
Index - The Raft index of the latest log entry in the snapshot.
Term - The Raft term of the latest log entry in the snapshot.
Version - The snapshot format version. This only refers to the structure of the snapshot, not the data contained within.
Each data type, size, and count within the read snapshot.

»Usage

Usage: consul snapshot inspect [options] FILE

»Examples

To inspect a snapshot from the file "backup.snap":

$ consul snapshot inspect backup.snap
 ID           2-12426-1604593650375
 Size         17228
 Index        12426
 Term         2
 Version      1

 Type                       Count      Size
 ----                       ----       ----
 KVS                        27         12.3KB
 Register                   5          3.4KB
 Index                      11         285B
 Autopilot                  1          199B
 Session                    1          199B
 CoordinateBatchUpdate      1          166B
 Tombstone                  2          146B
 FederationState            1          139B
 ChunkingState              1          12B
 ----                       ----       ----
 Total                                 16.8KB

$ consul snapshot inspect backup.snap
 ID           2-12426-1604593650375
 Size         17228
 Index        12426
 Term         2
 Version      1

 Type                       Count      Size
 ----                       ----       ----
 KVS                        27         12.3KB
 Register                   5          3.4KB
 Index                      11         285B
 Autopilot                  1          199B
 Session                    1          199B
 CoordinateBatchUpdate      1          166B
 Tombstone                  2          146B
 FederationState            1          139B
 ChunkingState              1          12B
 ----                       ----       ----
 Total                                 16.8KB

To get more details for a snapshot inspection from "backup.snap":

$ consul snapshot inspect -kvdetails -kvdepth 3 -kvfilter vault/core backup.snap
 ID           2-12426-1604593650375
 Size         17228
 Index        12426
 Term         2
 Version      1

 Type                       Count      Size
 ----                       ----       ----
 KVS                        27         12.3KB
 Register                   5          3.4KB
 Index                      11         285B
 Autopilot                  1          199B
 Session                    1          199B
 CoordinateBatchUpdate      1          166B
 Tombstone                  2          146B
 FederationState            1          139B
 ChunkingState              1          12B
 ----                       ----       ----
 Total                                 16.8KB

 Key Name                     Count      Size
 ----                         ----       ----
 vault/core/leader            1          1.6KB
 vault/core/mounts            1          675B
 vault/core/wrapping          1          633B
 vault/core/local-mounts      1          450B
 vault/core/auth              1          423B
 vault/core/cluster           2          388B
 vault/core/keyring           1          320B
 vault/core/master            1          237B
 vault/core/seal-config       1          211B
 vault/core/hsm               1          189B
 vault/core/local-audit       1          185B
 vault/core/local-auth        1          183B
 vault/core/audit             1          179B
 vault/core/lock              1          170B
 vault/core/shamir-kek        1          159B
 ----                         ----       ----
 Total                                   5.9KB

$ consul snapshot inspect -kvdetails -kvdepth 3 -kvfilter vault/core backup.snap
 ID           2-12426-1604593650375
 Size         17228
 Index        12426
 Term         2
 Version      1

 Type                       Count      Size
 ----                       ----       ----
 KVS                        27         12.3KB
 Register                   5          3.4KB
 Index                      11         285B
 Autopilot                  1          199B
 Session                    1          199B
 CoordinateBatchUpdate      1          166B
 Tombstone                  2          146B
 FederationState            1          139B
 ChunkingState              1          12B
 ----                       ----       ----
 Total                                 16.8KB

 Key Name                     Count      Size
 ----                         ----       ----
 vault/core/leader            1          1.6KB
 vault/core/mounts            1          675B
 vault/core/wrapping          1          633B
 vault/core/local-mounts      1          450B
 vault/core/auth              1          423B
 vault/core/cluster           2          388B
 vault/core/keyring           1          320B
 vault/core/master            1          237B
 vault/core/seal-config       1          211B
 vault/core/hsm               1          189B
 vault/core/local-audit       1          185B
 vault/core/local-auth        1          183B
 vault/core/audit             1          179B
 vault/core/lock              1          170B
 vault/core/shamir-kek        1          159B
 ----                         ----       ----
 Total                                   5.9KB

Please see the HTTP API documentation for more details about snapshot internals.

To inspect an internal snapshot directly from a Consul server data directory:

$ consul snapshot inspect /opt/consul/raft/snapshots/9-4600669-1618935304715/state.bin
 ID           9-4600669-1618935304715
 Size         4625420898
 Index        4600669
 Term         9
 Version      1

 Type                       Count        Size
 ----                       ----         ----
 KVS                        4089785      4.3GB
 Register                   9            5.2KB
 CoordinateBatchUpdate      3            465B
 Index                      8            224B
 Autopilot                  1            199B
 FederationState            1            139B
 ChunkingState              1            12B
 ----                       ----         ----
 Total                                   4.3GB

$ consul snapshot inspect /opt/consul/raft/snapshots/9-4600669-1618935304715/state.bin
 ID           9-4600669-1618935304715
 Size         4625420898
 Index        4600669
 Term         9
 Version      1

 Type                       Count        Size
 ----                       ----         ----
 KVS                        4089785      4.3GB
 Register                   9            5.2KB
 CoordinateBatchUpdate      3            465B
 Index                      8            224B
 Autopilot                  1            199B
 FederationState            1            139B
 ChunkingState              1            12B
 ----                       ----         ----
 Total                                   4.3GB

»Command Options

-kvdetails - Optional, provides a space usage breakdown for any KV data stored in Consul.
-kvdepth - Can only be used with -kvdetails. Used to adjust the grouping level of keys. Defaults to 2.
-kvfilter - Can only be used with -kvdetails. Used to specify a key prefix that excludes keys that don't match.
-format - Optional, allows from changing the output to JSON. Parameters accepted are "pretty" and "JSON".