Fast, composable structured and unstructured logging for Go

log.
  Tags("data", "trace").
  Data(
    log.String("SomeKey", "some value"),
    log.Int("SomeOtherKey", 123),
    log.Private.String("SomePrivateKey", "a value"),
  ).
  Trace("trace msg")

log.
  Tags("data", "debug").
  Data(
    log.String("SomeKey", "some value"),
    log.Int("SomeOtherKey", 123),
    log.Bool("SomeBool", true),
  ).
  Debugd()

log.Info("info message")

log.
  JSON.
  Tags("data", "warn").
  Data(
    log.String("SomeKey", "some value"),
    log.Int("SomeOtherKey", 123),
    log.Bool("SomeBool", true),
  ).
  Warn("warn message")

log.Errorf("error %s", "message")

log.
  Tags("fatal").
  Fatal("fatal msg")

The logger can be controlled using environment variables. The following is a list of all configuration options.

Log output can be filtered through level filtering and tag filtering. The filters are applied in sequence, that is, if a message has been excluded from the output from the level filter, it won't even be processed by tag filtering. Tag filtering will be performed only if the message passed through the level filtering and is going to be included into the output up to this point.

Filters applied can be configured through the LOG_FILTERS applied. Setting this variable to _none removes all sorts of filtering. This means all the messages will be written to the log output, but also none of the filtering code will be executed. This could be a valuable performance improvement in a production setting.

Alternatively, filters will be applied in the order they are specified in the LOG_FILTERS variable, separated by a comma, similar to a pipeline. The following example demonstrates the usage:

• level,tag will execute first the level filtering (which is lighter on resources) and then the tag filtering
• level will only execute level filtering
• tag,level will execute the tag filtering (heavier on resources) and then the level filtering
• tag will execute only tag filtering

The default value, when the variable is unset, is level,tag.

Levels are incremental. Each level is greater than the previous one, according to the following sequence:

• trace
• debug
• info
• warn
• error
• fatal

LOG_LEVEL configuration helps filtering which messages will be written. Setting LOG_LEVEL to a specific level will ensure that any message with a level lower than the selected one, will be omitted.

If the level is set to info, all messages of info level or above will be written.

_none will ensure no messages are going to be witten, _all and _min are equivalent to trace, while _max is equivalent to fatal

Tag filtering allows finer-grained control of messages included or excluded from the log output.

Setting LOG_TAGS to _all will ensure no message is excluded from the output due to tag filtering. When LOG_TAGS is set to _all.

If LOG_TAGS is not set to _all, it should contain a list of tags separated by comma. If the message has at least one of the tags listed in LOG_TAGS, it will be included in the output. A tag can be prefixed with a modifier, which is either + or -.

A tag prefixed with + must be present on the message. If multiple tags are prefixed with + they must all be present on the message. That means that a message must have every tag prefixed with a + and at least one unprefixed tag (if any present in LOG_TAGS).

If a tag is prefixed with -, it must be absent from the list of tags of the message.

Every untagged message (a message with no tags) is excluded from the output unless the keyword _untagged is present in the tag list.

A message to be included in the output must satisfy all the following conditions:

• Have at least one of: foo or tag1
• Have both: bar and baz

Alternatively the message could be untagged and it will be included in the output

A message to be included in the output must satisfy all the following conditions:

• Have at least one of: foo or tag1
• Have: bar
• Not have: baz

Requirements:

• bash version >= 5.0.0
• sed version >= 4.5.0