Skip to content

guidellm.benchmark.progress

Progress tracking and console display for benchmark execution monitoring.

Provides abstract interfaces and concrete implementations for tracking benchmark progress during execution. The module enables real-time display of benchmark statistics, metrics, and execution state through console-based UI components. Primary use cases include monitoring generative benchmark runs with detailed request/token statistics and scheduler state updates.

BenchmarkerProgress

Bases: Generic[BenchmarkAccumulatorT, BenchmarkT], ABC

Abstract interface for tracking and displaying benchmark execution progress.

Provides lifecycle hooks for monitoring benchmark stages including initialization, execution start, progress updates, compile, completion, and finalization. Implementations handle display updates, progress tracking, and resource management for benchmark monitoring.

Source code in src/guidellm/benchmark/progress.py
class BenchmarkerProgress(Generic[BenchmarkAccumulatorT, BenchmarkT], ABC):
    """
    Abstract interface for tracking and displaying benchmark execution progress.

    Provides lifecycle hooks for monitoring benchmark stages including initialization,
    execution start, progress updates, compile, completion, and finalization.
    Implementations handle display updates, progress tracking, and resource management
    for benchmark monitoring.
    """

    def __init__(self):
        """Initialize progress tracker with default state."""
        self.profile: Profile | None = None
        self.current_strategy: SchedulingStrategy | None = None

    @abstractmethod
    async def on_initialize(self, profile: Profile):
        """
        Initialize progress tracking for the given benchmark profile.

        :param profile: Benchmark profile configuration defining execution parameters
        """

    @abstractmethod
    async def on_benchmark_start(self, strategy: SchedulingStrategy):
        """
        Handle benchmark strategy execution start event.

        :param strategy: Scheduling strategy configuration being executed
        """

    def on_requests_prefetched(self, loaded: int, target: int | None) -> None:
        """
        Record request nodes loaded before the run starts.

        The scheduler calls this synchronously from the prefetch loop.
        Trackers that do not display loading progress keep the default.

        :param loaded: Request nodes loaded so far
        :param target: Request nodes to load, or ``None`` when loading all
        """

    @abstractmethod
    async def on_benchmark_update(
        self, accumulator: BenchmarkAccumulatorT, scheduler_state: SchedulerState
    ):
        """
        Handle benchmark execution progress update with current metrics.

        :param accumulator: Current accumulated benchmark metrics and statistics
        :param scheduler_state: Current scheduler execution state and counters
        """

    async def on_benchmark_compile(self):
        """
        Handle result processing after request execution has ended.

        Defaults to no action so existing progress trackers remain compatible.
        """

    @abstractmethod
    async def on_benchmark_complete(self, benchmark: BenchmarkT):
        """
        Handle benchmark strategy execution completion event.

        :param benchmark: Completed benchmark results with final metrics
        """

    @abstractmethod
    async def on_finalize(self):
        """Finalize progress tracking and release associated resources."""

__init__()

Initialize progress tracker with default state.

Source code in src/guidellm/benchmark/progress.py
def __init__(self):
    """Initialize progress tracker with default state."""
    self.profile: Profile | None = None
    self.current_strategy: SchedulingStrategy | None = None

on_benchmark_compile() async

Handle result processing after request execution has ended.

Defaults to no action so existing progress trackers remain compatible.

Source code in src/guidellm/benchmark/progress.py
async def on_benchmark_compile(self):
    """
    Handle result processing after request execution has ended.

    Defaults to no action so existing progress trackers remain compatible.
    """

on_benchmark_complete(benchmark) abstractmethod async

Handle benchmark strategy execution completion event.

Parameters:

Name Type Description Default
benchmark BenchmarkT

Completed benchmark results with final metrics

required
Source code in src/guidellm/benchmark/progress.py
@abstractmethod
async def on_benchmark_complete(self, benchmark: BenchmarkT):
    """
    Handle benchmark strategy execution completion event.

    :param benchmark: Completed benchmark results with final metrics
    """

on_benchmark_start(strategy) abstractmethod async

Handle benchmark strategy execution start event.

Parameters:

Name Type Description Default
strategy SchedulingStrategy

Scheduling strategy configuration being executed

required
Source code in src/guidellm/benchmark/progress.py
@abstractmethod
async def on_benchmark_start(self, strategy: SchedulingStrategy):
    """
    Handle benchmark strategy execution start event.

    :param strategy: Scheduling strategy configuration being executed
    """

on_benchmark_update(accumulator, scheduler_state) abstractmethod async

Handle benchmark execution progress update with current metrics.

Parameters:

Name Type Description Default
accumulator BenchmarkAccumulatorT

Current accumulated benchmark metrics and statistics

required
scheduler_state SchedulerState

Current scheduler execution state and counters

required
Source code in src/guidellm/benchmark/progress.py
@abstractmethod
async def on_benchmark_update(
    self, accumulator: BenchmarkAccumulatorT, scheduler_state: SchedulerState
):
    """
    Handle benchmark execution progress update with current metrics.

    :param accumulator: Current accumulated benchmark metrics and statistics
    :param scheduler_state: Current scheduler execution state and counters
    """

on_finalize() abstractmethod async

Finalize progress tracking and release associated resources.

Source code in src/guidellm/benchmark/progress.py
@abstractmethod
async def on_finalize(self):
    """Finalize progress tracking and release associated resources."""

on_initialize(profile) abstractmethod async

Initialize progress tracking for the given benchmark profile.

Parameters:

Name Type Description Default
profile Profile

Benchmark profile configuration defining execution parameters

required
Source code in src/guidellm/benchmark/progress.py
@abstractmethod
async def on_initialize(self, profile: Profile):
    """
    Initialize progress tracking for the given benchmark profile.

    :param profile: Benchmark profile configuration defining execution parameters
    """

on_requests_prefetched(loaded, target)

Record request nodes loaded before the run starts.

The scheduler calls this synchronously from the prefetch loop. Trackers that do not display loading progress keep the default.

Parameters:

Name Type Description Default
loaded int

Request nodes loaded so far

required
target int | None

Request nodes to load, or None when loading all

required
Source code in src/guidellm/benchmark/progress.py
def on_requests_prefetched(self, loaded: int, target: int | None) -> None:
    """
    Record request nodes loaded before the run starts.

    The scheduler calls this synchronously from the prefetch loop.
    Trackers that do not display loading progress keep the default.

    :param loaded: Request nodes loaded so far
    :param target: Request nodes to load, or ``None`` when loading all
    """

CompositeBenchmarkerProgress

Bases: BenchmarkerProgress[BenchmarkAccumulatorT, BenchmarkT]

Composite progress tracker that aggregates multiple progress trackers.

Delegates lifecycle events to all registered progress trackers, enabling simultaneous monitoring and display of benchmark execution across different interfaces or formats.

Source code in src/guidellm/benchmark/progress.py
class CompositeBenchmarkerProgress(
    BenchmarkerProgress[BenchmarkAccumulatorT, BenchmarkT]
):
    """
    Composite progress tracker that aggregates multiple progress trackers.

    Delegates lifecycle events to all registered progress trackers, enabling
    simultaneous monitoring and display of benchmark execution across different
    interfaces or formats.
    """

    def __init__(
        self, trackers: list[BenchmarkerProgress[BenchmarkAccumulatorT, BenchmarkT]]
    ):
        """
        Initialize composite progress tracker with a list of individual trackers.

        :param progress_trackers: Individual progress trackers to aggregate
        """
        super().__init__()
        self.trackers = trackers

    @staticmethod
    async def _notify_progress(*callbacks: Awaitable) -> None:
        """Finish every callback before propagating the first lifecycle failure."""
        results = await asyncio.gather(*callbacks, return_exceptions=True)
        for result in results:
            if isinstance(result, BaseException):
                raise result

    async def on_initialize(self, profile: Profile):
        await self._notify_progress(
            *(tracker.on_initialize(profile) for tracker in self.trackers)
        )

    async def on_benchmark_start(self, strategy: SchedulingStrategy):
        await self._notify_progress(
            *(tracker.on_benchmark_start(strategy) for tracker in self.trackers)
        )

    def on_requests_prefetched(self, loaded: int, target: int | None) -> None:
        """
        Forward a prefetch progress update to every tracker.

        :param loaded: Request nodes loaded so far
        :param target: Request nodes to load, or ``None`` when loading all
        """
        errors: list[Exception] = []

        for tracker in self.trackers:
            try:
                tracker.on_requests_prefetched(loaded, target)
            except Exception as error:  # noqa: BLE001  Re-raises an error
                errors.append(error)
        if errors:
            raise errors[0]

    async def on_benchmark_update(
        self, accumulator: BenchmarkAccumulatorT, scheduler_state: SchedulerState
    ):
        await self._notify_progress(
            *(
                tracker.on_benchmark_update(accumulator, scheduler_state)
                for tracker in self.trackers
            )
        )

    async def on_benchmark_compile(self):
        """Notify all trackers that benchmark results are being processed."""
        await self._notify_progress(
            *(tracker.on_benchmark_compile() for tracker in self.trackers)
        )

    async def on_benchmark_complete(self, benchmark: BenchmarkT):
        await self._notify_progress(
            *(tracker.on_benchmark_complete(benchmark) for tracker in self.trackers)
        )

    async def on_finalize(self):
        await self._notify_progress(
            *(tracker.on_finalize() for tracker in self.trackers)
        )

__init__(trackers)

Initialize composite progress tracker with a list of individual trackers.

Parameters:

Name Type Description Default
progress_trackers

Individual progress trackers to aggregate

required
Source code in src/guidellm/benchmark/progress.py
def __init__(
    self, trackers: list[BenchmarkerProgress[BenchmarkAccumulatorT, BenchmarkT]]
):
    """
    Initialize composite progress tracker with a list of individual trackers.

    :param progress_trackers: Individual progress trackers to aggregate
    """
    super().__init__()
    self.trackers = trackers

on_benchmark_compile() async

Notify all trackers that benchmark results are being processed.

Source code in src/guidellm/benchmark/progress.py
async def on_benchmark_compile(self):
    """Notify all trackers that benchmark results are being processed."""
    await self._notify_progress(
        *(tracker.on_benchmark_compile() for tracker in self.trackers)
    )

on_requests_prefetched(loaded, target)

Forward a prefetch progress update to every tracker.

Parameters:

Name Type Description Default
loaded int

Request nodes loaded so far

required
target int | None

Request nodes to load, or None when loading all

required
Source code in src/guidellm/benchmark/progress.py
def on_requests_prefetched(self, loaded: int, target: int | None) -> None:
    """
    Forward a prefetch progress update to every tracker.

    :param loaded: Request nodes loaded so far
    :param target: Request nodes to load, or ``None`` when loading all
    """
    errors: list[Exception] = []

    for tracker in self.trackers:
        try:
            tracker.on_requests_prefetched(loaded, target)
        except Exception as error:  # noqa: BLE001  Re-raises an error
            errors.append(error)
    if errors:
        raise errors[0]

GenerativeConsoleBenchmarkerProgress

Bases: BenchmarkerProgress[GenerativeBenchmarkAccumulator, GenerativeBenchmark], Live

Console-based real-time progress display for generative benchmarks.

Renders live benchmark execution statistics using Rich library components with structured progress bars, timing information, request/token metrics, and optional scheduler statistics. Updates refresh automatically during benchmark execution.

Attributes:

Name Type Description
display_scheduler_stats bool

Whether to include scheduler statistics in display

Source code in src/guidellm/benchmark/progress.py
class GenerativeConsoleBenchmarkerProgress(
    BenchmarkerProgress[GenerativeBenchmarkAccumulator, GenerativeBenchmark], Live
):
    """
    Console-based real-time progress display for generative benchmarks.

    Renders live benchmark execution statistics using Rich library components with
    structured progress bars, timing information, request/token metrics, and optional
    scheduler statistics. Updates refresh automatically during benchmark execution.

    :cvar display_scheduler_stats: Whether to include scheduler statistics in display
    """

    def __init__(self, display_scheduler_stats: bool = False, cleanup: bool = True):
        """
        Initialize console progress display with rendering configuration.

        :param display_scheduler_stats: Whether to display scheduler timing statistics
        :param cleanup: Whether to clear the console display after completion
        """
        super().__init__()
        Live.__init__(
            self,
            refresh_per_second=4,
            auto_refresh=True,
            redirect_stdout=True,
            # Only redirect stderr if it would interfere with stdout display
            redirect_stderr=stderr_eq_stdout(),
            transient=cleanup,
        )
        self.display_scheduler_stats: bool = display_scheduler_stats
        self.run_progress: Progress | None = None
        self.run_progress_task: TaskID | None = None
        self.tasks_progress: _GenerativeProgressTasks | None = None

    async def on_initialize(self, profile: Profile):
        """
        Initialize console display components and begin live rendering.

        :param profile: Benchmark profile configuration defining execution parameters
        """
        self.tasks_progress = _GenerativeProgressTasks(
            profile=profile, display_scheduler_stats=self.display_scheduler_stats
        )
        self.run_progress = Progress(
            TextColumn("Generating...", style=f"italic {Colors.progress}"),
            BarColumn(
                bar_width=None,
                complete_style=Colors.progress,
                finished_style=Colors.success,
            ),
            TextColumn(
                "({task.fields[completed_benchmarks]}/{task.fields[total_benchmarks]})",
                style=Colors.progress,
            ),
            TextColumn("["),
            TimeElapsedColumn(),
            TextColumn("<"),
            TimeRemainingColumn(),
            TextColumn("]"),
            auto_refresh=False,
        )
        self.run_progress_task = self.run_progress.add_task("")
        self._sync_run_progress()
        self.update(
            Group(
                Panel(
                    self.tasks_progress,
                    title="Benchmarks",
                    title_align="left",
                    expand=True,
                ),
                self.run_progress,
            )
        )
        self.start()

    async def on_benchmark_start(self, strategy: SchedulingStrategy):
        """
        Update display for benchmark strategy execution start.

        :param strategy: Scheduling strategy configuration being executed
        """
        if self.tasks_progress is not None:
            self.tasks_progress.start_benchmark(strategy)
            self._sync_run_progress()

    def on_requests_prefetched(self, loaded: int, target: int | None) -> None:
        """
        Update the loading bar with the number of prefetched requests.

        :param loaded: Request nodes loaded so far
        :param target: Request nodes to load, or ``None`` when loading all
        """
        if self.tasks_progress is not None:
            self.tasks_progress.note_prefetch(loaded, target)
            self._sync_run_progress()
            self.refresh()

    async def on_benchmark_update(
        self,
        accumulator: GenerativeBenchmarkAccumulator,
        scheduler_state: SchedulerState,
    ):
        """
        Update display with current benchmark progress and metrics.

        :param accumulator: Current accumulated benchmark metrics and statistics
        :param scheduler_state: Current scheduler execution state and counters
        """
        if self.tasks_progress is not None:
            self.tasks_progress.update_benchmark(accumulator, scheduler_state)
            self._sync_run_progress()

    async def on_benchmark_compile(self):
        """Show result processing before synchronous compilation begins."""
        if self.tasks_progress is not None:
            self.tasks_progress.compile_benchmark()
            self._sync_run_progress()
            self.refresh()

    async def on_benchmark_complete(self, benchmark: GenerativeBenchmark):
        """
        Update display for completed benchmark strategy.

        :param benchmark: Completed benchmark results with final metrics
        """
        if self.tasks_progress is not None:
            self.tasks_progress.complete_benchmark(benchmark)
            self._sync_run_progress()

    async def on_finalize(self):
        """Stop display rendering and release resources."""
        if self.tasks_progress is not None:
            self.tasks_progress.finalize()
            self._sync_run_progress()
        if self.run_progress is not None and self.run_progress_task is not None:
            self.run_progress.stop_task(self.run_progress_task)
        self.stop()
        self.run_progress = None
        self.run_progress_task = None
        self.tasks_progress = None

    def _sync_run_progress(self):
        """Synchronize overall progress display with task progress."""
        if (
            self.run_progress is not None
            and self.run_progress_task is not None
            and self.tasks_progress is not None
        ):
            self.run_progress.update(
                self.run_progress_task,
                total=self.tasks_progress.steps_total,
                completed=self.tasks_progress.steps_progress,
                completed_benchmarks=self.tasks_progress.tasks_progress,
                total_benchmarks=self.tasks_progress.tasks_total,
            )

__init__(display_scheduler_stats=False, cleanup=True)

Initialize console progress display with rendering configuration.

Parameters:

Name Type Description Default
display_scheduler_stats bool

Whether to display scheduler timing statistics

False
cleanup bool

Whether to clear the console display after completion

True
Source code in src/guidellm/benchmark/progress.py
def __init__(self, display_scheduler_stats: bool = False, cleanup: bool = True):
    """
    Initialize console progress display with rendering configuration.

    :param display_scheduler_stats: Whether to display scheduler timing statistics
    :param cleanup: Whether to clear the console display after completion
    """
    super().__init__()
    Live.__init__(
        self,
        refresh_per_second=4,
        auto_refresh=True,
        redirect_stdout=True,
        # Only redirect stderr if it would interfere with stdout display
        redirect_stderr=stderr_eq_stdout(),
        transient=cleanup,
    )
    self.display_scheduler_stats: bool = display_scheduler_stats
    self.run_progress: Progress | None = None
    self.run_progress_task: TaskID | None = None
    self.tasks_progress: _GenerativeProgressTasks | None = None

on_benchmark_compile() async

Show result processing before synchronous compilation begins.

Source code in src/guidellm/benchmark/progress.py
async def on_benchmark_compile(self):
    """Show result processing before synchronous compilation begins."""
    if self.tasks_progress is not None:
        self.tasks_progress.compile_benchmark()
        self._sync_run_progress()
        self.refresh()

on_benchmark_complete(benchmark) async

Update display for completed benchmark strategy.

Parameters:

Name Type Description Default
benchmark GenerativeBenchmark

Completed benchmark results with final metrics

required
Source code in src/guidellm/benchmark/progress.py
async def on_benchmark_complete(self, benchmark: GenerativeBenchmark):
    """
    Update display for completed benchmark strategy.

    :param benchmark: Completed benchmark results with final metrics
    """
    if self.tasks_progress is not None:
        self.tasks_progress.complete_benchmark(benchmark)
        self._sync_run_progress()

on_benchmark_start(strategy) async

Update display for benchmark strategy execution start.

Parameters:

Name Type Description Default
strategy SchedulingStrategy

Scheduling strategy configuration being executed

required
Source code in src/guidellm/benchmark/progress.py
async def on_benchmark_start(self, strategy: SchedulingStrategy):
    """
    Update display for benchmark strategy execution start.

    :param strategy: Scheduling strategy configuration being executed
    """
    if self.tasks_progress is not None:
        self.tasks_progress.start_benchmark(strategy)
        self._sync_run_progress()

on_benchmark_update(accumulator, scheduler_state) async

Update display with current benchmark progress and metrics.

Parameters:

Name Type Description Default
accumulator GenerativeBenchmarkAccumulator

Current accumulated benchmark metrics and statistics

required
scheduler_state SchedulerState

Current scheduler execution state and counters

required
Source code in src/guidellm/benchmark/progress.py
async def on_benchmark_update(
    self,
    accumulator: GenerativeBenchmarkAccumulator,
    scheduler_state: SchedulerState,
):
    """
    Update display with current benchmark progress and metrics.

    :param accumulator: Current accumulated benchmark metrics and statistics
    :param scheduler_state: Current scheduler execution state and counters
    """
    if self.tasks_progress is not None:
        self.tasks_progress.update_benchmark(accumulator, scheduler_state)
        self._sync_run_progress()

on_finalize() async

Stop display rendering and release resources.

Source code in src/guidellm/benchmark/progress.py
async def on_finalize(self):
    """Stop display rendering and release resources."""
    if self.tasks_progress is not None:
        self.tasks_progress.finalize()
        self._sync_run_progress()
    if self.run_progress is not None and self.run_progress_task is not None:
        self.run_progress.stop_task(self.run_progress_task)
    self.stop()
    self.run_progress = None
    self.run_progress_task = None
    self.tasks_progress = None

on_initialize(profile) async

Initialize console display components and begin live rendering.

Parameters:

Name Type Description Default
profile Profile

Benchmark profile configuration defining execution parameters

required
Source code in src/guidellm/benchmark/progress.py
async def on_initialize(self, profile: Profile):
    """
    Initialize console display components and begin live rendering.

    :param profile: Benchmark profile configuration defining execution parameters
    """
    self.tasks_progress = _GenerativeProgressTasks(
        profile=profile, display_scheduler_stats=self.display_scheduler_stats
    )
    self.run_progress = Progress(
        TextColumn("Generating...", style=f"italic {Colors.progress}"),
        BarColumn(
            bar_width=None,
            complete_style=Colors.progress,
            finished_style=Colors.success,
        ),
        TextColumn(
            "({task.fields[completed_benchmarks]}/{task.fields[total_benchmarks]})",
            style=Colors.progress,
        ),
        TextColumn("["),
        TimeElapsedColumn(),
        TextColumn("<"),
        TimeRemainingColumn(),
        TextColumn("]"),
        auto_refresh=False,
    )
    self.run_progress_task = self.run_progress.add_task("")
    self._sync_run_progress()
    self.update(
        Group(
            Panel(
                self.tasks_progress,
                title="Benchmarks",
                title_align="left",
                expand=True,
            ),
            self.run_progress,
        )
    )
    self.start()

on_requests_prefetched(loaded, target)

Update the loading bar with the number of prefetched requests.

Parameters:

Name Type Description Default
loaded int

Request nodes loaded so far

required
target int | None

Request nodes to load, or None when loading all

required
Source code in src/guidellm/benchmark/progress.py
def on_requests_prefetched(self, loaded: int, target: int | None) -> None:
    """
    Update the loading bar with the number of prefetched requests.

    :param loaded: Request nodes loaded so far
    :param target: Request nodes to load, or ``None`` when loading all
    """
    if self.tasks_progress is not None:
        self.tasks_progress.note_prefetch(loaded, target)
        self._sync_run_progress()
        self.refresh()

GenerativeLoggingBenchmarkerProgress

Bases: BenchmarkerProgress[GenerativeBenchmarkAccumulator, GenerativeBenchmark]

Log interval-limited progress independently of other progress trackers.

Source code in src/guidellm/benchmark/progress.py
class GenerativeLoggingBenchmarkerProgress(
    BenchmarkerProgress[GenerativeBenchmarkAccumulator, GenerativeBenchmark]
):
    """Log interval-limited progress independently of other progress trackers."""

    def __init__(self, interval: float = 10.0):
        """
        Initialize independent progress logging.

        :param interval: Positive finite minimum seconds between periodic records
        :raises ValueError: If the interval is not positive and finite
        """
        super().__init__()
        if not isfinite(interval) or interval <= 0:
            raise ValueError("Progress log interval must be positive and finite")
        self.interval = interval
        self._state: _GenerativeProgressTaskState | None = None
        self._index = 0
        self._started_at = 0.0
        self._last_update = 0.0
        self._logged_prefetch = False
        self._pending_prefetch = False

    async def on_initialize(self, profile: Profile):
        """
        Reset logging for a new run.

        :param profile: Benchmark profile
        """
        self.profile = profile
        self._index = 0
        self._state = None
        self._logged_prefetch = False
        self._pending_prefetch = False

    async def on_benchmark_start(self, strategy: SchedulingStrategy):
        """
        Log strategy start immediately.

        :param strategy: Strategy being executed
        """
        self._index += 1
        self._state = _GenerativeProgressTaskState(strategy_type=strategy.type_)
        self._state.start(strategy)
        self._started_at = monotonic()
        self._logged_prefetch = False
        self._pending_prefetch = False
        self._log_update("started")

    def on_requests_prefetched(self, loaded: int, target: int | None) -> None:
        """
        Log prefetch progress on the first update and then on the log interval.

        :param loaded: Request nodes loaded so far
        :param target: Request nodes to load, or ``None`` when loading all
        """
        if self._state is None:
            return
        self._state.note_prefetch(loaded, target)
        if (
            not self._logged_prefetch
            or monotonic() - self._last_update >= self.interval
        ):
            self._logged_prefetch = True
            self._pending_prefetch = False
            self._log_update("loading")
        else:
            self._pending_prefetch = True

    async def on_benchmark_update(
        self,
        accumulator: GenerativeBenchmarkAccumulator,
        scheduler_state: SchedulerState,
    ):
        """
        Periodically log current metrics.

        :param accumulator: Accumulated benchmark metrics
        :param scheduler_state: Scheduler counters and progress
        """
        if self._state:
            if self._pending_prefetch:
                self._pending_prefetch = False
                self._log_update("loading")
            if monotonic() - self._last_update >= self.interval:
                self._state.update(accumulator, scheduler_state)
                self._log_update(self._state.benchmark_status)

    async def on_benchmark_compile(self):
        """Log result processing immediately, regardless of the interval."""
        if self._state:
            self._state.benchmark_status = "compile"
            self._log_update("compile")

    async def on_benchmark_complete(self, benchmark: GenerativeBenchmark):
        """
        Log final metrics regardless of the interval.

        :param benchmark: Completed result
        """
        if self._state:
            self._state.complete(benchmark)
            self._log_update("completed")
            self._state = None

    async def on_finalize(self):
        """Release progress state."""
        self._state = None

    def _log_update(self, status: str):
        if self._state is None:
            return
        state = self._state
        now = monotonic()
        prefetched = ""
        if status == "loading":
            loaded = (
                f"{state.prefetched_requests}/{state.prefetch_target}"
                if state.prefetch_target is not None
                else str(state.prefetched_requests)
            )
            prefetched = f"prefetched={loaded} | "
        logger.bind(benchmark_index=self._index, progress_status=status).info(
            "Benchmark {} ({}): {} | elapsed={:.1f}s | {}"
            "successful={} errored={} incomplete={} | "
            "requests/s={:.2f} output_tokens/s={:.2f}",
            self._index,
            state.strategy,
            status,
            now - self._started_at,
            prefetched,
            state.successful_requests,
            state.errored_requests,
            state.cancelled_requests,
            state.requests_per_second,
            state.output_tokens_rate,
        )
        self._last_update = now

__init__(interval=10.0)

Initialize independent progress logging.

Parameters:

Name Type Description Default
interval float

Positive finite minimum seconds between periodic records

10.0

Raises:

Type Description
ValueError

If the interval is not positive and finite

Source code in src/guidellm/benchmark/progress.py
def __init__(self, interval: float = 10.0):
    """
    Initialize independent progress logging.

    :param interval: Positive finite minimum seconds between periodic records
    :raises ValueError: If the interval is not positive and finite
    """
    super().__init__()
    if not isfinite(interval) or interval <= 0:
        raise ValueError("Progress log interval must be positive and finite")
    self.interval = interval
    self._state: _GenerativeProgressTaskState | None = None
    self._index = 0
    self._started_at = 0.0
    self._last_update = 0.0
    self._logged_prefetch = False
    self._pending_prefetch = False

on_benchmark_compile() async

Log result processing immediately, regardless of the interval.

Source code in src/guidellm/benchmark/progress.py
async def on_benchmark_compile(self):
    """Log result processing immediately, regardless of the interval."""
    if self._state:
        self._state.benchmark_status = "compile"
        self._log_update("compile")

on_benchmark_complete(benchmark) async

Log final metrics regardless of the interval.

Parameters:

Name Type Description Default
benchmark GenerativeBenchmark

Completed result

required
Source code in src/guidellm/benchmark/progress.py
async def on_benchmark_complete(self, benchmark: GenerativeBenchmark):
    """
    Log final metrics regardless of the interval.

    :param benchmark: Completed result
    """
    if self._state:
        self._state.complete(benchmark)
        self._log_update("completed")
        self._state = None

on_benchmark_start(strategy) async

Log strategy start immediately.

Parameters:

Name Type Description Default
strategy SchedulingStrategy

Strategy being executed

required
Source code in src/guidellm/benchmark/progress.py
async def on_benchmark_start(self, strategy: SchedulingStrategy):
    """
    Log strategy start immediately.

    :param strategy: Strategy being executed
    """
    self._index += 1
    self._state = _GenerativeProgressTaskState(strategy_type=strategy.type_)
    self._state.start(strategy)
    self._started_at = monotonic()
    self._logged_prefetch = False
    self._pending_prefetch = False
    self._log_update("started")

on_benchmark_update(accumulator, scheduler_state) async

Periodically log current metrics.

Parameters:

Name Type Description Default
accumulator GenerativeBenchmarkAccumulator

Accumulated benchmark metrics

required
scheduler_state SchedulerState

Scheduler counters and progress

required
Source code in src/guidellm/benchmark/progress.py
async def on_benchmark_update(
    self,
    accumulator: GenerativeBenchmarkAccumulator,
    scheduler_state: SchedulerState,
):
    """
    Periodically log current metrics.

    :param accumulator: Accumulated benchmark metrics
    :param scheduler_state: Scheduler counters and progress
    """
    if self._state:
        if self._pending_prefetch:
            self._pending_prefetch = False
            self._log_update("loading")
        if monotonic() - self._last_update >= self.interval:
            self._state.update(accumulator, scheduler_state)
            self._log_update(self._state.benchmark_status)

on_finalize() async

Release progress state.

Source code in src/guidellm/benchmark/progress.py
async def on_finalize(self):
    """Release progress state."""
    self._state = None

on_initialize(profile) async

Reset logging for a new run.

Parameters:

Name Type Description Default
profile Profile

Benchmark profile

required
Source code in src/guidellm/benchmark/progress.py
async def on_initialize(self, profile: Profile):
    """
    Reset logging for a new run.

    :param profile: Benchmark profile
    """
    self.profile = profile
    self._index = 0
    self._state = None
    self._logged_prefetch = False
    self._pending_prefetch = False

on_requests_prefetched(loaded, target)

Log prefetch progress on the first update and then on the log interval.

Parameters:

Name Type Description Default
loaded int

Request nodes loaded so far

required
target int | None

Request nodes to load, or None when loading all

required
Source code in src/guidellm/benchmark/progress.py
def on_requests_prefetched(self, loaded: int, target: int | None) -> None:
    """
    Log prefetch progress on the first update and then on the log interval.

    :param loaded: Request nodes loaded so far
    :param target: Request nodes to load, or ``None`` when loading all
    """
    if self._state is None:
        return
    self._state.note_prefetch(loaded, target)
    if (
        not self._logged_prefetch
        or monotonic() - self._last_update >= self.interval
    ):
        self._logged_prefetch = True
        self._pending_prefetch = False
        self._log_update("loading")
    else:
        self._pending_prefetch = True