Document Analyzer Behavior and Output Expectations

[rayandrew]

Hi @izzet and @hariharan-devarajan,

This issue follows up on our Slack discussion.

We should document what users can expect when running the analyzer. Here’s a sample use case:

class AnalyzerPresetConfigAIDFtracer(AnalyzerPresetConfig):
    additional_metrics: Optional[Dict[str, Optional[str]]] = dc.field(
        default_factory=lambda: {
            'compute_util': 'compute_{time_metric} / (app_{time_metric} + {epsilon})',
            ...
        }
    )
    derived_metrics: Optional[Dict[str, Dict[str, str]]] = dc.field(
        default_factory=lambda: {
            ...
            'compute': {
                'forward': f'func_name == "{AIDFTracer.Compute.FORWARD}"',
                'backward': f'func_name == "{AIDFTracer.Compute.BACKWARD}"',
            },
            ...
        }
    )

...

result = dfa.analyze_trace(percentile=percentile, view_types=view_types)

Some key points we should clarify in the docs:

• What is result?
• Where do additional_metrics and derived_metrics show up?
  • As Izzet mentioned, users can access them via result.flat_views, which is the main output.
• What happens if users try to access private attributes like result._traces?
  • After checkpointing, result._traces will be None because raw traces are no longer loaded.
  • Even though it's a private attribute, we should clearly state this behavior and suggest users avoid relying on _-prefixed fields unless they know what they’re doing.
• How to access preprocessed data, e.g.:

  result.views['reader_posix_lustre'][('time_range',)].head()

  Users may not know they need to use a tuple as the dictionary key—this should be documented.

Open to any other suggestions or improvements!