An enhanced command line logging utility.
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:
The stumpless logger supports all of the target types that Stumpless provides,
which include everything logger has and then some.
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.
```sh stumpless Send it!
```
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:
```sh stumpless --default Send it!
```
stdout and stderrIf you just want to print logs, then use the stdout or stderr.
```sh stumpless --stdout Hello from Stumpless!
stumpless --stderr Stumpless says something went wrong...
```
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.
```sh stumpless --log-file round.log Everything is a file these days
cat round.log
```
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.
```sh stumpless --log-file square.log --log-file triangle.log You get a message, and you get a message!
cat square.log
cat triangle.log
```
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.
```sh 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.
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.
sh
stumpless --tcp4 special-snowflake-1.example --port 7777
--udp6 special-snowflake-2.exampel --port 8888
This message goes to two servers on different ports!
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.
sh
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.
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.
sh
stumpless --journald Send this message to the local journald service.
Journald logging is only available in builds where the journald feature has
been enabled.
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.
```sh stumpless --windows-event-log This will go into the Stumpless Application log.
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.
```sh
stumpless --install-wel-default-source ```
Windows Event Logging is only available in builds where the wel feature has
been enabled.
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:
```sh
stumpless --stdout --sd-id ball --sd-param color="red" --sd-param 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!
```
stumpless and loggerThis 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.
/dev/log.--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.--rfc3164 for the RFC 3164 BSD syslog format of messages