fastvideo.profiler

`fastvideo.profiler`#

Utilities for managing the PyTorch profiler within FastVideo.

The profiler is shared across the process; this module adds a light-weight controller that gates collection based on named regions. Regions may be enabled through dedicated environment variables (e.g. FASTVIDEO_TORCH_PROFILE_MODEL_LOADING=1) or via the consolidated FASTVIDEO_TORCH_PROFILE_REGIONS comma-separated list (e.g. FASTVIDEO_TORCH_PROFILE_REGIONS=model_loading,training_dit).

Typical usage from client code::

controller = TorchProfilerController(profiler, activities)
with controller.region("training_dit"):
    run_training_step()

To introduce a new region, register it via :func:register_profiler_region and wrap the corresponding code in :meth:TorchProfilerController.region.

Module Contents#

Classes#

`ProfilerRegion`	Metadata describing a profiler region.
`TorchProfilerConfig`	Configuration for torch profiler region control.
`TorchProfilerController`	Helper that toggles torch profiler collection for named regions.

Functions#

`get_global_controller`
`get_global_profiler`	Return the global profiler instance if one was created.
`get_or_create_profiler`	Create or reuse the process-wide torch profiler controller.
`list_profiler_regions`	Return all registered profiler regions sorted by canonical name.
`profile_region`	Wrap a bound method so it runs inside a profiler region if available.
`register_profiler_region`	Register a profiler region so configuration can validate inputs.
`resolve_profiler_region`	Return the registered region matching `name` or `None` if absent.
`set_global_controller`
`set_global_profiler`

Data#

logger

API#

class fastvideo.profiler.ProfilerRegion[source]#

Metadata describing a profiler region.

default_enabled: bool[source]#: False

description: str[source]#: None

name: str[source]#: None

class fastvideo.profiler.TorchProfilerConfig[source]#

Configuration for torch profiler region control.

Use :meth:from_env to construct an instance with defaults inherited from registered regions and optional overrides from the FASTVIDEO_TORCH_PROFILE_REGIONS environment variable. The resulting regions map is consumed by :class:TorchProfilerController to decide when collection should be enabled.

classmethod from_env() → fastvideo.profiler.TorchProfilerConfig[source]#: Build a configuration from process environment variables.

regions: dict[str, bool][source]#: None

class fastvideo.profiler.TorchProfilerController(profiler: Any, activities: collections.abc.Iterable[torch.profiler.ProfilerActivity], config: fastvideo.profiler.TorchProfilerConfig | None = None, disabled: bool = False)[source]#

Helper that toggles torch profiler collection for named regions.

Parameters:

profiler – The shared :class:torch.profiler.profile instance, or None if profiling is disabled.
activities – Iterable of :class:torch.profiler.ProfilerActivity recorded by the profiler.
config – Optional :class:TorchProfilerConfig. If omitted, :meth:from_env constructs one during initialization.

.. rubric:: Examples

Enabling an existing region from the command line::

FASTVIDEO_TORCH_PROFILE_REGIONS=model_loading,training_dit         python fastvideo/training/wan_training_pipeline.py ...

Wrapping a code block in a custom region::

controller = TorchProfilerController(profiler, activities)
with controller.region("training_validation"):
    run_validation_epoch()

Adding a new region requires three steps:

Define an env var in envs.py.
Add a default entry to register_profiler_region in this module.
Wrap the target code in :meth:region using the new name.

Initialization

property activities: tuple[torch.profiler.ProfilerActivity, ...][source]#

property has_profiler: bool[source]#: Return True when a profiler instance is available.

property is_enabled: bool[source]#: Return True when the underlying profiler is collecting.

is_region_enabled(region: str) → bool[source]#: Return True if region should be collected.

property profiler: torch.profiler.profile | None[source]#

region(region: str)[source]#: Context manager that enables profiling for region if configured.

start() → None[source]#: Start the profiler and pause collection until a region is entered.

stop() → None[source]#: Stop the profiler after disabling collection and clearing state.

fastvideo.profiler.get_global_controller() → TorchProfilerController | None[source]#

fastvideo.profiler.get_global_profiler() → torch.profiler.profile | None[source]#: Return the global profiler instance if one was created.

fastvideo.profiler.get_or_create_profiler(trace_dir: str | None) → TorchProfilerController[source]#: Create or reuse the process-wide torch profiler controller.

fastvideo.profiler.list_profiler_regions() → list[fastvideo.profiler.ProfilerRegion][source]#: Return all registered profiler regions sorted by canonical name.

fastvideo.profiler.logger[source]#: ‘init_logger(…)’

fastvideo.profiler.profile_region(region: str) → collections.abc.Callable[[collections.abc.Callable[..., Any]], collections.abc.Callable[..., Any]][source]#: Wrap a bound method so it runs inside a profiler region if available.

fastvideo.profiler.register_profiler_region(name: str, description: str, *, default_enabled: bool = False) → None[source]#: Register a profiler region so configuration can validate inputs.

fastvideo.profiler.resolve_profiler_region(name: str) → fastvideo.profiler.ProfilerRegion | None[source]#: Return the registered region matching name or None if absent.

fastvideo.profiler.set_global_controller(controller: TorchProfilerController | None) → None[source]#

fastvideo.profiler.set_global_profiler(profiler: torch.profiler.profile | None) → None[source]#