docs: document log appender filter features

README.md

@@ -9,7 +9,44 @@ As well as providing a semantic logger, this gem handles datadog telemetry assoc
 * logs
 * traces
 * metrics
-   * statsd is automatically attached to datadog runtime metrics and may also be used for custom metrics.
+    * statsd is automatically attached to datadog runtime metrics and may also be used for custom metrics.
+
+### Customise log level per logger
+
+For example, to show debug logging for `MySubscriber` while having all other logs on info.
+
+```
+# The log level must be set to the lowest level which can be dynamically controlled.
+LOG_LEVEL=DEBUG
+# The default level for filtered logs.
+LOG_NAMES_DEFAULT_LEVEL=INFO
+# Per level overrides for filtered logs.
+LOG_NAMES_DEBUG=MySubscriber
+```
+
+* Customised log names are available for each level e.g. `LOG_NAMES_TRACE`
+* Log names are matched on prefix.
+* Multiple log names are supported via comma separated values.
+
+### Changing log level dynamically
+
+The default level for filtered logs (`LOG_NAMES_DEFAULT_LEVEL`) may be changed on a running instance with the `WINCH`
+signal. This cycles through the available levels `[trace debug info warn error fatal]`.
+
+Note that you cannot dynamically enable a level lower than the `LOG_LEVEL`. Instead the env var must be adjusted and the
+instance restarted.
+
+Send signal: `pkill --signal WINCH --count --full "^puma.*"`
+
+Instance output: `WINCH signal changed LOG_NAMES_DEFAULT_LEVEL from debug to info`
+
+### Querying current log level
+
+The `SYS` signal will print the levels used by the running instance.
+
+Send signal: `pkill --signal SYS --count --full "^puma.*"`
+
+Instance output: `SYS signal reports LOG_LEVEL=debug LOG_NAMES_DEFAULT_LEVEL=warn`
 
 ### Sending metrics