tracing_indicatif/
span_ext.rs

1//! Helpers to modify a progress bar associated with a given span.
2use indicatif::ProgressStyle;
3use tracing::Span;
4
5use crate::IndicatifSpanContext;
6use crate::WithContext;
7
8// TODO(emersonford): expose stderr/stdout writers in span ext
9
10fn apply_to_indicatif_span(span: &Span, f: impl FnMut(&mut IndicatifSpanContext)) {
11    span.with_subscriber(|(id, subscriber)| {
12        if let Some(get_context) = subscriber.downcast_ref::<WithContext>() {
13            get_context.with_context(subscriber, id, f);
14        }
15    });
16}
17
18/// Utilities to modify the progress bar associated to tracing [`Span`]'s (if one exists).
19///
20/// For example, you can call these on the current Span:
21/// ```
22/// use tracing_indicatif::span_ext::IndicatifSpanExt;
23/// use indicatif::ProgressStyle;
24///
25/// tracing::Span::current().pb_set_style(&ProgressStyle::default_spinner());
26/// ```
27///
28/// NOTE: These methods will silently have no effect if a
29/// [`IndicatifLayer`](crate::IndicatifLayer) was not registered with the tracing subscriber,
30/// or if this span was filtered for the registered `IndicatifLayer`. Because of this behavior, you
31/// can "safely" call these methods inside of non-CLI contexts as these methods will gracefully
32/// do nothing if you have not enabled progress bars for your tracing spans.
33pub trait IndicatifSpanExt {
34    /// Sets the [`ProgressStyle`] of the progress bar associated with this span.
35    ///
36    /// If this span has not yet been entered, this will be the progress style the progress bar for
37    /// this span uses when the span is entered for the first time. If this span has been entered,
38    /// this will update the existing progress bar's style.
39    fn pb_set_style(&self, style: &ProgressStyle);
40
41    /// Briefly enters the span, which starts the progress bar for the span.
42    ///
43    /// Has no effect if the span has already been entered before.
44    fn pb_start(&self);
45
46    /// Sets the length of the progress bar for this span. See
47    /// [`set_length`](indicatif::ProgressBar::set_length).
48    fn pb_set_length(&self, len: u64);
49
50    /// Sets the position of the progress bar for this span. See
51    /// [`set_position`](indicatif::ProgressBar::set_position).
52    ///
53    /// WARNING: you should call [`Self::pb_set_length`] at least once before calling this method, or you
54    /// may see a buggy progress bar.
55    fn pb_set_position(&self, pos: u64);
56
57    /// Increments the position of the progress bar for this span. See
58    /// [`inc`](indicatif::ProgressBar::inc).
59    ///
60    /// WARNING: you should call [`Self::pb_set_length`] at least once before calling this method, or you
61    /// may see a buggy progress bar.
62    fn pb_inc(&self, delta: u64);
63
64    /// Increments the length of the progress bar for this span. See
65    /// [`inc_length`](indicatif::ProgressBar::inc_length).
66    ///
67    /// Has no effect if [`Self::pb_set_length`] has not been called at least once.
68    fn pb_inc_length(&self, delta: u64);
69
70    /// Sets the message of the progress bar for this span. See
71    /// [`set_message`](indicatif::ProgressBar::set_message).
72    fn pb_set_message(&self, msg: &str);
73
74    /// Trigger a recalculation of the progress bar state. See
75    /// [`tick`](indicatif::ProgressBar::tick).
76    ///
77    /// Has no effect if the progress bar for this span is not active.
78    fn pb_tick(&self);
79}
80
81impl IndicatifSpanExt for Span {
82    fn pb_set_style(&self, style: &ProgressStyle) {
83        apply_to_indicatif_span(self, |indicatif_ctx| {
84            // Cloning the `ProgressStyle` is necessary to make this `FnMut` :(
85            indicatif_ctx.set_progress_bar_style(style.clone());
86        });
87    }
88
89    fn pb_start(&self) {
90        let _ = self.enter();
91    }
92
93    fn pb_set_length(&self, len: u64) {
94        apply_to_indicatif_span(self, |indicatif_ctx| {
95            indicatif_ctx.set_progress_bar_length(len);
96        });
97    }
98
99    fn pb_set_position(&self, pos: u64) {
100        apply_to_indicatif_span(self, |indicatif_ctx| {
101            indicatif_ctx.set_progress_bar_position(pos);
102        });
103    }
104
105    fn pb_inc(&self, pos: u64) {
106        apply_to_indicatif_span(self, |indicatif_ctx| {
107            indicatif_ctx.inc_progress_bar_position(pos);
108        });
109    }
110
111    fn pb_inc_length(&self, delta: u64) {
112        apply_to_indicatif_span(self, |indicatif_ctx| {
113            indicatif_ctx.inc_progress_bar_length(delta);
114        });
115    }
116
117    fn pb_set_message(&self, msg: &str) {
118        apply_to_indicatif_span(self, |indicatif_ctx| {
119            indicatif_ctx.set_progress_bar_message(msg.to_string());
120        });
121    }
122
123    fn pb_tick(&self) {
124        apply_to_indicatif_span(self, |indicatif_ctx| {
125            indicatif_ctx.progress_bar_tick();
126        });
127    }
128}
tracing_indicatif/span_ext.rs

tracing_indicatif/
span_ext.rs
