Breadlog

For documentation about using Breadlog, see the User Guide.

Overview

Breadlog maintains stable, unique references to log messages in your source code.

This helps you identify application events from log messages using a numerical ID that stays the same even when log message content changes. No brittle or complex text parsing required, and no new runtime dependencies needed.

A log statement before Breadlog:

warn!("Bad incoming request: {}", uri);

A log statement after Breadlog:

warn!("[ref: 24] Bad incoming request: {}", uri);

Installing/Upgrading Breadlog

Note

Breadlog only supports Linux on x86-64 at the moment.

Install the latest version of Breadlog with the following command:

curl --proto "=https" -LsSf \
   "https://github.com/jamesmistry/breadlog/releases/latest/download/breadlog-package-linux_x86-64.tar.gz" \
   | sudo tar -xz -C /

Test your installation by running Breadlog:

breadlog --version

If you'd like to install a specific version of Breadlog, go to the list of Breadlog releases.

See the User Guide for how to get started.

Using Breadlog

See the User Guide.

Building Breadlog

Note

Breadlog only supports Linux x86-64 targets at the moment.

Prerequisites

Before building Breadlog, you need to:

• Install the Rust compiler toolchain. Find instructions at rust-lang.org.

• Install the Rust nightly toolchain:

  rustup toolchain install nightly

• (Optional) Install rustfmt and clippy (used for code formatting and static analysis, respectively):

  rustup update && rustup component add rustfmt clippy

• (Optional) Install cargo-fuzz (used for fuzz testing):

  cargo install cargo-fuzz

Building using Cargo

Breadlog currently requires nightly Rust features.

1. Clone the repository and change your working directory:

   git clone git@github.com:jamesmistry/breadlog.git && cd breadlog

2. Make sure the toolchain is up-to-date:

   rustup update nightly

3. Build using Cargo:

   cargo +nightly build

4. Find the Breadlog binary in target/debug/breadlog or target/release/breadlog if creating a release build.

To build the User Guide using Sphinx:

1. Install Sphinx if you haven't already:

   pip3 install -U sphinx sphinx_rtd_theme

2. From the repository root run the following command where <OUTPUT DIR> is the directory to write the generated HTML:

   sphinx-build -M html docs/ <OUTPUT DIR>

Running tests

All commands below are to be run from the repository root.

• Run the test suite:

  cargo test

• Start a fuzz test:

  cargo fuzz run fuzz_rust_parser

• Run the code format check:

  cargo +nightly fmt -- --check --config-path ./

• Run the linter:

  cargo clippy -- -D warnings