Getting Started

Step 1: 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.

Step 2: Configuring a repository

Warning

Ensure your code is backed up (e.g. committed to a git repository) before running Breadlog.

Create a file called Breadlog.yaml in the root of your repository.
Set the file contents as follows:
```
---
source_dir: <RELATIVE SOURCE DIRECTORY>
rust:
  structured: false
  log_macros:
    - module: log
      name: info
    - module: log
      name: warn
    - module: log
      name: error
```
Replace <RELATIVE SOURCE DIRECTORY> above with the path to the source code you want Breadlog to analyse, relative to the repository root.

For example, if your code was in a directory called my_app/, then you would set source_dir to ./my_app.

This configuration assumes you’re using the Rust log crate for logging in your code.

If you’re using structured logging (the “kv” feature), set structured to true and Breadlog will maintain references as key-value pairs rather than message text.

Step 3: Running Breadlog for the first time

When running Breadlog for the first time, start by running it in check mode.

In check mode, Breadlog won’t modify your code. Instead it’ll just report where there are missing references (numbers uniquely identifying log statements) within your code.

This is also useful in CI pipelines, allowing you to fail a build if someone has forgotten to use Breadlog before pushing changes. Breadlog’s exit code will be non-zero if it finds missing references in check mode.

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

Run Breadlog in check mode using the --check flag:

breadlog -c ./Breadlog.yaml --check

You’ll see output similar to the following:

2023-11-21T10:34:26.943Z INFO [breadlog] [ref: 22] Reading configuration file: ./Breadlog.yaml
2023-11-21T10:34:26.943Z INFO [breadlog] [ref: 25] Configuration loaded!
2023-11-21T10:34:26.943Z INFO [breadlog] [ref: 27] Running in check mode
2023-11-21T10:34:26.945Z INFO [breadlog::codegen::generate] [ref: 15] Found 280 file(s)
...
2023-11-21T10:34:29.872Z INFO [breadlog::codegen::generate] [ref: 6] Total missing references in ././core/http/src/status.rs: 0
2023-11-21T10:34:29.880Z INFO [breadlog::codegen::generate] [ref: 6] Total missing references in ././core/http/src/lib.rs: 0
2023-11-21T10:34:29.921Z WARN [breadlog::codegen::generate] [ref: 5] Missing reference in file ././core/http/src/listener.rs, line 178, column 36
2023-11-21T10:34:29.921Z WARN [breadlog::codegen::generate] [ref: 5] Missing reference in file ././core/http/src/listener.rs, line 186, column 32
2023-11-21T10:34:29.921Z WARN [breadlog::codegen::generate] [ref: 5] Missing reference in file ././core/http/src/listener.rs, line 189, column 32
2023-11-21T10:34:29.921Z INFO [breadlog::codegen::generate] [ref: 6] Total missing references in ././core/http/src/listener.rs: 3
...
2023-11-21T10:34:34.987Z INFO [breadlog::codegen::generate] [ref: 7] Total missing references (all files): 46
2023-11-21T10:34:34.987Z ERROR [breadlog] [ref: 28] Failed: One or more missing references were found

The locations Breadlog reports missing references are where it will insert references when run in edit mode (when you omit the --check flag).

If you’d like Breadlog to ignore a particular log statement, add a comment to the line before the statement with the text breadlog:ignore. For more details, see Directives.

Once you’re happy with the output, you can run Breadlog in edit mode (without the --check flag). This will modify your code, inserting references in log statements where they are found to be missing:
```
breadlog -c ./Breadlog.yaml
```
Assuming you’re happy with the changes Breadlog has made, commit them to your repository along with the Breadlog.yaml and Breadlog.lock files.

Next steps

Read the other sections in this user guide (it’s not very long!) to learn more about configuration options, using Breadlog from CI pipelines, known limitations and more.