Merge pull request #5609 from hashicorp/docs/enterprise-utilization-r…

…eporting

Add docs for enterprise utilization reporting

website/content/docs/agent/config/config-files.mdx

@@ -711,6 +711,10 @@ Refer to the [formatting specification](https://golang.org/pkg/time/#ParseDurati
     servers in all federated datacenters must have this enabled before any client can use
     [`use_streaming_backend`](#use_streaming_backend).
 
+- `reporting`<EnterpriseAlert inline /> - This option allows options for HashiCorp reporting.
+    - `license` - The license object allows users to control automatic reporting of license utilization metrics to HashiCorp.
+      - `enabled`: (Defaults to `true`) Enables automatic license utilization reporting.
+
 - `segment` <EnterpriseAlert inline /> - Equivalent to the [`-segment` command-line flag](/consul/docs/agent/config/cli-flags#_segment).
 
   ~> **Warning:** The `segment` option cannot be used with the [`partition`](#partition-1) option.

website/content/docs/agent/config/index.mdx

@@ -73,6 +73,7 @@ The following agent configuration options are reloadable at runtime:
     them without a restart provides a recovery path that doesn't involve
     downtime. They generally shouldn't be changed otherwise.
 - [RPC rate limits](/consul/docs/agent/config/config-files#limits)
+- [Reporting](/consul/docs/agent/config/config-files#reporting)
 - [HTTP Maximum Connections per Client](/consul/docs/agent/config/config-files#http_max_conns_per_client)
 - Services
 - TLS Configuration

website/content/docs/enterprise/license/utilization-reporting.mdx

@@ -0,0 +1,168 @@
+---
+page_title: Automated license utilization reporting
+description: >-
+  Learn what data HashiCorp collects to meter Enterprise license utilization. Enable or disable reporting. Review sample payloads and logs.
+---
+
+# Automated license utilization reporting
+
+Automated license utilization reporting sends license utilization data to HashiCorp without requiring you to manually collect and report them. It also enables you to review your license usage with the monitoring solution you already use, such as Splunk and Datadog, as you optimize and manage your deployments. You can use these reports to understand how much more you can deploy under your current contract, which can help you protect against overutilization and budget for predicted consumption.  
+
+Automated reporting shares the minimum data required to validate license utilization as defined in our contracts. This data mostly consists of computed metrics, and it 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.
+
+## Enable automated reporting
+
+Before you enable automated reporting, make sure that outbound network traffic is configured correctly and upgrade your enterprise product to a version that supports it. If your installation is air-gapped or network settings are not in place, automated reporting will not work. 
+
+To enable automated reporting, complete the following steps:
+
+1. [Allow outbound HTTPS traffic on port 443](#allow-outbound-https-traffic)
+1. Upgrade to Consul Enterprise v1.16.0 or newer (#upgrade-to-consul-enterprise)
+1. Check product logs(#check-product-logs)
+
+### Allow outbound HTTPS traffic on port 443
+
+Make sure that your network allows HTTPS egress on port 443 from `https://reporting.hashicorp.services` by allow-listing the following IP addresses:
+
+- `100.20.70.12`
+- `35.166.5.222`
+- `23.95.85.111`
+- `44.215.244.1`
+
+### Upgrade to Consul Enterprise v1.16.0 or newer
+
+Upgrade to a release that supports license utilization reporting. These [releases](https://releases.hashicorp.com/consul/) include:
+
+- Consul Enterprise 1.16.0 and newer.
+- Consul Enterprise 1.15.4 and newer.
+- Consul Enterprise 1.14.8 and newer.
+- Consul Enterprise 1.13.9 and newer.
+
+### Check product logs
+
+Automatic license utilization reporting starts sending data within 24 hours. Check the product logs for records that the data sent successfully.
+
+<CodeBlockConfig hideClipboard>
+
+```
+[DEBUG] beginning snapshot export
+[DEBUG] creating payload
+[DEBUG] marshalling payload to json
+[DEBUG] generating authentication headers
+[DEBUG] creating request
+[DEBUG] sending request
+[DEBUG] performing request: method=POST url=https://census.license.hashicorp.services
+[DEBUG] recording audit record
+[INFO]  reporting: Report sent: auditRecord={"payload":{"payload_version":"1","license_id":"d2cdd857-4202-5a45-70a6-e4b531050c34","product":"consul","product_version":"1.16.0-dev+ent","export_timestamp":"2023-05-26T20:09:13.753921087Z","snapshots":[{"snapshot_version":1,"snapshot_id":"0001J724F90F4XWQDSAA76ZQWA","process_id":"01H1CTJPC1S8H7Q45MKTJ689ZW","timestamp":"2023-05-26T20:09:13.753513962Z","schema_version":"1.0.0","service":"consul","metrics":{"consul.billable.nodes":{"key":"consul.billable.nodes","kind":"counter","mode":"write","value":2},"consul.billable.service_instances":{"key":"consul.billable.service_instances","kind":"counter","mode":"write","value":2}}}],"metadata":{}}}
+[DEBUG] completed recording audit record
+[DEBUG] export finished successfully"
+```
+
+</CodeBlockConfig>
+
+If your installation is air-gapped or your network does not allow the correct egress, the logs show an error. 
+
+<CodeBlockConfig hideClipboard>
+
+```
+[DEBUG] reporting: beginning snapshot export
+[DEBUG] reporting: creating payload
+[DEBUG] reporting: marshalling payload to json
+[DEBUG] reporting: generating authentication headers
+[DEBUG] reporting: creating request
+[DEBUG] reporting: sending request
+[DEBUG] reporting: performing request: method=POST url=https://census.license.hashicorp.services
+[DEBUG] reporting: error status code received: statusCode=403
+```
+
+</CodeBlockConfig>
+
+In this case, reconfigure your network to allow egress and check back in 24 hours. 
+
+## Opt out
+
+If your installation is air-gapped or you want to manually collect and report on the same license utilization metrics, you can opt out of automated reporting. 
+
+Manually reporting these metrics can be time consuming. Opting out of automated reporting does not mean that you also opt out from sending license utilization metrics. Customers who opt out of automated reporting are still required to manually collect and send license utilization metrics to HashiCorp. 
+
+If you are considering opting out because you are worried about the data, we strongly recommend that you review the [example payloads](#example-payloads) before opting out. If you have concerns with any of the automatically reported data, raise these concerns with your account manager. 
+
+There are two methods for opting out of automated reporting: 
+
+- HCL configuration (recommended)
+- Environment variable (requires restart)
+
+We recommend opting out in your product's configuration file because it does not require a system restart. Add the following block to your `configuration.hcl` or `configuration.json` file.
+
+```hcl
+reporting {
+	license {
+		enabled = false
+  }
+}
+```
+
+When you opt out using an environment variable, once you restart your system it will provide a startup message confirming that you have disabled automated reporting. Set the following environment variable to disable automated reporting:
+
+<CodeBlockConfig>
+
+```shell-session
+$ export OPTOUT_LICENSE_REPORTING=true
+```
+
+</CodeBlockConfig>
+
+After you set the environment variable, restart your system to complete the process for opting out.
+
+```shell-session
+$ consul reload
+```
+
+
+Check your product logs 24 hours after opting out to make sure that the system is not trying to send reports. Keep in mind that if your configuration file and environment variable differ, the environment variable setting takes precedence.
+
+## Example payloads
+
+HashiCorp collects the following utilization data as JSON payloads: 
+`exporter_version` - The version of the licensing exporter
+
+<CodeBlockConfig hideClipboard>
+
+```json
+{
+  "payload": {
+    "payload_version": "1",
+    "license_id": "d2cdd857-4202-5a45-70a6-e4b531050c34",
+    "product": "consul",
+    "product_version": "1.16.0-dev+ent",
+    "export_timestamp": "2023-05-26T20:09:13.753921087Z",
+    "snapshots": [
+      {
+        "snapshot_version": 1,
+        "snapshot_id": "0001J724F90F4XWQDSAA76ZQWA",
+        "process_id": "01H1CTJPC1S8H7Q45MKTJ689ZW",
+        "timestamp": "2023-05-26T20:09:13.753513962Z",
+        "schema_version": "1.0.0",
+        "service": "consul",
+        "metrics": {
+          "consul.billable.nodes": {
+            "key": "consul.billable.nodes",
+            "kind": "counter",
+            "mode": "write",
+            "value": 2
+          },
+          "consul.billable.service_instances": {
+            "key": "consul.billable.service_instances",
+            "kind": "counter",
+            "mode": "write",
+            "value": 2
+          }
+        }
+      }
+    ],
+    "metadata": {}
+  }
+}
+```
+
+</CodeBlockConfig>

website/data/docs-nav-data.json

@@ -1628,6 +1628,10 @@
             "title": "Overview",
             "path": "enterprise/license/overview"
           },
+          {
+            "title": "Automated entitlement utilization reporting",
+            "path": "enterprise/license/utilization-reporting"
+          },
           {
             "title": "FAQ",
             "path": "enterprise/license/faq"