structlog.nvim

Structured Logging for nvim, using Lua

Why using it

structlog makes logging in Lua less painful and more powerful by adding structure to your log entries.

Instead of writting complex messages, you can start thinking in terms of an event that happens in the context of key/value pairs.
Each log entry is a meaningful dictionary instead of an opaque string!

Thanks to its flexible design, the structure of the final log output is up for you to decide.
Each log entry goes through a processor pipeline that is just a chain of functions that receive a dictionary and return a new dictionary that gets fed into the next function. That allows for simple but powerful data manipulation.
This dictionary is then formatted and sent out to the sink.

For more details, consider reading the documentation.

Installation

Using packer.nvim

use { "Tastyep/structlog.nvim" }

Using luarocks

luarocks install --local structlog.nvim

Design

As explained in the introduction, log messages go through a pipeline of functions to provide common information and to structure them into a comprehensible format. Internally, the log message is a dictionary built by the logger and is composed as follow:

  local kwargs = {
    level = Level.name(level), -- The log level represented as a string
    msg = msg,                 -- The given message
    events = events or {},     -- The dictionary containing the 'key=value' arguments
  }

At the end of the processing pipeline, the message msg field should contain the text to write to the sinks.

Processors

Processors are functions with the goal of enriching log messages. These functions accept one parameter, kwargs which they edit by adding new key=value pairs, such as the logger's name or the current timestamp, and return it on completion.

See the processors documentation.

Formatters

Formatters define the structure of the log. By default vim.inspect is used to format the given arguments events as key=value pairs. All formatters have the same interface. They expose a formatting function accepting a dictionary kwargs and return that same dictionary, modified so that kwargs.msg contains the log to write to the sink.

See the formatters documentation.

Sinks

Sinks specify where to write the log message. Like the other elements of the pipeline, sinks accept kwargs as parameter.

See the sunks documentation.

Usage

Create and Use

local log = require("structlog")

local logger = log.Logger("name", {
  log.sinks.Console(
    log.level.INFO
    {
      processors = {
        log.processors.Namer(),
        log.processors.Timestamper("%H:%M:%S"),
      },
      formatter = log.formatters.Format( --
        "%s [%s] %s: %-30s",
        { "timestamp", "level", "logger_name", "msg" }
      ),
    }
  ),
})

logger:info("A log message")
logger:warn("A log message with keyword arguments", { warning = "something happened" })

10:32:40 [INFO] name: A log message
10:32:40 [WARN] name: A log message with keyword arguments     warning="something happened"

Configure and Retrieve

local log = require("structlog")

log.configure({
  name = {
    sinks = {
      log.sinks.Console(
        log.level.INFO,
        {
          processors = {
            log.processors.Namer(),
            log.processors.Timestamper("%H:%M:%S"),
          },
          formatter = log.formatters.Format( --
            "%s [%s] %s: %-30s",
            { "timestamp", "level", "logger_name", "msg" },
          ),
        }
      ),
    },
  },
  other_logger = {...},
})

local logger = log.get_logger("name")

Example

local log = require("structlog")

log.configure({
  name = {
    sinks = {
      log.sinks.Console(
        log.level.INFO,
        {
          processors = {
            log.processors.Namer(),
            log.processors.StackWriter({ "line", "file" }, { max_parents = 0, stack_level = 0 }),
            log.processors.Timestamper("%H:%M:%S"),
          },
          formatter = log.formatters.FormatColorizer( --
            "%s [%s] %s: %-30s",
            { "timestamp", "level", "logger_name", "msg" },
            { level = log.formatters.FormatColorizer.color_level() }
          ),
        }
      ),
      log.sinks.NvimNotify(
        log.level.WARN,
        {
          processors = {
            log.processors.Namer(),
          },
          formatter = log.formatters.Format( --
            "%s",
            { "msg" },
            { blacklist = { "level", "logger_name" } }
          ),
          params_map = { title = "logger_name" },
        }),
      log.sinks.File(
        log.level.TRACE,
        "./test.log",
        {
          processors = {
            log.processors.Namer(),
            log.processors.StackWriter({ "line", "file" }, { max_parents = 3 }),
            log.processors.Timestamper("%H:%M:%S"),
          },
          formatter = log.formatters.Format( --
            "%s [%s] %s: %-30s",
            { "timestamp", "level", "logger_name", "msg" }
          ),
        }
      ),
    },
  },
  -- other_logger = {...}
})

local logger = log.get_logger("name")
logger:info("A log message")
logger:warn("A log message with keyword arguments", { warning = "something happened" })

cat test.log:
10:43:23 [INFO] name: A log message                            file="lua/lsp/null-ls/formatters.lua", line=9
10:43:23 [WARN] name: A log message with keyword arguments     file="lua/lsp/null-ls/formatters.lua", line=10, warning="something happened"

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

Tastyep / structlog.nvim

Programming Languages

Labels

Projects that are alternatives of or similar to structlog.nvim