syslog-tracing

Introduction

syslog-tracing is a Rust workspace containing the crate tracing-rfc-5424 (along with a test crate). tracing-rfc-5424 is a tracing-subscriber Layer implementation that sends tracing Events to a syslog daemon.

tracing is a “scoped, structured logging and diagnostics system”. It provides a superset of the features offered by logging crates such as fern and log4rs particularly suited to asynchronous programming. Of particular interest is that it makes a very clear distinction between producers of events & their consumers (Subscribers, in tracing parlance); so much so that the tracing crate provides no support for consuming events, other than the definition of the Subscriber trait.

The tracing-subscriber crate (also part of the Tokio project) provides a few basic implementations along with “utilities for implementing and composing tracing subscribers.” A key notion introduced by this crate is the idea of a Layer. “Unlike Subscribers, which implement a complete strategy for how trace data is collected, Layers provide modular implementations of specific behaviors.” The concern here is that, in general, a consumer of tracing event data may want to do various things at the same time with that data: write it to a log file, just write it to stdout, shuttle it off to a log collection daemon, produce metrics based on it, and so on.

This could easily give rise to a geometric explosion in types: LogFile, LogFileWithStdout, LogFileWithLogStash, LogFileWithLogStashAndStdout, and so forth. The idea behind Layers is to decompose each facet of event handling into its own type, and then “stack them up” in a Subscriber as the application developer desires. In a sense, this design pattern is reminiscent of Alexandrescu’s concept of traits classes in C++– a way of decomposing functionality into orthogonal facets and composing them linearly rather than geometrically.

tracing-rfc-5424 provides a Layer implementation that will format tracing Events (& someday soon Spans) for syslog & send them to a syslog daemon. Both RFCs 3164 (BSD syslog) and 5424 are supported. Internet & Unix domain sockets are supported for transport, both in their datagram & stream flavors.

License

syslog-tracing is released under the GPL v3.0.

Prerequisites

Other than tracing and a syslog daemon, none. tracing-rfc-5424 was developed against rust 1.58.1, although tracing requires 1.49.

Usage

To add tracing-rfc-5424 to your crate, say cargo add tracing-rfc-5424, or add it directly to your Cargo.toml:

[dependencies]
tracing-rfc-5424 = "0.1.0"

Examples

To talk to a local syslog daemon over UDP:

use tracing::info;
use tracing_rfc_5424::{
    layer::Layer, rfc5424::Rfc5424, tracing::TrivialTracingFormatter, transport::UdpTransport,
};
use tracing_subscriber::{
    layer::SubscriberExt, // Needed to get `with()`
    registry::Registry,
};

// Setup the subsriber...
let subscriber = Registry::default()
    .with(Layer::<Layer::<tracing_subscriber::Registry, Rfc5424, TrivialTracingFormatter, UdpTransport>::try_default().unwrap());
// and install it.
let _guard = tracing::subscriber::set_default(subscriber);

info!("Hello, world!");
// Will produce a syslog line something like:
// Jun 23 16:10:55 my-host my-app[pid] Hello, world!

To talk to a local Unix socket:

use tracing::info;
use tracing_rfc_5424::{rfc3164::Rfc3164, tracing::TrivialTracingFormatter, transport::UnixSocket};
use tracing_subscriber::{
    layer::SubscriberExt, // Needed to get `with()`
    registry::Registry,
};

  // Setup the subsriber...
let subscriber = subscriber
    .with(tracing_rfc_5424::layer::Layer::<Layer::<tracing_subscriber::Registry, Rfc3164, TrivialTracingFormatter, UnixSocket>::try_default().unwrap());
// and install it.
let _guard = tracing::subscriber::set_default(subscriber);

info!("Hello, world!");

Hacking

cargo install rusty-tags
git clone git@github.com:sp1ff/syslog-tracing.git
cd syslog-tracing
make all doc check

Status, Rationale and Roadmap

This is a preliminary release; the version number (0.1.x) is intended to convey that. Additional features to be implemented:

more testing
more support for mapping from tracing primitives (=Event=s & =Span=s) to syslog messages (today, the crate simply uses the “message” field in Events while ignoring Spans)
async transport abstractions
more documentation
supporting MSGID for RFC 5424 formatting
support structured data for RFC 5424 formatting
Windows support
and many, many more (maybe I’ll start opening issues to track ‘em)

The name tracing-syslog seemed most natural to me, but had been already claimed (by an empty project) on crates.io. I’ve reached out to the author, but haven’t heard anything back. I moved on to syslog-tracing, but before I published the crate, that was claimed, too (by an implementation with a very different implementation approach– FFI straight to the libc syslog API). I wound-up re-factoring the repo into a library package & a test package and I’ve taken the opportunity to rename the library crate to tracing-rfc-5424 (after the RFC governing the modern syslog message format).

Bugs, comments, problems, criticism, PRs, feature requests &c welcome at sp1ff@pobox.com and in the issues.

kriomant / syslog-tracing