f742277996
* Documentation for client count API. * New concepts page Co-authored-by: swayne275 <swayne@hashicorp.com>
104 lines
4.9 KiB
Plaintext
104 lines
4.9 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Client Count
|
|
sidebar_title: Client Count
|
|
description: Counting the number of clients accessing Vault.
|
|
---
|
|
|
|
# Client Count
|
|
|
|
The number of active clients using a Vault cluster is the total of:
|
|
- active entities: identity entities that create a token via a login
|
|
- active non-entity tokens: tokens created via a method that is not associated with an entity
|
|
|
|
Prior to Vault 1.6, this metric could only be measured from the audit log, using the
|
|
`vault-advisor` tool. Starting with Vault 1.6, the number of clients per month, or for
|
|
a contiguous sequence of months, can be measured by Vault itself.
|
|
|
|
Please refer to [Vault Usage Metrics](https://learn.hashicorp.com/tutorials/vault/usage-metrics) for a
|
|
step-by-step tutorial and description of how to use the UI.
|
|
|
|
## Measuring clients
|
|
|
|
Each time a token is created, Vault checks to see whether it belongs to an identity entity
|
|
that has already been active in the current month. New entities are added to a log in Vault storage
|
|
periodically. New tokens without entities are added to the "non-entity token" count.
|
|
|
|
At the end of each month, Vault creates precomputed reports listing the number of active entities,
|
|
per namespace, in each time period within a configurable retention period. This process deduplicates
|
|
entities by ID, so that if an entity is active within every calendar month, it still only counts as
|
|
one client for the entire year.
|
|
|
|
There are no client count metrics available until after the first calendar month finishes.
|
|
|
|
The client counts sum activity from all nodes in a cluster, including batch tokens created by performance
|
|
standby nodes. Performance secondary clusters have their own client population, and their own client metrics;
|
|
Vault does not aggregate or deduplicate clients across clusters. However, the logs and precomputed
|
|
reports are included in DR replication.
|
|
|
|
### Costs of measurement
|
|
|
|
Each active entity in the log consumes a few bytes of storage. Vault limits the number of identity
|
|
entities it records per month (to 656,000) as a safety measure to prevent unbounded storage growth. However,
|
|
typical storage costs should be much less. 1000 monthly active entities will require about 1.5 MiB of storage
|
|
capacity over the default 24-month retention period. A smaller amount of additional storage is used for
|
|
precomputed reports for all valid start/end pairs of months.
|
|
|
|
### Disabling measurement
|
|
|
|
To avoid this potentially unwanted storage usage, the client count feature can be disabled via the UI or API.
|
|
By default, the client count is disabled on open source builds, and enabled on Enterprise binaries. The CLI command
|
|
to change its state is:
|
|
|
|
```shell-session
|
|
# To enable
|
|
$ vault write sys/internal/counters/config enabled=enable
|
|
|
|
# To disable
|
|
$ vault write sys/internal/counters/config enabled=disable
|
|
```
|
|
|
|
If you disable the client counter, then all complete months and all precomputed reports will remain in storage
|
|
until their normal expiration time. This allows queries to be run on older data, even if no new data is being collected.
|
|
|
|
Vault does not report across a disable/enable cycle of the client count. All subsequent reports will start at the
|
|
time that the feature is enabled.
|
|
|
|
## Understanding Non-entity tokens
|
|
|
|
A token without an entity can be created in any of the following ways:
|
|
- A root token creates a token via `auth/token/create`.
|
|
- Any other token without an entity creates a child token via `auth/token/create` or a token role.
|
|
- An orphan token is created via `auth/token/create-orphan`; such a token does not inherit the entity of its creator.
|
|
- A token is created using a token role that specifies `orphan=true`.
|
|
- An auth method would normally create an entity, but is not allowed to do so, such as:
|
|
- A batch token is created on a performance standby node.
|
|
- A service token is created on a performance secondary replica, using a local mount.
|
|
|
|
The `entity_id` field will be empty, or show as `n/a`, for any token that is classified as a non-entity token:
|
|
|
|
```shell-session
|
|
$ vault token lookup
|
|
Key Value
|
|
--- -----
|
|
entity_id n/a
|
|
```
|
|
|
|
To reduce the number of non-entity tokens in use, consider switching to an authentication method such as
|
|
[AppRole](/docs/auth/approle) instead of handing out directly-created tokens. Ensure that entities and
|
|
[entity aliases](/api/secret/identity/entity-alias) exist for all login methods used to create batch tokens.
|
|
|
|
## API and Permissions
|
|
|
|
Please see [Client Count API](/api/system/internal-counters#client-count) for more details. Note that this API is marked as
|
|
"internal" so its behavior or format may change without warning. The UI is the preferred means of interacting with the
|
|
client count feature.
|
|
|
|
For the UI to be able to use the client count feature, it needs `read` permission to the following paths:
|
|
- `sys/internal/counters/activity`
|
|
- `sys/internal/counters/config`
|
|
|
|
For the UI to be able to modify the configuration settings, it additionally needs `update` permission to
|
|
`sys/internal/counters/config`.
|
|
|