Update CC docs

website/content/api-docs/system/internal-counters.mdx

@@ -89,24 +89,89 @@ $ curl \
 
 ## Client Count
 
-This endpoint returns the number of clients per namespace, as the sum of clients calculated from the use 
-of active entities and non-entity tokens.
-An "active entity" is a distinct entity that has created one or more tokens in the given time period.
-A "non-entity token" is a token with no attached entity ID. 
-Both non-entity tokens and active entities have distinct client IDs. For more information on how clients
-map to these client IDs, and how clients are counted, please visit the 
-[client count](/docs/concepts/client-count) concepts page.
-
-A time period may be specified; otherwise it reports on a default reporting period, such as the
-previous twelve calendar months. Reports are only available with month granularity, after each month
-has completed. The response includes the actual time period covered, which may not exactly match
-the query parameters due to the monthly granularity of the data, or missing months in the requested
+This endpoint returns client activity information for a given billing
+period. The billing period is represented by the `start_time` and `end_time`
+parameters.
+
+There are a few things to be known while using this API.
+
+- The activity information only accounts for activity that has happened for the
+latest contiguous months in the billing period. For example, if the billing
+period is from Jan 2022 to June 2022, and say the activity subsystem in Vault
+was not capturing data for the months Jan to March for any reason, the response
+will only include information for the months of May and June.
+
+- The response contains the total activity for the billing period and the
+attributions of the total activity against specific components in Vault. This
+helps in understanding the total activity better by knowing which components in
+Vault are leading to that top level activity count. First level of attribution
+breakdowns are by namespaces and months, under the `by_namespaces` and `months`
+JSON block respectively.
+
+- `by_namespaces` breakdowns provide attributions of each namespace to the total
+activity count. These namespace attributions are further broken down by mount
+level attributions, wherein information can be found on attributions of each
+mount path within a given namespace to the overall activity of the namespace.
+
+- `months` breakdowns provide attributions of each month to the total activity
+count. These month level attributions are further broken down into namespace and mount
+level attributions for each month.
+
+- Each entry in the `months` breakdown contains a `new_clients` block. Within a
+billing period, when a token is first used, regardless of when it was created,
+that token is considered a new client for that billing period. This means that
+all the active clients in the first month of the billing period will be
+considered new clients for that billing period. These tokens could all be
+generated and counted in the previous billing period, but despite that they are
+still considered new clients in the context of the given billing period. For
+each subsequent month in the same billing period, the tokens used in those
+respective months that were not used in any of the previous months of the same
+billing period are considered new clients for that month. Hence, the computation
+of new clients differs for each combination of `start_time` and `end_time`.
+
+- The `new_clients` block within the `months` breakdown will also be further
+broken down by namespaces and mounts for visibility into which components in
+Vault lead to the new clients for each month.
+
+- The `distinct_entities` field name is deprecated since Vault 1.10. Refer to
+`entity_clients` field instead. The `distinct_entities` field is currently
+returned by the API for backwards compatibility and it may be removed in future.
+
+- The `non_entity_tokens` field name is deprecated since Vault 1.10. Refer to
+`non_entity_clients` field instead. The `non_entity_tokens` field is currently
+returned by the API for backwards compatibility and it may be removed in future.
+
+- All occurrences of namespace breakdowns, mount level breakdowns and month
+level breakdowns in the response are arranged in the decreasing order of their
+activity. Entries with highest activity will be at the top.
+
+- If the `end_date` supplied to the API is for the current month, the activity
+information returned by this API will only be till the previous month. The
+activity system is designed to process the accumulated activity only at the end
+of the month. Since the current month's information is not fully processed by
+the system it will not be added to the API response. However the accumulated
+response can be viewed using the partial month API.
+
+- The response includes the actual time period covered, which may not exactly
+match the query parameters due to the month granularity of data, or missing
+months in the requested time range.
+
+For more information on how clients map to these client IDs, and how clients are
+counted, please visit the [client count](/docs/concepts/client-count) concepts
+page.
+
+A time period may be specified; otherwise it reports on a default reporting
+period, such as the previous twelve calendar months. Reports are only available
+with month granularity, after each month has completed. The response includes
+the actual time period covered, which may not exactly match the query parameters
+due to the monthly granularity of the data, or missing months in the requested
 time range.
 
-The response will include all child namespaces of the namespace in which the request was made.
-If some namespace has subsequently been deleted, its path will be listed as "deleted namespace :ID:".
-Deleted namespaces are reported only for queries in the root namespace, because the information about
-the namespace path is unknown.
+The response will include all child namespaces of the namespace in which the
+request was made. If some namespace has subsequently been deleted, its path will
+be listed as "deleted namespace :ID:". Deleted namespaces are reported only for
+queries in the root namespace, because the information about the namespace path
+is unknown.
 
 This endpoint was added in Vault 1.6.
 
@@ -195,7 +260,7 @@ $ curl \
 
 ## Partial Month Client Count
 
-This endpoint returns the number of clients per namespace for the current month, as the sum of clients calculated from the use 
+This endpoint returns the number of clients per namespace for the current month, as the sum of clients calculated from the use
 of active entities and non-entity tokens.
 An "active entity" is a distinct entity that has created one or more tokens in the given time period.
 A "non-entity token" is a token with no attached entity ID.
@@ -237,7 +302,7 @@ $ curl \
            "distinct_entities":0,
            "non_entity_tokens":100,
            "clients":100
-        } 
+        }
       },
       {
         "namespace_id":"RxD81",