> For the complete documentation index, see [llms.txt](https://docs.enclaive.cloud/virtual-hsm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enclaive.cloud/virtual-hsm/cli/auditing-and-debugging/vhsm-debug.md).

# vhsm debug

The `debug` command starts a process that monitors a vHSM server, collecting and probing information for a specified duration. This helps operators retrieve and share consistent diagnostic information about the server state.

{% hint style="info" %}
**Note:** The command honors the same authentication variables as the base command, including the token stored from a previous login or the environment variables `VAULT_TOKEN` and `VAULT_ADDR`. The permissions granted by the token determine the extent of information collected.

If the command is interrupted, the collected data is persisted to an output directory.
{% endhint %}

***

### Permissions

The ability to fetch debug data depends on the provided token. Some targets, such as `server-status`, query unauthenticated endpoints, while others require ACL permissions.

#### Required Policy for Full Debugging

```
path "auth/token/lookup-self" {
  capabilities = ["read"]
}

path "sys/pprof/*" {
  capabilities = ["read"]
}

path "sys/config/state/sanitized" {
  capabilities = ["read"]
}

path "sys/monitor" {
  capabilities = ["read"]
}

path "sys/host-info" {
  capabilities = ["read"]
}

path "sys/in-flight-req" {
  capabilities = ["read"]
}
```

### Examples

#### Start debug with default settings:

```
vhsm debug
```

#### Run debug for 1 minute, with custom intervals and no compression:

```
vhsm debug -duration=1m -interval=10s -metrics-interval=5s -compress=false
```

#### Capture only specific targets:

```
vhsm debug -target=host -target=metrics
```

### Output

```
Finished capturing information, bundling files...
Success! Bundle written to: vault-debug-2025-03-04T08-28-46Z.tar.gz
```

### Command Options

| Flag                | Type              | Default Value           | Description                                                |
| ------------------- | ----------------- | ----------------------- | ---------------------------------------------------------- |
| `-compress`         | `bool`            | `true`                  | Toggles compression of the output package.                 |
| `-duration`         | `int` or `string` | `2m`                    | Duration for which the command runs.                       |
| `-interval`         | `int` or `string` | `30s`                   | Interval for collecting profiling data and server state.   |
| `-log-format`       | `string`          | `standard`              | Log format for `log` target (`standard` or `json`).        |
| `-metrics-interval` | `int` or `string` | `10s`                   | Interval for collecting metrics data.                      |
| `-output`           | `string`          | Auto-generated filename | Specifies output path for the debug package.               |
| `-target`           | `string`          | `all targets`           | Specifies targets to capture (can be used multiple times). |

### Capture Targets

The `-target` flag can be used multiple times to specify which information to capture. By default, all available targets are collected.

| Target               | Description                                                                  |
| -------------------- | ---------------------------------------------------------------------------- |
| `config`             | Sanitized version of the configuration state.                                |
| `host`               | Information about the server instance, including CPU, memory, and disk.      |
| `metrics`            | Telemetry information.                                                       |
| `pprof`              | Runtime profiling data, including heap, CPU, goroutine, and trace profiling. |
| `replication-status` | Replication status.                                                          |
| `server-status`      | Health and seal status.                                                      |

**Note:**

* The `config`, `host`, `metrics`, and `pprof` targets are only queried on active and performance standby nodes.
* The `host` target is unavailable on OpenBSD due to system library limitations.

### Output Layout

The collected data is stored in a structured directory format. Profiling data is captured at each interval in separate files, while other targets store data as JSON arrays.

#### Example Directory Structure

```
vault-debug-2025-03-04T21-44-49Z/
├── 2025-03-04T21-44-49Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── 2025-03-04T21-45-19Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── config.json
├── host_info.json
├── index.json
├── metrics.json
├── replication_status.json
├── server_status.json
```