VAULT: 36221 start time counters api bug (#637)

aslamovamir · web-flow · commit fc2b4f60412c · 2025-08-06T09:35:44.000-04:00
This PR updates the docs around the known issues with the `start_time` parameter leading to infinite loops as a bug when not provided to the Counters API. After investigation, we found this affects only Vault version 1.18.x and 1.19.x and has been fixed in 1.20.0. This PR accordingly updates docs around Counters API, release notes and upgrade docs for the affected Vault versions. Jira: https://hashicorp.atlassian.net/browse/VAULT-36221 Manual test snapshots: <img width="659" height="634" alt="Screenshot 2025-07-25 at 1 57 14 PM" src="https://github.com/user-attachments/assets/29b93419-ca2c-4763-a276-c74ed95087d0" /> <img width="837" height="599" alt="Screenshot 2025-07-25 at 2 08 48 PM" src="https://github.com/user-attachments/assets/5b7469b6-74b3-4997-b121-4e1291159e7a" /> <img width="875" height="689" alt="Screenshot 2025-07-28 at 12 31 00 PM" src="https://github.com/user-attachments/assets/5301ec54-d50b-46d7-85e4-ca3d2960b0cb" /> <img width="764" height="547" alt="Screenshot 2025-07-28 at 12 30 21 PM" src="https://github.com/user-attachments/assets/829d2ca7-611a-4ba3-b00a-259355a8365b" /> <img width="667" height="402" alt="Screenshot 2025-07-28 at 12 15 46 PM" src="https://github.com/user-attachments/assets/1c4eb18a-7e67-4412-ad65-3962a8750651" /> <img width="762" height="496" alt="Screenshot 2025-07-28 at 12 15 33 PM" src="https://github.com/user-attachments/assets/87becb9f-1f7e-49d5-97a6-8ae411dd5058" />
diff --git a/content/vault/v1.18.x/content/api-docs/system/internal-counters.mdx b/content/vault/v1.18.x/content/api-docs/system/internal-counters.mdx
@@ -366,9 +366,17 @@ is unknown.
 
 ### Parameters
 
-- `start_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the start of the
-  period for which client counts will be reported. If no start time is specified, the billing start date will be used.
-  The [billing start date](/vault/docs/concepts/billing-start-date) automatically rolls over to the latest billing year at the end of the last cycle.
+- `start_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time.
+  Specifies the start of the period for which client counts will be reported.
+  Vault uses the [billing start date](/vault/docs/concepts/billing-start-date)
+  by default, which automatically rolls over to the latest billing year at the
+  end of the last cycle. Vault Community **requires** `start_time`, but Vault
+  Enterprise uses the billing start date as defined by the cluster license by
+  default. Vault Community does not have a billing start time, so ommitting
+  `start_time` can lead to undefined behavior. We recommend setting an explicit
+  start time to ensure reliable behavior in all Vault versions.
+
+
 - `end_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the end of the period
   for which client counts will be reported. If no end time is specified, the end of the current month will be used.
 - `limit_namespaces` `(int, optional)` - Controls the total number of by_namespace data returned. This can
diff --git a/content/vault/v1.18.x/content/docs/release-notes/1.18.0.mdx b/content/vault/v1.18.x/content/docs/release-notes/1.18.0.mdx
@@ -16,6 +16,7 @@ description: |-
 | Change                      | Description                                                                                                          |
 |-----------------------------|----------------------------------------------------------------------------------------------------------------------|
 | New default (1.18.0)        | [Default activity log querying period](/vault/docs/upgrading/upgrade-to-1.18.x#default-activity-log-querying-period) |
+| Known issue (1.18.0-1.19.6) | [Counters API requires start_time parameter in Vault Community](/vault/docs/upgrading/upgrade-to-1.18.x#counters-api-requires-start-time-in-vault-community) |
 | New default (1.18.0)        | [Docker image no longer contains curl](/vault/docs/upgrading/upgrade-to-1.18.x#docker-image-no-longer-contains-curl) |
 | Beta feature removed (1.18) | [Request limiter removed](/vault/docs/upgrading/upgrade-to-1.18.x#request-limiter-configuration-removal)             |
 | New default (1.18.2)        | [Vault product usage metrics reporting](/vault/docs/upgrading/upgrade-to-1.18.x#product-usage-reporting)             |
diff --git a/content/vault/v1.18.x/content/docs/upgrading/upgrade-to-1.18.x.mdx b/content/vault/v1.18.x/content/docs/upgrading/upgrade-to-1.18.x.mdx
@@ -92,6 +92,17 @@ WARNING! The following warnings were returned from Vault:
 
 </CodeBlockConfig>
 
+#### Counters API requires start time in Vault Community
+
+Vault Community requires the `start_time` parameter  for
+`/sys/internal/counters/activity`. Unlike Enterprise Vault, Vault Commuity does
+not define a billing start time, and ommitting `start_time` may lead to
+unexpected behavior in affected versions (1.18.x and 1.19.x). 
+
+You can safely omit `start_time` for Vault Enterprise as `start_time` defaults
+to the billing start date for the cluster. To avoid issues and unexpected
+behavior, always provide an explicit start time if you use Vault Community.
+
 ### Docker image no longer contains `curl`
 
 The `curl` binary is no longer included in the published Docker container images for Vault and Vault
diff --git a/content/vault/v1.19.x/content/api-docs/system/internal-counters.mdx b/content/vault/v1.19.x/content/api-docs/system/internal-counters.mdx
@@ -376,18 +376,27 @@ is unknown.
 
 ### Parameters
 
-- `start_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the start of the
-  period for which client counts will be reported. If no start time is specified, the billing start date will be used.
-  The [billing start date](/vault/docs/concepts/billing-start-date) automatically rolls over to the latest billing year at the end of the last cycle.
-- `end_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the end of the period
-  for which client counts will be reported. If no end time is specified, the end of the current month will be used.
-- `limit_namespaces` `(int, optional)` - Controls the total number of by_namespace data returned. This can
-   be used to return the client counts for the specified number of namespaces having highest activity.
-   If no `limit_namespaces` parameter is specified, client counts for all namespaces in specified usage period is returned.
-- `current_billing_period` `(bool, optional)` - **DEPRECATED** Uses the builtin billing start
-  timestamp as `start_time` and the current time as the `end_time`, returning a
+- `start_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time.
+  Specifies the start of the period for which client counts will be reported.
+  Vault uses the [billing start date](/vault/docs/concepts/billing-start-date)
+  by default, which automatically rolls over to the latest billing year at the
+  end of the last cycle. Vault Community **requires** `start_time`, but Vault
+  Enterprise uses the billing start date as defined by the cluster license by
+  default. Vault Community does not have a billing start time, so ommitting
+  `start_time` can lead to undefined behavior. We recommend setting an explicit
+  start time to ensure reliable behavior in all Vault versions.
+- `end_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. 
+  Specifies the end of the period for which client counts will be reported. If 
+  no end time is specified, the end of the current month will be used.
+- `limit_namespaces` `(int, optional)` - Controls the total number of by_namespace
+  data returned. This can be used to return the client counts for the specified number
+  of namespaces having highest activity. If no `limit_namespaces` parameter is 
+  specified, client counts for all namespaces in specified usage period is returned.
+- `current_billing_period` `(bool, optional)` - **DEPRECATED** Uses the builtin billing
+  start timestamp as `start_time` and the current time as the `end_time`, returning a
   response with the current billing period information without having to
-  explicitly provide a start and end time. This parameter is deprecated, as this option is now the default, so no parameter is needed to specify.
+  explicitly provide a start and end time. This parameter is deprecated, as this option
+  is now the default, so no parameter is needed to specify.
 
 
 ### Sample request
diff --git a/content/vault/v1.19.x/content/docs/updates/important-changes.mdx b/content/vault/v1.19.x/content/docs/updates/important-changes.mdx
@@ -383,3 +383,22 @@ already rotated before the restart.
 Upgrade to 1.18.9+ or 1.19.3+. If you cannot upgrade, the only workaround is to
 avoid restarting the backend.
 
+### Counters API requires start time in Vault Community ((#start-time-counters-api))
+
+| Change      | Status | Affected version | Fixed version
+| ----------- | ------ | ---------------- | --------------------
+| Known issue | Fixed  | 1.18.x, 1.19.x   | 1.20.0
+
+Vault Community requires the `start_time` parameter  for
+`/sys/internal/counters/activity`. Unlike Enterprise Vault, Vault Commuity does
+not define a billing start time, and ommitting `start_time` may lead to
+unexpected behavior in affected versions (1.18.x and 1.19.x). 
+
+You can safely omit `start_time` for Vault Enterprise as `start_time` defaults
+to the billing start date for the cluster.
+
+#### Workaround
+
+To avoid issues and unexpected behavior with Vault Community, always provide a
+valid `start_time` value when calling `/sys/internal/counters/activity` or
+upgrade to v1.20.x.
diff --git a/content/vault/v1.19.x/content/partials/release-notes/change-summary/1_19.mdx b/content/vault/v1.19.x/content/partials/release-notes/change-summary/1_19.mdx
@@ -42,4 +42,5 @@ Found  | Fixed  | Workaround | Edition    | Issue
 1.19.0 | 1.19.3 | **Yes**    | All        | [Login/token renewal failures after group changes](/vault/docs/v1.19.x/updates/important-changes#group-writes)
 1.19.0 | 1.19.3 | Upgrade    | All        | [Unexpected DB static role rotations on upgrade](/vault/docs/v1.19.x/updates/important-changes#db-static-role-rotations)
 1.19.0 | 1.19.3 | Upgrade    | All        | [Unexpected LDAP static role rotations on upgrade](/vault/docs/v1.19.x/updates/important-changes#ldap-static-role-rotations)
-1.19.0 | 1.19.3 | **Yes**    | All        | [Unwanted secret rotation for DB and LDAP roles on restart](/vault/docs/v1.19.x/updates/important-changes#secret-rotate-on-restart)
+1.19.0 | 1.19.3 | **Yes**    | All        | [Unwanted secret rotation for DB and LDAP roles on restart](/vault/docs/v1.19.x/updates/important-changes#secret-rotate-on-restart)
+1.19.0 | No     | **Yes**    | All        | [Counters API requires start time in Vault Community](/vault/docs/v1.19.x/updates/important-changes#start-time-counters-api)
diff --git a/content/vault/v1.20.x/content/api-docs/system/internal-counters.mdx b/content/vault/v1.20.x/content/api-docs/system/internal-counters.mdx
@@ -315,11 +315,11 @@ When `end_time` falls in the current month or a future month, Vault adjusts the
 end time to the last day of the previous month and includes the following
 warning along with the associated counts:
 
-      ```json
-      {
-         "warning": "end_time parameter can only be used to specify a date until the end of previous month. The value provided for this parameter was in the current month or in the future date and was therefore ignored. The response includes data until the end of the previous month."
-      }
-      ```
+   ```json
+   {
+      "warning": "end_time parameter can only be used to specify a date until the end of previous month. The value provided for this parameter was in the current month or in the future date and was therefore ignored. The response includes data until the end of the previous month."
+   }
+   ```
 
 For example, assume the current date is September 25, 2025  and you call the
 Get Client Count endpoint with `end_time` set to `2025-10-01`:
