/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

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/entities

Sample response

{
  "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
}

Tokens

This endpoint returns the total number of Tokens.

Method	Path
`GET`	`/sys/internal/counters/tokens`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/tokens

Sample response

{
  "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
}

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.

For Vault versions before 1.11, 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. Note that if no start_time and end_time parameters are specified, the billing period defaults to 12 months, so the endpoint will return activity information from the end of the previous month to the start of 12 months prior to that date.
As of 1.11, this behavior has been modified to return all available data within the specified billing period.
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.

{
   "by_namespace":[],
   "months":[],
}

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.

{
   "by_namespace":[
      {
         "namespace_id":"root",
         "namespace_path":"",
         "counts":{},
         "mounts":[
            {
               "path":"auth/up1/",
               "counts":{}
            },
            {
               "path":"auth/up2/",
               "counts":{}
            }
         ]
      }
   ]
}

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.

{
   "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":{}
      }
   ],
}

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.

{
   "months":[
      {
         "new_clients":{
            "counts":{},
            "namespaces":[
               {
                  "namespace_id":"root",
                  "namespace_path":"",
                  "counts":{},
                  "mounts":[
                     {
                        "path":"auth/up2/",
                        "counts":{}
                     },
                     {
                        "path":"auth/up1/",
                        "counts":{}
                     }
                  ]
               }
            ]
         }
      }
   ],
}

The distinct_entities field name has been deprecated since Vault 1.10. Refer to entity_clients field instead. The distinct_entities field is currently returned by the API for backward compatibility and it may be removed in the future.
The non_entity_tokens field name has been deprecated since Vault 1.10. Refer to non_entity_clients field instead. The non_entity_tokens field is currently returned by the API for backward compatibility, and it may be removed in the future.
If the end_date supplied 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, the default_report_months prior to the end_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 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 no limit_namespaces parameter is specified, client counts for all namespaces in specified usage period is returned.
current_billing_period (bool, optional) - 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.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/activity

Sample response

{
   "request_id":"26be5ab9-dcac-9237-ec12-269a8ca647d5",
   "lease_id":"",
   "renewable":false,
   "lease_duration":0,
   "data":{
      "by_namespace":[
         {
            "namespace_id":"root",
            "namespace_path":"",
            "counts":{
               "distinct_entities":20,
               "entity_clients":20,
               "non_entity_tokens":10,
               "non_entity_clients":10,
               "clients":30
            },
            "mounts":[
               {
                  "path":"auth/up1/",
                  "counts":{
                     "distinct_entities":10,
                     "entity_clients":10,
                     "non_entity_tokens":10,
                     "non_entity_clients":10,
                     "clients":20
                  }
               },
               {
                  "path":"auth/up2/",
                  "counts":{
                     "distinct_entities":5,
                     "entity_clients":5,
                     "non_entity_tokens":5,
                     "non_entity_clients":5,
                     "clients":10
                  }
               }
            ]
         },
         {
            "namespace_id":"s07UR",
            "namespace_path":"ns1/",
            "counts":{
               "distinct_entities":5,
               "entity_clients":5,
               "non_entity_tokens":5,
               "non_entity_clients":5,
               "clients":10
            },
            "mounts":[
               {
                  "path":"auth/up1/",
                  "counts":{
                     "distinct_entities":0,
                     "entity_clients":0,
                     "non_entity_tokens":5,
                     "non_entity_clients":5,
                     "clients":5
                  }
               },
               {
                  "path":"auth/up2/",
                  "counts":{
                     "distinct_entities":5,
                     "entity_clients":5,
                     "non_entity_tokens":0,
                     "non_entity_clients":0,
                     "clients":5
                  }
               }
            ]
         }
      ],
      "end_time":"2021-05-31T23:59:59Z",
      "months":[
         {
            "timestamp":"2021-05-01T00:00:00Z",
            "counts":{
               "distinct_entities":20,
               "entity_clients":20,
               "non_entity_tokens":10,
               "non_entity_clients":10,
               "clients":30
            },
            "namespaces":[
               {
                  "namespace_id":"root",
                  "namespace_path":"",
                  "counts":{
                     "distinct_entities":15,
                     "entity_clients":15,
                     "non_entity_tokens":5,
                     "non_entity_clients":5,
                     "clients":20
                  },
                  "mounts":[
                     {
                        "path":"auth/up2/",
                        "counts":{
                           "distinct_entities":10,
                           "entity_clients":10,
                           "non_entity_tokens":5,
                           "non_entity_clients":5,
                           "clients":15
                        }
                     },
                     {
                        "path":"auth/up1/",
                        "counts":{
                           "distinct_entities":3,
                           "entity_clients":3,
                           "non_entity_tokens":2,
                           "non_entity_clients":2,
                           "clients":5
                        }
                     }
                  ]
               },
               {
                  "namespace_id":"s07UR",
                  "namespace_path":"ns1/",
                  "counts":{
                     "distinct_entities":5,
                     "entity_clients":5,
                     "non_entity_tokens":5,
                     "non_entity_clients":5,
                     "clients":10
                  },
                  "mounts":[
                     {
                        "path":"auth/up1/",
                        "counts":{
                           "distinct_entities":0,
                           "entity_clients":0,
                           "non_entity_tokens":5,
                           "non_entity_clients":5,
                           "clients":5
                        }
                     },
                     {
                        "path":"auth/up2/",
                        "counts":{
                           "distinct_entities":5,
                           "entity_clients":5,
                           "non_entity_tokens":0,
                           "non_entity_clients":0,
                           "clients":5
                        }
                     }
                  ]
               }
            ],
            "new_clients":{
               "counts":{
                  "distinct_entities":10,
                  "entity_clients":10,
                  "non_entity_tokens":10,
                  "non_entity_clients":10,
                  "clients":20
               },
               "namespaces":[
                  {
                     "namespace_id":"root",
                     "namespace_path":"",
                     "counts":{
                        "distinct_entities":5,
                        "entity_clients":5,
                        "non_entity_tokens":5,
                        "non_entity_clients":5,
                        "clients":10
                     },
                     "mounts":[
                        {
                           "path":"auth/up2/",
                           "counts":{
                              "distinct_entities":0,
                              "entity_clients":0,
                              "non_entity_tokens":5,
                              "non_entity_clients":5,
                              "clients":5
                           }
                        },
                        {
                           "path":"auth/up1/",
                           "counts":{
                              "distinct_entities":5,
                              "entity_clients":5,
                              "non_entity_tokens":0,
                              "non_entity_clients":0,
                              "clients":5
                           }
                        }
                     ]
                  },
                  {
                     "namespace_id":"s07UR",
                     "namespace_path":"ns1/",
                     "counts":{
                        "distinct_entities":5,
                        "entity_clients":5,
                        "non_entity_tokens":5,
                        "non_entity_clients":5,
                        "clients":10
                     },
                     "mounts":[
                        {
                           "path":"auth/up1/",
                           "counts":{
                              "distinct_entities":0,
                              "entity_clients":0,
                              "non_entity_tokens":5,
                              "non_entity_clients":5,
                              "clients":5
                           }
                        },
                        {
                           "path":"auth/up2/",
                           "counts":{
                              "distinct_entities":5,
                              "entity_clients":5,
                              "non_entity_tokens":0,
                              "non_entity_clients":0,
                              "clients":5
                           }
                        }
                     ]
                  }
               ]
            }
         },
         {
            "timestamp":"2021-04-01T00:00:00Z",
            "counts":{
               "distinct_entities":5,
               "entity_clients":5,
               "non_entity_tokens":5,
               "non_entity_clients":5,
               "clients":10
            },
            "namespaces":[
               {
                  "namespace_id":"root",
                  "namespace_path":"",
                  "counts":{
                     "distinct_entities":5,
                     "entity_clients":5,
                     "non_entity_tokens":5,
                     "non_entity_clients":5,
                     "clients":10
                  },
                  "mounts":[
                     {
                        "path":"auth/up1/",
                        "counts":{
                           "distinct_entities":0,
                           "entity_clients":0,
                           "non_entity_tokens":5,
                           "non_entity_clients":5,
                           "clients":5
                        }
                     },
                     {
                        "path":"auth/up2/",
                        "counts":{
                           "distinct_entities":5,
                           "entity_clients":5,
                           "non_entity_tokens":0,
                           "non_entity_clients":0,
                           "clients":5
                        }
                     }
                  ]
               }
            ],
            "new_clients":{
               "counts":{
                  "distinct_entities":5,
                  "entity_clients":5,
                  "non_entity_tokens":5,
                  "non_entity_clients":5,
                  "clients":10
               },
               "namespaces":[
                  {
                     "namespace_id":"root",
                     "namespace_path":"",
                     "counts":{
                        "distinct_entities":5,
                        "entity_clients":5,
                        "non_entity_tokens":5,
                        "non_entity_clients":5,
                        "clients":10
                     },
                     "mounts":[
                        {
                           "path":"auth/up1/",
                           "counts":{
                              "distinct_entities":0,
                              "entity_clients":0,
                              "non_entity_tokens":5,
                              "non_entity_clients":5,
                              "clients":5
                           }
                        },
                        {
                           "path":"auth/up2/",
                           "counts":{
                              "distinct_entities":5,
                              "entity_clients":5,
                              "non_entity_tokens":0,
                              "non_entity_clients":0,
                              "clients":5
                           }
                        }
                     ]
                  }
               ]
            }
         }
      ],
      "start_time":"2021-01-01T00:00:00Z",
      "total":{
         "distinct_entities":20,
         "entity_clients":20,
         "non_entity_tokens":20,
         "non_entity_clients":20,
         "clients":40
      }
   },
   "wrap_info":null,
   "warnings":null,
   "auth":null
}

Sample request for a single month

$ 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 to get client counts for top 2 namespaces with highest activity for a usage period

$ 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.

This endpoint was added in Vault 1.7.

Method	Path
`GET`	`/sys/internal/counters/activity/monthly`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/activity/monthly

Sample response

{
  "request_id": "d0d37f90-96ec-28c7-b59c-b53612cbbcad",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "by_namespace": [
      {
        "counts": {
          "clients": 1,
          "distinct_entities": 0,
          "entity_clients": 0,
          "non_entity_clients": 1,
          "non_entity_tokens": 1
        },
        "mounts": [
          {
            "counts": {
              "clients": 1,
              "distinct_entities": 0,
              "entity_clients": 0,
              "non_entity_clients": 1,
              "non_entity_tokens": 0
            },
            "mount_path": "auth_token_0747d59c"
          }
        ],
        "namespace_id": "root",
        "namespace_path": ""
      }
    ],
    "clients": 1,
    "distinct_entities": 0,
    "entity_clients": 0,
    "months": [
      {
        "counts": {
          "clients": 1,
          "distinct_entities": 0,
          "entity_clients": 0,
          "non_entity_clients": 1,
          "non_entity_tokens": 0
        },
        "namespaces": [
          {
            "counts": {
              "clients": 1,
              "distinct_entities": 0,
              "entity_clients": 0,
              "non_entity_clients": 1,
              "non_entity_tokens": 0
            },
            "mounts": [
              {
                "counts": {
                  "clients": 1,
                  "distinct_entities": 0,
                  "entity_clients": 0,
                  "non_entity_clients": 1,
                  "non_entity_tokens": 0
                },
                "mount_path": "auth_token_0747d59c"
              }
            ],
            "namespace_id": "root",
            "namespace_path": ""
          }
        ],
        "new_clients": {
          "counts": {
            "clients": 1,
            "distinct_entities": 0,
            "entity_clients": 0,
            "non_entity_clients": 1,
            "non_entity_tokens": 0
          },
          "namespaces": [
            {
              "counts": {
                "clients": 1,
                "distinct_entities": 0,
                "entity_clients": 0,
                "non_entity_clients": 1,
                "non_entity_tokens": 0
              },
              "mounts": [
                {
                  "counts": {
                    "clients": 1,
                    "distinct_entities": 0,
                    "entity_clients": 0,
                    "non_entity_clients": 1,
                    "non_entity_tokens": 0
                  },
                  "mount_path": "auth_token_0747d59c"
                }
              ],
              "namespace_id": "root",
              "namespace_path": ""
            }
          ]
        },
        "timestamp": "2022-04-01T04:00:00Z"
      }
    ],
    "non_entity_clients": 1,
    "non_entity_tokens": 1
  },
  "warnings": null
}

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

{
  "enabled": "enable",
  "default_report_months": 3,
  "retention_months": 12
}

Sample request

$ 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.

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

$ curl \
    --request GET
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/internal/counters/config

Sample response

{
  "request_id": "25a94b99-b49a-c4ac-cb7b-5ba0eb390a25",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "default_report_months": 12,
    "enabled": "default-enabled",
    "queries_available": true,
    "retention_months": 24,
    "reporting_enabled": false,
    "billing_start_timestamp": "2022-03-01T00:00:00Z",
  },
  "warnings": null
}

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_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 was added in Vault 1.11.

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 default_report_months prior to the end_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 the previous calendar 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.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/activity/export

Sample response

{"client_id":"3f210722-7210-98e8-1f0d-e6a39ffb29c6","namespace_id":"root","timestamp":1653350457,"mount_accessor":"auth_userpass_bb52979d"}
{"client_id":"X/Yed4Oj4cqODj9tSHjKwnRy5QVSBRlX3COxjjWSXyI=","namespace_id":"root","timestamp":1653350491,"non_entity":true,"mount_accessor":"auth_token_f6f2c11c"}
{"client_id":"d93405dc-b592-b1c3-a520-14e618d359c1","namespace_id":"root","timestamp":1653350501,"mount_accessor":"auth_userpass_bb52979d"}