Merge pull request #562 from google/sighup

mtail doesn't automatically reload programmes.

Author: jaqx0r

docs/Deploying.md

@@ -6,7 +6,7 @@ mtail is intended to run one per machine, and serve as monitoring glue for multi
 
 ## Configuration Overview
 
-mtail is configured through commandline flags.
+mtail is configured with commandline flags.
 
 The `--help` flag will print a list of flags for configuring `mtail`.
 
@@ -99,6 +99,26 @@ Read the [Programming Guide](Programming-Guide.md) for instructions on how to wr
 
 `mtail` does not automatically reload programmes after it starts up.  To ask `mtail` to scan for and reload programmes from the supplied `--progs` directory, send it a `SIGHUP` signal on UNIX-like systems.
 
+For example, if configs are being delivered by a configuration management tool like Puppet, then program Puppet to send a SIGHUP when it has copied a new config file over.
+
+```puppet
+exec { 'reload_mtail_programmes':
+  command => "killall -HUP mtail",
+  refreshonly = True,
+}
+
+file { mtail_programme:
+  source => mtail_programme,
+  notify => Exec['reload_mtail_programmes'],
+}
+```
+
+Alternatively, if you're using `scp` or some similiar method to copy the programme files without a receiver, then either follow it with a `ssh $host 'killall -HUP mtail'` or use a tool like [`inotifywait`](https://linux.die.net/man/1/inotifywait) in a side process next to mtail to watch for changes and send the reload signal.
+
+```shell
+inotifywait /etc/mtail/progs | while read event; do killall -HUP mtail; done
+```
+
 ## Getting the Metrics Out
 
 ### Pull based collection

docs/faq.md

@@ -87,3 +87,11 @@ So, given that the monitoring system needs to handle missing and resetting data
 already in a distributed system, there is no compelling reason to implement
 metric checkpointing in `mtail` as well.  It just adds complexity for little
 overall gain.
+
+## Why doesn't `mtail` automatically reload programme files?
+
+`mtail` will reload programme files when it receives a `SIGHUP` signal.
+
+It's assumed that programmes do not change very often, so it relies on an external trigger rather than spend resourecs of its own polling for changes at all.  `inotify` is not used either, as programme reloads would be the only use of that library, and the benefit does not seem worth the cost of including the extra dependency.
+
+See the [Deployment](Deployment.md) guide for suggestions for "automatic" programme reloads.