# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/virtual-hsm/cli/auditing-and-debugging/vhsm-debug.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.