Crate tracing_indicatif

source
Expand description

A tracing layer that automatically creates and manages indicatif progress bars for active spans.

Progress bars are a great way to make your CLIs feel more responsive. However, adding and managing progress bars in your libraries can be invasive, unergonomic, and difficult to keep track of.

This library aims to make it easy to show progress bars for your CLI by tying progress bars to tracing spans. For CLIs/libraries already using tracing spans, this allow for a dead simple (3 line) code change to enable a smooth progress bar experience for your program. This eliminates having to have code in your libraries to manually manage progress bar instances.

This ends up working quite well as progress bars are fundamentally tracking the lifetime of some “span” (whether that “span” is defined explicitly or implicitly), so might as well make that relationship explicit.

An easy quick start for this crate is:

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

let indicatif_layer = IndicatifLayer::new();

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

See IndicatifLayer for additional documentation.

See the examples folder for examples of how to customize the layer / progress bar appearance.

Note: it is highly recommended you pass indicatif_layer.get_stderr_writer() or indicatif_layer.get_stdout_writer() to your fmt::layer() (depending on where you want to emit tracing logs) to prevent progress bars from clobbering any console logs.

Modules§

  • filter
    Provides a rudimentary filter layer that can be used to selectively enable progress bars on a per-span level.
  • span_ext
    Helpers to modify a progress bar associated with a given span.
  • style
    Re-export of indicatif’s style module for ease of use.
  • util
    Provides some general tracing utilities that are useful for this crate, for example a utility to filter “indicatif.pb_show” and “indicatif.pb_hide” from printing spans.
  • writer
    Helpers to prevent progress bars from clobbering your console output.

Macros§

  • indicatif_eprintln
    Helper macro that allows you to print to stderr without interfering with the progress bars created by tracing-indicatif.
  • indicatif_println
    Helper macro that allows you to print to stdout without interfering with the progress bars created by tracing-indicatif.

Structs§

  • IndicatifLayer
    The layer that handles creating and managing indicatif progress bars for active spans. This layer must be registered with your tracing subscriber to have any effect.
  • IndicatifWriter
    A wrapper around std::io::stdout() or std::io::stderr() to ensure that output to either is not clobbered by active progress bars. This should be passed into tracing fmt’s layer so tracing log entries are not clobbered.
  • TickSettings
    Controls how often progress bars are recalculated and redrawn to the terminal.

Functions§