HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Consul
Consul Home

License utilization reporting

This topic describes how to enable automated license utilization reporting in Consul Enterprise. This feature automatically sends license utilization data to HashiCorp so that you do not have to manually collect and report it. If you have security limitations on automated reporting, such as an air-gapped network, you can also choose to create a report and submit it manually.

Introduction

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. This process is GDPR-compliant.

Requirements

Automated license utilization reporting does not support air-gapped installations, which are systems with no network interfaces.

The following versions of Consul Enterprise support automated license utilization reporting:

  • Consul Enterprise v1.16.0 and newer.
  • Patch releases of Consul Enterprise v1.15.4 and newer.
  • Patch releases of Consul Enterprise v1.14.8 and newer.
  • Patch releases of Consul Enterprise v1.13.9 and newer.

Download a supported release from the Consul Versions page.

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
  2. 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 adding the following IP addresses to your allow-list:

Check product logs

Automatic license utilization reporting starts sending data within roughly 24 hours. Check the product logs for records that the data sent successfully.

[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"

If your installation is air-gapped or your network does not allow the correct egress, the logs show an error.

[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

In this case, reconfigure your network to allow egress and check the logs again in roughly 24 hours to confirm that automated reporting works correctly.

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

reporting {
    license {
        enabled = false
  }
}

When opting out using an environment variable, the system provides a startup message confirming that you have disabled automated reporting. Set the following environment variable to disable automated reporting:

$ export OPTOUT_LICENSE_REPORTING=true

After you set the environment variable, restart your system to complete the process for opting out.

$ consul reload

Check your product logs roughly 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.

Manual license utilization reporting

Even if you opted out of the automated license utilization reporting, you might still need to produce license utilization reports.

Use the consul operator utilization CLI command to generate these reports.

This command asks if you want to automatically send the report to HashiCorp. If you are running an air-gapped environment or you did not configure your traffic to enable automated reporting, select N.

$ consul operator utilization -output license-report.json 
Send usage report to HashiCorp? [y/N]:
Utilization bundle written to license-report.json

After the command completes you can review the report.

license-report.json

{
  "version": "2",
  "mode": "manual",
  "timestamp": "2025-10-09T10:11:36.849310301Z",
  "signature": "f15e8bd08f1801bbfa4584ec4c2fbc78567ba3b7c8d7e970a30a5ad6d2a2ae14",
  "checksum": 550082486861627675,
  "snapshots": [
    {
      "snapshot_version": 2,
      "id": "0001MEEQV2BQ8E5V0Q4D4V0A35",
      "timestamp": "2025-10-09T07:08:18.339715794Z",
      "schema_version": "2.0.0",
      "product": "consul",
      "process_id": "01K6FXJDTFBQQP5B3RAXRFRB1K",
      "metrics": {
        "consul.billable.nodes": {
          "key": "consul.billable.nodes",
          "value": 7,
          "mode": "write"
        },
        "consul.billable.service_instances": {
          "key": "consul.billable.service_instances",
          "value": 4,
          "mode": "write"
        }
      },
      "product_version": "1.22.0-rc1+ent",
      "license_id": "642088be-c801-c34a-bb5c-e70d4feb18fe",
      "checksum": 5213090069640891750,
      "metadata": {
        "billing_start": "2021-09-30T00:00:00Z",
        "cluster_id": "dc1"
      }
    }
  ]
}

The amount of snapshots exported by the command depends on the agent configuration's snapshot_retention_time parameter. Consul takes a snapshot every 24 hours, even if automated reporting to HashiCorp is disabled.

For the full list of options, refer to the consul operator utilization CLI documentation.

Example payloads

HashiCorp collects the following utilization data as JSON payloads: exporter_version - The version of the licensing exporter

{
  "version": "2",
  "mode": "manual",
  "timestamp": "2025-10-09T10:11:36.849310301Z",
  "signature": "f15e8bd08f1801bbfa4584ec4c2fbc78567ba3b7c8d7e970a30a5ad6d2a2ae14",
  "checksum": 550082486861627675,
  "snapshots": [
    {
      "snapshot_version": 2,
      "id": "0001MEEQV2BQ8E5V0Q4D4V0A35",
      "timestamp": "2025-10-09T07:08:18.339715794Z",
      "schema_version": "2.0.0",
      "product": "consul",
      "process_id": "01K6FXJDTFBQQP5B3RAXRFRB1K",
      "metrics": {
        "consul.billable.nodes": {
          "key": "consul.billable.nodes",
          "value": 7,
          "mode": "write"
        },
        "consul.billable.service_instances": {
          "key": "consul.billable.service_instances",
          "value": 4,
          "mode": "write"
        }
      },
      "product_version": "1.22.0-rc1+ent",
      "license_id": "642088be-c801-c34a-bb5c-e70d4feb18fe",
      "checksum": 5213090069640891750,
      "metadata": {
        "billing_start": "2021-09-30T00:00:00Z",
        "cluster_id": "dc1"
      }
    }
  ]
}
Edit this page on GitHub