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.