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
Lucy Davinhart || Strawb System dec3bcc1aa
docs: sys/internal/counters/activity, explain deprecation for current_billing_period (#28773) 
per discussion
https://hashicorp.slack.com/archives/CPEPB6WRL/p1729786785076429
the reason this parameter is deprecated is because it's no longer required. make that clear in the docs.
2024-10-25 14:31:06 +02:00

1371 lines
43 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 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
```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>
## Tokens
This endpoint returns the total number of Tokens.
| Method | Path |
| :----- | :------------------------------ |
| `GET` | `/sys/internal/counters/tokens` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/internal/counters/tokens
```
### Sample response
<CodeBlockConfig hideClipboard>
```json
{
"request_id": "75cbaa46-e741-3eba-2be2-325b1ba8f03f",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"counters": {
"service_tokens": {
"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, except for the
current month. The last element in the `months` response stanza will signify the current month. Furthermore, the
`new_clients` counts 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'
<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 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.
@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.
### 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":[
{
"path":"auth/up1/",
"counts":{
"entity_clients":10,
"non_entity_clients":10,
"secret_syncs": 0,
"acme_clients": 0,
"clients":20
}
},
{
"path":"auth/up2/",
"counts":{
"entity_clients":5,
"non_entity_clients":5,
"secret_syncs": 0,
"acme_clients": 0,
"clients":10
}
},
{
"path":"secrets/kv1/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":3,
"acme_clients": 0,
"clients":3
}
},
{
"path":"secrets/kv2/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients": 0,
"clients":2
}
},
{
"path":"secrets/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":[
{
"path":"auth/up1/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"path":"auth/up2/",
"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":[
{
"path":"auth/up2/",
"counts":{
"entity_clients":10,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":15
}
},
{
"path":"auth/up1/",
"counts":{
"entity_clients":3,
"non_entity_clients":2,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"path":"secrets/kv1/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":3,
"acme_clients":0,
"clients":3
}
},
{
"path":"secrets/kv2/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":2,
"acme_clients":0,
"clients":2
}
},
{
"path":"secrets/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":[
{
"path":"auth/up1/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"path":"auth/up2/",
"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":[
{
"path":"auth/up2/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"clients":5
}
},
{
"path":"auth/up1/",
"counts":{
"entity_clients":5,
"non_entity_clients":0,
"clients":5
}
},
{
"path":"secrets/kv1/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":1,
"clients":1
}
},
{
"path":"secrets/kv2/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":1,
"clients":1
}
},
{
"path":"secrets/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":[
{
"path":"auth/up1/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"path":"auth/up2/",
"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":[
{
"path":"auth/up1/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"path":"auth/up2/",
"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":[
{
"path":"auth/up1/",
"counts":{
"entity_clients":0,
"non_entity_clients":5,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"path":"auth/up2/",
"counts":{
"entity_clients":5,
"non_entity_clients":0,
"secret_syncs":0,
"acme_clients":0,
"clients":5
}
},
{
"path":"secrets/kv1/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":2,
"acme_clients":0,
"clients":2
}
},
{
"path":"secrets/kv2/",
"counts":{
"entity_clients":0,
"non_entity_clients":0,
"secret_syncs":1,
"acme_clients":0,
"clients":1
}
},
{
"path":"secrets/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>
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.
</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"
}
],
"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"
}
],
"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"
}
],
"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.
- `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="Techn 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