synapse/docs/metrics-howto.rst

How to monitor Synapse metrics using Prometheus

1: Install prometheus:

Follow instructions at http://prometheus.io/docs/introduction/install/

2: Enable synapse metrics:

Simply setting a (local) port number will enable it. Pick a port. prometheus itself defaults to 9090, so starting just above that for locally monitored services seems reasonable. E.g. 9092:

Add to homeserver.yaml

metrics_port: 9092

Restart synapse

3: Add a prometheus target for synapse. It needs to set the metrics_path

to a non-default value:

- job_name: "synapse"
  metrics_path: "/_synapse/metrics"
  static_configs:
    - targets:
        "my.server.here:9092"

Standard Metric Names

As of synapse version 0.18.2, the format of the process-wide metrics has been changed to fit prometheus standard naming conventions. Additionally the units have been changed to seconds, from miliseconds.

New name	Old name
process_cpu_user_seconds_total	process_resource_utime / 1000
process_cpu_system_seconds_total	process_resource_stime / 1000
process_open_fds (no 'type' label)	process_fds

The python-specific counts of garbage collector performance have been renamed.

New name	Old name
python_gc_time	reactor_gc_time
python_gc_unreachable_total	reactor_gc_unreachable
python_gc_counts	reactor_gc_counts

The twisted-specific reactor metrics have been renamed.

New name	Old name
python_twisted_reactor_pending_calls	reactor_pending_calls
python_twisted_reactor_tick_time	reactor_tick_time