radioviz.services.perf_tracing

Performance tracing helpers.

This module provides opt-in timing utilities for diagnosing slow paths. Tracing is controlled via environment variables and can be applied with either a context manager or a decorator.

Example usage:

from radioviz.services.perf_tracing import (
    PerfTracer,
    is_env_tracing_enabled,
    trace_env,
)

# Context manager style
with PerfTracer(
    'image_window._update_canvas',
    enabled=is_env_tracing_enabled('RADIOVIZ_PERF_TRACE'),
    factor=4,
):
    update_canvas()


# Decorator style
@trace_env('RADIOVIZ_PERF_TRACE', name='load_image')
def load_image(path): ...

Functions

`is_env_tracing_enabled`(env_var)	Check whether tracing is enabled via the given environment variable.
`perf_logger`([name])	Return a dedicated logger for performance tracing.
`trace_env`(env_var, *[, name, logger_name])	Decorator factory that enables tracing via an environment variable.
`trace_if`(enabled, *[, name, logger])	Decorator factory for conditional tracing.

Classes

PerfTracer(name, *[, enabled, logger])

Context manager for measuring elapsed time of a traced step.

class radioviz.services.perf_tracing.PerfTracer(name: str, *, enabled: bool = True, logger: Logger | None = None, **fields: object)[source]

Bases: object

Context manager for measuring elapsed time of a traced step.

The tracer records elapsed time and logs it when enabled.

Initialize the tracer.

Parameters:

name (str) – Name of the traced step.
enabled (bool) – Whether tracing is enabled for this span.
logger (logging.Logger | None) – Logger to emit timing information.
fields (object) – Additional structured fields for logging.

_format_fields() → str[source]

Format fields into a key=value string.

Returns:: Joined field values.
Return type:: str

_format_message() → str[source]

Format the log message with optional fields.

Returns:: Formatted message.
Return type:: str

property elapsed_ms: float | None

Return the elapsed time in milliseconds.

Returns:: Elapsed milliseconds or None when disabled.
Return type:: Optional[float]

property enabled: bool

Return whether tracing is enabled for this instance.

Returns:: True when enabled, False otherwise.
Return type:: bool

radioviz.services.perf_tracing.is_env_tracing_enabled(env_var: str) → bool[source]

Check whether tracing is enabled via the given environment variable.

Parameters:: env_var (str) – Name of the environment variable.
Returns:: True when tracing is enabled, False otherwise.
Return type:: bool

radioviz.services.perf_tracing.perf_logger(name: str | None = None) → Logger[source]

Return a dedicated logger for performance tracing.

Parameters:: name (str | None) – Optional logger name override.
Returns:: Logger instance.
Return type:: logging.Logger

radioviz.services.perf_tracing.trace_env(env_var: str, *, name: str | None = None, logger_name: str | None = None, **fields: object) → Callable[[Callable[[P], R]], Callable[[P], R]][source]

Decorator factory that enables tracing via an environment variable.

Parameters:

env_var (str) – Name of the environment variable controlling tracing.
name (str | None) – Optional name override for the span.
logger_name (str | None) – Optional logger name override.
fields (object) – Additional structured fields for logging.

Returns:

Decorator.

Return type:

Callable

radioviz.services.perf_tracing.trace_if(enabled: bool, *, name: str | None = None, logger: Logger | None = None, **fields: object) → Callable[[Callable[[P], R]], Callable[[P], R]][source]

Decorator factory for conditional tracing.

Parameters:

enabled (bool) – Whether tracing is enabled.
name (str | None) – Optional name override for the span.
logger (logging.Logger | None) – Logger to emit timing information.
fields (object) – Additional structured fields for logging.

Returns:

Decorator.

Return type:

Callable