From 1c3f37b4b4c5090efcb5af456306f46a5b732af6 Mon Sep 17 00:00:00 2001 From: James Hillyerd Date: Mon, 13 Nov 2023 13:47:58 -0800 Subject: [PATCH] initial logger docs --- Lua-Examples.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/Lua-Examples.md b/Lua-Examples.md index 80460fb..05a8449 100644 --- a/Lua-Examples.md +++ b/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.(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.