mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-10 16:47:01 +02:00
a2390d3234
* Add UI screenshots * Add 'usage metrics' page * Align the step instruction and its screenshot * Additional notes * Add link to API docs
305 lines
11 KiB
Plaintext
305 lines
11 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Vault usage metrics
|
|
description: |-
|
|
Learn how to discover the number of Vault clients for each namespace in Vault.
|
|
---
|
|
|
|
# Vault usage metrics
|
|
|
|
Client calculation and sizing can be complex to compute when you have multiple
|
|
namespaces and auth mounts. The **Vault Usage Metrics** dashboard on Vault UI
|
|
provides the information where you can filter the data by namespace and/or auth
|
|
mounts. You can also use Vault CLI or API to query the usage metrics.
|
|
|
|
## Enable usage metrics
|
|
|
|
Usage metrics are a feature that is enabled by default for Vault Enterprise and
|
|
HCP Vault Dedicated. However, if you are running Vault Community Edition, you
|
|
need to enable usage metrics since it is disabled by default.
|
|
|
|
<Tabs>
|
|
<Tab heading="Web UI" group="ui">
|
|
|
|
1. Open a web browser to access the Vault UI, and sign in.
|
|
|
|
1. Select **Client Count** from the left navigation menu.
|
|
|
|
1. Select **Configuration**.
|
|
|
|
1. Select **Edit configuration**.
|
|
|
|
|
|
|
|
1. Select the toggle for **Usage data collection** so that the text reads **Data
|
|
collection is on**.
|
|
|
|
<Tip title="Retention period">
|
|
|
|
The retention period sets the number of months for which Vault will maintain
|
|
activity logs to track active clients. (Default: 48 months)
|
|
|
|
</Tip>
|
|
|
|
1. Click **Save** to apply the changes.
|
|
|
|
1. Click **Continue** in the confirmation dialog to enable usage metrics tracking.
|
|
|
|
</Tab>
|
|
<Tab heading="CLI command" group="cli">
|
|
|
|
```shell-session
|
|
$ vault write sys/internal/counters/config enabled=enable
|
|
```
|
|
|
|
Valid values for `enabled` parameter are: `default`, `enable`, and `disable`.
|
|
|
|
<Tip title="Retention period">
|
|
|
|
By default, Vault maintains activity logs to track
|
|
active clients for 24 months. If you wish to change the retention period, use
|
|
the `retention_months` parameter.
|
|
|
|
</Tip>
|
|
|
|
**Example:**
|
|
|
|
```shell-session
|
|
$ vault write sys/internal/counters/config \
|
|
enabled=enable \
|
|
retention_months=12
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="API call using cURL" group="api">
|
|
|
|
```shell-session
|
|
$ curl --header "X-Vault-Token: <TOKEN>" \
|
|
--request POST \
|
|
--data '{"enabled": "enable"}' \
|
|
$VAULT_ADDR/v1/sys/internal/counters/config
|
|
```
|
|
|
|
Valid values for `enabled` parameter are: `default`, `enable`, and `disable`.
|
|
|
|
<Tip title="Retention period">
|
|
|
|
By default, Vault maintains activity logs to track
|
|
active clients for 24 months. If you wish to change the retention period, use
|
|
the `retention_months` parameter.
|
|
|
|
</Tip>
|
|
|
|
**Example:**
|
|
|
|
```shell-session
|
|
$ curl --header "X-Vault-Token: <TOKEN>" \
|
|
--request POST \
|
|
--data '{"enabled": "enable", "retention_months": 12}' \
|
|
$VAULT_ADDR/v1/sys/internal/counters/config
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## Usage metrics dashboard
|
|
|
|
1. Sign into Vault UI. The **Client count** section displays the total number of
|
|
clients for the current billing period.
|
|
|
|
1. Select **Details**.
|
|
|
|
|
|
1. Examine the **Vault Usage Metrics** dashboard to learn your Vault usage.
|
|
|
|
|
|
#### Usage metrics data categories
|
|
|
|
- **Running client total** are the primary metric on which pricing is based.
|
|
It is the sum of entity clients (or distinct entities) and non-entity clients.
|
|
|
|
- **Entity clients** (distinct entities) are representations of a particular
|
|
user, client, or application that belongs to a defined Vault entity. If you
|
|
are unfamiliar with Vault entities, refer to the [Identity: Entities and
|
|
Groups](/vault/tutorials/auth-methods/identity) tutorial.
|
|
|
|
- **Non-entity clients** are clients without an entity attached.
|
|
This is because some customers or workflows might avoid using entity-creating
|
|
authentication methods and instead depend on token creation through the Vault
|
|
API. Refer to [understanding non-entity
|
|
tokens](/vault/docs/concepts/client-count#understanding-non-entity-tokens)
|
|
to learn more.
|
|
|
|
<Note>
|
|
|
|
The non-entity client count excludes `root` tokens.
|
|
|
|
</Note>
|
|
|
|
- **Secrets sync clients** are the number of external destinations Vault
|
|
connects to sync the secrets. Refer to the
|
|
[documentation](/vault/docs/concepts/client-count#secret-sync-clients) for
|
|
more details.
|
|
|
|
- **ACME clients** are the ACME connections that authenticate under the same
|
|
certificate identifier (domain) as the same certificate entity for client
|
|
count calculations. Refer to the
|
|
[documentation](/vault/docs/concepts/client-count#entity-assignment-with-acme)
|
|
for more details.
|
|
|
|
|
|
|
|
|
|
## Select a data range
|
|
|
|
Under the **Client counting period**, select **Edit** to query the data for
|
|
a different billing period.
|
|
|
|
|
|
|
|
Keep in mind that Vault begins collecting data when the feature is enabled. For
|
|
example, if you enabled the usage metrics in March of 2023, you cannot query
|
|
data in January of 2023.
|
|
|
|
Vault will return metrics from March of 2023 through most recent full month.
|
|
|
|
## Filter by namespaces
|
|
|
|
If you have [namespaces](/vault/docs/enterprise/namespaces), the dashboard
|
|
displays the top ten namespaces by total clients.
|
|
|
|
|
|
|
|
Use the **Filters** to view the metrics data of a specific namespace.
|
|
|
|
|
|
|
|
## Mount attribution
|
|
|
|
The clients are also shown as graphs per auth mount. The **Mount attribution**
|
|
section displays the top auth mounts where you can expect to find your most used
|
|
auth method mounts with respect to client usage. This allows you to detect which
|
|
auth mount had the most number of total clients in the given billing period. You
|
|
can filter for auth mounts within a namespace, or view auth mounts across
|
|
namespaces. The mount attribution is available even if you are not using
|
|
namespaces.
|
|
|
|
|
|
|
|
|
|
## Query usage metrics via CLI
|
|
|
|
Retrieve the usage metrics for the current billing period.
|
|
|
|
```shell-session
|
|
$ vault operator usage
|
|
```
|
|
|
|
**Example output:**
|
|
|
|
<CodeBlockConfig hideClipboard>
|
|
|
|
```plaintxt
|
|
Period start: 2024-03-01T00:00:00Z
|
|
Period end: 2024-10-31T23:59:59Z
|
|
|
|
Namespace path Entity Clients Non-Entity clients Secret syncs ACME clients Active clients
|
|
-------------- -------------- ------------------ ------------ ------------ --------------
|
|
[root] 86 114 0 0 200
|
|
education/ 31 31 0 0 62
|
|
education/certification/ 18 25 0 0 43
|
|
education/training/ 192 197 0 0 389
|
|
finance/ 18 26 0 0 44
|
|
marketing/ 28 17 0 0 45
|
|
test-ns-1-with-namespace-length-over-18-characters/ 84 75 0 0 159
|
|
test-ns-1/ 59 66 0 0 125
|
|
test-ns-2-with-namespace-length-over-18-characters/ 58 46 0 0 104
|
|
test-ns-2/ 56 47 0 0 103
|
|
|
|
Total 630 644 0 0 1274
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
The output shows client usage metrics for each namespace.
|
|
|
|
### Filter by namespace
|
|
|
|
You can narrow the scope for `education` namespace and its child namespaces.
|
|
|
|
```shell-session
|
|
$ vault operator usage -namespace education
|
|
|
|
Period start: 2024-03-01T00:00:00Z
|
|
Period end: 2024-10-31T23:59:59Z
|
|
|
|
Namespace path Entity Clients Non-Entity clients Secret syncs ACME clients Active clients
|
|
-------------- -------------- ------------------ ------------ ------------ --------------
|
|
education/ 31 31 0 0 62
|
|
education/certification/ 18 25 0 0 43
|
|
education/training/ 192 197 0 0 389
|
|
|
|
Total 241 253 0 0 494
|
|
```
|
|
|
|
### Query with a time frame
|
|
|
|
To query the client usage metrics for the month of June, 2024. The start
|
|
time is June 1, 2024 (`2024-06-01T00:00:00Z`) and the end time is June
|
|
30, 2024 (`2024-06-30T23:59:59Z`).
|
|
|
|
The `start_time` and `end_time` should be an RFC3339 timestamp or Unix epoch
|
|
time.
|
|
|
|
```shell-session
|
|
$ vault operator usage \
|
|
-start-time=2024-06-01T00:00:00Z \
|
|
-end-time=2024-06-30T23:59:59Z
|
|
```
|
|
|
|
**Example output:**
|
|
|
|
<CodeBlockConfig hideClipboard>
|
|
|
|
```plaintext
|
|
Period start: 2024-06-01T00:00:00Z
|
|
Period end: 2024-06-30T23:59:59Z
|
|
|
|
Namespace path Entity Clients Non-Entity clients Secret syncs ACME clients Active clients
|
|
-------------- -------------- ------------------ ------------ ------------ --------------
|
|
[root] 10 16 0 0 26
|
|
education/ 7 1 0 0 8
|
|
education/certification/ 2 4 0 0 6
|
|
education/training/ 37 30 0 0 67
|
|
finance/ 3 6 0 0 9
|
|
marketing/ 2 2 0 0 4
|
|
test-ns-1-with-namespace-length-over-18-characters/ 6 9 0 0 15
|
|
test-ns-1/ 9 12 0 0 21
|
|
test-ns-2-with-namespace-length-over-18-characters/ 5 5 0 0 10
|
|
test-ns-2/ 9 7 0 0 16
|
|
|
|
Total 90 92 0 0 182
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
|
|
## Export the metrics data
|
|
|
|
You can export the metrics data by clicking on the **Export attribution data**
|
|
button.
|
|
|
|
|
|
|
|
This downloads the usage metrics data on your local drive in comma separated
|
|
values format (`.csv`) or JSON.
|
|
|
|
|
|
## API
|
|
|
|
- Refer to the
|
|
[`sys/internal/counters`](/vault/api-docs/system/internal-counters#client-count)
|
|
page to retrieve client count using API.
|
|
- [Activity export API](/vault/api-docs/system/internal-counters#activity-export) to
|
|
export activity log.
|