status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Add docs

This commit is contained in:
freddygv 2020-06-12 09:03:14 -06:00
parent 19e3954603
commit b2c66359ab
2 changed files with 181 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
website/pages/api-docs/catalog.mdx
View File

@ -901,3 +901,144 @@ top level object. The following selectors and filter operations are supported:
| `Tags` | In, Not In, Is Empty, Is Not Empty |
| `Weights.Passing` | Equal, Not Equal |
| `Weights.Warning` | Equal, Not Equal |
## List Services for Gateway
This endpoint returns the services associated with an ingress gateway or terminating gateway.
| Method | Path | Produces |
| ------ | ------------------------------ | ------------------ |
| `GET` | `/catalog/gateway-services/:gateway` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------ |
| `YES` | `all` | `none` | `service:read` |
### Parameters
- `gateway` `(string: <required>)` - Specifies the name of the node for which
to list services. This is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the gateway.
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
from the request's ACL token or will default to the `default` namespace. The `*`
wildcard may be used and then services from all namespaces will be returned. Added in Consul 1.7.0.
### Sample Request
```shell-session
$ curl \
http://127.0.0.1:8500/v1/catalog/gateway-services/my-terminating-gateway
```
### Sample Responses
```json
[
{
"Gateway": {
"Name": "my-terminating-gateway",
"Namespace": "default"
},
"Service": {
"Name": "api",
"Namespace": "frontend"
},
"GatewayKind": "terminating-gateway",
"CAFile": "/etc/certs/ca.pem",
"CertFile": "/etc/certs/api/client.pem",
"KeyFile": "/etc/certs/api/client.key",
"SNI": "api.my-domain",
"CreateIndex": 16,
"ModifyIndex": 16
},
{
"Gateway": {
"Name": "my-terminating-gateway",
"Namespace": "default"
},
"Service": {
"Name": "web",
"Namespace": "frontend"
},
"GatewayKind": "terminating-gateway",
"CreateIndex": 17,
"ModifyIndex": 17
}
]
```
```json
[
{
"Gateway": {
"Name": "my-ingress-gateway",
"Namespace": "default"
},
"Service": {
"Name": "api",
"Namespace": "frontend"
},
"GatewayKind": "ingress-gateway",
"Port": 8888,
"Protocol": "http",
"Hosts": ["api.mydomain.com"],
"CreateIndex": 15,
"ModifyIndex": 15
},
{
"Gateway": {
"Name": "my-ingress-gateway",
"Namespace": "default"
},
"Service": {
"Name": "redis",
"Namespace": "ops"
},
"GatewayKind": "ingress-gateway",
"Port": 8443,
"Protocol": "tcp",
"CreateIndex": 16,
"ModifyIndex": 16
}
]
```
- `Gateway.Name` is the name of the gateway service of the request
- `Gateway.Namespace` is the Consul Enterprise namespace of the gateway
- `Service.Name` is the name of a service associated with the gateway
- `Service.Namespace` is the Consul Enterprise namespace of a service associated with the gateway
- `ServiceKind` is the kind of service, will be one of "ingress-gateway" or "terminating-gateway". See the Agent
[service registration API](/api/agent/service#kind) for more information.
- `CAFile` is the path to a CA file the gateway will use for TLS origination to the associated service
- `CertFile` is the path to a client certificate the gateway will use for TLS origination to the associated service
- `KeyFile` is the path to a key file the gateway will use for TLS origination to the associated service
- `SNI` is a hostname or domain name the gateway will specify during the TLS handshake with the associated service
- `Port` is the port the ingress gateway is listening on for the associated service
- `Protocol` is the protocol of the ingress gateway's listener for the associated service
- `Hosts` list of hosts that specify what requests will match to this associated service
- `FromWildcard` determines whether the service was associated with the gateway by providing a wildcard specifier
in the gateway's configuration entry

78
website/pages/docs/agent/telemetry.mdx
View File

@ -137,44 +137,46 @@ when retrieving metrics from the built-in store using the above described signal
This is a full list of metrics emitted by Consul.
| Metric | Description | Unit | Type |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------- |
| `consul.acl.blocked.service.registration` | This increments whenever a deregistration fails for a service (blocked by an ACL) | requests | counter |
| `consul.acl.blocked..registration` | This increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL | requests | counter |
| `consul.client.rpc` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server. This gives a measure of how much a given agent is loading the Consul servers. Currently, this is only generated by agents in client mode, not Consul servers. | requests | counter |
| `consul.client.rpc.exceeded` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter |
| `consul.client.rpc.failed` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter |
| `consul.client.api.catalog_register.` | This increments whenever a Consul agent receives a catalog register request. | requests | counter |
| `consul.client.api.success.catalog_register.` | This increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter |
| `consul.client.rpc.error.catalog_register.` | This increments whenever a Consul agent receives an RPC error for a catalog register request. | errors | counter |
| `consul.client.api.catalog_deregister.` | This increments whenever a Consul agent receives a catalog deregister request. | requests | counter |
| `consul.client.api.success.catalog_deregister.` | This increments whenever a Consul agent successfully responds to a catalog deregister request. | requests | counter |
| `consul.client.rpc.error.catalog_deregister.` | This increments whenever a Consul agent receives an RPC error for a catalog deregister request. | errors | counter |
| `consul.client.api.catalog_datacenters.` | This increments whenever a Consul agent receives a request to list datacenters in the catalog. | requests | counter |
| `consul.client.api.success.catalog_datacenters.` | This increments whenever a Consul agent successfully responds to a request to list datacenters. | requests | counter |
| `consul.client.rpc.error.catalog_datacenters.` | This increments whenever a Consul agent receives an RPC error for a request to list datacenters. | errors | counter |
| `consul.client.api.catalog_nodes.` | This increments whenever a Consul agent receives a request to list nodes from the catalog. | requests | counter |
| `consul.client.api.success.catalog_nodes.` | This increments whenever a Consul agent successfully responds to a request to list nodes. | requests | counter |
| `consul.client.rpc.error.catalog_nodes.` | This increments whenever a Consul agent receives an RPC error for a request to list nodes. | errors | counter |
| `consul.client.api.catalog_services.` | This increments whenever a Consul agent receives a request to list services from the catalog. | requests | counter |
| `consul.client.api.success.catalog_services.` | This increments whenever a Consul agent successfully responds to a request to list services. | requests | counter |
| `consul.client.rpc.error.catalog_services.` | This increments whenever a Consul agent receives an RPC error for a request to list services. | errors | counter |
| `consul.client.api.catalog_service_nodes.` | This increments whenever a Consul agent receives a request to list nodes offering a service. | requests | counter |
| `consul.client.api.success.catalog_service_nodes.` | This increments whenever a Consul agent successfully responds to a request to list nodes offering a service. | requests | counter |
| `consul.client.rpc.error.catalog_service_nodes.` | This increments whenever a Consul agent receives an RPC error for a request to list nodes offering a service. | errors | counter |
| `consul.client.api.catalog_node_services.` | This increments whenever a Consul agent receives a request to list services registered in a node. | requests | counter |
| `consul.client.api.success.catalog_node_services.` | This increments whenever a Consul agent successfully responds to a request to list services in a service. | requests | counter |
| `consul.client.rpc.error.catalog_node_services.` | This increments whenever a Consul agent receives an RPC error for a request to list services in a service. | errors | counter |
| `consul.runtime.num_goroutines` | This tracks the number of running goroutines and is a general load pressure indicator. This may burst from time to time but should return to a steady state value. | number of goroutines | gauge |
| `consul.runtime.alloc_bytes` | This measures the number of bytes allocated by the Consul process. This may burst from time to time but should return to a steady state value. | bytes | gauge |
| `consul.runtime.heap_objects` | This measures the number of objects allocated on the heap and is a general memory pressure indicator. This may burst from time to time but should return to a steady state value. | number of objects | gauge |
| `consul.acl.cache_hit` | The number of ACL cache hits. | hits | counter |
| `consul.acl.cache_miss` | The number of ACL cache misses. | misses | counter |
| `consul.acl.replication_hit` | The number of ACL replication cache hits (when not running in the ACL datacenter). | hits | counter |
| `consul.dns.stale_queries` | This increments when an agent serves a query within the allowed stale threshold. | queries | counter |
| `consul.dns.ptr_query.` | This measures the time spent handling a reverse DNS query for the given node. | ms | timer |
| `consul.dns.domain_query.` | This measures the time spent handling a domain query for the given node. | ms | timer |
| `consul.http..` | This tracks how long it takes to service the given HTTP request for the given verb and path. Paths do not include details like service or key names, for these an underscore will be present as a placeholder (eg. `consul.http.GET.v1.kv._`) | ms | timer |
| Metric | Description | Unit | Type |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------- |
| `consul.acl.blocked.service.registration` | This increments whenever a deregistration fails for a service (blocked by an ACL) | requests | counter |
| `consul.acl.blocked..registration` | This increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL | requests | counter |
| `consul.client.rpc` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server. This gives a measure of how much a given agent is loading the Consul servers. Currently, this is only generated by agents in client mode, not Consul servers. | requests | counter |
| `consul.client.rpc.exceeded` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter |
| `consul.client.rpc.failed` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter |
| `consul.client.api.catalog_register.` | This increments whenever a Consul agent receives a catalog register request. | requests | counter |
| `consul.client.api.success.catalog_register.` | This increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter |
| `consul.client.rpc.error.catalog_register.` | This increments whenever a Consul agent receives an RPC error for a catalog register request. | errors | counter |
| `consul.client.api.catalog_deregister.` | This increments whenever a Consul agent receives a catalog deregister request. | requests | counter |
| `consul.client.api.success.catalog_deregister.` | This increments whenever a Consul agent successfully responds to a catalog deregister request. | requests | counter |
| `consul.client.rpc.error.catalog_deregister.` | This increments whenever a Consul agent receives an RPC error for a catalog deregister request. | errors | counter |
| `consul.client.api.catalog_datacenters.` | This increments whenever a Consul agent receives a request to list datacenters in the catalog. | requests | counter |
| `consul.client.api.success.catalog_datacenters.` | This increments whenever a Consul agent successfully responds to a request to list datacenters. | requests | counter |
| `consul.client.rpc.error.catalog_datacenters.` | This increments whenever a Consul agent receives an RPC error for a request to list datacenters. | errors | counter |
| `consul.client.api.catalog_nodes.` | This increments whenever a Consul agent receives a request to list nodes from the catalog. | requests | counter |
| `consul.client.api.success.catalog_nodes.` | This increments whenever a Consul agent successfully responds to a request to list nodes. | requests | counter |
| `consul.client.rpc.error.catalog_nodes.` | This increments whenever a Consul agent receives an RPC error for a request to list nodes. | errors | counter |
| `consul.client.api.catalog_services.` | This increments whenever a Consul agent receives a request to list services from the catalog. | requests | counter |
| `consul.client.api.success.catalog_services.` | This increments whenever a Consul agent successfully responds to a request to list services. | requests | counter |
| `consul.client.rpc.error.catalog_services.` | This increments whenever a Consul agent receives an RPC error for a request to list services. | errors | counter |
| `consul.client.api.catalog_service_nodes.` | This increments whenever a Consul agent receives a request to list nodes offering a service. | requests | counter |
| `consul.client.api.success.catalog_service_nodes.` | This increments whenever a Consul agent successfully responds to a request to list nodes offering a service. | requests | counter |
| `consul.client.rpc.error.catalog_service_nodes.` | This increments whenever a Consul agent receives an RPC error for a request to list nodes offering a service. | errors | counter |
| `consul.client.api.catalog_node_services.` | This increments whenever a Consul agent receives a request to list services registered in a node. | requests | counter |
| `consul.client.api.success.catalog_node_services.` | This increments whenever a Consul agent successfully responds to a request to list services in a node. | requests | counter |
| `consul.client.rpc.error.catalog_node_services.` | This increments whenever a Consul agent receives an RPC error for a request to list services in a node. | errors | counter |
| `consul.client.api.success.catalog_gateway_services.` | This increments whenever a Consul agent successfully responds to a request to list services associated with a gateway. | requests | counter |
| `consul.client.rpc.error.catalog_gateway_services.` | This increments whenever a Consul agent receives an RPC error for a request to list services associated with a gateway. | errors | counter |
| `consul.runtime.num_goroutines` | This tracks the number of running goroutines and is a general load pressure indicator. This may burst from time to time but should return to a steady state value. | number of goroutines | gauge |
| `consul.runtime.alloc_bytes` | This measures the number of bytes allocated by the Consul process. This may burst from time to time but should return to a steady state value. | bytes | gauge |
| `consul.runtime.heap_objects` | This measures the number of objects allocated on the heap and is a general memory pressure indicator. This may burst from time to time but should return to a steady state value. | number of objects | gauge |
| `consul.acl.cache_hit` | The number of ACL cache hits. | hits | counter |
| `consul.acl.cache_miss` | The number of ACL cache misses. | misses | counter |
| `consul.acl.replication_hit` | The number of ACL replication cache hits (when not running in the ACL datacenter). | hits | counter |
| `consul.dns.stale_queries` | This increments when an agent serves a query within the allowed stale threshold. | queries | counter |
| `consul.dns.ptr_query.` | This measures the time spent handling a reverse DNS query for the given node. | ms | timer |
| `consul.dns.domain_query.` | This measures the time spent handling a domain query for the given node. | ms | timer |
| `consul.http..` | This tracks how long it takes to service the given HTTP request for the given verb and path. Paths do not include details like service or key names, for these an underscore will be present as a placeholder (eg. `consul.http.GET.v1.kv._`) | ms | timer |
## Server Health