Read subsystem, category, and log level values from environment

[marcransome]

The problem

Given that flog is primarily intended for use in shell scripts, expressing command arguments for each invocation can lead to repetitive code:

#!/bin/bash

flog -s uk.co.fidgetbox.system -c health -l info 'message'

...

flog -s uk.co.fidgetbox.system -c health -l error 'message'

This is particularly apparent when considering the subsystem and category names¹.

🙄

Proposal

Add support for reading default subsystem, category, and log level values from the shell environment, allowing command-line arguments to override them when provided:

Environment variable	Description
FLOG_CATEGORY	The default category name
FLOG_SUBSYSTEM	The default subsystem name
FLOG_LOG_LEVEL	The default log level

This could reduce the repetitiveness of command arguments significantly:

#!/bin/bash

export FLOG_SUBSYSTEM='uk.co.fidgetbox.system'
export FLOG_CATEGORY='health-check'
export FLOG_LOG_LEVEL='info'
 
if [[ ... ]]; then
    flog 'healthy'
else
    flog -l fault 'unhealthy'
fi

Function-scoped variables (shown here using declare in a bash script) could be used to set the category name and distinguish functional aspects of the script, whilst reducing repetitive command arguments within those functions:

#!/bin/bash

export FLOG_SUBSYSTEM='uk.co.fidgetbox.system'
export FLOG_LOG_LEVEL='info'

function operation() {
    declare -x FLOG_CATEGORY='operation'
    
    flog 'starting operation'

    ...

    if [ ... ]; then
        flog 'operation succeeded'
    else
        flog -l fault 'operation failed'
    fi
}

function another_operation() {
    declare -x FLOG_CATEGORY='another_operation'
    
    flog 'starting another operation'

    ...
}

Footnotes

1. Apple has this to say about subsystem and category naming:

   The subsystem argument should be the identifier of the subsystem in reverse DNS form.
   The category argument should be the category within the subsystem, for differentiating by
   topic and settings.

   Source: os_log_create(3) ↩

[marcransome]

An alternative/additional method of reducing repetitive command arguments might be to leverage option aliasing support provided by the libpopt library, which was recently introduced to the main branch in #47 as a replacement for getopt. This would allow user-defined option aliases as expansions for multiple options. For example, --my-script might be a user-defined alias whose expansion includes a subsystem and category name in the user's .popt configuration file:

# $HOME/.popt
flog alias --my-script -s com.my-domain.my-script -c health

To log a message from a script—or the command-line—using the aliased options configured above:

flog --my-script 'healthy'

Which replaces the more verbose:

flog -s com.my-domain.my-script -c health 'healthy'

[marcransome]

Option aliasing support was added in #71 and released in 1.4.0.