mirrors/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2025-08-22 23:21:08 +02:00
Code Issues Projects Releases Wiki Activity
vault/website/content/api-docs/system/internal-counters.mdx
Amir Aslamov a005b20ae5
VAULT-36166 Deprecate counters/tokens api in Docs (#30591) 
* remove reference to tokens api

* remove the tokens word from the page and use clients instead for clarity

* add the deprecation notice to the deprecations page

* Update website/content/partials/deprecation/internal-counters-tokens-api.mdx

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* Update website/content/partials/deprecation/internal-counters-tokens-api.mdx

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* Update website/content/api-docs/system/internal-counters.mdx

Co-authored-by: akshya96 <87045294+akshya96@users.noreply.github.com>

* Update website/content/partials/deprecation/internal-counters-tokens-api.mdx

Co-authored-by: divyaac <divya.chandrasekaran@hashicorp.com>

---------

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
Co-authored-by: akshya96 <87045294+akshya96@users.noreply.github.com>
Co-authored-by: divyaac <divya.chandrasekaran@hashicorp.com>
2025-05-20 16:18:03 -04:00

1521 lines
50 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
layout: api
page_title: /sys/internal/counters - HTTP API
description: >-
The `/sys/internal/counters` endpoints are used to return data about Vault usage.
---
# `/sys/internal/counters`
The `/sys/internal/counters` endpoints are used to return data about the number of Clients 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
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/internal/counters/entities
```
### Sample response
<CodeBlockConfig hideClipboard>
```json
{
"request_id": "75cbaa46-e741-3eba-2be2-325b1ba8f03f",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"counters": {
"entities": {
"total": 1
}
}
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
</CodeBlockConfig>
## 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_namespaces` and `months`
JSON block, respectively.
<CodeBlockConfig hideClipboard>
```json
{
"by_namespace":[],
"months":[]
}
```
</CodeBlockConfig>
- `by_namespaces` breakdowns 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.
<CodeBlockConfig hideClipboard>
```json
{
"by_namespace":[
{
"namespace_id":"root",
"namespace_path":"",
"counts":{},
"mounts":[
{
"path":"auth/up1/",
"counts":{}
},
{
"path":"auth/up2/",
"counts":{}
}
]
}
]
}
```
</CodeBlockConfig>
- `months` breakdowns 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.
<CodeBlockConfig hideClipboard>
```json
{
"months":[
{
"timestamp":"2021-05-01T00:00:00Z",
"counts":{},
"namespaces":[
{
"namespace_id":"root",
"namespace_path":"",
"counts":{},
"mounts":[
{
"path":"auth/up2/",
"counts":{}
},
{
"path":"auth/up1/",
"counts":{}
}
]
},
{
"namespace_id":"s07UR",
"namespace_path":"ns1/",
"counts":{},
"mounts":[
{
"path":"auth/up1/",
"counts":{}
},
{
"path":"auth/up2/",
"counts":{}
}
]
}
],
"new_clients":{}
}
],
}
```
</CodeBlockConfig>
- Each entry in the `months` breakdown contains a `new_clients` block. 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 of `start_time` and `end_time`.
- The `new_clients` block within the `months` breakdown 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.
<CodeBlockConfig hideClipboard>
```json
{
"months":[
{
"new_clients":{
"counts":{},
"namespaces":[
{
"namespace_id":"root",
"namespace_path":"",
"counts":{},
"mounts":[
{
"path":"auth/up2/",
"counts":{}
},
{
"path":"auth/up1/",
"counts":{}
}
]
}
]
}
}
],
}
```
</CodeBlockConfig>
- The response includes month data for the entire queried period, but may
not exactly match the `start_time` and `end_time` returned in the response.
The `start_time` in the response is the earliest time there is activity data
in the queried period. The `end_time` is the end of the final month of the queried
period.
- If the `end_date` supplied to the API is the current month, exact activity
information will be returned for all months in the queried period. The last element
in the `months` response stanza will signify the current month.
@include 'counters-api-new-clients-behavior-change.mdx'
### Behavior Differences between Vault Enterprise and Vault Community ((#count-difference))
The `start_time` and `end_time` request parameters behave differently between
Vault Enterprise and Vault Community edition.
In Vault Enterprise edition, the time parameters must align with the entire default
billing period of 12 months. In Vault Community edition, the Get Client Count endpoint
supports flexible historical time ranges, but excludes the current month and any
future dates.
<Tabs>
<Tab heading="Vault Enterprise">
In Vault Enterprise, the Get Client Count endpoint adjusts `start_time` and
`end_time` to align with the start and end of the corresponding billing period.
- The endpoint only returns data for an entire billing period.
- By default, the endpoint returns activity data from the start of the current
billing period up to the time you call the endpoint.
- If you provide a start time outside the current billing period, Vault
aligns the query to the full default billing period associated with the
provided start time.
- If you provide an end time, but no start time, Vault aligns the query to the
full default billing period associated with the provided end time.
- If you provide start and end times from different billing periods:
- Vault adjusts `start_time` to the start of the associated billing period.
- Vault adjusts `end_time` to the end of the billing period associated with `start_time`.
- The endpoint returns the associated counts and the following warning:
```json
{
"warning": "start_time and end_time parameters can only be used to specify the beginning or end of the same billing period. The values provided for these parameters are not supported and are ignored. Showing the data for the entire billing period corresponding to start_time. If start_time is not provided, the billing period is determined based on the end_time."
}
```
For example, assume the start of the billing period is January 1, 2023 and
current date is December 31, 2025 and you make the following API call:
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/internal/counters/activity?end_time=2023-12-31T00%3A00%3A00Z&start_time=2023-03-01T00%3A00%3A00Z
```
If `start_time` or `end_time` falls within the billing period or overlaps multiple billing periods, Vault returns the following::
<CodeBlockConfig hideClipboard>
```json
{
"request_id":"26be5ab9-dcac-9237-ec12-269a8ca647d5",
"lease_id":"",
"renewable":false,
"lease_duration":0,
"data":{
"start_time":"2023-01-01T00:00:00Z",
"end_time":"2023-12-31T23:59:59Z",
"total":{
"entity_clients":20,
"non_entity_clients":20,
"secret_syncs":5,
"acme_clients":3,
"clients":48
}
},
"wrap_info":null,
"warnings":"start_time and end_time parameters can only be used to specify the beginning or end of the same billing period. The values provided for these parameters are not supported and are ignored. Showing the data for the entire billing period corresponding to start_time. If start_time is not provided, the billing period is determined based on the end_time.",
"auth":null
}
```
</CodeBlockConfig>
</Tab>
<Tab heading="Vault Community">
In Vault Community edition, the Get Client Count endpoint supports arbitrary
historical time ranges. The default range for Get Client Count is the start of
the current cycle through the end of the previous month.
When `end_time` falls in the current month or a future month, Vault adjusts the query
end time to the last day of the previous month and includes the following
warning along with the associated counts:
```json
{
"warning": "end_time parameter can only be used to specify a date until the end of previous month. The value provided for this parameter was in the current month or in the future date and was therefore ignored. The response includes data until the end of the previous month."
}
```
For example, assume the current date is September 25, 2025 and you call the
Get Client Count endpoint with `end_time` set to `2025-10-01`:
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/internal/counters/activity?end_time=2025-10-01T00%3A00%3A00Z&start_time=2025-01-01T00%3A00%3A00Z
```
Vault adjusts `end_time` to the last day in the previous month (August 31, 2025) and returns the following:
<CodeBlockConfig hideClipboard>
```json
{
"request_id":"26be5ab9-dcac-9237-ec12-269a8ca647d5",
"lease_id":"",
"renewable":false,
"lease_duration":0,
"data":{
"start_time":"2025-01-01T00:00:00Z",
"end_time":"2025-08-31T23:59:59Z",
"total":{
"entity_clients":20,
"non_entity_clients":20,
"secret_syncs":5,
"acme_clients":3,
"clients":48
}
},
"wrap_info":null,
"warnings":"end_time parameter can only be used to specify a date until the end of previous month. The value provided for this parameter was in the current month or in the future date and was therefore ignored. The response includes data until the end of the previous month.",
"auth":null
}
```
</CodeBlockConfig>
</Tab>
</Tabs>
### Sample response
The following is an example of the `months` breakdown with just the current month information.
@include 'auto-roll-billing-start-example.mdx'
<CodeBlockConfig hideClipboard>
```json
{
"months":[
{
"timestamp":"current_month_timestamp",
"counts":{
"entity_clients":"exact int value",
"non_entity_clients":"exact int value",
"secret_syncs":"exact int value",
"acme_clients":"exact int value",
"clients":"exact int value"
},
"namespaces": [
{
"namespace_id":"root",
"namespace_path":"path",
"counts":{
"entity_clients":"exact int value",
"non_entity_clients":"exact int value",
"secret_syncs":"exact int value",
"acme_clients":"exact int value",
"clients":"exact int value"
},
"mounts":[
{
"path":"auth/up2/",
"counts":{
"entity_clients":"exact int value",
"non_entity_clients":"exact int value",
"secret_syncs":"exact int value",
"acme_clients":"exact int value",
"clients":"exact int value"
},
},
]
},
],
"new_clients":{
"counts":{
"entity_clients":"approx int value",
"non_entity_clients":"approx int value",
"secret_syncs":"approx int value",
"acme_clients":"approx int value",
"clients":"approx int value"
},
"namespaces":[
{
"namespace_id":"root",
"namespace_path":"",
"counts":{},
"mounts":[
{
"path":"auth/up2/",
"counts":{
"entity_clients":"approx int value",
"non_entity_clients":"approx int value",
"secret_syncs":"approx int value",
"acme_clients":"approx int value",
"clients":"approx int value"
},
},
{
"path":"auth/up1/",
"counts":{
"entity_clients":"approx int value",
"non_entity_clients":"approx int value",
"secret_syncs":"approx int value",
"acme_clients":"approx int value",
"clients":"approx int value"
}
}
]
}
]
}
}
],
}
```
</CodeBlockConfig>
Refer to the [client count](/vault/docs/concepts/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 calculated.
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.
@include 'alerts/restricted-root.mdx'
| 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](/vault/docs/concepts/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 current 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 no `limit_namespaces` parameter is specified, client counts for all namespaces in specified usage period is returned.
- `current_billing_period` `(bool, optional)` - **DEPRECATED** Uses the builtin billing start
timestamp as `start_time` and the current time as the `end_time`, returning a
response with the current billing period information without having to
explicitly provide a start and end time. This parameter is deprecated, as this option is now the default, so no parameter is needed to specify.
@include 'counters-api-new-clients-behavior-change.mdx'
<Note>
<EnterpriseAlert product="vault" inline />
- @include 'counters-api-wait-warning.mdx'
- @include 'counters-api-custom-contract-note.mdx'
</Note>
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/internal/counters/activity
```
### Sample response
<CodeBlockConfig hideClipboard>
```json
{
"request_id":"26be5ab9-dcac-9237-ec12-269a8ca647d5",
"lease_id":"",
"renewable":false,
"lease_duration":0,
"data":{
"by_namespace":[
{
"namespace_id":"root",
"namespace_path":"",
"counts":{
"entity_clients":20,
"non_entity_clients":10,
"secret_syncs": 5,
"acme_clients": 3,
"clients":38
},
"mounts":[
{
"mount_path":"auth/up1/",
"mount_type":"userpass/",
"counts":{
"entity_clients":10,
"non_entity_clients":10,
"secret_syncs": 0,
"acme_clients": 0,
"clients":20
}
},
{
"mount_path":"auth/up2/",
"mount_type":"userpass/",
"counts":{
"entity_clients":5,
"non_entity_clients":5,
"secret_syncs": 0,
"acme_clients": 0,
"clients":10
}
},
{
"mount_path":"secrets/kv1/",
"mount_type":"kv/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":3,
"acme_clients": 0,
"clients":3
}
},
{
"mount_path":"secrets/kv2/",
"mount_type":"kv/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients": 0,
"clients":2
}
},
{
"mount_path":"secrets/pki/",
"mount_type":"pki/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients": 3,
"clients":3
}
}
]
},
{
"namespace_id":"s07UR",
"namespace_path":"ns1/",
"counts":{
"entity_clients":5,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":10
},
"mounts":[
{
"mount_path":"auth/up1/",
"mount_type":"userpass/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"mount_path":"auth/up2/",
"mount_type":"userpass/",
"counts":{
"entity_clients":5,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
}
]
}
],
"end_time":"2021-05-31T23:59:59Z",
"months":[
{
"timestamp":"2021-05-01T00:00:00Z",
"counts":{
"entity_clients":20,
"non_entity_clients":10,
"secret_syncs":5,
"acme_clients":3,
"clients":38
},
"namespaces":[
{
"namespace_id":"root",
"namespace_path":"",
"counts":{
"entity_clients":15,
"non_entity_clients":5,
"secret_syncs":5,
"acme_clients":3,
"clients":23
},
"mounts":[
{
"mount_path":"auth/up2/",
"mount_type":"userpass/",
"counts":{
"entity_clients":10,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":15
}
},
{
"mount_path":"auth/up1/",
"mount_type":"userpass/",
"counts":{
"entity_clients":3,
"non_entity_clients":2,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"mount_path":"secrets/kv1/",
"mount_type":"kv/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":3,
"acme_clients":0,
"clients":3
}
},
{
"mount_path":"secrets/kv2/",
"mount_type":"kv/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":2,
"acme_clients":0,
"clients":2
}
},
{
"mount_path":"secrets/pki/",
"mount_type":"pki/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients":3,
"clients":3
}
},
]
},
{
"namespace_id":"s07UR",
"namespace_path":"ns1/",
"counts":{
"entity_clients":5,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":10
},
"mounts":[
{
"mount_path":"auth/up1/",
"mount_type":"userpass/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"mount_path":"auth/up2/",
"mount_type":"userpass/",
"counts":{
"entity_clients":5,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
}
]
}
],
"new_clients":{
"counts":{
"entity_clients":10,
"non_entity_clients":10,
"secret_syncs":2,
"acme_clients":1,
"clients":23
},
"namespaces":[
{
"namespace_id":"root",
"namespace_path":"",
"counts":{
"entity_clients":5,
"non_entity_clients":5,
"secret_syncs":2,
"acme_clients":1,
"clients":13
},
"mounts":[
{
"mount_path":"auth/up2/",
"mount_type":"userpass/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"clients":5
}
},
{
"mount_path":"auth/up1/",
"mount_type":"userpass/",
"counts":{
"entity_clients":5,
"non_entity_clients":0,
"clients":5
}
},
{
"mount_path":"secrets/kv1/",
"mount_type":"kv/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":1,
"clients":1
}
},
{
"mount_path":"secrets/kv2/",
"mount_type":"kv/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":1,
"clients":1
}
},
{
"mount_path":"secrets/pki/",
"mount_type":"pki/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients":1,
"clients":1
}
}
]
},
{
"namespace_id":"s07UR",
"namespace_path":"ns1/",
"counts":{
"entity_clients":5,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":10
},
"mounts":[
{
"mount_path":"auth/up1/",
"mount_type":"userpass/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"mount_path":"auth/up2/",
"mount_type":"userpass/",
"counts":{
"entity_clients":5,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
}
]
}
]
}
},
{
"timestamp":"2021-04-01T00:00:00Z",
"counts":{
"entity_clients":5,
"non_entity_clients":5,
"secret_syncs":3,
"acme_clients":1,
"clients":14
},
"namespaces":[
{
"namespace_id":"root",
"namespace_path":"",
"counts":{
"entity_clients":5,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":10
},
"mounts":[
{
"mount_path":"auth/up1/",
"mount_type":"userpass/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"mount_path":"auth/up2/",
"mount_type":"userpass/",
"counts":{
"entity_clients":5,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
}
]
}
],
"new_clients":{
"counts":{
"entity_clients":5,
"non_entity_clients":5,
"secret_syncs":3,
"acme_clients":1,
"clients":14
},
"namespaces":[
{
"namespace_id":"root",
"namespace_path":"",
"counts":{
"entity_clients":5,
"non_entity_clients":5,
"secret_syncs":3,
"acme_clients":1,
"clients":14
},
"mounts":[
{
"mount_path":"auth/up1/",
"mount_type":"userpass/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"mount_path":"auth/up2/",
"mount_type":"userpass/",
"counts":{
"entity_clients":5,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"mount_path":"secrets/kv1/",
"mount_type":"kv/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":2,
"acme_clients":0,
"clients":2
}
},
{
"mount_path":"secrets/kv2/",
"mount_type":"kv/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":1,
"acme_clients":0,
"clients":1
}
},
{
"mount_path":"secrets/pki/",
"mount_type":"pki/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients":1,
"clients":1
}
}
]
}
]
}
}
],
"start_time":"2021-01-01T00:00:00Z",
"total":{
"entity_clients":20,
"non_entity_clients":20,
"secret_syncs":5,
"acme_clients":3,
"clients":48
}
},
"wrap_info":null,
"warnings":null,
"auth":null
}
```
</CodeBlockConfig>
### Sample request
The following example retrieves the client count for a single month.
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/internal/counters/activity?end_time=2020-06-30T00%3A00%3A00Z&start_time=2020-06-01T00%3A00%3A00Z
```
### Sample request
The following example retrieves the client counts for top 2 namespaces with
highest activity for a usage period.
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/internal/counters/activity?end_time=2020-06-30T00%3A00%3A00Z&start_time=2020-06-01T00%3A00%3A00Z&limit_namespaces=2
```
## 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>
- For Vault versions prior to 1.20 and 1.20+ent, the client count may be inaccurate in the moments following a Vault
reboot, or leadership change. The count will stabilize when background
loading of client data has completed.
- @include 'counters-api-wait-warning.mdx'
</Note>
@include 'alerts/restricted-root.mdx'
| Method | Path |
| :----- | :---------------------------------------- |
| `GET` | `/sys/internal/counters/activity/monthly` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/internal/counters/activity/monthly
```
### Sample response
<CodeBlockConfig hideClipboard>
```json
{
"request_id": "d0d37f90-96ec-28c7-b59c-b53612cbbcad",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"acme_clients": 0,
"by_namespace": [
{
"counts": {
"acme_clients": 0,
"clients": 1,
"entity_clients": 0,
"non_entity_clients": 1,
"secret_syncs": 0
},
"mounts": [
{
"counts": {
"acme_clients": 0,
"clients": 1,
"entity_clients": 0,
"non_entity_clients": 1,
"secret_syncs": 0
},
"mount_path": "auth_token_0747d59c"
"mount_type":"token/",
}
],
"namespace_id": "root",
"namespace_path": ""
}
],
"clients": 1,
"entity_clients": 0,
"months": [
{
"counts": {
"acme_clients": 0,
"clients": 1,
"entity_clients": 0,
"non_entity_clients": 1,
"secret_syncs": 0
},
"namespaces": [
{
"counts": {
"acme_clients": 0,
"clients": 1,
"entity_clients": 0,
"non_entity_clients": 1,
"secret_syncs": 0
},
"mounts": [
{
"counts": {
"acme_clients": 0,
"clients": 1,
"entity_clients": 0,
"non_entity_clients": 1,
"secret_syncs": 0
},
"mount_path": "auth_token_0747d59c"
"mount_type":"token/",
}
],
"namespace_id": "root",
"namespace_path": ""
}
],
"new_clients": {
"counts": {
"acme_clients": 0,
"clients": 1,
"entity_clients": 0,
"non_entity_clients": 1,
"secret_syncs": 0
},
"namespaces": [
{
"counts": {
"acme_clients": 0,
"clients": 1,
"entity_clients": 0,
"non_entity_clients": 1,
"secret_syncs": 0
},
"mounts": [
{
"counts": {
"acme_clients": 0,
"clients": 1,
"entity_clients": 0,
"non_entity_clients": 1,
"secret_syncs": 0
},
"mount_path": "auth_token_0747d59c"
"mount_type":"token/",
}
],
"namespace_id": "root",
"namespace_path": ""
}
]
},
"timestamp": "2022-04-01T04:00:00Z"
}
],
"non_entity_clients": 1,
"secret_syncs": 0
},
"warnings": null
}
```
</CodeBlockConfig>
## Update the client count configuration
@include 'alerts/restricted-root.mdx'
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)` - **DEPRECATED** The number
of months to report if no `start_time` is specified in a query.
- `enabled` `(string: enable, disable, default)` - Enable or disable counting of client activity. When set to `default`, 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.
<Note>
<EnterpriseAlert product="vault" inline />
License utilization cannot be reported if client counting is disabled.
As of 1.16.0, 1.15.6 and 1.14.10, client counting cannot be disabled as manual license utilization reporting is always enabled.
As of 1.14.0, 1.13.4, 1.12.8 and 1.11.12, client counting cannot be disabled when automated license utilization reporting is enabled.
</Note>
- `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
```json
{
"enabled": "enable",
"retention_months": 54
}
```
### Sample request
```shell-session
$ curl \
--request POST
--header "X-Vault-Token: ..." \
--data @payload.json
http://127.0.0.1:8200/v1/sys/internal/counters/config
```
## 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)` - returns `default-enabled` or `default-disabled` if the configuration is `default`.
- `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
```shell-session
$ curl \
--request GET
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/sys/internal/counters/config
```
### Sample response
<CodeBlockConfig hideClipboard>
```json
{
"request_id": "25a94b99-b49a-c4ac-cb7b-5ba0eb390a25",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"enabled": "default-enabled",
"queries_available": true,
"retention_months": 48,
"reporting_enabled": false,
"billing_start_timestamp": "2022-03-01T00:00:00Z",
},
"warnings": null
}
```
</CodeBlockConfig>
<Note title="Important change to supported versions">
As of 1.16.7, 1.17.3 and later,
the <a href="/vault/docs/concepts/billing-start-date">billing start date</a> 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:
- [Vault v1.16.x](/vault/docs/upgrading/upgrade-to-1.16.x#auto-rolled-billing-start-date)
- [Vault v1.17.x](/vault/docs/upgrading/upgrade-to-1.17.x#auto-rolled-billing-start-date)
</Note>
## 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 title="Tech preview">
This endpoint is currently in tech preview status.
</Note>
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_date` supplied 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.
- This endpoint can be called from all namespaces. The requested namespace will act as a filter. The exported data will include activity for the requested
namespace and all of its children.
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.
| 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, the billing start time will 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 current month will be used.
- `format` `(string, optional)` - The desired format of the output file. Allowed
values are `csv` and `json`. If no format is provided a default of `json`
will be used.
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:`.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/internal/counters/activity/export
```
### Sample JSON response
The entity alias names for userpass in the sample response records below are user-provided. They are
system-provided for AWS and Kubernetes based on how the auth backend has been configured. In the case of
AWS, an IAM role ID is used but this can be configured via the [iam_alias](/vault/api-docs/auth/aws#iam_alias)
or [ec2_alias](/vault/api-docs/auth/aws#ec2_alias) configuration parameters. In the case of Kubernetes, the entity
alias name has been populated with the service account ID though this can be configured via the
[alias_name_source](/vault/api-docs/auth/kubernetes#alias_name_source) configuration parameter.
<Tip title="Formatted for readability">
The activity records below are pretty-printed to improve readability. The API
returns JSON lines and will thus be compacted so that each record consumes a
single line.
</Tip>
<CodeBlockConfig hideClipboard>
```json
{
"entity_name": "admin",
"entity_alias_name": "admin",
"local_entity_alias": false,
"client_id": "3f210722-7210-98e8-1f0d-e6a39ffb29c6",
"client_type": "entity",
"namespace_id": "root",
"namespace_path": "",
"mount_accessor": "auth_userpass_a005db73",
"mount_type": "userpass",
"mount_path": "auth/userpass/",
"timestamp": "2024-07-10T09:33:51Z",
"policies": [
"secret-read",
"secret-list",
"secret-write",
"secret-delete"
],
"entity_metadata": {
"email_address": "admin@example.com"
},
"entity_alias_metadata": {},
"entity_alias_custom_metadata": {
"region": "west",
"group": "san_francisco",
"contact_email": "admin@example.com"
},
"entity_group_ids": [
"746fbaf9-ffeb-62b9-7f0b-42d79ca0883f"
]
}
{
"entity_name": "",
"entity_alias_name": "",
"local_entity_alias": false,
"client_id": "590198f7-9178-57d6-c345-48746bb438d8",
"client_type": "non-entity-token",
"namespace_id": "YWZzu",
"namespace_path": "ns1/a/",
"mount_accessor": "auth_ns_token_e3119312",
"mount_type": "ns_token",
"mount_path": "auth/token/",
"timestamp": "2024-07-08T11:35:23Z",
"policies": [],
"entity_metadata": {},
"entity_alias_metadata": {},
"entity_alias_custom_metadata": {},
"entity_group_ids": []
}
{
"entity_name": "jdoe",
"entity_alias_name": "jdoe",
"local_entity_alias": false,
"client_id": "665a54bf-8652-c0c5-8121-40adf0d9786a",
"client_type": "entity",
"namespace_id": "wOsmr",
"namespace_path": "ns1/a",
"mount_accessor": "auth_ldap_a005db73",
"mount_type": "ldap",
"mount_path": "auth/ldap/",
"timestamp": "2024-07-08T11:47:57Z",
"policies": [
"secret-read"
],
"entity_metadata": {},
"entity_alias_metadata": {},
"entity_alias_custom_metadata": {
"contact_email": "jdoe@example.com",
"region": "east",
"group": "new_york"
},
"entity_group_ids": [
"9f18cd4a-4e64-a2b2-b001-7b6b0dfb1270"
]
}
{
"entity_name": "jdoe",
"entity_alias_name": "jdoe",
"local_entity_alias": false,
"client_id": "0640a8f0-b315-cc8a-c0c2-713f663774df",
"client_type": "entity",
"namespace_id": "oIiGy",
"namespace_path": "ns1/b",
"mount_accessor": "auth_userpass_01a6ea85",
"mount_type": "userpass",
"mount_path": "auth/userpass/",
"timestamp": "2024-07-21T14:51:36Z",
"policies": [
"secret-read"
],
"entity_metadata": {},
"entity_alias_metadata": {},
"entity_alias_custom_metadata": {
"region": "east",
"group": "new_york"
},
"entity_group_ids": [
"76a374a1-72fd-30ca-2455-f51dfeaa805e"
]
}
{
"entity_name": "e91fa61e-d53e-4b0a-8fe2-ce813a064caa",
"entity_alias_name": "bee2d6ea-b873-47bc-9bc3-6f5e16e5c1b3",
"local_entity_alias": false,
"client_id": "cc7c504f-8d10-4add-9951-f6a194f188ec",
"client_type": "entity",
"namespace_id": "root",
"namespace_path": "",
"mount_accessor": "auth_kubernetes_b596406f",
"mount_type": "kubernetes",
"mount_path": "auth/kubernetes/",
"timestamp": "2024-07-10T09:33:51Z",
"policies": [
"secret-read"
],
"entity_metadata": {},
"entity_alias_metadata": {
"service_account_uid": "bee2d6ea-b873-47bc-9bc3-6f5e16e5c1b3",
"service_account_name": "vault-auth",
"service_account_namespace": "default",
"service_account_secret_name": "vault-auth-token"
},
"entity_alias_custom_metadata": {},
"entity_group_ids": []
}
{
"entity_name": "55ee5905-0314-485d-85ad-c29dc987a054",
"entity_alias_name": "admin",
"local_entity_alias": false,
"client_id": "cc7c504f-8d10-4add-9951-f6a194f188ec",
"client_type": "entity",
"namespace_id": "root",
"namespace_path": "",
"mount_accessor": "auth_aws_c223ff01",
"mount_type": "aws",
"mount_path": "auth/aws/",
"timestamp": "2024-07-10T09:33:51Z",
"policies": [
"secret-read"
],
"entity_metadata": {},
"entity_alias_metadata": {},
"entity_alias_custom_metadata": {},
"entity_group_ids": []
}
```
</CodeBlockConfig>
### Sample CSV response
Nested fields within the exported records will be flattened into individual CSV columns. Columns for arrays (`policies` and `entity_group_ids`)
will be named using the field name and underlying index (e.g. `policies.0`, `policies.1`). Columns for key-value pairs
(`entity_metadata`, `entity_alias_metadata`, and `entity_alias_custom_metadata`) will be named using the field name and underlying key
(e.g. `entity_metadata.email_address`, `entity_alias_metadata.region`). A flattened field will only be added if at least one record contains
it. If a top-level field (e.g. `entity_metadata`) is not populated in any of the
records then there will not be any flattened fields of prefix
`enttiy_metadata.`.
<CodeBlockConfig hideClipboard>
```text
entity_name,entity_alias_name,client_id,client_type,local_entity_alias,namespace_id,namespace_path,mount_accessor,mount_path,mount_type,timestamp,entity_alias_custom_metadata.contact_email,entity_alias_custom_metadata.group,entity_alias_custom_metadata.region,entity_metadata.email_address,entity_group_ids.0,policies.0,policies.1,policies.2,policies.4
admin,admin,3f210722-7210-98e8-1f0d-e6a39ffb29c6,entity,false,root,,auth_userpass_a005db73,auth/userpass/,userpass,2024-07-10T09:33:51Z,admin@example.com,san_francisco,west,admin@example.com,746fbaf9-ffeb-62b9-7f0b-42d79ca0883f,secret-read,secret-list,secret-write,secret-delete
,,590198f7-9178-57d6-c345-48746bb438d8,non-entity-token,false,YWZzu,ns1/a/,auth_ns_token_e3119312,auth/token/,ns_token,2024-07-08T11:35:23Z,,,,,,,,,
jdoe,jdoe,665a54bf-8652-c0c5-8121-40adf0d9786a,entity,false,wOsmr,ns1/a,auth_ldap_a005db73,auth/ldap/,ldap,2024-07-08T11:47:57Z,jdoe@example.com,new_york,east,,9f18cd4a-4e64-a2b2-b001-7b6b0dfb1270,secret-read,,,
jdoe,jdoe,0640a8f0-b315-cc8a-c0c2-713f663774df,entity,false,oIiGy,ns1/b,auth_userpass_01a6ea85,auth/userpass/,userpass,2024-07-21T14:51:36Z,,new_york,east,,76a374a1-72fd-30ca-2455-f51dfeaa805e,secret-read,,,
```
</CodeBlockConfig>
Reference in New Issue View Git Blame Copy Permalink