Clarify how traces are collected + Some Minor Documentation Updates

[wkaisertexas]

What does this PR do?

Clarifies documentation surrounding how traces are collected.

In #107, I had some issues collecting traces to use with HTA. The core of this issue was the example on the Read The Docs for this project. From an outside perspective, it is not immediately clear how to collect traces.

My Code:

# config from: https://github.com/facebookresearch/HolisticTraceAnalysis/blob/ec3abf17e1afbf2d443e504d0c9a9ee4c9c87a03/examples/cupti_profiler_demo.py#L15
with profile(
  activities = [ProfilerActivity.CUDA, ProfilerActivity.CPU],
  profile_memory = True,
  record_shapes = True,
  with_stack=True,
  experimental_config=torch.profiler._ExperimentalConfig(
            profiler_metrics=[
                # Metrics can be picked from
                # https://docs.nvidia.com/cupti/r_main.html#r_profiler
                # or use kineto__tensor_core_insts, kineto__cuda_core_flops
                "kineto__tensor_core_insts",
                "dram__bytes_read.sum",
                "dram__bytes_write.sum",
            ],
            profiler_measure_per_kernel=True)
) as prof:
    cnn.train() # puts the model into train mode
    print("Starting training")
    for i in range(1, 5):
        train_mnist_for_epoch(i) 
        prof.step() # tells the profiler that the steps are correlated
    print("Finished training (need to wait for collection)")
print("Collection finished")

Code from the documentation:

from torch.profiler import profile, schedule, tensorboard_trace_handler

tracing_schedule = schedule(skip_first=5, wait=5, warmup=2, active=2, repeat=1)
trace_handler = tensorboard_trace_handler(dir_name=/output/folder, use_gzip=True)

with profile(
  activities = [ProfilerActivity.CPU, ProfilerActivity.CUDA],
  schedule = tracing_schedule,
  on_trace_ready = trace_handler,
  profile_memory = True,
  record_shapes = True,
  with_stack = True
) as prof:
    for step, batch_data in enumerate(data_loader):
        train(batch_data)
        prof.step()

The difference here is that the code in the documentation ensures to step for every batch rather than every epoch. A subtle difference, but one a core library maintainer was unable to spot right away.

Given models are trained in many epochs, updating the examples to show the more common pattern of training for epochs and iterating over the data loader for each epoch helps clarify trace collection in my opinion.

That was the main change, but I made some others. Please let me know if you have questions. I marked this PR as a draft because I would love to hear from maintainers about their opinions on documentation and the right thing to do.

---

Also, if no ranks are found, what are your thoughts on populating this information with a rank of zero. Or, alternatively, allowing the user to specify a default rank when creating a TraceAnalysis object.

i.e.

TraceAnalysis(trace_dir = "traces/", default_rank = 0)

Let me know your thoughts. Thank you!

Before submitting

• Was this discussed/approved via a Github issue? (no need for typos, doc improvements)
  • N/A
• Did you write any new necessary tests?
  • N/A
• Did you make sure to update the docs?
  • N/A
• Did you update the changelog?
  • N/A

[facebook-github-bot]

Hi @wkaisertexas!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at [email protected]. Thanks!

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!