mirror of
https://github.com/status-im/consul.git
synced 2025-02-02 08:56:43 +00:00
Add docs for usage endpoint and command (#16258)
* Add docs for usage endpoint and command
This commit is contained in:
Kyle Havlovitz
GitHub
parent
182f6c8be5
commit
5400e3d83d
161
website/content/api-docs/operator/usage.mdx
Normal file
161
website/content/api-docs/operator/usage.mdx
Normal file
@ -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)
|
area Provides tools for working with network areas (Enterprise-only)
|
||||||
autopilot Provides tools for modifying Autopilot configuration
|
autopilot Provides tools for modifying Autopilot configuration
|
||||||
raft Provides cluster-level tools for Consul operators
|
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
|
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 />
|
- [area](/consul/commands/operator/area) <EnterpriseAlert inline />
|
||||||
- [autopilot](/consul/commands/operator/autopilot)
|
- [autopilot](/consul/commands/operator/autopilot)
|
||||||
- [raft](/consul/commands/operator/raft)
|
- [raft](/consul/commands/operator/raft)
|
||||||
|
- [usage](/consul/commands/operator/usage)
|
||||||
|
|||||||
100
website/content/commands/operator/usage.mdx
Normal file
100
website/content/commands/operator/usage.mdx
Normal file
@ -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",
|
"title": "Segment",
|
||||||
"path": "operator/segment"
|
"path": "operator/segment"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "Usage",
|
||||||
|
"path": "operator/usage"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
|||||||
@ -425,6 +425,10 @@
|
|||||||
{
|
{
|
||||||
"title": "raft",
|
"title": "raft",
|
||||||
"path": "operator/raft"
|
"path": "operator/raft"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "usage",
|
||||||
|
"path": "operator/usage"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user