Backport of Enterprise reporting: add product usage metrics into release/1.8.x (#27011)

Add documentation for an enterprise-only feature which will allow us on the Nomad team to better understand how Nomad is being used by enterprise customers.

This does not apply at all to CE code or binaries. This only documents what metrics we gather in enterprise binaries, and how to disable the extra metrics if desired.

---------

Co-authored-by: Daniel Bennett <[email protected]>
Co-authored-by: Daniel Bennett <[email protected]>

Author: hc-github-team-nomad-core

.changelog/27005.txt

@@ -0,0 +1,3 @@
+```release-note:improvement
+reporting (Enterprise): Include product usage metrics with license utilization reports
+```

website/content/commands/operator/utilization.mdx

@@ -0,0 +1,79 @@
+---
+layout: docs
+page_title: nomad operator utilization command reference
+description: |-
+  The "operator utilization" generates utilization reporting bundles for Nomad Enterprise users.
+---
+
+# `nomad operator utilization` command reference
+
+The `operator utilization` command allows Nomad Enterprise users to generate
+utilization reporting bundles. If you have disabled [automated
+reporting](/nomad/docs/enterprise/license/utilization-reporting), use
+this command to manually generate the report and send it to HashiCorp. Nomad
+takes a new snapshot when there are no snapshots from the past twenty-four
+hours.
+
+If ACLs are enabled, this command requires a token with the `operator:write`
+capability.
+
+<EnterpriseAlert />
+
+## Options
+
+- `-message` `(string; "")` - Provide context about the conditions under which
+  the report was generated and submitted. This message is not included in the
+  utilization bundle but is included in the Nomad server logs.
+
+- `-output` `(string; "")` - Specifies the output path for the bundle. Defaults
+  to a time-based generated file name in the current working directory.
+
+- `-today-only` `(bool: false)` - Include snapshots from the previous 24 hours,
+  not historical snapshots.
+
+## Examples
+
+Create a utilization reporting bundle that includes all persisted historical
+snapshots and has the default bundle name
+(`nomad-utilization-<time_stamp>.json`).
+
+```shell-session
+$ nomad operator utilization
+Success! Utilization reporting bundle written to: nomad-utilization-2024-02-16T22-23-25Z.json
+```
+
+Create a utilization reporting bundle with a message about the bundle, and
+output the file at the specified path, `/utilization/reports/latest.json`.
+
+```shell-session
+$ nomad operator utilization \
+    -message="Change Control 654987" \
+    -output="/utilization/reports/latest.json"
+```
+
+**Example output**
+
+<CodeBlockConfig hideClipboard>
+
+```plaintext
+Success! Utilization reporting bundle written to: /utilization/reports/latest.json
+```
+
+</CodeBlockConfig>
+
+The message, `Change Control 654987`, is included in the _server log_, but not
+in the bundle.
+
+**Example entry in the server log**
+
+<CodeBlockConfig hideClipboard>
+
+```plaintext
+[INFO]  reporting: reporting bundle generated: message="Change Control 654987"
+```
+
+</CodeBlockConfig>
+
+## General options
+
+@include 'general_options.mdx'

website/content/docs/configuration/reporting.mdx

@@ -19,9 +19,11 @@ For more information about automated license utilization reporting, please see t
 
 ```hcl
 reporting {
-    license {
-      enabled = true
-    }
+  license {
+    enabled = true
+  }
+
+  snapshot_retention_time = "9600h"
 }
 ```
 
@@ -30,10 +32,23 @@ reporting {
 - `license` <code>([license](#license-block): default)</code> - Configures
   automated license utilization reporting.
 
+- `snapshot_retention_time` `(string: "9600h")` - Configures the maximum amount
+  of time that Nomad retains a utilization reporting snapshot in the Nomad
+  state store. You can export these snapshots with the [`nomad operator
+  utilization`][] command.
+
+- `disable_product_usage_reporting` `(bool: false)` - Specifies whether detailed
+  product usage metrics should be disabled. Review the
+  [full list of metrics](/nomad/docs/enterprise/license/utilization-reporting#full-list-of-metrics)
+  before disabling this option, and share any concerns you may have
+  with your account manager.
+
 ## `license` Block
 
 - `enabled` `(bool: true)` - Specifies whether automated license utilization
-  reporting should be enabled and run.
+  reporting should be enabled and run. License utilization metrics are still
+  gathered for offline reporting.
 
 [server_mode_enabled]: /nomad/docs/configuration/server#enabled
 [automated_license_utilization_reporting]: /nomad/docs/enterprise/license/utilization-reporting
+[`nomad operator utilization`]: /nomad/docs/commands/operator/utilization