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

---
layout: docs
page_title: Automated license utilization reporting
description: >-
  Learn about the data HashiCorp collects automatically to meter Enterprise
  license utilization and how to enable or disable automated reporting.
---

> [!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.

# Automated license utilization reporting

@include 'alerts/enterprise-only.mdx'

Automated license utilization reporting sends license utilization data to
HashiCorp without requiring you to manually collect and report them.

Automated reporting shares the minimum data required to validate license
utilization as defined in our contracts. They consist of mostly computed metrics
and 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. The reporting process submits
reports roughly once every 24 hours.

## Enable automated reporting

To enable automated reporting, you need to 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.

### 1. Allow outbound HTTPS traffic on port 443

Make sure that your network allows HTTPS egress on port 443 to
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

### 2. Upgrade

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

- [Vault Enterprise 1.14.0](https://releases.hashicorp.com/vault/) and later
- [Vault Enterprise 1.13.4](https://releases.hashicorp.com/vault/) and later 1.13.x versions
- [Vault Enterprise 1.12.8](https://releases.hashicorp.com/vault/) and later 1.12.x versions
- [Vault Enterprise 1.11.12](https://releases.hashicorp.com/vault/)

### 3. Check logs

Automatic license utilization reporting will start sending data within roughly 24 hours.
Check the server logs for records that the data sent successfully.

You will find log entries similar to the following:

<CodeBlockConfig hideClipboard>

```
[DEBUG] reporting.auto_exporter: beginning snapshot export
[DEBUG] reporting.auto_exporter: creating bundle
[DEBUG] reporting.auto_exporter: marshalling bundle to json
[DEBUG] reporting.auto_exporter: creating request
[DEBUG] reporting.auto_exporter: sending request
[DEBUG] reporting.auto_exporter: performing request: method=POST url=https://reporting.hashicorp.services/v2
[DEBUG] reporting.auto_exporter: recording audit record
[DEBUG] reporting.auto_exporter: completed recording audit record
[INFO]  reporting.auto_exporter: Report sent: auditRecord="{\"bundle\":{\"version\":\"2\",\"mode\":\"automatic\",\"license_id\":\"97afe7b4-b9c8-bf19-bf35-b89b5cc0efea\",\"product\":\"vault\",\"product_version\":\"1.14.0-rc1+ent\",\"export_timestamp\":\"2023-06-01T09:34:44.215133-04:00\",\"snapshots\":[{\"snapshot_version\":1,\"snapshot_id\":\"0001J7H7KMEDRXKM5C1QJGBXV3\",\"process_id\":\"01H1T45CZK2GN9WR22863W2K32\",\"timestamp\":\"2023-06-01T09:34:44.215001-04:00\",\"schema_version\":\"1.0.0\",\"service\":\"vault\",\"metrics\":{\"clientcount.current_month_estimate\":{\"key\":\"clientcount.current_month_estimate\",\"kind\":\"sum\",\"mode\":\"write\",\"labels\":{\"type\":{\"entity\":20,\"nonentity\":11}}},\"clientcount.previous_month_complete\":{\"key\":\"clientcount.previous_month_complete\",\"kind\":\"sum\",\"mode\":\"write\",\"labels\":{\"type\":{\"entity\":10,\"nonentity\":11}}}}}],\"metadata\":{\"vault\":{\"billing_start\":\"2023-03-01T00:00:00Z\",\"cluster_id\":\"a8d95acc-ec0a-6087-d7f6-4f054ab2e7fd\"}}}}"
[DEBUG] reporting.auto_exporter: completed recording audit record
[DEBUG] reporting.auto_exporter: export finished successfully
```

</CodeBlockConfig>

If your installation is air-gapped or your network doesn’t allow the correct
egress, logs will show an error.

<CodeBlockConfig hideClipboard>

```
[DEBUG] reporting.auto_exporter: beginning snapshot export
[DEBUG] reporting.auto_exporter: creating bundle
[DEBUG] reporting.auto_exporter: marshalling bundle to json
[DEBUG] reporting.auto_exporter: creating request
[DEBUG] reporting.auto_exporter: sending request
[DEBUG] reporting.auto_exporter: performing request: method=POST url=https://reporting.hashicorp.services/v2
[DEBUG] core.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 will still be required to
manually collect and send license utilization metrics to HashiCorp.

If you are considering opting out because you’re 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 please bring them to your account manager.

You have two options to opt out of automated reporting:

- 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 {
	license {
		enabled = false
   }
}
```

<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
automated reporting. Inconsistent configuration between nodes will change the
reporting status upon active unseal.

</Warning>


You will find the following entry in the server log.

<CodeBlockConfig hideClipboard>

```
[DEBUG] reporting: automated reporting is disabled; license utilization data will not be exported unless triggered manually
```

</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 disabled automated reporting.
This option requires a system restart.

<Note>

If the reporting stanza exists in the configuration file, the
`OPTOUT_LICENSE_REPORTING` value overrides the configuration.

</Note>

Set the following environment variable.

```shell-session
$ export OPTOUT_LICENSE_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>

```
[INFO]  core: automated reporting disabled via environment variable: env=OPTOUT_LICENSE_REPORTING
[DEBUG] reporting: automated reporting is disabled; license utilization data will not be exported unless triggered manually
```

</CodeBlockConfig>


Check your product logs roughly 24 hours after opting out to make sure that the system
isn’t trying to send reports.

If your configuration file and environment variable differ, the environment
variable setting will take precedence.

## Development cluster configuration

As of 1.20.0, clusters now report the `development_cluster` metadata field, which
indicates whether the cluster is used for development (non-production) purposes. By default, the field is set to `false`,
indicating the cluster is running in a production environment. Changing the value is done via HCL configuration by adding
the `development_cluster` field to the `license` parameter within the `reporting` stanza.
Do not use `development_cluster` outside of development environments. Setting
`development_cluster` to `true` on production clusters can violate EULA obligations.

```hcl
reporting {
  license {
    development_cluster = true
  }
}
```

#### Replication considerations

The `development_cluster` configuration cannot differ across replicated clusters.
In [performance replication](/vault/docs/enterprise/replication#performance-replication), secondary clusters inherit the
`development_cluster` value from the primary cluster, regardless of their own HCL configuration.

If the `development_cluster` setting in the secondary cluster configuration
differs from the value inherited from the primary cluster, the secondary cluster
logs the following error to warn about the discrepancy:

`"development cluster setting in config does not match that of the primary, updating to follow the primary config setting"`

If the secondary cluster is promoted to a primary, it reports the
`development_cluster` value determined by its own HCL configuration.
The reverse is also true, if the primary cluster is demoted to a secondary, it will report the `development_cluster`
value of its new primary.

[Disaster recovery](/vault/docs/enterprise/replication#disaster-recovery-dr-replication) secondaries do not send reports.
However, if promoted to primary during failover, they will report their own `development_cluster` value based on their HCL configuration.

<Warning>

All clusters in a replication group must have the same `development_cluster` setting in their HCL configuration.
In the event of a promotion or failover, the new primary cluster's HCL configuration will determine the value reported
by all clusters in the replication group. Inconsistent configurations between clusters can lead to changes to the
reported `development_cluster` value when the primary cluster changes.

Within each cluster, each node must have the same `development_cluster` setting in its configuration to be consistent.
In the event of leadership change, the active node will use its own server configuration to determine the value to report.
Inconsistent configuration between nodes will change the `development_cluster` setting reported upon active unseal.

</Warning>

## Example payloads

HashiCorp collects the following utilization data as JSON payloads:

- `payload_version` - The version of this payload schema
- `license_id` - The license ID for this product
- `product` - The product that this contribution is for
- `product_version` - The product version this contribution is for
- `export_timestamp`- The date and time for this contribution
- `snapshots` - An array of snapshot details. A snapshot is a structure that
  represents a single data collection
   - `snapshot_version` - The version of the snapshot package that produced this
     snapshot
   - `snapshot_id` - A unique identifier for this particular snapshot
   - `process_id` - An identifier for the system that produced this snapshot
   - `timestamp` - The date and time for this snapshot
   - `schema_version` - The version of the schema associated with this snapshot
   - `service` - The service that produced this snapshot (likely to be product
     name)
   - `metrics` - A map of representations of snapshot metrics contained within
     this snapshot
      - `key` - The key name associated with this metric
      - `kind` - The kind of metric (feature, counter, sum, or mean)
      - `mode` - The mode of operation associated with this metric (write or
        collect)
      - `labels` - The labels associated with each collected metric
         - `entity` - The sum of tokens generated for a unique client identifier
         - `nonentity` - The sum of tokens without an entity attached
- `metadata` - Optional product-specific metadata
   - `billing_start` - The billing start date associated with the reporting cluster (license start date if not configured).

   <Note title="Important change to supported versions">

      As of 1.16.7, 1.17.3 and later,
      the <a href="/vault/docs/concepts/billing-start-date">billing start date</a> automatically
      rolls over to the latest billing year at the end of the last cycle.

      For more information, refer to the upgrade guide for your Vault version:

      [Vault v1.16.x](/vault/docs/upgrading/upgrade-to-1.16.x#auto-rolled-billing-start-date),
      [Vault v1.17.x](/vault/docs/upgrading/upgrade-to-1.17.x#auto-rolled-billing-start-date)

    </Note>

   - `cluster_id` - The cluster UUID as shown by `vault status` on the reporting
     cluster.
   - `development_cluster` - Whether the cluster is operating as a development (non-production) cluster.

<CodeBlockConfig hideClipboard>

```json
{
  "payload_version": "1",
  "license_id": "97afe7b4-b9c8-bf19-bf35-b89b5cc0efea",
  "product": "vault",
  "product_version": "1.14.0-rc1+ent",
  "export_timestamp": "2023-06-01T11:39:00.76643-04:00",
  "snapshots": [
    {
      "snapshot_version": 1,
      "snapshot_id": "0001J7HEWM1PEHPMF5YZT8EV65",
      "process_id": "01H1VSQMNYAP77R566F1Y03GE6",
      "timestamp": "2023-06-01T11:39:00.766099-04:00",
      "schema_version": "1.0.0",
      "service": "vault",
      "metrics": {
        "clientcount.current_month_estimate": {
          "key": "clientcount.current_month_estimate",
          "kind": "sum",
          "mode": "write",
          "labels": {
            "type": {
              "entity": 20,
              "nonentity": 11
            }
          }
        },
        "clientcount.previous_month_complete": {
          "key": "clientcount.previous_month_complete",
          "kind": "sum",
          "mode": "write",
          "labels": {
            "type": {
              "entity": 10,
              "nonentity": 11
            }
          }
        }
      }
    }
  ],
  "metadata": {
    "vault": {
      "billing_start": "2023-03-01T00:00:00Z",
      "cluster_id": "a8d95acc-ec0a-6087-d7f6-4f054ab2e7fd",
      "development_cluster": "false",
    }
  }
}
```

</CodeBlockConfig>

## Pre-1.9 counts

When upgrading Vault from 1.8 (or earlier) to 1.9 (or later), utilization reporting will only include the [non-entity tokens](/vault/docs/concepts/client-count#non-entity-tokens) that are used after the upgrade.

Starting in Vault 1.9, the activity log records and de-duplicates non-entity tokens by using the namespace and token's policies to generate a unique identifier. Because Vault did not create identifiers for these tokens before 1.9, the activity log cannot know whether this token has been seen pre-1.9. To prevent inaccurate and inflated counts, the activity log will ignore any counts of non-entity tokens that were created before the upgrade and only the non-entity tokens from versions 1.9 and later will be counted.

See the client count [overview](/vault/docs/concepts/client-count) and [FAQ](/vault/docs/concepts/client-count/faq) for more information.