> 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/documentation/setup/configuration/server/telemetry.md).

# Telemetry

The vHSM server collects runtime telemetry to provide insight into the performance of its internal components and subsystems. Metrics are aggregated every 10 seconds and stored in-memory for one minute. High-cardinality metrics, are reported every 10 minutes, or at a custom interval defined in the `telemetry` stanza.

To persist and monitor these metrics, vHSM can stream telemetry data to external aggregation software such as [Prometheus](#prometheus-parameters). 

These tools can be configured within vHSM’s `telemetry` stanza to receive and process metrics for long-term storage and monitoring. For example, Prometheus can scrape metrics from the `/v1/sys/metrics` endpoint for visualization and alerting.

### Common Parameters

| Parameter                            | Type   | Default | Description                                                                                                     |
| ------------------------------------ | ------ | ------- | --------------------------------------------------------------------------------------------------------------- |
| `usage_gauge_period`                 | string | "10m"   | Interval for collecting high-cardinality usage data. Set to `"none"` to disable.                                |
| `maximum_gauge_cardinality`          | int    | 500     | Maximum cardinality of gauge labels.                                                                            |
| `disable_hostname`                   | bool   | false   | Prefixes gauge values with the local hostname if set to `false`.                                                |
| `enable_hostname_label`              | bool   | false   | Adds `host` label with local hostname to all metrics. Recommended to enable `disable_hostname` if this is used. |
| `metrics_prefix`                     | string | "vhsm"  | Prefix for metric values.                                                                                       |
| `lease_metrics_epsilon`              | string | "1h"    | Size of buckets for lease expiration metrics.                                                                   |
| `num_lease_metrics_buckets`          | int    | 168     | Number of lease expiration buckets.                                                                             |
| `add_lease_metrics_namespace_labels` | bool   | false   | Adds namespace labels to lease expiration metrics. May increase cardinality.                                    |
| `add_mount_point_rollback_metrics`   | bool   | false   | Enables rollback metrics per mount point. May increase cardinality.                                             |
| `filter_default`                     | bool   | true    | Whether to allow metrics not matched by any filter.                                                             |
| `prefix_filter`                      | array  | \[]     | Filters metrics by prefix. Example: `["+vhsm.token", "-vhsm.expire"]`                                           |

### Prometheus Parameters

| Parameter                   | Type   | Default | Description                                                                |
| --------------------------- | ------ | ------- | -------------------------------------------------------------------------- |
| `prometheus_retention_time` | string | "24h"   | Duration Prometheus metrics are retained. Set to `0` to disable.           |
| `disable_hostname`          | bool   | false   | Disables hostname prefix in metrics. Recommended to enable for Prometheus. |

#### Prometheus Endpoint

The `/v1/sys/metrics` endpoint is only accessible on active vHSM nodes. To enable it on standby nodes, unauthenticated metrics access must be enabled. Querying the endpoint with headers such as `Accept: prometheus/telemetry` will return Prometheus-formatted data.

#### Authorization

A vHSM token with `["read", "list"]` capabilities to `/v1/sys/metrics` is required. The Prometheus `bearer_token` or `bearer_token_file` must be specified.

#### Prometheus Scrape Job Example

```yaml
# prometheus.yml
scrape_configs:
  - job_name: 'vhsm'
    metrics_path: "/v1/sys/metrics"
    scheme: https
    tls_config:
      ca_file: <your_ca_here.pem>
    bearer_token: "<your_vhsm_token_here>"
    static_configs:
      - targets: ['<your_vhsm_server_here:8200>']
```

#### vHSM Telemetry Configuration Example

```hcl
telemetry {
  prometheus_retention_time = "30s"
  disable_hostname = true
}
```