tracing-indicatif

tracing-indicatif provides several capabilities for managing CLI progress:

• Customizable Styles: Use the standard indicatif::ProgressStyle API to customize the appearance of your progress bars.
• Hierarchical Spans: Supports displaying parent-child relationships between progress bars, mirroring the structure of your tracing spans.
• Display Limits: You can limit the number of progress bars visible on the terminal at once.
• Log Protection: Prevents progress bars from clobbering (interfering with) your tracing logs.

tracing-indicatif is a tracing layer designed to automatically create and manage indicatif progress bars for active spans.

Instead of manually managing progress bar instances within your library code—which can be invasive and difficult to track—you can tie progress bars directly to tracing spans. This allows you to enable a smooth progress bar experience for your CLI with minimal code changes (as few as 3 lines) if you are already using tracing spans.

IndicatifWriter is a wrapper around std::io::stdout() or std::io::stderr() designed to ensure that tracing log entries do not clobber active indicatif progress bars. It achieves this by calling MultiProgress::suspend whenever a write occurs, temporarily hiding the progress bars so the log line can be printed cleanly.

While you can construct one manually using IndicatifWriter::new(mp), it is highly recommended to use the helper methods provided by IndicatifLayer (e.g., get_stderr_writer or get_stdout_writer) to ensure the writer is correctly integrated with your existing tracing subscriber.

// Recommended usage pattern (via IndicatifLayer):
// let writer = indicatif_layer.get_stderr_writer();

// Manual construction (less recommended):
// let writer = IndicatifWriter::<Stderr>::new(multi_progress_instance);

The IndicatifLayer automatically manages indicatif progress bars by tying them to the lifetime of tracing spans.

• Lifecycle: A progress bar is started the first time a span is entered (or when one of its child spans is entered) and is finished when the span is closed (after all child spans have closed).
• Display: Progress bars are emitted to stderr by default. The layer uses indicatif::MultiProgress under the hood to manage multiple active bars.
• Filtering: The layer itself performs no filtering. You should attach tracing_subscriber filters to the layer to control which spans trigger progress bars.
• Hierarchy: The layer supports nested spans, using indentation and symbols to denote the hierarchy in the terminal.

To enable progress bars for your CLI using tracing-indicatif, create an IndicatifLayer and register it with your tracing_subscriber. It is highly recommended to pass indicatif_layer.get_stderr_writer() (or get_stdout_writer()) to your fmt::layer() to prevent progress bars from being clobbered by log output.

use tracing_indicatif::IndicatifLayer;
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

let indicatif_layer = IndicatifLayer::new();

tracing_subscriber::registry()
    .with(tracing_subscriber::fmt::layer().with_writer(indicatif_layer.get_stderr_writer()))
    .with(indicatif_layer)
    .init();

You can customize the IndicatifLayer using a builder-like pattern before registering it with your subscriber:

• with_span_field_formatter(formatter): Set a custom formatter for span fields (used in the span_fields template key).
• with_progress_style(style): Override the indicatif::ProgressStyle used for bars. Available keys: span_fields, span_name, and span_child_prefix.
• with_span_child_prefix_indent(indent): Set the string used for indentation of child spans.
• with_span_child_prefix_symbol(symbol): Set the symbol (e.g., ↳ ) used to denote child spans.
• with_max_progress_bars(max, footer_style): Limit the number of visible bars. If exceeded, a footer showing pending_progress_bars is displayed.
• with_tick_settings(tick_settings): Configure how often bars are redrawn.

The suspend_tracing_indicatif function allows you to execute a closure while the progress bars are temporarily hidden. This is useful for performing operations that need to print directly to the terminal without the indicatif management interfering.

WARNING: This holds an internal lock within MultiProgress. Calling writeln!(get_indicatif_stderr_writer(), ...) or calling suspend_tracing_indicatif recursively inside the closure will result in a deadlock.

suspend_tracing_indicatif(|| {
    // Code here runs while progress bars are suspended
});

These macros allow you to print to stdout or stderr without interfering with the progress bars managed by IndicatifLayer.

• indicatif_println!(...): Prints to stdout using the IndicatifLayer's stdout writer if available.
• indicatif_eprintln!(...): Prints to stderr using the IndicatifLayer's stderr writer if available.

WARNING: Do not call these macros inside a suspend_tracing_indicatif block, as this will cause a deadlock.

When using IndicatifFilter to control progress bars via span fields, those fields (indicatif.pb_show and indicatif.pb_hide) will appear in your log output by default. To keep your logs clean, use hide_indicatif_span_fields to wrap your field formatter. This function returns a FilteredFormatFields that ignores these specific control fields.

use tracing_indicatif::filter::hide_indicatif_span_fields;
use tracing_subscriber::fmt::format::DefaultFields;

// Wrap your existing formatter to hide the control fields
let formatter = hide_indicatif_span_fields(DefaultFields::new());