README.md
1# Consul Exporter [][travis]
2
3[][circleci]
4[][quay]
5[][hub]
6
7Export Consul service health to Prometheus.
8
9To run it:
10
11```bash
12make
13./consul_exporter [flags]
14```
15
16## Exported Metrics
17
18| Metric | Meaning | Labels |
19| ------ | ------- | ------ |
20| consul_up | Was the last query of Consul successful | |
21| consul_raft_peers | How many peers (servers) are in the Raft cluster | |
22| consul_serf_lan_members | How many members are in the cluster | |
23| consul_catalog_services | How many services are in the cluster | |
24| consul_catalog_service_node_healthy | Is this service healthy on this node | service, node |
25| consul_health_node_status | Status of health checks associated with a node | check, node |
26| consul_health_service_status | Status of health checks associated with a service | check, node, service |
27| consul_catalog_kv | The values for selected keys in Consul's key/value catalog. Keys with non-numeric values are omitted | key |
28
29### Flags
30
31```bash
32./consul_exporter --help
33```
34
35* __`consul.server`:__ Address (host and port) of the Consul instance we should
36 connect to. This could be a local agent (`localhost:8500`, for instance), or
37 the address of a Consul server.
38* __`consul.health-summary`:__ Collects information about each registered
39 service and exports `consul_catalog_service_node_healthy`. This requires n+1
40 Consul API queries to gather all information about each service. Health check
41 information are available via `consul_health_service_status` as well, but
42 only for services which have a health check configured. Defaults to true.
43* __`web.listen-address`:__ Address to listen on for web interface and telemetry.
44* __`web.telemetry-path`:__ Path under which to expose metrics.
45* __`log.level`:__ Logging level. `info` by default.
46
47#### Key/Value Checks
48
49This exporter supports grabbing key/value pairs from Consul's KV store and
50exposing them to Prometheus. This can be useful, for instance, if you use
51Consul KV to store your intended cluster size, and want to graph that value
52against the actual value found via monitoring.
53
54* __`kv.prefix`:__ Prefix under which to look for KV pairs.
55* __`kv.filter`:__ Only store keys that match this regex pattern.
56
57A prefix must be supplied to activate this feature. Pass `/` if you want to
58search the entire keyspace.
59
60### Environment variables
61
62The consul\_exporter supports all environment variables provided by the official
63[consul/api package](https://github.com/hashicorp/consul/blob/c744792fc4d665363dba0ecfc7d05fdedc9cab32/api/api.go#L23-L43),
64including `CONSUL_HTTP_TOKEN` to set the [ACL](https://www.consul.io/docs/internals/acl.html) token.
65
66## Useful Queries
67
68__Are my services healthy?__
69
70 min(consul_catalog_service_node_healthy) by (service)
71
72Values of 1 mean that all nodes for the service are passing. Values of 0 mean at least one node for the service is not passing.
73
74__What service nodes are failing?__
75
76 sum by (node, service)(consul_catalog_service_node_healthy == 0)
77
78## Using Docker
79
80You can deploy this exporter using the [prom/consul-exporter](https://registry.hub.docker.com/u/prom/consul-exporter/) Docker image.
81
82For example:
83
84```bash
85docker pull prom/consul-exporter
86
87docker run -d -p 9107:9107 prom/consul-exporter -consul.server=172.17.0.1:8500
88```
89
90Keep in mind that your container needs to be able to communicate with the Consul server or agent. Use an IP accessible from the container or set the `--dns` and `--dns-search` options of the `docker run` command:
91
92```bash
93docker run -d -p 9107:9107 --dns=172.17.0.1 --dns-search=service.consul \
94 prom/consul-exporter -consul.server=consul:8500
95```
96
97
98[circleci]: https://circleci.com/gh/prometheus/consul_exporter
99[hub]: https://hub.docker.com/r/prom/consul-exporter/
100[travis]: https://travis-ci.org/prometheus/consul_exporter
101[quay]: https://quay.io/repository/prometheus/consul-exporter
102
){kind=link}
){kind=link}
){kind=link}