/sys/internal/counters
The /sys/internal/counters endpoints are used to return data about the number of Tokens and Entities in Vault. They return information for the entire cluster.
NOTE: These endpoints are only available in Vault version 1.3+. Backwards compatibility is not guaranteed. These endpoints are subject to change or may disappear without notice.
Entities
This endpoint returns the total number of Entities.
| Method | Path |
|---|---|
GET | /sys/internal/counters/entities |
Sample Request
Sample Response
Tokens
This endpoint returns the total number of Tokens.
| Method | Path |
|---|---|
GET | /sys/internal/counters/tokens |
Sample Request
Sample Response
Client Count
This endpoint returns client activity information for a given billing
period, which is represented by the start_time and end_time parameters.
There are a few things to keep in mind while using this API.
The activity information only accounts for the activity of the latest contiguous months in the billing period. For example, if the billing period is from Jan 2022 to June 2022, and the activity subsystem in Vault was not capturing data for the months Jan to March, the response will only include information for May and June.
The response contains the total activity for the billing period and the attributions of the total activity against specific components in Vault. This helps in understanding the total activity better by knowing which components in Vault lead to that top-level activity count. First-level of attribution breakdowns are by namespaces and months, under the
by_namespacesandmonthsJSON block, respectively.
by_namespacesbreakdowns provide attributions of each namespace to the total activity count. Mount level attributions further break down these namespaces attributions, wherein information can be found on the attributions of each mount path within a given namespace to the overall activity of the namespace.
monthsbreakdowns provide attributions of each month to the total activity count. These month-level attributions are further broken down into namespace and mount level attributions for each month.
Each entry in the
monthsbreakdown contains anew_clientsblock. When a token is first used within a billing period, it is considered a new client for that billing period. This means that all the active clients in the first month of the billing period will be considered new clients for that billing period. While these tokens could be generated and counted in the previous billing period, they are still considered new clients in the context of the given billing period. For each subsequent month in the same billing period, the tokens used in those months that were unused in previous months of the same billing period are considered new clients for that month. Hence, the computation of new clients differs for each combination ofstart_timeandend_time.The
new_clientsblock within themonthsbreakdown will also be further broken down by namespaces and mounts for visibility into which components in Vault lead to the new clients for each month.
The
distinct_entitiesfield name has been deprecated since Vault 1.10. Refer toentity_clientsfield instead. Thedistinct_entitiesfield is currently returned by the API for backward compatibility and it may be removed in the future.The
non_entity_tokensfield name has been deprecated since Vault 1.10. Refer tonon_entity_clientsfield instead. Thenon_entity_tokensfield is currently returned by the API for backward compatibility, and it may be removed in the future.If the
end_datesupplied to the API is for the current month, the activity information returned by this API will only be till the previous month. The activity system is designed to process the accumulated activity only at the end of the month. Since the system does not fully process the current month's information, it will not be added to the API response.The response includes the actual time period covered, which may not exactly match the query parameters due to the month granularity of data or missing months in the requested time range.
Please visit the client count concepts page for more information on how clients map to these client IDs and how they are counted.
The response will include all child namespaces of the namespace in which the request was made. If some namespace has subsequently been deleted, its path will be listed as "deleted namespace :ID:." Deleted namespaces are reported only for queries in the root namespace because the information about the namespace path is unknown.
This endpoint was added in Vault 1.6.
| Method | Path |
|---|---|
GET | /sys/internal/counters/activity |
Parameters
start_time(string, optional)- An RFC3339 timestamp or Unix epoch time. Specifies the start of the period for which client counts will be reported. If no start time is specified, thedefault_report_monthsprior to theend_timewill be used.end_time(string, optional)- An RFC3339 timestamp or Unix epoch time. Specifies the end of the period for which client counts will be reported. If no end time is specified, the end of the previous calendar month will be used.
Sample Request
Sample Response
Sample request for a single month
Partial Month Client Count
This endpoint returns the client activity in the current month. The response will have activity attributions per namespace, per mount within each namespaces, and new clients information.
The time period is from the start of the current month, up until the time that this request was made.
Note: the client count may be inaccurate in the moments following a Vault reboot, or leadership change. The estimate will stabilize when background loading of client data has completed.
This endpoint was added in Vault 1.7.
| Method | Path |
|---|---|
GET | /sys/internal/counters/activity/monthly |
Sample Request
Sample Response
Update the Client Count Configuration
The /sys/internal/counters/config endpoint is used to configure logging of active clients.
| Method | Path |
|---|---|
POST | /sys/internal/counters/config |
Parameters
default_report_months(integer: 12)- The number of months to report if nostart_timeis specified in a query.enabled(string: enable, disable, default)- Enable or disable counting of client activity. When set todefault, the client counts are enabled on Enterprise builds and disabled on OSS builds. Disabling the feature during the middle of a month will discard any data recorded for that month, but does not delete previous months.retention_months(integer: 24)- The number of months of history to retain.
Any missing parameters are left at their existing value.
Sample Payload
Sample Request
Read the Client Count Configuration
Reading the configuration shows the current settings, as well as a flag as to whether any data can be queried.
enabled(string)- returnsdefault-enabledordefault-disabledif the configuration isdefault.queries_available(bool)- indicates whether any usage report is available. This will initially be false until the end of the first calendar month after the feature is enabled.
Sample Request
Sample Response