Lib.rs

An enhanced command line logging utility.

Key Features

The stumpless logger aims to be a replacement for and improvement over the traditional logger utility. It is written with Rust and Stumpless, and offers a number of improvements over legacy tools, including:

• more logging target options (files, Windows Event Log)
• log to multiple destinations with a single invocation
• portable and tested on Windows and Linux
• separate thread for each log target

Send Your Logs Anywhere

The stumpless logger supports all of the target types that Stumpless provides, which include everything logger has and then some.

The Default Target

Stumpless has the concept of a default target, which attempts to abstract away the most logical place to send logs on your system. For Windows this is the Windows Event Log in a log named Stumpless, for Linux and Mac systems this is /var/run/syslog or /dev/log, and if all else fails this is a file named stumpless-default.log. If you don't provide an explicit target to stumpless, this is what it will send logs to.

stumpless Send it!
# where this goes depends on your system!

You can explicitly send logs to the default target if you want to, for example if you need to send to other locations as well as this one, using the --default option like this:

stumpless --default Send it!
# same as before!

stdout and stderr

If you just want to print logs, then use the stdout or stderr.

stumpless --stdout Hello from Stumpless!
# <13>1 2023-01-01T19:32:19.802953Z dante stumpless-cli - - - Hello from Stumpless!

stumpless --stderr Stumpless says something went wrong...
# <13>1 2023-01-01T19:33:08.957079Z dante stumpless-cli - - - Stumpless says something went wrong...

Files

Stumpless provides an easy way to write logs to files without going through a syslog daemon or abusing stream redirection. The --log-file flag lets you specify a file to send logs to, with the predictable choice of -l as the short option.

stumpless --log-file round.log Everything is a file these days

cat round.log
# <13>1 2023-01-19T02:20:22.984425Z dante stumpless-cli - - - Everything is a file these days

If you want to write log entries into more than one file, you can just specify this flag multiple times. This is true for most log targets in stumpless, and means that it's simple to send messages to a variety of diverse locations straight from a shell. Each different log target is handled in its own thread to prevent them from blocking one another.

stumpless --log-file square.log --log-file triangle.log You get a message, and you get a message!

# note that the timestamp is slightly different in these two messages
cat square.log
# <13>1 2023-01-22T01:35:07.112856Z dante stumpless-cli - - - You get a message, and you get a message!

cat triangle.log
# <13>1 2023-01-22T01:35:07.112963Z dante stumpless-cli - - - You get a message, and you get a message!

Network

Sending logs to network servers is a common task. Stumpless supports this with the network feature, which is enabled by default. This supports both IPv4 and IPv6, for both TCP and UDP. You can specify these with the --tcp4, --udp4, --tcp6, and --udp6 options.

stumpless --tcp4 one-log-server.example Send this message over TCP on IPv4.

stumpless --udp6 two-log-server.example Send this message over UDP on IPv6.

# of course, you can send multiple messages at once, as with other target types:
stumpless --tcp6 red-log-server.example \
          --udp4 blue-log-server.example \
          Send this message to two servers at once!

By default, these targets use port 514. If you want to use a different port, then use the --port option (or -P short option) to customize this.

stumpless --tcp4 special-snowflake-1.example --port 7777
          --udp6 special-snowflake-2.exampel --port 8888
          This message goes to two servers on different ports!

Sockets

If you want to send messages to Unix sockets (such as the traditional /dev/log), then you can use --socket, or -u for short (think 'u' for Unix). You'll note that this is the same option as logger uses.

stumpless --socket /dev/log Say hello to the daemon for me

Socket logging is only available in builds where the socket feature has been enabled.

Journald

Of course, stumpless can log to systemd's journaling service if desired. This uses the same --journald option that logger users may already be familiar with.

stumpless --journald Send this message to the local journald service.

Journald logging is only available in builds where the journald feature has been enabled.

Windows Event Logs

On machines where a Windows Event Log is present, you can send messages to it as well. By default this will go to an application log named "Stumpless", but you change this if you want.

stumpless --windows-event-log This will go into the Stumpless Application log.

# if you have your own special log, you can send to that instead
stumpless --windows-event-log=MySpecialLog This is a message for my own special log.

Note that logs don't show up for applications that aren't configured, including the default Stumpless log. If you just want to install the default and use it this way, you can run stumpless with the --install-wel-default-source option to do this. You can run this by itself if you want to install. Note that this requires enough privileges to make registry changes. It will also point registry entries it creates at the stumpless executable for resources it needs, so don't do this until you have stumpless in a place where you plan to leave it.

# makes registry entries to install the Stumpless application log
# these will point at stumpless.exe, so make sure it's where you want it!
# and that it is in a place that Event Viewer has permissions, if you intend to
# browse the logs through that application
stumpless --install-wel-default-source

Windows Event Logging is only available in builds where the wel feature has been enabled.

Structured Data

Log entries can often be made easier to parse by using structured data fields. You can add these with the same options as logger uses: --sd-id adds an element, and any --sd-param after this adds more detailed fields to the element. This is easier to understand with some examples:

# Note that, as with logger, the quotes are required, and may need to be escaped
# for your shell. For bash or cmd.exe this might instead be color=\"red\", for
#PowerShell color='\"red\"', and so on.
stumpless --stdout --sd-id ball --sd-param color="red" --sd-param size="medium" Caught a ball!
# <13>1 2023-01-28T02:34:50.127Z Angus stumpless-cli - - [ball color="red" size="medium"] Caught a ball!

stumpless --stdout \
          --sd-id breadsticks \
          --sd-id mainCourse --sd-param meat="beef" --sd-param side="potatoes" \
          --sd-id dessert --sd-param type="cake" \
          Ate a feast!
# <13>1 2023-01-28T18:53:14.721851Z dante stumpless-cli - - [breadsticks][mainCourse meat="beef" side="potatoes"][dessert type="cake"] Ate a feast!

Differences Between stumpless and logger

This tool is not written as a drop-in replacement for other logger implementations. This is not to say that it is completely different: most of the options are the same, and the general modes of use are the same. But there are differences that arise from decisions made for simplicity, performance, or necessity. Here are the deviations that are relevant to you if you're already familiar with or using other loggers.

• The default output with no arguments is determined by the default target of the underlying stumpless build instead of /dev/log.
• The time quality structured data element is not included (pending Stumpless implementation of this feature).
• Network servers IP version and protocol are specified together such as --tcp4 rather than separately via -T or -d flags independent of the -n flag. This is to support the specification of multiple targets using different combinations in a single invocation.
• The following flags/modes of operation are not supported:
  • --rfc3164 for the RFC 3164 BSD syslog format of messages