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

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.

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 the number of clients per namespace, as the sum of clients calculated from the use of active entities and non-entity tokens. An "active entity" is a distinct entity that has created one or more tokens in the given time period. A "non-entity token" is a token with no attached entity ID. Both non-entity tokens and active entities have distinct client IDs. For more information on how clients map to these client IDs, and how clients are counted, please visit the client count concepts page.

A time period may be specified; otherwise it reports on a default reporting period, such as the previous twelve calendar months. Reports are only available with month granularity, after each month has completed. The response includes the actual time period covered, which may not exactly match the query parameters due to the monthly granularity of the data, or missing months in the requested time range.

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.

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.

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": {
    "start_time": "2019-11-01T00:00:00Z",
    "end_time": "2020-10-31T23:59:59Z",
    "total": {
      "distinct_entities": 90,
      "non_entity_tokens": 130,
      "clients": 220
    },
    "by_namespace": [
      {
        "namespace_id": "root",
        "namespace_path": "",
        "counts": {
          "distinct_entities": 85,
          "non_entity_tokens": 15,
          "clients": 100
        }
      },
      {
        "namespace_id": "DochC",
        "namespace_path": "ns2/",
        "counts": {
          "distinct_entities": 0,
          "non_entity_tokens": 100,
          "clients": 100
        }
      },
      {
        "namespace_id": "RtgpW",
        "namespace_path": "ns1/",
        "counts": {
          "distinct_entities": 5,
          "non_entity_tokens": 15,
          "clients": 20
        }
      }
    ]
  },
  "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

Partial Month Client Count

This endpoint returns the number of clients per namespace for the current month, as the sum of clients calculated from the use of active entities and non-entity tokens. An "active entity" is a distinct entity that has created one or more tokens in the given time period. A "non-entity token" is a token with no attached entity ID.

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.

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": "26be5ab9-dcac-9237-ec12-269a8ca64742",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "by_namespace":[
      {
        "namespace_id":"0lHBL",
        "namespace_path":"ns1/",
        "counts":{
           "distinct_entities":0,
           "non_entity_tokens":100,
           "clients":100
        } 
      },
      {
        "namespace_id":"RxD81",
        "namespace_path":"ns2/",
        "counts":{
          "distinct_entities":5,
          "non_entity_tokens":15,
          "clients":20
        }
      },
      {
        "namespace_id":"root",
        "namespace_path":"",
        "counts":{
          "distinct_entities":85,
          "non_entity_tokens":15,
          "clients":100
        }
      }
    ],
    "distinct_entities": 90,
    "non_entity_tokens": 130,
    "clients": 220
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Update the Client Count Configuration

The /sys/internal/counters/config endpoint is used to configure logging of active clients.

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
  },
  "warnings": null
}