3.1. Keep names stable and put variation in metadata🔗

An event name answers “what work was this?” Metadata answers “under which conditions?” A stable name makes runs comparable even when the module, shape, or backend changes.

span "source.analyze" (analyzeSource syntax) (metadata := {
  phase := some "analysis"
  activity := some "source file"
  backend := some analyzerName
  moduleName := some moduleName
  stepIndex := some fileIndex
})

LeanProfiler uses the following fields as the summary key:

name, phase, activity, backend, dtype, device, module

All of these fields are optional. They split rows when they identify meaningfully different implementations. Two analyzers should not be averaged together, and neither should two modules whose costs need to be compared. Numerical programs can additionally use dtype and device.

Step, graph node, and shape arrays remain attached to individual trace events. Putting a step number in the grouping key would create one summary row per iteration. The trace is where per-call details belong; the summary is where repeated observations become a distribution.

When another dimension really does define a separate benchmark population, use a stable name or one of the grouping fields deliberately. Do not encode an entire JSON payload into an event name.