https://github.com/jamesmistry/breadlog
Maintain unique references to log messages in source code.
https://github.com/jamesmistry/breadlog
code diagnostics logging logging-and-metrics security-audit security-automation security-tools source-code troubleshooting
Last synced: 7 days ago
JSON representation
Maintain unique references to log messages in source code.
- Host: GitHub
- URL: https://github.com/jamesmistry/breadlog
- Owner: jamesmistry
- License: mit
- Created: 2022-07-24T13:48:29.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-12-09T21:57:43.000Z (about 1 year ago)
- Last Synced: 2024-12-09T22:34:49.040Z (about 1 year ago)
- Topics: code, diagnostics, logging, logging-and-metrics, security-audit, security-automation, security-tools, source-code, troubleshooting
- Language: Rust
- Homepage:
- Size: 1.19 MB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Breadlog
For documentation about using Breadlog, see the [User Guide](https://breadlog.readthedocs.io/en/stable/).
## 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:
```bash
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:
```bash
breadlog --version
```
If you'd like to install a specific version of Breadlog, go to the
[list of Breadlog releases](https://github.com/jamesmistry/breadlog/releases).
See the [User Guide](https://breadlog.readthedocs.io/en/stable/) for how to get started.
## Using Breadlog
See the [User Guide](https://breadlog.readthedocs.io/en/stable/).
## 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](https://www.rust-lang.org/tools/install).
- Install the Rust nightly toolchain:
```bash
rustup toolchain install nightly
```
- (Optional) Install `rustfmt` and `clippy` (used for code formatting and
static analysis, respectively):
```bash
rustup update && rustup component add rustfmt clippy
```
- (Optional) Install `cargo-fuzz` (used for fuzz testing):
```bash
cargo install cargo-fuzz
```
### Building using Cargo
Breadlog currently requires nightly Rust features.
1. Clone the repository and change your working directory:
```bash
git clone git@github.com:jamesmistry/breadlog.git && cd breadlog
```
2. Make sure the toolchain is up-to-date:
```bash
rustup update nightly
```
3. Build using Cargo:
```bash
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:
```bash
pip3 install -U sphinx sphinx_rtd_theme
```
2. From the repository root run the following command where `` is
the directory to write the generated HTML:
```bash
sphinx-build -M html docs/
```
### Running tests
*All commands below are to be run from the repository root.*
- Run the test suite:
```bash
cargo test
```
- Start a fuzz test:
```bash
cargo fuzz run fuzz_rust_parser
```
- Run the code format check:
```bash
cargo +nightly fmt -- --check --config-path ./
```
- Run the linter:
```bash
cargo clippy -- -D warnings
```