Function mz_repr::explain::tracing::trace_plan

pub fn trace_plan<T: Clone + 'static>(plan: &T)

Trace a fragment of type T to be emitted as part of an EXPLAIN OPTIMIZER TRACE output.

For best compatibility with the existing UI (which at the moment is the only sane way to look at such EXPLAIN traces), code instrumentation should adhere to the following constraints:

1. The plan type should be listed in the layers created in the OptimizerTrace constructor.
2. Each trace_plan should be unique within it’s enclosing span and should represent the result of the stage idenified by that span. In particular, this means that functions that call trace_plan more than once need to construct ad-hoc spans (see the iteration spans in the Fixpoint transform for example).

As a consequence of the second constraint, a sequence of paths such as

optimizer.foo.bar
optimizer.foo.baz

is not well-formed as it is missing the results of the prefix paths at the end:

optimizer.foo.bar
optimizer.foo.baz
optimizer.foo
optimizer

Also, note that full paths can be repeated within a pipeline, but adjacent duplicates are interpreted as separete invocations. For example, the sub-sequence

... // preceding stages
optimizer.foo.bar // 1st call
optimizer.foo.bar // 2nd call
... // following stages

will be rendered by the UI as the following tree structure.

optimizer
  ... // following stages
  foo
    bar // 2nd call
    bar // 1st call
  ... // preceding stages