vault/website/content/docs/license/utilization/manual-reporting.mdx

---
layout: docs
page_title: Manual license utilization reporting
description: >-
  Learn how to manually export, review, and send license utilization data to
  HashiCorp through the Vault CLI or HCP web portal.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# Manual license utilization reporting

@include 'alerts/enterprise-only.mdx'

Manual license utilization reporting allows you to export, review, and send
license utilization data to HashiCorp via the CLI or
[HCP web portal](https://portal.cloud.hashicorp.com/). Use these
reports to understand how much more you can deploy under your current contract,
protect against overutilization, and budget for predicted consumption. Manual
reporting shares the minimum data required to validate license utilization as
defined in our contracts. The reports consist of mostly computed metrics and
will never contain Personal Identifiable Information (PII) or other sensitive
information.

Manual license utilization shares the same data as automated license utilization
but is more time consuming. Unless you are running in an air-gapped environment
or have another reason to report data manually, we strongly recommend using
automated reporting instead. If you have disabled automated license reporting,
you can re-enable it by reversing the opt-out process described in the
[documentation](/vault/docs/enterprise/license/utilization-reporting#opt-out).

If you are considering manual reporting because you’re worried about your data,
we strongly recommend that you review the [example
payloads](#data-file-content), which are the same for automated and manual
reporting. If you have further concerns with any of the automatically-reported
data please bring them to your account manager before opting out of automated
reporting in favor of manual reporting.

## How to manually send data reports

### Generate a data bundle

Data bundles include collections of JSON snapshots that contain license
utilization information.

<Note title="Vault policy requirement">

To run the reporting command, you must have a Vault policy that grants
`update` permission on the `sys/utilization` endpoint:

```
path "sys/utilization" {
  capabilities = ["update"]
}
```

</Note>

1. Login into your [cluster node](/vault/tutorials/cloud/vault-access-cluster).
1. Run this CLI command to generate a data bundle:

   ```shell-session
   $ vault operator utilization
   ```

   By default, the bundle will include all historical snapshots.

   You can provide context about the conditions under which the report was
   generated and submitted by providing a comment. This optional comment will
   not be included in the license utilization bundle, but will be included in
   the Vault server logs.

   **Example:**

   ```shell-session
   $ vault operator utilization -message=”Change Control 654987” \
        -output=”/utilization/reports/latest.json”
   ```

   This command will export all the persisted snapshots into a bundle. The
   message “Change Control 654987” will not be included in the bundle but will
   be included in Vault server logs. The `-output` flags specifies the output
   location of the JSON bundle.

   **Available command flags:**

   - `-message` `(string: “”)` - Provide context about the conditions under
   which the report was generated and submitted. This message is not included
   in the license utilization bundle but will be included in the vault server
   logs. (optional)

   - `-today-only` `(bool: false)` - To include only today’s snapshot, no
   historical snapshots. If no snapshots were persisted in the last 24 hrs, it
   takes a snapshot and exports it to a bundle. (optional)

   - `-output` `(string: “”)` - Specifies the output path for the bundle.
   Defaults to a time-based generated file name. (optional)


### Send the data bundle to HashiCorp

1. Go to https://portal.cloud.hashicorp.com/license-utilization/reports/create
1. Click on **Choose files**, or drop your file(s) into the container.

    a. If the upload succeeded, the HCP user interface will change the file
    status to **Uploaded** in green.

    b. If the upload failed, the file status will say **Failed** in red, and
    will include error information.

If the upload fails make sure you haven’t modified the file signature. If the
error persists, please contact your account representative.


## Enable manual reporting

Upgrade to a release that supports manual license utilization reporting. These
releases include:

- Vault Enterprise 1.16.0 and later
- Vault Enterprise 1.15.6 and later
- Vault Enterprise 1.14.10 and later

## Configuration

Administrators can manage disk space for storing snapshots by defining the
number of days snapshots can be retained.

```hcl
reporting {
    snapshot_retention_time = "2400h"
}
```

The default retention period is 400 days.

## Data file content

<CodeBlockConfig hideClipboard>

```json
{
  "snapshot_version": 2,
  "id": "0001JWAY00BRF8TEXC9CVRHBAC",
  "timestamp": "2024-02-08T16:55:28.085215-08:00",
  "schema_version": "2.0.0",
  "product": "vault",
  "process_id": "01HP5NJS21HN50FY0CBS0SYGCH",
  "metrics": {
    "clientcount.current_month_estimate.type.acme_client": {
      "key": "clientcount.current_month_estimate.type.acme_client",
      "value": 0,
      "mode": "write"
    },
    "clientcount.current_month_estimate.type.entity": {
      "key": "clientcount.current_month_estimate.type.entity",
      "value": 20,
      "mode": "write"
    },
    "clientcount.current_month_estimate.type.nonentity": {
      "key": "clientcount.current_month_estimate.type.nonentity",
      "value": 11,
      "mode": "write"
    },
    "clientcount.current_month_estimate.type.secret_sync": {
      "key": "clientcount.current_month_estimate.type.secret_sync",
      "value": 0,
      "mode": "write"
    },
    "clientcount.previous_month_complete.type.acme_client": {
      "key": "clientcount.previous_month_complete.type.acme_client",
      "value": 0,
      "mode": "write"
    },
    "clientcount.previous_month_complete.type.entity": {
      "key": "clientcount.previous_month_complete.type.entity",
      "value": 0,
      "mode": "write"
    },
    "clientcount.previous_month_complete.type.nonentity": {
      "key": "clientcount.previous_month_complete.type.nonentity",
      "value": 0,
      "mode": "write"
    },
    "clientcount.previous_month_complete.type.secret_sync": {
      "key": "clientcount.previous_month_complete.type.secret_sync",
      "value": 0,
      "mode": "write"
    }
  },
  "product_version": "1.16.0+ent",
  "license_id": "7d68b16a-74fe-3b9f-a1a7-08cf461fff1c",
  "checksum": 6861637915450723051,
  "metadata": {
    "billing_start": "2023-05-04T00:00:00Z",
    "cluster_id": "16d0ff5b-9d40-d7a7-384c-c9b95320c60e",
    "development_cluster": "false"
  }
```

</CodeBlockConfig>