/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.
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.
- 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.The response includes month data for the entire queried period, but may not exactly match the
start_timeandend_timereturned in the response. Thestart_timein the response is the earliest time there is activity data in the queried period. Theend_timeis the end of the final month of the queried period.If the
end_datesupplied to the API is the current month, exact activity information will be returned for all months in the queried period, except for the current month. The last element in themonthsresponse stanza will signify the current month. Furthermore, thenew_clientscounts returned for the current month will be an estimate.
The following is an example of the months breakdown with just the current month information.
@include 'auto-roll-billing-start-example.mdx'
Please visit the client count concepts page for more information on how clients map to these client IDs and how they are counted, or for more information about how the new clients for the current month are estimated in a billing period.
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.
Restricted endpoint
The API path can only be called from the root namespace.| 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, the billing start date will be used. The billing start date automatically rolls over to the latest billing year at the end of the last cycle.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.limit_namespaces(int, optional)- Controls the total number of by_namespace data returned. This can be used to return the client counts for the specified number of namespaces having highest activity. If nolimit_namespacesparameter is specified, client counts for all namespaces in specified usage period is returned.current_billing_period(bool, optional)- Uses the builtin billing start timestamp asstart_timeand the current time as theend_time, returning a response with the current billing period information without having to explicitly provide a start and end time.
Sample request
Sample response
Sample request for a single month
Sample request to get client counts for top 2 namespaces with highest activity for a usage period
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.
Restricted endpoint
The API path can only be called from the root namespace.| Method | Path |
|---|---|
GET | /sys/internal/counters/activity/monthly |
Sample request
Sample response
Update the client count configuration
Restricted endpoint
The API path can only be called from the root namespace.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 community 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: 48)- The number of months of history to retain. The minimum is 48 months and the maximum is 60 months.
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.
| Method | Path |
|---|---|
GET | /sys/internal/counters/config |
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
Important change to supported versions
As of 1.16.7, 1.17.3 and later, the billing start date automatically rolls over to the latest billing year at the end of the last cycle.For more information, refer to the upgrade guide for your Vault version:
Activity export
This endpoint returns an export of the clients that had activity within the provided start and end times. The returned set of client information will be deduplicated over the time window and will show the earliest activity logged for each client. The output will be ordered chronologically by month of activity.
NOTE: This endpoint is currently in tech preview status.
There are a few things to keep in mind while using this API.
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.
If the
end_datesupplied to the API is for the current month, the activity information returned by this API will include activity for this month, however it may be up to 20 minutes delayed.
Restricted endpoint
The API path can only be called from the root namespace.| Method | Path |
|---|---|
GET | /sys/internal/counters/activity/export |
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.format(string, optional)- The desired format of the output file. Allowed values arecsvandjson. If no format is provided a default ofjsonwill be used.
Sample request
Sample response