flog

flog is a command-line tool for sending log messages to Apple's unified logging system and is primarily intended for use in scripts.

---

Rationale

Why not use logger(1)?

logger doesn't support the full set of log levels offered by Apple's unified logging system, and it lacks support for subsystem and category strings. flog uses the C language APIs for the unified logging system and supports both.

Installation

Install with Homebrew:

brew install marcransome/tap/flog

Logging messages

To log a message using the default log level:

flog '<message>'

Optionally specify a subsystem and category using the -s, --subsystem and -c, --category options:

flog -s uk.co.fidgetbox -c general 'informational message'

Override the default log level using the -l, --level option and one of the values info, debug, error or fault:

flog -l fault -s uk.co.fidgetbox -c general 'unrecoverable failure'

flog can also read the log message from the standard input stream using a pipe:

./some-script | flog -l info

Or the log message can be read from a file using shell redirection:

flog < /var/log/some-script.log

Use the -a, --append option to also append the log message to a file (creating the file if necessary):

flog -a /var/log/some-script.log -l fault -s uk.co.fidgetbox -c general 'unrecoverable failure'

Warning

Log message strings are public by default and can be read using the log(1) command or Console app. To mark a message as private add the -p|--private option to the command. Doing so will redact the message string, which will be shown as '<private>' when accessed using the methods previously mentioned. Device Management Profiles can be used to grant access to private log messages.

Reading log messages

Refer to the log(1) man page provided on macOS-based systems for extensive documentation on how to access system wide log messages, or alternatively use the Console app.

Here's an example log stream in Console, filtered by subsystem name, showing messages generated by flog:

And here's a similar log stream viewed with Apple's log(1) command:

Option Aliasing

flog supports option aliasing (via the libpopt library). An alias is an arbitrary name which expands to one or more command-line options, making repeat operations less verbose and allowing for sets of options to be grouped contextually by name.

For example, the --runtime-failure alias below expands to the command-line options -l fault -s uk.co.fidgetbox.server -c runtime:

$ flog --runtime-failure "Expected a numeric value to be provided"

User-defined aliases can be added to the files /etc/popt and $HOME/.popt, both of which can contain an arbitrary number of aliases. Each alias should be formatted as:

uk.co.fidgetbox.flog alias <alias-name> <options>

For the previous example, the entry would read:

uk.co.fidgetbox.flog alias --runtime--failure -l fault -s uk.co.fidgetbox.server -c runtime

Development

flog is written in C and requires a suitable compiler and additional tools to build from source. The just command runner is used to manage the development and release process, which functions in a similar manner to make. For an overview of the available recipes and their usage run just --list.

Requirements

• macOS 11.x (Big Sur) or later
• A C17 compiler
• CMake version >=3.22
• The just command runner
• pkg-config version >=0.29.2
• libpopt version >=1.19
• libcmocka version >=1.1.7
• Pandoc (if building the man page)

Building from source

To perform a development build from the project directory:

just build

The resulting flog binary will be output to a build/debug/bin directory and test targets to build/debug/test.

Running unit tests

To build and execute all test targets:

just test

Alternatively, invoke individual test targets directly from the build/debug/test directory. All test target files begin with the prefix test_ followed by the name of the source file under test.

Building the man page

To build the man page:

just man

The flog.1 man page is output to the man directory and is converted from the source file man/flog.1.md using Pandoc.

Acknowledgements

• Trunk icon made by Freepik from www.flaticon.com

License

flog is provided under the terms of the MIT License.

Contact

Email me at [email protected] or create an issue.