backport of commit aa09d0c (#28903)

Co-authored-by: Violet Hynes <[email protected]>

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.
+```

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: <generated>)` – 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/).
@@ -306,6 +309,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

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.

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
+}
+```
+
+<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` |

website/data/docs-nav-data.json

@@ -403,6 +403,15 @@
         },
         "path": "configuration/replication"
       },
+      {
+        "title": "<code>reporting</code>",
+        "badge": {
+          "text": "ENTERPRISE",
+          "type": "outlined",
+          "color": "neutral"
+        },
+        "path": "configuration/reporting"
+      },
       {
         "title": "<code>seal</code>",
         "routes": [
@@ -464,6 +473,11 @@
       },
       {
         "title": "<code>sentinel</code>",
+        "badge": {
+          "text": "ENTERPRISE",
+          "type": "outlined",
+          "color": "neutral"
+        },
         "path": "configuration/sentinel"
       },
       {
@@ -2832,6 +2846,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"