Add docs for usage endpoint and command (#16258)
* Add docs for usage endpoint and command
This commit is contained in:
Kyle Havlovitz
GitHub
parent
f5fae302d4
commit
f0b2b16ef6
|
|
@ -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
|
||||
|
||||
<Tabs>
|
||||
<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
|
||||
}
|
||||
},
|
||||
"Index": 13,
|
||||
"LastContact": 0,
|
||||
"KnownLeader": true,
|
||||
"ConsistencyLevel": "leader",
|
||||
"NotModified": false,
|
||||
"Backend": 0,
|
||||
"ResultsFilteredByACLs": false
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<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 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` <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 Connect service instances registered in the datacenter,
|
||||
by partition and namespace.
|
||||
|
|
@ -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) <EnterpriseAlert inline />
|
||||
- [autopilot](/consul/commands/operator/autopilot)
|
||||
- [raft](/consul/commands/operator/raft)
|
||||
- [usage](/consul/commands/operator/usage)
|
||||
|
|
|
|||
|
|
@ -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 <subcommand> [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`.
|
||||
|
|
@ -165,6 +165,10 @@
|
|||
{
|
||||
"title": "Segment",
|
||||
"path": "operator/segment"
|
||||
},
|
||||
{
|
||||
"title": "Usage",
|
||||
"path": "operator/usage"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
|
|
@ -425,6 +425,10 @@
|
|||
{
|
||||
"title": "raft",
|
||||
"path": "operator/raft"
|
||||
},
|
||||
{
|
||||
"title": "usage",
|
||||
"path": "operator/usage"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
Loading…
Reference in New Issue