-
Notifications
You must be signed in to change notification settings - Fork 4.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Product usage reporting docs (#28858)
* First draft of product usage reporting docs * Table data, fix issues * Changelog
- Loading branch information
1 parent
f5e0fbc
commit 08a6d3a
Showing
5 changed files
with
231 additions
and
14 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| ```release-note:feature | ||
| **Product Usage Reporting**: Added product usage reporting, which collects anonymous, numerical, non-sensitive data about Vault feature usage, and adds it to the existing utilization reports. | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| --- | ||
| layout: docs | ||
| page_title: Reporting - Configuration | ||
| description: |- | ||
| The reporting stanza specifies various parameters for tuning reporting and licensing related values. | ||
| --- | ||
|
|
||
| # `replication` stanza | ||
|
|
||
| @include 'alerts/enterprise-only.mdx' | ||
|
|
||
| The `reporting` stanza specifies various parameters for tuning replication related values. | ||
|
|
||
| Please see the pages relating to | ||
| [license utilization reporting](/vault/docs/enterprise/license/utilization-reporting) | ||
| and [product usage reporting](/vault/docs/enterprise/license/product-usage-reporting) | ||
| for more information regarding the license reporting. | ||
|
|
||
| ```hcl | ||
| reporting { | ||
| snapshot_retention_time = 9600 | ||
| disable_product_usage_reporting = false | ||
| license { | ||
| enabled = true | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## `reporting` parameters | ||
|
|
||
| - `snapshot_retention_time` `(duration: 9600h)` - The retention time for manual reporting snapshots in hours. Defaults to 9600 (400 days). | ||
| Uses [duration format strings](/vault/docs/concepts/duration-format). | ||
| - `disable_product_usage_reporting` `(boolean: false)` - Determines whether [product usage reporting](/vault/docs/enterprise/license/product-usage-reporting) | ||
| is enabled. | ||
|
|
||
| ## `license` parameters | ||
|
|
||
| - `enabled` `(boolean: true)` - Toggles automatic reporting of license utilization. See the | ||
| [license utilization reporting](/vault/docs/enterprise/license/utilization-reporting) | ||
| page for more details. | ||
| - `billing_start_timestamp` `(timestamp)` - The start timestamp for billing for license reporting (manual and automated). | ||
| Defaults to the license start timestamp. |
131 changes: 131 additions & 0 deletions
131
website/content/docs/enterprise/license/product-usage-reporting.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,131 @@ | ||
| --- | ||
| layout: docs | ||
| page_title: Product usage reporting | ||
| description: >- | ||
| Learn what anonymous usage data HashiCorp collects as part of Enterprise utilization reporting. Enable or disable collection. | ||
| --- | ||
|
|
||
| # Product usage reporting | ||
|
|
||
| @include 'alerts/enterprise-only.mdx' | ||
|
|
||
| HashiCorp collects usage data about how Vault clusters are being used. This data is not | ||
| used for billing or and is numerical only, and no sensitive information of | ||
| any nature is being collected. The data is GDPR compliant and is collected as part of | ||
| the [license utilization reporting](/vault/docs/enterprise/license/utilization-reporting) | ||
| process. If automated reporting is enabled, this data will be collected automatically. | ||
| If automated reporting is disabled, then this will be collected as part of the manual reports. | ||
|
|
||
| ## Opt out | ||
|
|
||
| While none of the collected usage metrics are sensitive in any way, if you are still concerned | ||
| about these usage metrics being reported, then you can opt-out of them being collected. | ||
|
|
||
| If you are considering opting out because you’re worried about the data, we | ||
| strongly recommend that you review the [usage metrics list](#usage-metrics-list) | ||
| before opting out. If you have concerns with any of the automatically-reported | ||
| data please bring them to your account manager. | ||
|
|
||
| You have two options to opt out of product usage collection: | ||
|
|
||
| - HCL configuration (recommended) | ||
| - Environment variable (requires restart) | ||
|
|
||
|
|
||
| #### HCL configuration | ||
|
|
||
| Opting out in your product's configuration file doesn't require a system | ||
| restart, and is the method we recommend. Add the following block to your server | ||
| configuration file (e.g. `vault-config.hcl`). | ||
|
|
||
| ```hcl | ||
| reporting { | ||
| disable_product_usage_reporting = true | ||
| } | ||
| ``` | ||
|
|
||
| <Warning> | ||
|
|
||
| When you have a cluster, each node must have the reporting stanza in its | ||
| configuration to be consistent. In the event of leadership change, nodes will | ||
| use its server configuration to determine whether or not to opt-out the | ||
| product usage collection. Inconsistent configuration between nodes will change the | ||
| reporting status upon active unseal. | ||
|
|
||
| </Warning> | ||
|
|
||
|
|
||
| You will find the following entries in the server log. | ||
|
|
||
| <CodeBlockConfig hideClipboard> | ||
|
|
||
| ``` | ||
| [DEBUG] activity: there is no reporting agent configured, skipping counts reporting | ||
| ``` | ||
|
|
||
| </CodeBlockConfig> | ||
|
|
||
| #### Environment variable | ||
|
|
||
| If you need to, you can also opt out using an environment variable, which will | ||
| provide a startup message confirming that you have product usage data collection. | ||
| This option requires a system restart. | ||
|
|
||
| <Note> | ||
|
|
||
| If the reporting stanza exists in the configuration file, the | ||
| `OPTOUT_PRODUCT_USAGE_REPORTING` value overrides the configuration. | ||
|
|
||
| </Note> | ||
|
|
||
| Set the following environment variable. | ||
|
|
||
| ```shell-session | ||
| $ export OPTOUT_PRODUCT_USAGE_REPORTING=true | ||
| ``` | ||
|
|
||
| Now, restart your [Vault servers](/vault/docs/commands/server) from the shell | ||
| where you set the environment variable. | ||
|
|
||
| You will find the following entries in the server log. | ||
|
|
||
| <CodeBlockConfig hideClipboard> | ||
|
|
||
| ``` | ||
| [DEBUG] core: product usage reporting disabled | ||
| ``` | ||
|
|
||
| </CodeBlockConfig> | ||
|
|
||
| If your configuration file and environment variable differ, the environment | ||
| variable setting will take precedence. | ||
|
|
||
| ## Usage metrics list | ||
|
|
||
| HashiCorp collects the following product usage metrics as part of the `metrics` part of the | ||
| [JSON payload that it collects for licence utilization](/vault/docs/enterprise/license/utilization-reporting#example-payloads). | ||
| All of these metrics are numerical, and contain no sensitive values or additional metadata: | ||
|
|
||
| | Metric Name | Description | | ||
| |--------------------------------------------|--------------------------------------------------------------------------| | ||
| | `vault.namespaces.count` | Total number of namespaces. | | ||
| | `vault.leases.count` | Total number of leases within Vault. | | ||
| | `vault.quotas.ratelimit.count` | Total number of rate limit quotas within Vault. | | ||
| | `vault.quotas.leasecount.count` | Total number of lease count quotas within Vault. | | ||
| | `vault.kv.version1.secrets.count` | Total number of KVv1 secrets within Vault. | | ||
| | `vault.kv.version2.secrets.count` | Total number of KVv2 secrets within Vault. | | ||
| | `vault.kv.version1.secrets.namespace.max` | The highest number of KVv1 secrets in a namespace in Vault, e.g. `1000`. | | ||
| | `vault.kv.version2.secrets.namespace.max` | The highest number of KVv2 secrets in a namespace in Vault, e.g. `1000`. | | ||
| | `vault.kv.version1.secrets.namespace.min` | The lowest number of KVv1 secrets in a namespace in Vault, e.g. `2`. | | ||
| | `vault.kv.version2.secrets.namespace.min` | The highest number of KVv2 secrets in a namespace in Vault, e.g. `1000`. | | ||
| | `vault.kv.version1.secrets.namespace.mean` | The mean number of KVv1 secrets in namespaces in Vault, e.g. `52.8`. | | ||
| | `vault.kv.version1.secrets.namespace.mean` | The mean number of KVv2 secrets in namespaces in Vault, e.g. `52.8`. | | ||
|
|
||
| ## Usage metadata list | ||
|
|
||
| HashiCorp collects the following product usage metadata as part of the `metadata` part of the | ||
| [JSON payload that it collects for licence utilization](/vault/docs/enterprise/license/utilization-reporting#example-payloads): | ||
|
|
||
| | Metadata Name | Description | | ||
| |----------------------|----------------------------------------------------------------------| | ||
| | `replication_status` | Replication status of this cluster, e.g. `perf-disabled,dr-disabled` | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters