Merge pull request #1187 from matrix-org/paul/metrics-howto

Update documentation about exported prometheus metrics

docs/metrics-howto.rst

@@ -15,36 +15,45 @@ How to monitor Synapse metrics using Prometheus
 
   Restart synapse
 
-3: Check out synapse-prometheus-config
+3: Add a prometheus target for synapse. It needs to set the ``metrics_path``
-  https://github.com/matrix-org/synapse-prometheus-config
+   to a non-default value::
 
-4: Add ``synapse.html`` and ``synapse.rules``
+    - job_name: "synapse"
-  The ``.html`` file needs to appear in prometheus's ``consoles`` directory,
+      metrics_path: "/_synapse/metrics"
-  and the ``.rules`` file needs to be invoked somewhere in the main config
+      static_configs:
-  file. A symlink to each from the git checkout into the prometheus directory
+        - targets:
-  might be easiest to ensure ``git pull`` keeps it updated.
+            "my.server.here:9092"
 
-5: Add a prometheus target for synapse
+Standard Metric Names
-  This is easiest if prometheus runs on the same machine as synapse, as it can
+---------------------
-  then just use localhost::
 
-    global: {
+As of synapse version 0.18.2, the format of the process-wide metrics has been
-      rule_file: "synapse.rules"
+changed to fit prometheus standard naming conventions. Additionally the units
-    }
+have been changed to seconds, from miliseconds.
 
-    job: {
+================================== =============================
-      name: "synapse"
+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
+================================== =============================
 
-      target_group: {
+The python-specific counts of garbage collector performance have been renamed.
-        target: "http://localhost:9092/"
-      }
-    }
 
-6: Start prometheus::
+=========================== ======================
+New name                    Old name
+--------------------------- ----------------------
+python_gc_time              reactor_gc_time      
+python_gc_unreachable_total reactor_gc_unreachable
+python_gc_counts            reactor_gc_counts
+=========================== ======================
 
-   ./prometheus -config.file=prometheus.conf
+The twisted-specific reactor metrics have been renamed.
 
-7: Wait a few seconds for it to start and perform the first scrape,
+==================================== =================
-   then visit the console:
+New name                             Old name
-
+------------------------------------ -----------------
-    http://server-where-prometheus-runs:9090/consoles/synapse.html
+python_twisted_reactor_pending_calls reactor_tick_time
+python_twisted_reactor_tick_time     reactor_tick_time
+==================================== =================