For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /get-started.md).

Python module

max.profiler

Performance profiling and tracing utilities for MAX.

This module provides tools for profiling and tracing MAX operations to analyze performance characteristics. Profiling captures timing information for code execution, which helps identify bottlenecks and optimize your models.

To enable in-runtime NVTX markers, set MODULAR_ENABLE_PROFILING to on or detailed before running your code. Without it, profiling calls are no-ops with minimal overhead.

The host-side spans reach NVTX (or roctx) through libmax_profiler_shim.so, which is loaded at runtime. A wheel install finds it on its own; a source build does not, and needs MODULAR_PROFILER_SHIM set to the shim’s path (the br-nsys, bt-nsys and *-rocprof aliases do this for you). Without it the host-side spans are dropped and only kernel-level ranges appear in the capture.

The profiler exposes two layers:

1. In-source spans: Tracer (context manager / manual stack) and @traced (decorator) emit NVTX ranges around blocks or functions. These show up in any Nsight Systems capture of the process.
2. One-shot CLI capture: maybe_reexec_under_nsys() re-launches the current process under nsys profile and renders a top-N kernel summary on exit; profiled_region() is the corresponding context manager that brackets the timed region with cudaProfilerStart/Stop and prints a cProfile Python/CPU summary. These power the --profile flag on max generate / max benchmark.

Submodules

• max.profiler.cpu
• max.profiler.gpu

Tracing

Tracer	A stack-based profiling manager for creating nested profiling spans.

traced	Decorator for creating a profiling span for a function.

Configuration

is_profiling_enabled	is_profiling_enabled() -> bool
set_gpu_profiling_state	str, /) -> None