git.sesse.net Git - nageru-docs/blob - monitoring.rst

   1 Monitoring
   2 ==========
   3
   4 If you have a large Nageru installation, you may want to monitor it remotely,
   5 as opposed to just eyeballing the UI and occasionally checking into the stream
   6 to verify everything is OK. As of version 1.6.1, Nageru supports native
   7 `Prometheus <https://prometheus.io/>`_ metrics.
   8
   9 This section is not intended to explain Prometheus; for that, see the Prometheus
  10 documentation. You do not need a separate exporter for Nageru, you simply point
  11 Prometheus to the same HTTP port as is used for your stream, and it will fetch
  12 all metrics from the /metrics endpoint.
  13
  14 Nageru's metrics export basically everything you can get from the UI and much more.
  15 Unfortunately, Prometheus is relatively inefficient when it comes to dealing with
  16 histograms, and many of the values Nageru tries to measure (like latency through
  17 the various points in the pipeline) can take on a quite wide range of values.
  18 Thus, most values that would normally be exported as Prometheus histograms are
  19 exported as summaries over one-minute sliding windows instead. This means they
  20 are highly precise, but unfortunately, it means you cannot aggregate them
  21 meaningfully.
  22
  23
  24 Grafana dashboard
  25 -----------------
  26
  27 Nageru ships with an example `Grafana <https://grafana.com/>`_ dashboard exported
  28 in JSON format; it does not graph all metrics, but it should cover most of the
  29 interesting parts. Note that there is currently no guarantee of forward or
  30 backward compatibility in metrics, so if Nageru internals change significantly,
  31 some graphs could stop working. Of course, you can change the dashboard as you
  32 see fit; if you don't use e.g. HDMI/SDI output, you will probably want to
  33 remove the panels related to it.
  34
  35 .. _tally:
  36
  37 Tally display
  38 -------------
  39
  40 Not related to Prometheus per se, but yet an important part of monitoring is the
  41 *tally light*, or just tally for short. The tally is a talkback signal from the
  42 mixer to the camera, showing the cameraperson that they are indeed on air (or are
  43 about to get to). Professional studio cameras will often not only have a tally
  44 light for the operator, but also for the subject (to know which camera to look
  45 into). However, most cheaper cameras will have none at all.
  46
  47 Nageru does not have functionality to talk to tally lights directly (there are too
  48 many kinds of interfaces and standards), but it does have functionality to expose
  49 tally *data*. Using this, you can build your own tally light, be in through injecting
  50 the right bits on an SDI cable, having a single-board computer set some GPIO pins
  51 for a LED, or simply show a red or green dot on a mobile phone with a web browser.
  52
  53 Nageru's tally data is automatically exposed over HTTP, just as any other monitoring.
  54 You can get one JSON file with a list of all channels (at “http://yourserver.example.org:9095/channels”),
  55 or you can ask for a specific channel and get just its color in plain text
  56 (at “http://yourserver.example.org:9095/channels/2”, where 2 is the lowest
  57 channel ID, since live and preview don't have tally). The tally color values
  58 are taken automatically from the theme's *channel_color* function, so that they
  59 match the borders around the input in the producer's mixer display—typically
  60 green for on preview and red for live. This also means they can be CSS textual
  61 colors (like “red”), although you can of course make the theme return only
  62 “#ff0000” or similar if this makes your tally application simpler.
  63
  64 Note that the tally endpoints have fully open `CORS <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_
  65 headers, so that they can be queried from anywhere; tally data is not sensitive,
  66 and this makes it significantly easier to query them from a web page.