Add a monitoring section.

[nageru-docs] / monitoring.rst

diff --git a/monitoring.rst b/monitoring.rst
new file mode 100644 (file)
index 0000000..8e64307
--- /dev/null
+++ b/monitoring.rst
@@ -0,0 +1,33 @@
+Monitoring
+==========
+
+If you have a large Nageru installation, you may want to monitor it remotely,
+as opposed to just eyeballing the UI and occasionally checking into the stream
+to verify everything is OK. As of version 1.6.1, Nageru supports native
+`Prometheus <https://prometheus.io/>`_ metrics.
+
+This section is not intended to explain Prometheus; for that, see the Prometheus
+documentation. You do not need a separate exporter for Nageru, you simply point
+Prometheus to the same HTTP port as is used for your stream, and it will fetch
+all metrics from the /metrics endpoint.
+
+Nageru's metrics export basically everything you can get from the UI and much more.
+Unfortunately, Prometheus is relatively inefficient when it comes to dealing with
+histograms, and many of the values Nageru tries to measure (like latency through
+the various points in the pipeline) can take on a quite wide range of values.
+Thus, most values that would normally be exported as Prometheus histograms are
+exported as summaries over one-minute sliding windows instead. This means they
+are highly precise, but unfortunately, it means you cannot aggregate them
+meaningfully.
+
+
+Grafana dashboard
+-----------------
+
+Nageru ships with an example `Grafana <https://grafana.com/>`_ dashboard exported
+in JSON format; it does not graph all metrics, but it should cover most of the
+interesting parts. Note that there is currently no guarantee of forward or
+backward compatibility in metrics, so if Nageru internals change significantly,
+some graphs could stop working. Of course, you can change the dashboard as you
+see fit; if you don't use e.g. HDMI/SDI output, you will probably want to
+remove the panels related to it.