@@ -53,13 +53,72 @@ pub trait EnteredTraceSpan {}
5353impl EnteredTraceSpan for ( ) { }
5454impl EnteredTraceSpan for tracing:: span:: EnteredSpan { }
5555
56- /// Shortand for calling [crate::interpret::Machine::enter_trace_span] on a [tracing::info_span].
56+ /// Shortand for calling [crate::interpret::Machine::enter_trace_span] on a [tracing::info_span! ].
5757/// This is supposed to be compiled out when [crate::interpret::Machine::enter_trace_span] has the
5858/// default implementation (i.e. when it does not actually enter the span but instead returns `()`).
59+ /// This macro takes a type implementing the [crate::interpret::Machine] trait as its first argument
60+ /// and otherwise accepts the same syntax as [tracing::span!] (see some tips below).
5961/// Note: the result of this macro **must be used** because the span is exited when it's dropped.
62+ ///
63+ /// ### Syntax accepted by this macro
64+ ///
65+ /// The full documentation for the [tracing::span!] syntax can be found at [tracing] under "Using the
66+ /// Macros". A few possibly confusing syntaxes are listed here:
67+ /// ```rust
68+ /// # use rustc_const_eval::enter_trace_span;
69+ /// # type M = rustc_const_eval::const_eval::CompileTimeMachine<'static>;
70+ /// # let my_display_var = String::new();
71+ /// # let my_debug_var = String::new();
72+ /// // logs a span named "hello" with a field named "arg" of value 42 (works only because
73+ /// // 42 implements the tracing::Value trait, otherwise use one of the options below)
74+ /// let _span = enter_trace_span!(M, "hello", arg = 42);
75+ /// // logs a field called "my_display_var" using the Display implementation
76+ /// let _span = enter_trace_span!(M, "hello", %my_display_var);
77+ /// // logs a field called "my_debug_var" using the Debug implementation
78+ /// let _span = enter_trace_span!(M, "hello", ?my_debug_var);
79+ /// ```
80+ ///
81+ /// ### `NAME::SUBNAME` syntax
82+ ///
83+ /// In addition to the syntax accepted by [tracing::span!], this macro optionally allows passing
84+ /// the span name (i.e. the first macro argument) in the form `NAME::SUBNAME` (without quotes) to
85+ /// indicate that the span has name "NAME" (usually the name of the component) and has an additional
86+ /// more specific name "SUBNAME" (usually the function name). The latter is passed to the [tracing]
87+ /// infrastructure as a span field with the name "NAME". This allows not being distracted by
88+ /// subnames when looking at the trace in <https://ui.perfetto.dev>, but when deeper introspection
89+ /// is needed within a component, it's still possible to view the subnames directly in the UI by
90+ /// selecting a span, clicking on the "NAME" argument on the right, and clicking on "Visualize
91+ /// argument values".
92+ /// ```rust
93+ /// # use rustc_const_eval::enter_trace_span;
94+ /// # type M = rustc_const_eval::const_eval::CompileTimeMachine<'static>;
95+ /// // for example, the first will expand to the second
96+ /// let _span = enter_trace_span!(M, borrow_tracker::on_stack_pop, /* ... */);
97+ /// let _span = enter_trace_span!(M, "borrow_tracker", borrow_tracker = "on_stack_pop", /* ... */);
98+ /// ```
99+ ///
100+ /// ### `tracing_separate_thread` parameter
101+ ///
102+ /// This macro was introduced to obtain better traces of Miri without impacting release performance.
103+ /// Miri saves traces using the the `tracing_chrome` `tracing::Layer` so that they can be visualized
104+ /// in <https://ui.perfetto.dev>. To instruct `tracing_chrome` to put some spans on a separate trace
105+ /// thread/line than other spans when viewed in <https://ui.perfetto.dev>, you can pass
106+ /// `tracing_separate_thread = tracing::field::Empty` to the tracing macros. This is useful to
107+ /// separate out spans which just indicate the current step or program frame being processed by the
108+ /// interpreter. You should use a value of [tracing::field::Empty] so that other tracing layers
109+ /// (e.g. the logger) will ignore the `tracing_separate_thread` field. For example:
110+ /// ```rust
111+ /// # use rustc_const_eval::enter_trace_span;
112+ /// # type M = rustc_const_eval::const_eval::CompileTimeMachine<'static>;
113+ /// let _span = enter_trace_span!(M, step::eval_statement, tracing_separate_thread = tracing::field::Empty);
114+ /// ```
60115#[ macro_export]
61116macro_rules! enter_trace_span {
117+ ( $machine: ident, $name: ident :: $subname: ident $( $tt: tt) * ) => { {
118+ $crate:: enter_trace_span!( $machine, stringify!( $name) , $name = %stringify!( $subname) $( $tt) * )
119+ } } ;
120+
62121 ( $machine: ident, $( $tt: tt) * ) => {
63- $machine:: enter_trace_span( || tracing:: info_span!( $( $tt) * ) )
122+ < $machine as $crate :: interpret :: Machine > :: enter_trace_span( || tracing:: info_span!( $( $tt) * ) )
64123 }
65124}
0 commit comments