[Docs] Add usage metrics page (#28723)

* Add UI screenshots

* Add 'usage metrics' page

* Align the step instruction and its screenshot

* Additional notes

* Add link to API docs

website/content/docs/concepts/client-count/usage-metrics.mdx

@@ -0,0 +1,304 @@
+---
+layout: docs
+page_title: Vault usage metrics
+description: |-
+  Learn how to discover the number of Vault clients for each namespace in Vault.
+---
+
+# Vault usage metrics
+
+Client calculation and sizing can be complex to compute when you have multiple
+namespaces and auth mounts. The **Vault Usage Metrics** dashboard on Vault UI
+provides the information where you can filter the data by namespace and/or auth
+mounts. You can also use Vault CLI or API to query the usage metrics.
+
+## Enable usage metrics
+
+Usage metrics are a feature that is enabled by default for Vault Enterprise and
+HCP Vault Dedicated. However, if you are running Vault Community Edition, you
+need to enable usage metrics since it is disabled by default.
+
+<Tabs>
+<Tab heading="Web UI" group="ui">
+
+1. Open a web browser to access the Vault UI, and sign in.
+
+1. Select **Client Count** from the left navigation menu.
+
+1. Select **Configuration**.
+
+1. Select **Edit configuration**.
+
+   ![Edit configuration](/img/ui-usage-metrics-config.png)
+
+1. Select the toggle for **Usage data collection** so that the text reads **Data
+   collection  is on**.
+
+   <Tip title="Retention period">
+
+    The retention period sets the number of months for which Vault will maintain
+    activity logs to track active clients. (Default: 48 months)
+
+    </Tip>
+
+1. Click **Save** to apply the changes.
+
+1. Click **Continue** in the confirmation dialog to enable usage metrics tracking.
+
+</Tab>
+<Tab heading="CLI command" group="cli">
+
+```shell-session
+$ vault write sys/internal/counters/config enabled=enable
+```
+
+Valid values for `enabled` parameter are: `default`, `enable`, and `disable`.
+
+<Tip title="Retention period">
+
+ By default, Vault maintains activity logs to track
+active clients for 24 months. If you wish to change the retention period, use
+the `retention_months` parameter.
+
+</Tip>
+
+**Example:**
+
+```shell-session
+$ vault write sys/internal/counters/config \
+    enabled=enable \
+    retention_months=12
+```
+
+</Tab>
+<Tab heading="API call using cURL" group="api">
+
+```shell-session
+$ curl --header "X-Vault-Token: <TOKEN>" \
+    --request POST \
+    --data '{"enabled": "enable"}' \
+    $VAULT_ADDR/v1/sys/internal/counters/config
+```
+
+Valid values for `enabled` parameter are: `default`, `enable`, and `disable`.
+
+<Tip title="Retention period">
+
+ By default, Vault maintains activity logs to track
+active clients for 24 months. If you wish to change the retention period, use
+the `retention_months` parameter.
+
+</Tip>
+
+**Example:**
+
+```shell-session
+$ curl --header "X-Vault-Token: <TOKEN>" \
+    --request POST \
+    --data '{"enabled": "enable", "retention_months": 12}' \
+    $VAULT_ADDR/v1/sys/internal/counters/config
+```
+
+</Tab>
+</Tabs>
+
+## Usage metrics dashboard
+
+1. Sign into Vault UI. The **Client count** section displays the total number of
+   clients for the current billing period.
+
+1. Select **Details**.
+   ![Vault UI default dashboard example](/img/ui-client-count.png)
+
+1. Examine the **Vault Usage Metrics** dashboard to learn your Vault usage.
+   ![Example Vault Usage Metrics dashboard view](/img/ui-usage-metrics-1.png)
+
+#### Usage metrics data categories
+
+- **Running client total** are the primary metric on which pricing is based.
+  It is the sum of entity clients (or distinct entities) and non-entity clients.
+
+- **Entity clients** (distinct entities) are representations of a particular
+  user, client, or application that belongs to a defined Vault entity. If you
+  are unfamiliar with Vault entities, refer to the [Identity: Entities and
+  Groups](/vault/tutorials/auth-methods/identity) tutorial.
+
+- **Non-entity clients** are clients without an entity attached.
+  This is because some customers or workflows might avoid using entity-creating
+  authentication methods and instead depend on token creation through the Vault
+  API. Refer to [understanding non-entity
+  tokens](/vault/docs/concepts/client-count#understanding-non-entity-tokens)
+  to learn more.
+
+  <Note>
+
+  The non-entity client count excludes `root` tokens.
+
+  </Note>
+
+- **Secrets sync clients** are the number of external destinations Vault
+  connects to sync the secrets. Refer to the
+  [documentation](/vault/docs/concepts/client-count#secret-sync-clients) for
+  more details.
+
+- **ACME clients** are the ACME connections that authenticate under the same
+  certificate identifier (domain) as the same certificate entity for client
+  count calculations. Refer to the
+  [documentation](/vault/docs/concepts/client-count#entity-assignment-with-acme)
+  for more details.
+
+    ![ACME clients example](/img/ui-usage-metrics-acme.png)
+
+
+## Select a data range
+
+Under the **Client counting period**, select **Edit** to query the data for
+a different billing period.
+
+![Query](/img/ui-usage-metrics-period.png)
+
+Keep in mind that Vault begins collecting data when the feature is enabled. For
+example, if you enabled the usage metrics in March of 2023, you cannot query
+data in January of 2023.
+
+Vault will return metrics from March of 2023 through most recent full month. 
+
+## Filter by namespaces
+
+If you have [namespaces](/vault/docs/enterprise/namespaces), the dashboard
+displays the top ten namespaces by total clients.
+
+![Namespace attribution example](/img/ui-usage-metrics-namespace.png)
+
+Use the **Filters** to view the metrics data of a specific namespace.
+
+![Filter by namespace](/img/ui-usage-metrics-filter.png)
+
+## Mount attribution
+
+The clients are also shown as graphs per auth mount. The **Mount attribution**
+section displays the top auth mounts where you can expect to find your most used
+auth method mounts with respect to client usage. This allows you to detect which
+auth mount had the most number of total clients in the given billing period. You
+can filter for auth mounts within a namespace, or view auth mounts across
+namespaces. The mount attribution is available even if you are not using
+namespaces. 
+
+![Usage metrics by mount attribution](/img/ui-usage-metrics-mounts.png)
+
+
+## Query usage metrics via CLI
+
+Retrieve the usage metrics for the current billing period.
+
+```shell-session
+$ vault operator usage
+```
+
+**Example output:**
+
+<CodeBlockConfig hideClipboard>
+
+```plaintxt
+Period start: 2024-03-01T00:00:00Z
+Period end: 2024-10-31T23:59:59Z
+
+Namespace path                                        Entity Clients   Non-Entity clients   Secret syncs   ACME clients   Active clients
+--------------                                        --------------   ------------------   ------------   ------------   --------------
+[root]                                                86               114                  0              0              200
+education/                                            31               31                   0              0              62
+education/certification/                              18               25                   0              0              43
+education/training/                                   192              197                  0              0              389
+finance/                                              18               26                   0              0              44
+marketing/                                            28               17                   0              0              45
+test-ns-1-with-namespace-length-over-18-characters/   84               75                   0              0              159
+test-ns-1/                                            59               66                   0              0              125
+test-ns-2-with-namespace-length-over-18-characters/   58               46                   0              0              104
+test-ns-2/                                            56               47                   0              0              103
+
+Total                                                 630              644                  0              0              1274
+```
+
+</CodeBlockConfig>
+
+The output shows client usage metrics for each namespace.
+
+### Filter by namespace
+
+You can narrow the scope for `education` namespace and its child namespaces.
+
+```shell-session
+$ vault operator usage -namespace education
+
+Period start: 2024-03-01T00:00:00Z
+Period end: 2024-10-31T23:59:59Z
+
+Namespace path             Entity Clients   Non-Entity clients   Secret syncs   ACME clients   Active clients
+--------------             --------------   ------------------   ------------   ------------   --------------
+education/                 31               31                   0              0              62
+education/certification/   18               25                   0              0              43
+education/training/        192              197                  0              0              389
+
+Total                      241              253                  0              0              494
+```
+
+### Query with a time frame
+
+To query the client usage metrics for the month of June, 2024. The start
+time is June 1, 2024 (`2024-06-01T00:00:00Z`) and the end time is June
+30, 2024 (`2024-06-30T23:59:59Z`).
+
+The `start_time` and `end_time` should be an RFC3339 timestamp or Unix epoch
+time.
+
+```shell-session
+$ vault operator usage \
+     -start-time=2024-06-01T00:00:00Z \
+     -end-time=2024-06-30T23:59:59Z 
+```
+
+**Example output:**
+
+<CodeBlockConfig hideClipboard>
+
+```plaintext
+Period start: 2024-06-01T00:00:00Z
+Period end: 2024-06-30T23:59:59Z
+
+Namespace path                                        Entity Clients   Non-Entity clients   Secret syncs   ACME clients   Active clients
+--------------                                        --------------   ------------------   ------------   ------------   --------------
+[root]                                                10               16                   0              0              26
+education/                                            7                1                    0              0              8
+education/certification/                              2                4                    0              0              6
+education/training/                                   37               30                   0              0              67
+finance/                                              3                6                    0              0              9
+marketing/                                            2                2                    0              0              4
+test-ns-1-with-namespace-length-over-18-characters/   6                9                    0              0              15
+test-ns-1/                                            9                12                   0              0              21
+test-ns-2-with-namespace-length-over-18-characters/   5                5                    0              0              10
+test-ns-2/                                            9                7                    0              0              16
+
+Total                                                 90               92                   0              0              182
+```
+
+</CodeBlockConfig>
+
+
+## Export the metrics data
+
+You can export the metrics data by clicking on the **Export attribution data**
+button.
+
+![Metrics UI](/img/ui-usage-metrics-export.png)
+
+This downloads the usage metrics data on your local drive in comma separated
+values format (`.csv`) or JSON.
+
+
+## API 
+
+- Refer to the
+  [`sys/internal/counters`](/vault/api-docs/system/internal-counters#client-count)
+  page to retrieve client count using API.
+- [Activity export API](/vault/api-docs/system/internal-counters#activity-export) to
+  export activity log.

website/data/docs-nav-data.json

@@ -281,6 +281,10 @@
             "title": "Client count calculation",
             "path": "concepts/client-count/counting"
           },
+          {
+            "title": "Usage metrics",
+            "path": "concepts/client-count/usage-metrics"
+          },
           {
             "title": "FAQ",
             "path": "concepts/client-count/faq"