Trace messages

Trace messages explain to the user what problem Lean solved and what steps it took. Think of trace messages like a figure in a paper.

They are shown in the editor as a collapsible tree, usually as [class.name] message ▸. Every trace node has a class name, a message, and an array of children. This module provides the API to produce trace messages, the key entry points are:

• registerTraceClass `class.name registers a trace class
• ``withTraceNode class.name (fun result => return msg) do body produces a trace message containing the trace messages in body as children
• trace[class.name] msg produces a trace message without children

Users can enable trace options for a class using set_option trace.class.name true. This only enables trace messages for the class.name trace class as well as child classes that are explicitly marked as inherited (see registerTraceClass).

Internally, trace messages are stored as MessageData: .trace cls msg #[.trace .., .trace ..]

When writing trace messages, try to follow these guidelines:

1. Expansion progressively increases detail. Each level of expansion (of the trace node in the editor) should reveal more details. For example, the unexpanded node should show the top-level goal. Expanding it should show a list of steps. Expanding one of the steps then shows what happens during that step.
2. One trace message per step. The [trace.class] marker functions as a visual bullet point, making it easy to identify the different steps at a glance.
3. Outcome first. The top-level trace message should already show whether the action failed or succeeded, as opposed to a "success" trace message that comes pages later.
4. Be concise. Keep messages short. Avoid repetitive text. (This is also why the editor plugins abbreviate the common prefixes.)
5. Emoji are concisest. Several helper functions in this module help with a consistent emoji language.
6. Good defaults. Setting set_option trace.Meta.synthInstance true (etc.) should produce great trace messages out-of-the-box, without needing extra options to tweak it.

structure Lean.TraceElem : Type

• ref : Lean.Syntax
• msg : Lean.MessageData

instance Lean.instInhabitedTraceElem : Inhabited Lean.TraceElem

structure Lean.TraceState : Type

• tid : UInt64

  Thread ID, used by trace.profiler.output.

• traces : Lean.PersistentArray Lean.TraceElem

instance Lean.instInhabitedTraceState : Inhabited Lean.TraceState

opaque Lean.inheritedTraceOptions : IO.Ref (Std.HashSet Lean.Name)

class Lean.MonadTrace (m : Type → Type) : Type

• modifyTraceState : (Lean.TraceState → Lean.TraceState) → m Unit
• getTraceState : m Lean.TraceState

instance Lean.instMonadTraceOfMonadLift (m n : Type → Type) [MonadLift m n] [Lean.MonadTrace m] : Lean.MonadTrace n

Equations

• Lean.instMonadTraceOfMonadLift m n = { modifyTraceState := fun (f : Lean.TraceState → Lean.TraceState) => liftM (Lean.modifyTraceState f), getTraceState := liftM Lean.getTraceState }

def Lean.printTraces {m : Type → Type} [Monad m] [Lean.MonadTrace m] [MonadLiftT IO m] : m Unit

def Lean.resetTraceState {m : Type → Type} [Lean.MonadTrace m] : m Unit

def Lean.isTracingEnabledForCore (cls : Lean.Name) (opts : Lean.Options) : BaseIO Bool

def Lean.isTracingEnabledFor {m : Type → Type} [Monad m] [Lean.MonadOptions m] [MonadLiftT IO m] (cls : Lean.Name) : m Bool

@[inline]

def Lean.getTraces {m : Type → Type} [Monad m] [Lean.MonadTrace m] : m (Lean.PersistentArray Lean.TraceElem)

@[inline]

def Lean.modifyTraces {m : Type → Type} [Lean.MonadTrace m] (f : Lean.PersistentArray Lean.TraceElem → Lean.PersistentArray Lean.TraceElem) : m Unit

@[inline]

def Lean.setTraceState {m : Type → Type} [Lean.MonadTrace m] (s : Lean.TraceState) : m Unit

def Lean.addRawTrace {m : Type → Type} [Monad m] [Lean.MonadTrace m] [Lean.MonadRef m] [Lean.AddMessageContext m] (msg : Lean.MessageData) : m Unit

Equations

• Lean.addRawTrace msg = do let ref ← Lean.getRef let msg ← Lean.addMessageContext msg Lean.modifyTraces fun (x : Lean.PersistentArray Lean.TraceElem) => x.push { ref := ref, msg := msg }

def Lean.addTrace {m : Type → Type} [Monad m] [Lean.MonadTrace m] [Lean.MonadRef m] [Lean.AddMessageContext m] (cls : Lean.Name) (msg : Lean.MessageData) : m Unit

Equations

• One or more equations did not get rendered due to their size.

@[inline]

def Lean.trace {m : Type → Type} [Monad m] [Lean.MonadTrace m] [MonadLiftT IO m] [Lean.MonadRef m] [Lean.AddMessageContext m] [Lean.MonadOptions m] (cls : Lean.Name) (msg : Unit → Lean.MessageData) : m Unit

Equations

• Lean.trace cls msg = do let __do_lift ← Lean.isTracingEnabledFor cls if __do_lift = true then Lean.addTrace cls (msg ()) else pure PUnit.unit

@[inline]

def Lean.traceM {m : Type → Type} [Monad m] [Lean.MonadTrace m] [MonadLiftT IO m] [Lean.MonadRef m] [Lean.AddMessageContext m] [Lean.MonadOptions m] (cls : Lean.Name) (mkMsg : m Lean.MessageData) : m Unit

Equations

• Lean.traceM cls mkMsg = do let __do_lift ← Lean.isTracingEnabledFor cls if __do_lift = true then do let msg ← mkMsg Lean.addTrace cls msg else pure PUnit.unit

opaque Lean.trace.profiler : Lean.Option Bool

opaque Lean.trace.profiler.threshold : Lean.Option Nat

opaque Lean.trace.profiler.useHeartbeats : Lean.Option Bool

opaque Lean.trace.profiler.output : Lean.Option String

opaque Lean.trace.profiler.output.pp : Lean.Option Bool

@[inline]

def Lean.trace.profiler.threshold.unitAdjusted (o : Lean.Options) : Float

class Lean.MonadAlwaysExcept (ε : outParam (Type u)) (m : Type u → Type v) : Type (max (u + 1) v)

MonadExcept variant that is expected to catch all exceptions of the given type in case the standard instance doesn't.

In most circumstances, we want to let runtime exceptions during term elaboration bubble up to the command elaborator (see Core.tryCatch). However, in a few cases like building the trace tree, we really need to handle (and then re-throw) every exception lest we end up with a broken tree.

• except : MonadExceptOf ε m

instance Lean.instMonadAlwaysExceptEIO {ε : Type} : Lean.MonadAlwaysExcept ε (EIO ε)

Equations

• Lean.instMonadAlwaysExceptEIO = { except := inferInstance }

instance Lean.instMonadAlwaysExceptStateT {m : Type → Type} [Monad m] {ε σ : Type} [always : Lean.MonadAlwaysExcept ε m] : Lean.MonadAlwaysExcept ε (StateT σ m)

instance Lean.instMonadAlwaysExceptStateRefT' {m : Type → Type} {ε ω σ : Type} [always : Lean.MonadAlwaysExcept ε m] : Lean.MonadAlwaysExcept ε (StateRefT' ω σ m)

Equations

• Lean.instMonadAlwaysExceptStateRefT' = { except := let x := Lean.MonadAlwaysExcept.except; inferInstance }

instance Lean.instMonadAlwaysExceptReaderT {m : Type → Type} {ε ρ : Type} [always : Lean.MonadAlwaysExcept ε m] : Lean.MonadAlwaysExcept ε (ReaderT ρ m)

instance Lean.instMonadAlwaysExceptMonadCacheT {α : Type} {m : Type → Type} {ε ω β : Type} [always : Lean.MonadAlwaysExcept ε m] [STWorld ω m] [BEq α] [Hashable α] : Lean.MonadAlwaysExcept ε (Lean.MonadCacheT α β m)

Equations

• Lean.instMonadAlwaysExceptMonadCacheT = { except := let x := Lean.MonadAlwaysExcept.except; inferInstance }

def Lean.withTraceNode {α : Type} {m : Type → Type} [Monad m] [Lean.MonadTrace m] [MonadLiftT IO m] [Lean.MonadRef m] [Lean.AddMessageContext m] [Lean.MonadOptions m] {ε : Type} [always : Lean.MonadAlwaysExcept ε m] [MonadLiftT BaseIO m] (cls : Lean.Name) (msg : Except ε α → m Lean.MessageData) (k : m α) (collapsed : Bool := true) (tag : String := "") : m α

Equations

• One or more equations did not get rendered due to their size.

def Lean.withTraceNode' {α : Type} {m : Type → Type} [Monad m] [Lean.MonadTrace m] [MonadLiftT IO m] [Lean.MonadRef m] [Lean.AddMessageContext m] [Lean.MonadOptions m] [Lean.MonadAlwaysExcept Lean.Exception m] [MonadLiftT BaseIO m] (cls : Lean.Name) (k : m (α × Lean.MessageData)) (collapsed : Bool := true) (tag : String := "") : m α

Equations

• One or more equations did not get rendered due to their size.

def Lean.registerTraceClass (traceClassName : Lean.Name) (inherited : Bool := false) (ref : Lean.Name := by exact decl_name%) : IO Unit

Registers a trace class.

By default, trace classes are not inherited; that is, set_option trace.foo true does not imply set_option trace.foo.bar true. Calling registerTraceClass `foo.bar (inherited := true) enables this inheritance on an opt-in basis.

def Lean.«doElemTrace[_]__» : Lean.ParserDescr

Equations

• One or more equations did not get rendered due to their size.

def Lean.bombEmoji : String

Equations

• Lean.bombEmoji = "💥️"

def Lean.checkEmoji : String

def Lean.crossEmoji : String

def Lean.exceptBoolEmoji {ε : Type u_1} : Except ε Bool → String

Equations

• Lean.exceptBoolEmoji (Except.error a) = Lean.bombEmoji
• Lean.exceptBoolEmoji (Except.ok true) = Lean.checkEmoji
• Lean.exceptBoolEmoji (Except.ok false) = Lean.crossEmoji

def Lean.exceptOptionEmoji {α : Type} {ε : Type u_1} : Except ε (Option α) → String

Equations

• Lean.exceptOptionEmoji (Except.error a) = Lean.bombEmoji
• Lean.exceptOptionEmoji (Except.ok (some val)) = Lean.checkEmoji
• Lean.exceptOptionEmoji (Except.ok none) = Lean.crossEmoji

def Lean.exceptEmoji {α : Type} {ε : Type u_1} : Except ε α → String

Visualize an Except using a checkmark or a cross.

class Lean.ExceptToEmoji (ε α : Type) : Type

• toEmoji : Except ε α → String

instance Lean.instExceptToEmojiBool {ε : Type} : Lean.ExceptToEmoji ε Bool

instance Lean.instExceptToEmojiOption {α ε : Type} : Lean.ExceptToEmoji ε (Option α)

Equations

• Lean.instExceptToEmojiOption = { toEmoji := Lean.exceptOptionEmoji }

def Lean.withTraceNodeBefore {α : Type} {m : Type → Type} [Monad m] [Lean.MonadTrace m] [MonadLiftT IO m] {ε : Type} [Lean.MonadRef m] [Lean.AddMessageContext m] [Lean.MonadOptions m] [always : Lean.MonadAlwaysExcept ε m] [MonadLiftT BaseIO m] [Lean.ExceptToEmoji ε α] (cls : Lean.Name) (msg : m Lean.MessageData) (k : m α) (collapsed : Bool := true) (tag : String := "") : m α

Similar to withTraceNode, but msg is constructed before executing k. This is important when debugging methods such as isDefEq, and we want to generate the message before k updates the metavariable assignment. The class ExceptToEmoji is used to convert the result produced by k into an emoji (e.g., 💥️, ✅️, ❌️).

TODO: find better name for this function.

def Lean.addTraceAsMessages {m : Type → Type} [Lean.MonadOptions m] [Monad m] [Lean.MonadRef m] [Lean.MonadLog m] [Lean.MonadTrace m] : m Unit