initial logger docs

Lua-Examples.md

@@ -2,6 +2,34 @@
 
 By default Inbucket will load `inbucket.lua`, but you may use the `INBUCKET_LUA_PATH` environment variable to change that.
 
+## Logging
+
+Inbucket allows Lua scripts to write log entries via the built-in `logger` package -- API provided by [loguago](https://github.com/cosmotek/loguago).
+
+Each logging call must include a level.  Only log entries greater than or equal to global `INBUCKET_LOGLEVEL` environment variable will be output.   In order of least to most severe, the available log levels are: `debug`, `info`, `warn`, and `error`.  Inbucket will output the level `info` and higher by default.
+
+Usage: `logger.<level>(message, fields)`
+
+The first parameter is the log message; you may use Lua's `string.format` to interpolate values into the message, if needed.  The second parameter is a table of fields that will be included in the log entry JSON data.  While you are not required to add fields, the current API requires at least an empty table parameter.
+
+```lua
+local logger = require("logger")
+
+-- The following functions all have the same signature but different names to
+-- allow for log leveling.
+logger.debug("message at debug level", {})
+logger.info("message at info level", {})
+logger.warn("message at warn level", {})
+logger.error("message at error level", {})
+
+-- Example with formatting and fields.
+local orig_addr = "input@example.com"
+local new_addr = "output@example.com"
+
+logger.info(string.format("Mapping address to %q", new_addr), {address = orig_addr})
+```
+
+
 ## Event trigger: before mail accepted
 
 This event fires when Inbucket is evaluating an SMTP "MAIL FROM" command.