»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 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:

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

$ 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 instead of handing out directly-created tokens. Ensure that entities and entity aliases exist for all login methods used to create batch tokens.

»API and Permissions

Please see Client Count API 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:

For the UI to be able to modify the configuration settings, it additionally needs update permission to sys/internal/counters/config.