From 74accb7b32cd09a51b26c1cb634a3691d3e54c96 Mon Sep 17 00:00:00 2001 From: Violet Hynes Date: Tue, 12 Nov 2024 09:15:52 -0500 Subject: [PATCH] Product usage reporting docs (#28858) * First draft of product usage reporting docs * Table data, fix issues * Changelog --- changelog/28858.txt | 3 + website/content/docs/configuration/index.mdx | 4 + .../content/docs/configuration/reporting.mdx | 42 ++++++ .../license/product-usage-reporting.mdx | 131 ++++++++++++++++++ website/data/docs-nav-data.json | 18 +++ 5 files changed, 198 insertions(+) create mode 100644 changelog/28858.txt create mode 100644 website/content/docs/configuration/reporting.mdx create mode 100644 website/content/docs/enterprise/license/product-usage-reporting.mdx diff --git a/changelog/28858.txt b/changelog/28858.txt new file mode 100644 index 000000000000..422b9d650609 --- /dev/null +++ b/changelog/28858.txt @@ -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. +``` \ No newline at end of file diff --git a/website/content/docs/configuration/index.mdx b/website/content/docs/configuration/index.mdx index b1dbdea4597b..42b0c22c25fe 100644 --- a/website/content/docs/configuration/index.mdx +++ b/website/content/docs/configuration/index.mdx @@ -80,6 +80,9 @@ to specify where the configuration is. auto-unsealing, as well as for [seal wrapping][sealwrap] as an additional layer of data protection. +- `reporting` `([Reporting][reporting]: nil)` - + Configures options relating to license reporting in Vault. + - `cluster_name` `(string: )` – Specifies a human-readable identifier for the Vault cluster. If omitted, Vault will generate a value. The cluster name is included as a label in some [telemetry metrics](/vault/docs/internals/telemetry/metrics/). @@ -309,6 +312,7 @@ The following parameters are only used with Vault Enterprise [storage-backend]: /vault/docs/configuration/storage [listener]: /vault/docs/configuration/listener +[reporting]: /vault/docs/configuration/reporting [seal]: /vault/docs/configuration/seal [sealwrap]: /vault/docs/enterprise/sealwrap [telemetry]: /vault/docs/configuration/telemetry diff --git a/website/content/docs/configuration/reporting.mdx b/website/content/docs/configuration/reporting.mdx new file mode 100644 index 000000000000..4978d6dd3654 --- /dev/null +++ b/website/content/docs/configuration/reporting.mdx @@ -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. diff --git a/website/content/docs/enterprise/license/product-usage-reporting.mdx b/website/content/docs/enterprise/license/product-usage-reporting.mdx new file mode 100644 index 000000000000..860d2bc28c35 --- /dev/null +++ b/website/content/docs/enterprise/license/product-usage-reporting.mdx @@ -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 +} +``` + + + + 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. + + + + +You will find the following entries in the server log. + + + + ``` + [DEBUG] activity: there is no reporting agent configured, skipping counts reporting + ``` + + + +#### 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. + + + + If the reporting stanza exists in the configuration file, the + `OPTOUT_PRODUCT_USAGE_REPORTING` value overrides the configuration. + + + +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. + + + + ``` + [DEBUG] core: product usage reporting disabled + ``` + + + +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` | diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 908facdc1431..568fbd63e152 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -423,6 +423,15 @@ }, "path": "configuration/replication" }, + { + "title": "reporting", + "badge": { + "text": "ENTERPRISE", + "type": "outlined", + "color": "neutral" + }, + "path": "configuration/reporting" + }, { "title": "seal", "routes": [ @@ -476,6 +485,11 @@ }, { "title": "sentinel", + "badge": { + "text": "ENTERPRISE", + "type": "outlined", + "color": "neutral" + }, "path": "configuration/sentinel" }, { @@ -2777,6 +2791,10 @@ "title": "Manual license utilization reporting", "path": "enterprise/license/manual-reporting" }, + { + "title": "Product usage reporting", + "path": "enterprise/license/product-usage-reporting" + }, { "title": "FAQ", "path": "enterprise/license/faq"