Skip to content

VAULT-39930 Add certificate counters to license usage reporting #1147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 22, 2025
Merged

VAULT-39930 Add certificate counters to license usage reporting #1147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
819f056
VAULT-39930 Add certificate counters to license usage reporting
gsantos-hc Oct 21, 2025
6c958c5
Merge branch 'main' into VAULT-39930-lic-usage-cert-counts
schavis Oct 22, 2025
f4d5dc8
Apply suggestions from code review
gsantos-hc Oct 22, 2025
a343a60
Merge branch 'main' into VAULT-39930-lic-usage-cert-counts
schavis Oct 22, 2025
2a6fa3e
Merge branch 'main' into VAULT-39930-lic-usage-cert-counts
schavis Oct 22, 2025
b95d407
Merge branch 'main' into VAULT-39930-lic-usage-cert-counts
schavis Oct 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 109 additions & 80 deletions content/vault/v1.21.x (rc)/content/docs/license/utilization/auto-reporting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,18 @@ description: >-
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.
Automated reporting shares the minimum data required to validate license utilization
as defined in our contracts. The reported data consists mostly of computed metrics
and never contains personal identifiable information (PII) or other sensitive information.
As of Vault 1.21+, automated metrics include the following:

- The number of [Vault clients](../../concepts/client-count/counting)
- The number of certificates issued by the PKI secrets engine.

Automated reporting writes to your Vault logs every time it submits a
report and shares the report data with HashiCorp using a secure,
unidirectional HTTPS API call. The reporting process submits reports
roughly once every 24 hours.

## Enable automated reporting

Expand Down Expand Up @@ -113,7 +118,6 @@ 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
Expand All @@ -138,7 +142,6 @@ reporting status upon active unseal.

</Warning>


You will find the following entry in the server log.

<CodeBlockConfig hideClipboard>
Expand Down Expand Up @@ -182,7 +185,6 @@ You will find the following entries in the server log.

</CodeBlockConfig>


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

Expand Down Expand Up @@ -250,25 +252,28 @@ HashiCorp collects the following utilization data as JSON payloads:
- `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).
- `snapshot_version` - The version of the snapshot package that produced the reporting
snapshot.
- `snapshot_id` - A unique identifier for this particular snapshot
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `snapshot_id` - A unique identifier for this particular snapshot
- `snapshot_id` - A unique identifier for the generated snapshot.

- `process_id` - An identifier for the system that produced this snapshot
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `process_id` - An identifier for the system that produced this snapshot
- `process_id` - An identifier for the system that produced the generated snapshot.

- `timestamp` - The date and time for this snapshot
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `timestamp` - The date and time for this snapshot
- `timestamp` - The date and time for the generated snapshot

Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `timestamp` - The date and time for this snapshot
- `timestamp` - The date and time for the generated snapshot.

- `schema_version` - The version of the schema associated with this snapshot
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `schema_version` - The version of the schema associated with this snapshot
- `schema_version` - The version of the schema associated with the generated snapshot.

- `service` - The service that produced this snapshot (likely to be product
name)
Comment on lines +261 to +262
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `service` - The service that produced this snapshot (likely to be product
name)
- `service` - Name of the service that produced the generated snapshot.
Typically the same as the product name.

- `metrics` - A map of representations of snapshot metrics contained within
this snapshot
Comment on lines +263 to +264
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `metrics` - A map of representations of snapshot metrics contained within
this snapshot
- `metrics` - A map of representations of snapshot metrics contained within
the generated snapshot.

What does "a map of representations of snapshots" mean?

- `key` - The key name associated with this metric
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `key` - The key name associated with this metric
- `key` - The key name associated with the metric entry.

- `kind` - The kind of metric (feature, counter, sum, or mean)
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `kind` - The kind of metric (feature, counter, sum, or mean)
- `kind` - The kind of metric (feature, counter, sum, or mean).

- `mode` - The mode of operation associated with this metric (write or
collect)
Comment on lines +267 to +268
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `mode` - The mode of operation associated with this metric (write or
collect)
- `mode` - The mode of operation associated with the metric entry (write or
collect).

- `labels` - The labels associated with each collected metric
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `labels` - The labels associated with each collected metric
- `labels` - The labels associated with each collected metric.

- `entity` - The sum of tokens generated for a unique client identifier
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `entity` - The sum of tokens generated for a unique client identifier
- `entity` - The sum of tokens generated for a unique client identifier.

- `nonentity` - The sum of tokens without an entity attached
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `nonentity` - The sum of tokens without an entity attached
- `nonentity` - The sum of tokens without an entity attached.

- `metadata` - Optional product-specific metadata
Copy link
Contributor

@schavis schavis Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `metadata` - Optional product-specific metadata
- `metadata` - Optional, product-specific metadata.

- `billing_start` - The billing start date associated with the reporting
cluster or the license start date if you do not have a billing date configured.
- `cluster_id` - The cluster UUID as shown by `vault status` on the reporting cluster.
- `development_cluster` - Whether or not the cluster operates as a development (non-production) cluster.

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

Expand All @@ -283,60 +288,85 @@ HashiCorp collects the following utilization data as JSON payloads:

</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",
}
}
"payload_version": "1",
"license_id": "7d68b16a-74fe-3b9f-a1a7-08cf461fff1c",
"product": "vault",
"product_version": "1.21.0+ent",
"export_timestamp": "2024-02-08T18:55:28.085215-08:00",
"snapshots": [
{
"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"
},
"certcount.current_month_estimate": {
"key": "certcount.current_month_estimate",
"value": 0,
"mode": "write"
},
"certcount.previous_month_complete": {
"key": "certcount.previous_month_complete",
"value": 0,
"mode": "write"
}
},
"product_version": "1.21.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"
}
}
]
}
```

Expand All @@ -349,4 +379,3 @@ When upgrading Vault from 1.8 (or earlier) to 1.9 (or later), utilization report
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.

Loading
Loading