consul/website/content/api-docs/operator/usage.mdx

169 lines
4.6 KiB
Plaintext
Raw Normal View History

---
layout: api
page_title: Usage - Operator - HTTP API
description: |-
The /operator/usage endpoint returns usage information about the number of
services, service instances and mesh-enabled service instances by
datacenter.
---
# Usage Operator HTTP API
The `/operator/usage` endpoint returns usage information about the number of
services, service instances and mesh-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
<Tabs>
Docs/cluster peering 1.15 updates (#16291) * initial commit * initial commit * Overview updates * Overview page improvements * More Overview improvements * improvements * Small fixes/updates * Updates * Overview updates * Nav data * More nav updates * Fix * updates * Updates + tip test * Directory test * refining * Create restructure w/ k8s * Single usage page * Technical Specification * k8s pages * typo * L7 traffic management * Manage connections * k8s page fix * Create page tab corrections * link to k8s * intentions * corrections * Add-on intention descriptions * adjustments * Missing </CodeTabs> * Diagram improvements * Final diagram update * Apply suggestions from code review Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> Co-authored-by: David Yu <dyu@hashicorp.com> * diagram name fix * Fixes * Updates to index.mdx * Tech specs page corrections * Tech specs page rename * update link to tech specs * K8s - new pages + tech specs * k8s - manage peering connections * k8s L7 traffic management * Separated establish connection pages * Directory fixes * Usage clean up * k8s docs edits * Updated nav data * CodeBlock Component fix * filename * CodeBlockConfig removal * Redirects * Update k8s filenames * Reshuffle k8s tech specs for clarity, fmt yaml files * Update general cluster peering docs, reorder CLI > API > UI, cross link to kubernetes * Fix config rendering in k8s usage docs, cross link to general usage from k8s docs * fix legacy link * update k8s docs * fix nested list rendering * redirect fix * page error --------- Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> Co-authored-by: David Yu <dyu@hashicorp.com> Co-authored-by: Tu Nguyen <im2nguyen@gmail.com>
2023-02-23 17:58:39 +00:00
<Tab heading="OSS">
```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,
"Nodes": 1
}
},
"Index": 13,
"LastContact": 0,
"KnownLeader": true,
"ConsistencyLevel": "leader",
"NotModified": false,
"Backend": 0,
"ResultsFilteredByACLs": false
}
```
</Tab>
Docs/cluster peering 1.15 updates (#16291) * initial commit * initial commit * Overview updates * Overview page improvements * More Overview improvements * improvements * Small fixes/updates * Updates * Overview updates * Nav data * More nav updates * Fix * updates * Updates + tip test * Directory test * refining * Create restructure w/ k8s * Single usage page * Technical Specification * k8s pages * typo * L7 traffic management * Manage connections * k8s page fix * Create page tab corrections * link to k8s * intentions * corrections * Add-on intention descriptions * adjustments * Missing </CodeTabs> * Diagram improvements * Final diagram update * Apply suggestions from code review Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> Co-authored-by: David Yu <dyu@hashicorp.com> * diagram name fix * Fixes * Updates to index.mdx * Tech specs page corrections * Tech specs page rename * update link to tech specs * K8s - new pages + tech specs * k8s - manage peering connections * k8s L7 traffic management * Separated establish connection pages * Directory fixes * Usage clean up * k8s docs edits * Updated nav data * CodeBlock Component fix * filename * CodeBlockConfig removal * Redirects * Update k8s filenames * Reshuffle k8s tech specs for clarity, fmt yaml files * Update general cluster peering docs, reorder CLI > API > UI, cross link to kubernetes * Fix config rendering in k8s usage docs, cross link to general usage from k8s docs * fix legacy link * update k8s docs * fix nested list rendering * redirect fix * page error --------- Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> Co-authored-by: David Yu <dyu@hashicorp.com> Co-authored-by: Tu Nguyen <im2nguyen@gmail.com>
2023-02-23 17:58:39 +00:00
<Tab heading="Enterprise">
```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
}
```
</Tab>
</Tabs>
- `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 mesh 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 mesh service
instances or any Consul server instances.
- `PartitionNamespaceServices` <EnterpriseAlert inline /> is the total number
of unique service names registered in the datacenter, by partition and
namespace.
- `PartitionNamespaceServiceInstances` <EnterpriseAlert inline /> is the total
number of service instances registered in the datacenter, by partition and
namespace.
- `PartitionNamespaceBillableServiceInstances` <EnterpriseAlert inline /> is
the total number of billable service instances registered in the datacenter,
by partition and namespace.
- `PartitionNamespaceConnectServiceInstances` <EnterpriseAlert inline /> is
the total number of mesh service instances registered in the datacenter,
by partition and namespace.