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.
Open a web browser to access the Vault UI, and sign in.
Select Client Count from the left navigation menu.
Select Configuration.
Select Edit configuration.
Select the toggle for Usage data collection so that the text reads Data collection is on.
Retention period
The retention period sets the number of months for which Vault will maintain activity logs to track active clients. (Default: 48 months)
Click Save to apply the changes.
Click Continue in the confirmation dialog to enable usage metrics tracking.
Usage metrics dashboard
Sign into Vault UI. The Client count section displays the total number of clients for the current billing period.
Select Details.
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 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 to learn more.
Note
The non-entity client count excludes
roottokens.Secrets sync clients are the number of external destinations Vault connects to sync the secrets. Refer to the documentation 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 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, 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.
$ vault operator usageExample output:
Period start: 2024-03-01T00:00:00ZPeriod end: 2024-10-31T23:59:59ZNamespace path Entity Clients Non-Entity clients Secret syncs ACME clients Active clients-------------- -------------- ------------------ ------------ ------------ --------------[root] 86 114 0 0 200education/ 31 31 0 0 62education/certification/ 18 25 0 0 43education/training/ 192 197 0 0 389finance/ 18 26 0 0 44marketing/ 28 17 0 0 45test-ns-1-with-namespace-length-over-18-characters/ 84 75 0 0 159test-ns-1/ 59 66 0 0 125test-ns-2-with-namespace-length-over-18-characters/ 58 46 0 0 104test-ns-2/ 56 47 0 0 103Total 630 644 0 0 1274The output shows client usage metrics for each namespace.
Filter by namespace
You can narrow the scope for education namespace and its child namespaces.
$ vault operator usage -namespace education Period start: 2024-03-01T00:00:00ZPeriod end: 2024-10-31T23:59:59Z Namespace path Entity Clients Non-Entity clients Secret syncs ACME clients Active clients-------------- -------------- ------------------ ------------ ------------ --------------education/ 31 31 0 0 62education/certification/ 18 25 0 0 43education/training/ 192 197 0 0 389 Total 241 253 0 0 494Query 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.
$ vault operator usage \ -start-time=2024-06-01T00:00:00Z \ -end-time=2024-06-30T23:59:59Z Example output:
Period start: 2024-06-01T00:00:00ZPeriod end: 2024-06-30T23:59:59ZNamespace path Entity Clients Non-Entity clients Secret syncs ACME clients Active clients-------------- -------------- ------------------ ------------ ------------ --------------[root] 10 16 0 0 26education/ 7 1 0 0 8education/certification/ 2 4 0 0 6education/training/ 37 30 0 0 67finance/ 3 6 0 0 9marketing/ 2 2 0 0 4test-ns-1-with-namespace-length-over-18-characters/ 6 9 0 0 15test-ns-1/ 9 12 0 0 21test-ns-2-with-namespace-length-over-18-characters/ 5 5 0 0 10test-ns-2/ 9 7 0 0 16Total 90 92 0 0 182Export 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/counterspage to retrieve client count using API. - Activity export API to export activity log.