Improve documentation how to configure prometheus for workers (#8822)

This commit is contained in:
Dirk Klimpel 2020-11-26 11:42:55 +01:00 committed by GitHub
parent 3f0ff53158
commit 14f81a6d24
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 65 additions and 20 deletions

1
changelog.d/8822.doc Normal file
View File

@ -0,0 +1 @@
Improve documentation how to configure prometheus for workers.

View File

@ -20,6 +20,7 @@ Add a new job to the main prometheus.conf file:
``` ```
### for Prometheus v2 ### for Prometheus v2
Add a new job to the main prometheus.yml file: Add a new job to the main prometheus.yml file:
```yaml ```yaml
@ -29,14 +30,17 @@ Add a new job to the main prometheus.yml file:
scheme: "https" scheme: "https"
static_configs: static_configs:
- targets: ['SERVER.LOCATION:PORT'] - targets: ["my.server.here:port"]
``` ```
An example of a Prometheus configuration with workers can be found in
[metrics-howto.md](https://github.com/matrix-org/synapse/blob/master/docs/metrics-howto.md).
To use `synapse.rules` add To use `synapse.rules` add
```yaml ```yaml
rule_files: rule_files:
- "/PATH/TO/synapse-v2.rules" - "/PATH/TO/synapse-v2.rules"
``` ```
Metrics are disabled by default when running synapse; they must be enabled Metrics are disabled by default when running synapse; they must be enabled

View File

@ -13,10 +13,12 @@
can be enabled by adding the \"metrics\" resource to the existing can be enabled by adding the \"metrics\" resource to the existing
listener as such: listener as such:
resources: ```yaml
- names: resources:
- client - names:
- metrics - client
- metrics
```
This provides a simple way of adding metrics to your Synapse This provides a simple way of adding metrics to your Synapse
installation, and serves under `/_synapse/metrics`. If you do not installation, and serves under `/_synapse/metrics`. If you do not
@ -31,11 +33,13 @@
Add a new listener to homeserver.yaml: Add a new listener to homeserver.yaml:
listeners: ```yaml
- type: metrics listeners:
port: 9000 - type: metrics
bind_addresses: port: 9000
- '0.0.0.0' bind_addresses:
- '0.0.0.0'
```
For both options, you will need to ensure that `enable_metrics` is For both options, you will need to ensure that `enable_metrics` is
set to `True`. set to `True`.
@ -47,10 +51,13 @@
It needs to set the `metrics_path` to a non-default value (under It needs to set the `metrics_path` to a non-default value (under
`scrape_configs`): `scrape_configs`):
- job_name: "synapse" ```yaml
metrics_path: "/_synapse/metrics" - job_name: "synapse"
static_configs: scrape_interval: 15s
- targets: ["my.server.here:port"] metrics_path: "/_synapse/metrics"
static_configs:
- targets: ["my.server.here:port"]
```
where `my.server.here` is the IP address of Synapse, and `port` is where `my.server.here` is the IP address of Synapse, and `port` is
the listener port configured with the `metrics` resource. the listener port configured with the `metrics` resource.
@ -60,7 +67,8 @@
1. Restart Prometheus. 1. Restart Prometheus.
1. Consider using the [grafana dashboard](https://github.com/matrix-org/synapse/tree/master/contrib/grafana/) and required [recording rules](https://github.com/matrix-org/synapse/tree/master/contrib/prometheus/) 1. Consider using the [grafana dashboard](https://github.com/matrix-org/synapse/tree/master/contrib/grafana/)
and required [recording rules](https://github.com/matrix-org/synapse/tree/master/contrib/prometheus/)
## Monitoring workers ## Monitoring workers
@ -76,9 +84,9 @@ To allow collecting metrics from a worker, you need to add a
under `worker_listeners`: under `worker_listeners`:
```yaml ```yaml
- type: metrics - type: metrics
bind_address: '' bind_address: ''
port: 9101 port: 9101
``` ```
The `bind_address` and `port` parameters should be set so that The `bind_address` and `port` parameters should be set so that
@ -87,6 +95,38 @@ don't clash with an existing worker.
With this example, the worker's metrics would then be available With this example, the worker's metrics would then be available
on `http://127.0.0.1:9101`. on `http://127.0.0.1:9101`.
Example Prometheus target for Synapse with workers:
```yaml
- job_name: "synapse"
scrape_interval: 15s
metrics_path: "/_synapse/metrics"
static_configs:
- targets: ["my.server.here:port"]
labels:
instance: "my.server"
job: "master"
index: 1
- targets: ["my.workerserver.here:port"]
labels:
instance: "my.server"
job: "generic_worker"
index: 1
- targets: ["my.workerserver.here:port"]
labels:
instance: "my.server"
job: "generic_worker"
index: 2
- targets: ["my.workerserver.here:port"]
labels:
instance: "my.server"
job: "media_repository"
index: 1
```
Labels (`instance`, `job`, `index`) can be defined as anything.
The labels are used to group graphs in grafana.
## Renaming of metrics & deprecation of old names in 1.2 ## Renaming of metrics & deprecation of old names in 1.2
Synapse 1.2 updates the Prometheus metrics to match the naming Synapse 1.2 updates the Prometheus metrics to match the naming