Pythonpythondecoratormonitoringperformanceproduction-ready

Execution Timing Decorator

A flexible timing decorator that captures execution duration, emits metrics, supports async functions, and integrates with logging.

import time
import functools
import asyncio
import logging
from typing import TypeVar, Callable, ParamSpec, overload, Any
from contextlib import contextmanager
from dataclasses import dataclass, field

P = ParamSpec("P")
R = TypeVar("R")

logger = logging.getLogger(__name__)


@dataclass
class TimingStats:
    """Accumulated timing statistics for a function."""
    name: str
    call_count: int = 0
    total_ms: float = 0.0
    min_ms: float = float("inf")
    max_ms: float = 0.0
    _durations: list[float] = field(default_factory=list, repr=False)

    def record(self, duration_ms: float) -> None:
        self.call_count += 1
        self.total_ms += duration_ms
        self.min_ms = min(self.min_ms, duration_ms)
        self.max_ms = max(self.max_ms, duration_ms)
        self._durations.append(duration_ms)

    @property
    def avg_ms(self) -> float:
        return self.total_ms / self.call_count if self.call_count > 0 else 0.0

    @property
    def p95_ms(self) -> float:
        if not self._durations:
            return 0.0
        sorted_d = sorted(self._durations)
        idx = int(len(sorted_d) * 0.95)
        return sorted_d[min(idx, len(sorted_d) - 1)]

    def __repr__(self) -> str:
        return (
            f"TimingStats({self.name}: calls={self.call_count}, "
            f"avg={self.avg_ms:.2f}ms, p95={self.p95_ms:.2f}ms, "
            f"min={self.min_ms:.2f}ms, max={self.max_ms:.2f}ms)"
        )


# Global stats registry
_stats_registry: dict[str, TimingStats] = {}


def get_all_stats() -> dict[str, TimingStats]:
    return dict(_stats_registry)


def timed(
    name: str | None = None,
    *,
    log_level: int = logging.DEBUG,
    slow_threshold_ms: float | None = None,
    emit_metric: Callable[[str, float], None] | None = None,
):
    """Decorator that times function execution with optional alerting.

    Args:
        name: Custom name for the timer (defaults to function qualname)
        log_level: Logging level for timing messages
        slow_threshold_ms: Log a warning if execution exceeds this threshold
        emit_metric: Callback to emit timing to external metrics system
    """
    def decorator(func: Callable[P, R]) -> Callable[P, R]:
        timer_name = name or func.__qualname__
        stats = TimingStats(name=timer_name)
        _stats_registry[timer_name] = stats

        if asyncio.iscoroutinefunction(func):
            @functools.wraps(func)
            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
                start = time.perf_counter()
                try:
                    return await func(*args, **kwargs)
                finally:
                    duration_ms = (time.perf_counter() - start) * 1000
                    stats.record(duration_ms)
                    logger.log(log_level, "%s completed in %.2fms", timer_name, duration_ms)
                    if slow_threshold_ms and duration_ms > slow_threshold_ms:
                        logger.warning("%s is slow: %.2fms (threshold: %.2fms)", timer_name, duration_ms, slow_threshold_ms)
                    if emit_metric:
                        emit_metric(timer_name, duration_ms)
            return async_wrapper  # type: ignore
        else:
            @functools.wraps(func)
            def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
                start = time.perf_counter()
                try:
                    return func(*args, **kwargs)
                finally:
                    duration_ms = (time.perf_counter() - start) * 1000
                    stats.record(duration_ms)
                    logger.log(log_level, "%s completed in %.2fms", timer_name, duration_ms)
                    if slow_threshold_ms and duration_ms > slow_threshold_ms:
                        logger.warning("%s is slow: %.2fms (threshold: %.2fms)", timer_name, duration_ms, slow_threshold_ms)
                    if emit_metric:
                        emit_metric(timer_name, duration_ms)
            sync_wrapper.stats = stats  # type: ignore
            return sync_wrapper

    return decorator


@contextmanager
def timer(name: str = "block"):
    """Context manager for timing code blocks."""
    start = time.perf_counter()
    yield
    duration_ms = (time.perf_counter() - start) * 1000
    logger.debug("%s completed in %.2fms", name, duration_ms)

title: "Execution Timing Decorator" description: "A flexible timing decorator that captures execution duration, emits metrics, supports async functions, and integrates with logging." category: "Python" language: "python" tags: ["python", "decorator", "monitoring", "performance", "production-ready"] createdAt: "2025-02-12" updatedAt: "2025-03-01"

Overview

A timing decorator that tracks execution duration, accumulates statistics (min, max, avg, p95), alerts on slow executions, and optionally emits metrics to external systems. Works with both sync and async functions.

Code

@timed(slow_threshold_ms=100)
def slow_operation():
    ...
 
with timer("block_name"):
    ...

Notes

  • time.perf_counter() provides the highest resolution timer available on the platform
  • The stats registry enables a /metrics endpoint to expose all timing data
  • slow_threshold_ms triggers WARNING-level logs for performance regression detection
  • The emit_metric callback integrates with DataDog, Prometheus, or StatsD
  • Supports both sync and async functions via asyncio.iscoroutinefunction detection