Introduction to Sawmill

Sawmill provides mechanisms to generate structured logging and diagnostic information based on events. When working with large and complex systems, such as multi-threaded and asynchronous code, traditional logging systems fail at appropriately maintaining structure, causality, and temporality of events.

Concepts

Sawmill provides two over-arching constructs, slices and events. The information then generated by them is then optionally fed to a collector.

Slices

In order to record the flow of execution through a program, Sawmill has the concept of a slice. Unlike a traditional log message which represents a single moment in time, a slice represents a span of time, with a beginning and an end. When a program starts execution or begins a unit of work, it enters the slice, and when it is completed, it exits the slice. The current slice is the one which is most recently entered for the current thread of execution.

/* Create a new slice context */
const auto slice = sawmill::slice{sawmill::Level::Info, "example slice"sv};

/* Do some work */

/* Slice is automatically exited when it goes out of scope, or slice.leave() is called */
/*...*/

The association of slices can be thought of either a tree, or a directed graph of slice causality.

For more documentation and information, see the slice documentation.

Events

To represent a single moment in time, sawmill has the concept of events. It indicates that something happened while a trace was being collected. An event can be compared to a traditional log record, but have the added benefit of being associated with the the slice that it occurred in. However an event can occur outside of a slice as well. In general though to make the most use of events, they should be associated with a slice.

/* Generate and record an event unrelated to any slice */
sawmill::event(sawmill::Level::Trace, "uwu");

/* Create a slice and record an event to be associated with that slice */
const auto slice = sawmill::slice{sawmill::Level::Debug, "some_work"};
const auto _sentinel = slice.enter();

sawmill::event(sawmill::Level::Info, 2);

For more documentation and information, see the event documentation.

Collectors

When slices and events occur, the information generated by them is sent to a collector. The collectors are notified when an event occurs, and when slices enter and exit.

Todo

More details on collectors.

For more documentation and information, see the collector documentation.

Recording Slices and Events

Todo

Fill out with more details.

Slices

Todo

See above.

Events

Todo

See above.