From 819f056aea327f906c6dde559926abcfe6ca97a5 Mon Sep 17 00:00:00 2001 From: Guilherme Santos <157053549+gsantos-hc@users.noreply.github.com> Date: Tue, 21 Oct 2025 11:44:41 -0400 Subject: [PATCH 1/2] VAULT-39930 Add certificate counters to license usage reporting Add mention of PKI certificate counts to the automated and manual license usage reporting docs. --- .../license/utilization/auto-reporting.mdx | 187 ++++++++++-------- .../license/utilization/manual-reporting.mdx | 154 +++++++-------- 2 files changed, 184 insertions(+), 157 deletions(-) diff --git a/content/vault/v1.21.x (rc)/content/docs/license/utilization/auto-reporting.mdx b/content/vault/v1.21.x (rc)/content/docs/license/utilization/auto-reporting.mdx index 3b8ca8eef..e258e409f 100644 --- a/content/vault/v1.21.x (rc)/content/docs/license/utilization/auto-reporting.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/license/utilization/auto-reporting.mdx @@ -13,13 +13,17 @@ description: >- Automated license utilization reporting sends license utilization data to HashiCorp without requiring you to manually collect and report them. -Automated reporting shares the minimum data required to validate license -utilization as defined in our contracts. They consist of mostly computed metrics -and will never contain Personal Identifiable Information (PII) or other -sensitive information. Automated reporting shares the data with HashiCorp using -a secure, unidirectional HTTPS API and makes an auditable record in the product -logs each time it submits a report. The reporting process submits -reports roughly once every 24 hours. +Automated reporting shares the minimum data required to validate license utilization +as defined in our contracts. They consist of mostly computed metrics and will never +contain Personal Identifiable Information (PII) or other sensitive information. +As of Vault 1.21+, the metrics include counters related to the number of: + +- [Vault clients](../../concepts/client-count/counting) +- Certificates issued by Vault's built-in PKI secrets engine + +Automated reporting shares the data with HashiCorp using a secure, unidirectional +HTTPS API and makes an auditable record in the product logs each time it submits +a report. The reporting process submits reports roughly once every 24 hours. ## Enable automated reporting @@ -113,7 +117,6 @@ You have two options to opt out of automated reporting: - HCL configuration (recommended) - Environment variable (requires restart) - #### HCL configuration Opting out in your product’s configuration file doesn’t require a system @@ -138,7 +141,6 @@ reporting status upon active unseal. - You will find the following entry in the server log. @@ -182,7 +184,6 @@ You will find the following entries in the server log. - Check your product logs roughly 24 hours after opting out to make sure that the system isn’t trying to send reports. @@ -250,25 +251,27 @@ HashiCorp collects the following utilization data as JSON payloads: - `export_timestamp`- The date and time for this contribution - `snapshots` - An array of snapshot details. A snapshot is a structure that represents a single data collection - - `snapshot_version` - The version of the snapshot package that produced this - snapshot - - `snapshot_id` - A unique identifier for this particular snapshot - - `process_id` - An identifier for the system that produced this snapshot - - `timestamp` - The date and time for this snapshot - - `schema_version` - The version of the schema associated with this snapshot - - `service` - The service that produced this snapshot (likely to be product - name) - - `metrics` - A map of representations of snapshot metrics contained within - this snapshot - - `key` - The key name associated with this metric - - `kind` - The kind of metric (feature, counter, sum, or mean) - - `mode` - The mode of operation associated with this metric (write or - collect) - - `labels` - The labels associated with each collected metric - - `entity` - The sum of tokens generated for a unique client identifier - - `nonentity` - The sum of tokens without an entity attached -- `metadata` - Optional product-specific metadata - - `billing_start` - The billing start date associated with the reporting cluster (license start date if not configured). + - `snapshot_version` - The version of the snapshot package that produced this + snapshot + - `snapshot_id` - A unique identifier for this particular snapshot + - `process_id` - An identifier for the system that produced this snapshot + - `timestamp` - The date and time for this snapshot + - `schema_version` - The version of the schema associated with this snapshot + - `service` - The service that produced this snapshot (likely to be product + name) + - `metrics` - A map of representations of snapshot metrics contained within + this snapshot + - `key` - The key name associated with this metric + - `kind` - The kind of metric (feature, counter, sum, or mean) + - `mode` - The mode of operation associated with this metric (write or + collect) + - `labels` - The labels associated with each collected metric + - `entity` - The sum of tokens generated for a unique client identifier + - `nonentity` - The sum of tokens without an entity attached + - `metadata` - Optional product-specific metadata + - `billing_start` - The billing start date associated with the reporting cluster (license start date if not configured). + - `cluster_id` - The cluster UUID as shown by `vault status` on the reporting cluster. + - `development_cluster` - Whether the cluster is operating as a development (non-production) cluster. @@ -283,60 +286,85 @@ HashiCorp collects the following utilization data as JSON payloads: - - `cluster_id` - The cluster UUID as shown by `vault status` on the reporting - cluster. - - `development_cluster` - Whether the cluster is operating as a development (non-production) cluster. - ```json { - "payload_version": "1", - "license_id": "97afe7b4-b9c8-bf19-bf35-b89b5cc0efea", - "product": "vault", - "product_version": "1.14.0-rc1+ent", - "export_timestamp": "2023-06-01T11:39:00.76643-04:00", - "snapshots": [ - { - "snapshot_version": 1, - "snapshot_id": "0001J7HEWM1PEHPMF5YZT8EV65", - "process_id": "01H1VSQMNYAP77R566F1Y03GE6", - "timestamp": "2023-06-01T11:39:00.766099-04:00", - "schema_version": "1.0.0", - "service": "vault", - "metrics": { - "clientcount.current_month_estimate": { - "key": "clientcount.current_month_estimate", - "kind": "sum", - "mode": "write", - "labels": { - "type": { - "entity": 20, - "nonentity": 11 - } - } - }, - "clientcount.previous_month_complete": { - "key": "clientcount.previous_month_complete", - "kind": "sum", - "mode": "write", - "labels": { - "type": { - "entity": 10, - "nonentity": 11 - } - } - } - } - } - ], - "metadata": { - "vault": { - "billing_start": "2023-03-01T00:00:00Z", - "cluster_id": "a8d95acc-ec0a-6087-d7f6-4f054ab2e7fd", - "development_cluster": "false", - } - } + "payload_version": "1", + "license_id": "7d68b16a-74fe-3b9f-a1a7-08cf461fff1c", + "product": "vault", + "product_version": "1.21.0+ent", + "export_timestamp": "2024-02-08T18:55:28.085215-08:00", + "snapshots": [ + { + "snapshot_version": 2, + "id": "0001JWAY00BRF8TEXC9CVRHBAC", + "timestamp": "2024-02-08T16:55:28.085215-08:00", + "schema_version": "2.0.0", + "product": "vault", + "process_id": "01HP5NJS21HN50FY0CBS0SYGCH", + "metrics": { + "clientcount.current_month_estimate.type.acme_client": { + "key": "clientcount.current_month_estimate.type.acme_client", + "value": 0, + "mode": "write" + }, + "clientcount.current_month_estimate.type.entity": { + "key": "clientcount.current_month_estimate.type.entity", + "value": 20, + "mode": "write" + }, + "clientcount.current_month_estimate.type.nonentity": { + "key": "clientcount.current_month_estimate.type.nonentity", + "value": 11, + "mode": "write" + }, + "clientcount.current_month_estimate.type.secret_sync": { + "key": "clientcount.current_month_estimate.type.secret_sync", + "value": 0, + "mode": "write" + }, + "clientcount.previous_month_complete.type.acme_client": { + "key": "clientcount.previous_month_complete.type.acme_client", + "value": 0, + "mode": "write" + }, + "clientcount.previous_month_complete.type.entity": { + "key": "clientcount.previous_month_complete.type.entity", + "value": 0, + "mode": "write" + }, + "clientcount.previous_month_complete.type.nonentity": { + "key": "clientcount.previous_month_complete.type.nonentity", + "value": 0, + "mode": "write" + }, + "clientcount.previous_month_complete.type.secret_sync": { + "key": "clientcount.previous_month_complete.type.secret_sync", + "value": 0, + "mode": "write" + }, + "certcount.current_month_estimate": { + "key": "certcount.current_month_estimate", + "value": 0, + "mode": "write" + }, + "certcount.previous_month_complete": { + "key": "certcount.previous_month_complete", + "value": 0, + "mode": "write" + } + }, + "product_version": "1.21.0+ent", + "license_id": "7d68b16a-74fe-3b9f-a1a7-08cf461fff1c", + "checksum": 6861637915450723051, + "metadata": { + "billing_start": "2023-05-04T00:00:00Z", + "cluster_id": "16d0ff5b-9d40-d7a7-384c-c9b95320c60e", + "development_cluster": "false" + } + } + ] } ``` @@ -349,4 +377,3 @@ When upgrading Vault from 1.8 (or earlier) to 1.9 (or later), utilization report Starting in Vault 1.9, the activity log records and de-duplicates non-entity tokens by using the namespace and token's policies to generate a unique identifier. Because Vault did not create identifiers for these tokens before 1.9, the activity log cannot know whether this token has been seen pre-1.9. To prevent inaccurate and inflated counts, the activity log will ignore any counts of non-entity tokens that were created before the upgrade and only the non-entity tokens from versions 1.9 and later will be counted. See the client count [overview](/vault/docs/concepts/client-count) and [FAQ](/vault/docs/concepts/client-count/faq) for more information. - diff --git a/content/vault/v1.21.x (rc)/content/docs/license/utilization/manual-reporting.mdx b/content/vault/v1.21.x (rc)/content/docs/license/utilization/manual-reporting.mdx index e65a2920b..c088f5b54 100644 --- a/content/vault/v1.21.x (rc)/content/docs/license/utilization/manual-reporting.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/license/utilization/manual-reporting.mdx @@ -71,8 +71,8 @@ path "sys/utilization" { **Example:** ```shell-session - $ vault operator utilization -message=”Change Control 654987” \ - -output=”/utilization/reports/latest.json” + $ vault operator utilization -message="Change Control 654987" \ + -output="/utilization/reports/latest.json" ``` This command will export all the persisted snapshots into a bundle. The @@ -82,18 +82,17 @@ path "sys/utilization" { **Available command flags:** - - `-message` `(string: “”)` - Provide context about the conditions under - which the report was generated and submitted. This message is not included - in the license utilization bundle but will be included in the vault server - logs. (optional) + - `-message` `(string: "")` - Provide context about the conditions under + which the report was generated and submitted. This message is not included + in the license utilization bundle but will be included in the vault server + logs. (optional) - `-today-only` `(bool: false)` - To include only today’s snapshot, no - historical snapshots. If no snapshots were persisted in the last 24 hrs, it - takes a snapshot and exports it to a bundle. (optional) - - - `-output` `(string: “”)` - Specifies the output path for the bundle. - Defaults to a time-based generated file name. (optional) + historical snapshots. If no snapshots were persisted in the last 24 hrs, it + takes a snapshot and exports it to a bundle. (optional) + - `-output` `(string: "")` - Specifies the output path for the bundle. + Defaults to a time-based generated file name. (optional) ### Send the data bundle to HashiCorp @@ -138,72 +137,73 @@ The default retention period is 400 days. ```json { - "snapshot_version": 2, - "id": "0001JWAY00BRF8TEXC9CVRHBAC", - "timestamp": "2024-02-08T16:55:28.085215-08:00", - "schema_version": "2.0.0", - "product": "vault", - "process_id": "01HP5NJS21HN50FY0CBS0SYGCH", - "metrics": { - "clientcount.current_month_estimate.type.acme_client": { - "key": "clientcount.current_month_estimate.type.acme_client", - "value": 0, - "mode": "write" - }, - "clientcount.current_month_estimate.type.entity": { - "key": "clientcount.current_month_estimate.type.entity", - "value": 20, - "mode": "write" - }, - "clientcount.current_month_estimate.type.nonentity": { - "key": "clientcount.current_month_estimate.type.nonentity", - "value": 11, - "mode": "write" - }, - "clientcount.current_month_estimate.type.secret_sync": { - "key": "clientcount.current_month_estimate.type.secret_sync", - "value": 0, - "mode": "write" - }, - "clientcount.previous_month_complete.type.acme_client": { - "key": "clientcount.previous_month_complete.type.acme_client", - "value": 0, - "mode": "write" - }, - "clientcount.previous_month_complete.type.entity": { - "key": "clientcount.previous_month_complete.type.entity", - "value": 0, - "mode": "write" - }, - "clientcount.previous_month_complete.type.nonentity": { - "key": "clientcount.previous_month_complete.type.nonentity", - "value": 0, - "mode": "write" - }, - "clientcount.previous_month_complete.type.secret_sync": { - "key": "clientcount.previous_month_complete.type.secret_sync", - "value": 0, - "mode": "write" - }, - "certcount.current_month_estimate": { - "key": "certcount.current_month_estimate", - "value": 0, - "mode": "write" - }, - "certcount.previous_month_complete": { - "key": "certcount.previous_month_complete", - "value": 0, - "mode": "write" - } - }, - "product_version": "1.16.0+ent", - "license_id": "7d68b16a-74fe-3b9f-a1a7-08cf461fff1c", - "checksum": 6861637915450723051, - "metadata": { - "billing_start": "2023-05-04T00:00:00Z", - "cluster_id": "16d0ff5b-9d40-d7a7-384c-c9b95320c60e", - "development_cluster": "false" - } + "snapshot_version": 2, + "id": "0001JWAY00BRF8TEXC9CVRHBAC", + "timestamp": "2024-02-08T16:55:28.085215-08:00", + "schema_version": "2.0.0", + "product": "vault", + "process_id": "01HP5NJS21HN50FY0CBS0SYGCH", + "metrics": { + "clientcount.current_month_estimate.type.acme_client": { + "key": "clientcount.current_month_estimate.type.acme_client", + "value": 0, + "mode": "write" + }, + "clientcount.current_month_estimate.type.entity": { + "key": "clientcount.current_month_estimate.type.entity", + "value": 20, + "mode": "write" + }, + "clientcount.current_month_estimate.type.nonentity": { + "key": "clientcount.current_month_estimate.type.nonentity", + "value": 11, + "mode": "write" + }, + "clientcount.current_month_estimate.type.secret_sync": { + "key": "clientcount.current_month_estimate.type.secret_sync", + "value": 0, + "mode": "write" + }, + "clientcount.previous_month_complete.type.acme_client": { + "key": "clientcount.previous_month_complete.type.acme_client", + "value": 0, + "mode": "write" + }, + "clientcount.previous_month_complete.type.entity": { + "key": "clientcount.previous_month_complete.type.entity", + "value": 0, + "mode": "write" + }, + "clientcount.previous_month_complete.type.nonentity": { + "key": "clientcount.previous_month_complete.type.nonentity", + "value": 0, + "mode": "write" + }, + "clientcount.previous_month_complete.type.secret_sync": { + "key": "clientcount.previous_month_complete.type.secret_sync", + "value": 0, + "mode": "write" + }, + "certcount.current_month_estimate": { + "key": "certcount.current_month_estimate", + "value": 0, + "mode": "write" + }, + "certcount.previous_month_complete": { + "key": "certcount.previous_month_complete", + "value": 0, + "mode": "write" + } + }, + "product_version": "1.21.0+ent", + "license_id": "7d68b16a-74fe-3b9f-a1a7-08cf461fff1c", + "checksum": 6861637915450723051, + "metadata": { + "billing_start": "2023-05-04T00:00:00Z", + "cluster_id": "16d0ff5b-9d40-d7a7-384c-c9b95320c60e", + "development_cluster": "false" + } +} ``` From f4d5dc8f38b7e8bee4b05596114d1aff55e9d69f Mon Sep 17 00:00:00 2001 From: Guilherme Santos <157053549+gsantos-hc@users.noreply.github.com> Date: Tue, 21 Oct 2025 21:04:17 -0400 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> --- .../license/utilization/auto-reporting.mdx | 26 ++++++++++--------- .../license/utilization/manual-reporting.mdx | 2 +- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/content/vault/v1.21.x (rc)/content/docs/license/utilization/auto-reporting.mdx b/content/vault/v1.21.x (rc)/content/docs/license/utilization/auto-reporting.mdx index e258e409f..bba9fa7ba 100644 --- a/content/vault/v1.21.x (rc)/content/docs/license/utilization/auto-reporting.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/license/utilization/auto-reporting.mdx @@ -14,16 +14,17 @@ Automated license utilization reporting sends license utilization data to HashiCorp without requiring you to manually collect and report them. Automated reporting shares the minimum data required to validate license utilization -as defined in our contracts. They consist of mostly computed metrics and will never -contain Personal Identifiable Information (PII) or other sensitive information. -As of Vault 1.21+, the metrics include counters related to the number of: +as defined in our contracts. The reported data consists mostly of computed metrics +and never contains personal identifiable information (PII) or other sensitive information. +As of Vault 1.21+, automated metrics include the following: -- [Vault clients](../../concepts/client-count/counting) -- Certificates issued by Vault's built-in PKI secrets engine +- The number of [Vault clients](../../concepts/client-count/counting) +- The number of certificates issued by the PKI secrets engine. -Automated reporting shares the data with HashiCorp using a secure, unidirectional -HTTPS API and makes an auditable record in the product logs each time it submits -a report. The reporting process submits reports roughly once every 24 hours. +Automated reporting writes to your Vault logs every time it submits a +report and shares the report data with HashiCorp using a secure, +unidirectional HTTPS API call. The reporting process submits reports +roughly once every 24 hours. ## Enable automated reporting @@ -251,8 +252,8 @@ HashiCorp collects the following utilization data as JSON payloads: - `export_timestamp`- The date and time for this contribution - `snapshots` - An array of snapshot details. A snapshot is a structure that represents a single data collection - - `snapshot_version` - The version of the snapshot package that produced this - snapshot + - `snapshot_version` - The version of the snapshot package that produced the reporting + snapshot. - `snapshot_id` - A unique identifier for this particular snapshot - `process_id` - An identifier for the system that produced this snapshot - `timestamp` - The date and time for this snapshot @@ -269,9 +270,10 @@ HashiCorp collects the following utilization data as JSON payloads: - `entity` - The sum of tokens generated for a unique client identifier - `nonentity` - The sum of tokens without an entity attached - `metadata` - Optional product-specific metadata - - `billing_start` - The billing start date associated with the reporting cluster (license start date if not configured). + - `billing_start` - The billing start date associated with the reporting + cluster or the license start date if you do not have a billing date configured. - `cluster_id` - The cluster UUID as shown by `vault status` on the reporting cluster. - - `development_cluster` - Whether the cluster is operating as a development (non-production) cluster. + - `development_cluster` - Whether or not the cluster operates as a development (non-production) cluster. diff --git a/content/vault/v1.21.x (rc)/content/docs/license/utilization/manual-reporting.mdx b/content/vault/v1.21.x (rc)/content/docs/license/utilization/manual-reporting.mdx index c088f5b54..c5654fd9f 100644 --- a/content/vault/v1.21.x (rc)/content/docs/license/utilization/manual-reporting.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/license/utilization/manual-reporting.mdx @@ -92,7 +92,7 @@ path "sys/utilization" { takes a snapshot and exports it to a bundle. (optional) - `-output` `(string: "")` - Specifies the output path for the bundle. - Defaults to a time-based generated file name. (optional) + Defaults to a time-based generated file name. ### Send the data bundle to HashiCorp