diff --git a/website/content/api-docs/operator/usage.mdx b/website/content/api-docs/operator/usage.mdx
new file mode 100644
index 000000000000..82202b13fb82
--- /dev/null
+++ b/website/content/api-docs/operator/usage.mdx
@@ -0,0 +1,161 @@
+---
+layout: api
+page_title: Usage - Operator - HTTP API
+description: |-
+ The /operator/usage endpoint returns usage information about the number of
+ services, service instances and Connect-enabled service instances by
+ datacenter.
+---
+
+# Usage Operator HTTP API
+
+The `/operator/usage` endpoint returns usage information about the number of
+services, service instances and Connect-enabled service instances by datacenter.
+
+| Method | Path | Produces |
+| ------ | ----------------- | ------------------ |
+| `GET` | `/operator/usage` | `application/json` |
+
+The table below shows this endpoint's support for
+[blocking queries](/consul/api-docs/features/blocking),
+[consistency modes](/consul/api-docs/features/consistency),
+[agent caching](/consul/api-docs/features/caching), and
+[required ACLs](/consul/api-docs/api-structure#authentication).
+
+| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
+| ---------------- | ----------------- | ------------- | --------------- |
+| `YES` | `all` | `none` | `operator:read` |
+
+The corresponding CLI command is [`consul operator usage instances`](/consul/commands/operator/usage).
+
+### Query Parameters
+
+- `global` `(bool: false)` - If present, usage information for all
+ known datacenters will be returned. By default, only the local datacenter's
+ usage information is returned.
+
+- `stale` `(bool: false)` - If the cluster does not currently have a leader, an
+ error will be returned. You can use the `?stale` query parameter to read the
+ Raft configuration from any of the Consul servers.
+
+### Sample Request
+
+```shell-session
+$ curl \
+ http://127.0.0.1:8500/v1/operator/usage
+```
+
+### Sample Response
+
+
+
+```json
+{
+ "Usage": {
+ "dc1": {
+ "Services": 1,
+ "ServiceInstances": 1,
+ "ConnectServiceInstances": {
+ "connect-native": 0,
+ "connect-proxy": 0,
+ "ingress-gateway": 0,
+ "mesh-gateway": 0,
+ "terminating-gateway": 0
+ },
+ "BillableServiceInstances": 0
+ }
+ },
+ "Index": 13,
+ "LastContact": 0,
+ "KnownLeader": true,
+ "ConsistencyLevel": "leader",
+ "NotModified": false,
+ "Backend": 0,
+ "ResultsFilteredByACLs": false
+}
+```
+
+
+```json
+{
+ "Usage": {
+ "dc1": {
+ "Services": 1,
+ "ServiceInstances": 1,
+ "ConnectServiceInstances": {
+ "connect-native": 0,
+ "connect-proxy": 0,
+ "ingress-gateway": 0,
+ "mesh-gateway": 0,
+ "terminating-gateway": 0
+ },
+ "BillableServiceInstances": 0,
+ "PartitionNamespaceServices": {
+ "default": {
+ "default": 1
+ }
+ },
+ "PartitionNamespaceServiceInstances": {
+ "default": {
+ "default": 1
+ }
+ },
+ "PartitionNamespaceBillableServiceInstances": {
+ "default": {
+ "default": 1
+ }
+ },
+ "PartitionNamespaceConnectServiceInstances": {
+ "default": {
+ "default": {
+ "connect-native": 0,
+ "connect-proxy": 0,
+ "ingress-gateway": 0,
+ "mesh-gateway": 0,
+ "terminating-gateway": 0
+ }
+ }
+ }
+ }
+ },
+ "Index": 13,
+ "LastContact": 0,
+ "KnownLeader": true,
+ "ConsistencyLevel": "leader",
+ "NotModified": false,
+ "Backend": 0,
+ "ResultsFilteredByACLs": false
+}
+```
+
+
+
+- `Services` is the total number of unique service names registered in the
+ datacenter.
+
+- `ServiceInstances` is the total number of service instances registered in
+ the datacenter.
+
+- `ConnectServiceInstances` is the total number of Connect service instances
+ registered in the datacenter.
+
+- `BillableServiceInstances` is the total number of billable service instances
+ registered in the datacenter. This is only relevant in Consul Enterprise
+ and is the total service instance count, not including any Connect service
+ instances or any Consul server instances.
+
+- `PartitionNamespaceServices` is the total number
+ of unique service names registered in the datacenter, by partition and
+ namespace.
+
+- `PartitionNamespaceServiceInstances` is the total
+ number of service instances registered in the datacenter, by partition and
+ namespace.
+
+- `PartitionNamespaceBillableServiceInstances` is
+ the total number of billable service instances registered in the datacenter,
+ by partition and namespace.
+
+- `PartitionNamespaceConnectServiceInstances` is
+ the total number of Connect service instances registered in the datacenter,
+ by partition and namespace.
\ No newline at end of file
diff --git a/website/content/commands/operator/index.mdx b/website/content/commands/operator/index.mdx
index 14ba32905283..060c42255880 100644
--- a/website/content/commands/operator/index.mdx
+++ b/website/content/commands/operator/index.mdx
@@ -37,6 +37,7 @@ Subcommands:
area Provides tools for working with network areas (Enterprise-only)
autopilot Provides tools for modifying Autopilot configuration
raft Provides cluster-level tools for Consul operators
+ usage Provides cluster-level usage information
```
For more information, examples, and usage about a subcommand, click on the name
@@ -45,3 +46,4 @@ of the subcommand in the sidebar or one of the links below:
- [area](/consul/commands/operator/area)
- [autopilot](/consul/commands/operator/autopilot)
- [raft](/consul/commands/operator/raft)
+- [usage](/consul/commands/operator/usage)
diff --git a/website/content/commands/operator/usage.mdx b/website/content/commands/operator/usage.mdx
new file mode 100644
index 000000000000..b0d7d03db2f9
--- /dev/null
+++ b/website/content/commands/operator/usage.mdx
@@ -0,0 +1,100 @@
+---
+layout: commands
+page_title: 'Commands: Operator Usage'
+description: >
+ The operator usage command provides cluster-level tools for Consul operators
+ to view usage information, such as service and service instance counts.
+---
+
+# Consul Operator Usage
+
+Command: `consul operator usage`
+
+The Usage `operator` command provides cluster-level tools for Consul operators
+to view usage information, such as service and service instance counts.
+
+```text
+Usage: consul operator usage [options]
+
+ # ...
+
+Subcommands:
+ instances Display service instance usage information
+```
+
+## instances
+
+Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/usage](/consul/api-docs/operator/usage#operator-usage)
+
+This command retrieves usage information about the number of services registered in a given
+datacenter. By default, the datacenter of the local agent is queried.
+
+The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of
+[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching)
+are not supported from commands, but may be from the corresponding HTTP endpoint.
+
+| ACL Required |
+| --------------- |
+| `operator:read` |
+
+Usage: `consul operator usage instances`
+
+The output looks like this:
+
+```text
+$ consul operator usage instances
+Billable Service Instances Total: 3
+dc1 Billable Service Instances: 3
+
+Billable Services
+Services Service instances
+2 3
+
+Connect Services
+Type Service instances
+connect-native 0
+connect-proxy 0
+ingress-gateway 0
+mesh-gateway 1
+terminating-gateway 0
+```
+
+With the `-all-datacenters` flag:
+
+```text
+$ consul operator usage instances -all-datacenters
+Billable Service Instances Total: 4
+dc1 Billable Service Instances: 3
+dc2 Billable Service Instances: 1
+
+Billable Services
+Datacenter Services Service instances
+dc1 2 3
+dc2 1 1
+
+Total 3 4
+
+Connect Services
+Datacenter Type Service instances
+dc1 connect-native 0
+dc1 connect-proxy 0
+dc1 ingress-gateway 0
+dc1 mesh-gateway 1
+dc1 terminating-gateway 0
+dc2 connect-native 0
+dc2 connect-proxy 0
+dc2 ingress-gateway 0
+dc2 mesh-gateway 1
+dc2 terminating-gateway 1
+
+Total 3
+```
+
+#### Command Options
+
+- `-all-datacenters` - Display service counts from all known datacenters.
+ Default is `false`.
+
+- `-billable` - Display only billable service information. Default is `false`.
+
+- `-connect` - Display only Connect service information. Default is `false`.
diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json
index fb1dd87421be..66d8fa9a9492 100644
--- a/website/data/api-docs-nav-data.json
+++ b/website/data/api-docs-nav-data.json
@@ -165,6 +165,10 @@
{
"title": "Segment",
"path": "operator/segment"
+ },
+ {
+ "title": "Usage",
+ "path": "operator/usage"
}
]
},
diff --git a/website/data/commands-nav-data.json b/website/data/commands-nav-data.json
index aac55d7952bb..ee491e9dfa7b 100644
--- a/website/data/commands-nav-data.json
+++ b/website/data/commands-nav-data.json
@@ -425,6 +425,10 @@
{
"title": "raft",
"path": "operator/raft"
+ },
+ {
+ "title": "usage",
+ "path": "operator/usage"
}
]
},