openspeechapi 0.1.0__py3-none-any.whl

openspeech/telemetry/perf.py

@@ -0,0 +1,307 @@
+"""Structured performance / milestone logging primitives.
+
+Two integration points are exposed:
+
+1. :class:`PerfTimer` — context manager that measures an operation's wall
+   time and emits an ``event`` record on exit.  Use for *phases* that have
+   a clear start/end (WS accept, provider init, streaming total, ...).
+
+2. :func:`milestone` — one-shot event emitter (TTFB, first frame, ...).
+
+Both helpers obey the global ``perf`` level configured in
+:mod:`openspeech.logging_config`:
+
+- ``off``:     :class:`PerfTimer` / :func:`milestone` become no-ops.
+- ``basic``:   milestones tagged ``basic`` (the default) are emitted.
+- ``verbose``: both ``basic`` and ``verbose`` milestones are emitted.
+
+An :class:`Event` enum holds the full event taxonomy.  New events should
+be added there and documented in ``docs/architecture/logging-spec.md`` so
+consumers (dashboards, LLM log analysis) have a stable vocabulary.
+"""
+from __future__ import annotations
+
+import functools
+import time
+from contextlib import contextmanager
+from enum import Enum
+from typing import Any, Awaitable, Callable, Iterator, TypeVar
+
+from openspeech.logging_config import logger
+
+from openspeech.logging_config import get_log_settings
+
+# ---------------------------------------------------------------------------
+# Event taxonomy
+# ---------------------------------------------------------------------------
+
+
+class Event(str, Enum):
+    """Canonical event names used in structured logs.
+
+    Names use dotted namespaces: ``<layer>.<phase>``.  Values are stable
+    strings — never rename once shipped; add new ones instead.
+    """
+
+    # ---- WebSocket layer -------------------------------------------------
+    WS_ACCEPT = "ws.accept"
+    WS_META_SENT = "ws.meta_sent"
+    WS_FIRST_AUDIO_FRAME = "ws.first_audio_frame"
+    WS_FIRST_RESPONSE = "ws.first_response"
+    WS_PARTIAL_SENT = "ws.partial_sent"
+    WS_FINAL_SENT = "ws.final_sent"
+    WS_CLOSED = "ws.closed"
+    WS_ERROR = "ws.error"
+    WS_TOTAL = "ws.total"
+
+    # ---- HTTP layer ------------------------------------------------------
+    HTTP_REQUEST_START = "http.request_start"
+    HTTP_REQUEST_END = "http.request_end"
+
+    # ---- Dispatcher layer -----------------------------------------------
+    DISPATCH_QUEUE_WAIT = "dispatch.queue_wait"
+    DISPATCH_EXECUTOR_ACQUIRE = "dispatch.executor_acquire"
+    DISPATCH_INVOKE_START = "dispatch.invoke_start"
+    DISPATCH_INVOKE_END = "dispatch.invoke_end"
+    DISPATCH_INVOKE_ERROR = "dispatch.invoke_error"
+    DISPATCH_TOTAL = "dispatch.total"
+    DISPATCH_STREAM_START = "dispatch.stream_start"
+    DISPATCH_STREAM_END = "dispatch.stream_end"
+
+    # ---- Lifecycle layer -------------------------------------------------
+    LIFECYCLE_PROVIDER_INIT = "lifecycle.provider_init"
+    LIFECYCLE_PROVIDER_WARMUP = "lifecycle.provider_warmup"
+    LIFECYCLE_PROVIDER_READY = "lifecycle.provider_ready"
+    LIFECYCLE_PROVIDER_STOP = "lifecycle.provider_stop"
+    LIFECYCLE_IDLE_RECYCLE = "lifecycle.idle_recycle"
+
+    # ---- Provider layer --------------------------------------------------
+    PROVIDER_CONNECT = "provider.connect"
+    PROVIDER_FIRST_CHUNK_SENT = "provider.first_chunk_sent"
+    PROVIDER_FIRST_PARTIAL = "provider.first_partial"
+    PROVIDER_FINAL = "provider.final"
+    PROVIDER_TOTAL = "provider.total"
+    PROVIDER_ERROR = "provider.error"
+
+    # ---- Audio utilities -------------------------------------------------
+    AUDIO_DECODE = "audio.decode"
+    AUDIO_ENCODE = "audio.encode"
+    AUDIO_RESAMPLE = "audio.resample"
+
+    def __str__(self) -> str:  # noqa: D401
+        return self.value
+
+
+# ---------------------------------------------------------------------------
+# Perf-level gating
+# ---------------------------------------------------------------------------
+
+_LEVELS = {"off": 0, "basic": 1, "verbose": 2}
+
+
+def perf_enabled(level: str = "basic") -> bool:
+    """Return True if a record at the given verbosity should be emitted."""
+    current = get_log_settings().perf
+    return _LEVELS.get(current, 1) >= _LEVELS.get(level, 1)
+
+
+# ---------------------------------------------------------------------------
+# Core helpers
+# ---------------------------------------------------------------------------
+
+
+def _coerce_event(event: Event | str) -> str:
+    if isinstance(event, Event):
+        return event.value
+    return str(event)
+
+
+def perf_event(
+    event: Event | str,
+    *,
+    level: str = "basic",
+    message: str | None = None,
+    **fields: Any,
+) -> None:
+    """Emit a structured perf event without a duration.
+
+    Equivalent to :func:`milestone`. Thin wrapper kept for readability when
+    the call site is clearly a "phase marker" rather than a "milestone".
+    """
+    milestone(event, level=level, message=message, **fields)
+
+
+def milestone(
+    event: Event | str,
+    *,
+    level: str = "basic",
+    message: str | None = None,
+    **fields: Any,
+) -> None:
+    """Emit a structured milestone event.
+
+    The event's ``level`` (``basic`` or ``verbose``) gates whether the
+    record is produced, based on the global ``perf`` setting.
+    """
+    if not perf_enabled(level):
+        return
+    evt_str = _coerce_event(event)
+    # ``event`` is a reserved attribute on loguru records, so we pass it as
+    # bound extra. Same for optional elapsed/ttfb fields.
+    bindings = {"event": evt_str}
+    for k in ("elapsed_ms", "ttfb_ms", "phase"):
+        if k in fields and fields[k] is not None:
+            bindings[k] = fields.pop(k)
+    msg = message or evt_str
+    logger.bind(**bindings, **fields).info(msg)
+
+
+# ---------------------------------------------------------------------------
+# PerfTimer
+# ---------------------------------------------------------------------------
+
+
+class PerfTimer:
+    """Context manager that times a phase and emits a structured event.
+
+    Usage::
+
+        with PerfTimer(Event.WS_TOTAL, level="basic", request_id=rid) as t:
+            ...
+            t.add(bytes_received=1024)
+            ...
+        # On exit, emits: event=ws.total elapsed_ms=...
+
+    Inside the block, :meth:`mark` records intermediate milestones (e.g.
+    TTFB) relative to the timer's start.
+    """
+
+    __slots__ = ("_event", "_level", "_fields", "_start_ns", "_ttfb_ns", "_active", "_message")
+
+    def __init__(
+        self,
+        event: Event | str,
+        *,
+        level: str = "basic",
+        message: str | None = None,
+        **fields: Any,
+    ) -> None:
+        self._event = _coerce_event(event)
+        self._level = level
+        self._message = message
+        self._fields: dict[str, Any] = dict(fields)
+        self._start_ns: int = 0
+        self._ttfb_ns: int | None = None
+        self._active = False
+
+    # -- context manager ---------------------------------------------------
+
+    def __enter__(self) -> "PerfTimer":
+        self._start_ns = time.perf_counter_ns()
+        self._active = perf_enabled(self._level)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # noqa: D401
+        self._emit(error=exc_val)
+
+    # -- accessors ---------------------------------------------------------
+
+    @property
+    def elapsed_ms(self) -> float:
+        return (time.perf_counter_ns() - self._start_ns) / 1_000_000
+
+    @property
+    def ttfb_ms(self) -> float | None:
+        if self._ttfb_ns is None:
+            return None
+        return (self._ttfb_ns - self._start_ns) / 1_000_000
+
+    def add(self, **fields: Any) -> None:
+        """Attach extra fields to be emitted on exit."""
+        self._fields.update(fields)
+
+    def mark_ttfb(self) -> float:
+        """Record first-byte/first-response time; returns ms since start."""
+        if self._ttfb_ns is None:
+            self._ttfb_ns = time.perf_counter_ns()
+        return self.ttfb_ms  # type: ignore[return-value]
+
+    def emit_milestone(
+        self,
+        event: Event | str,
+        *,
+        level: str = "basic",
+        **fields: Any,
+    ) -> None:
+        """Emit an intermediate milestone with ``elapsed_ms`` relative to this timer."""
+        elapsed = self.elapsed_ms
+        milestone(event, level=level, elapsed_ms=elapsed, **fields)
+
+    # -- internal ----------------------------------------------------------
+
+    def _emit(self, *, error: BaseException | None = None) -> None:
+        if not self._active:
+            return
+        elapsed = self.elapsed_ms
+        fields = dict(self._fields)
+        if self._ttfb_ns is not None:
+            fields["ttfb_ms"] = self.ttfb_ms
+        if error is not None:
+            fields["error_type"] = type(error).__name__
+            fields["error_message"] = str(error)
+        milestone(
+            self._event,
+            level=self._level,
+            message=self._message,
+            elapsed_ms=elapsed,
+            **fields,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Decorators
+# ---------------------------------------------------------------------------
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def timed(event: Event | str, *, level: str = "basic"):
+    """Decorator: time a sync function and emit an event on return."""
+
+    def _wrap(fn: F) -> F:
+        @functools.wraps(fn)
+        def inner(*args: Any, **kwargs: Any) -> Any:
+            with PerfTimer(event, level=level):
+                return fn(*args, **kwargs)
+        return inner  # type: ignore[return-value]
+
+    return _wrap
+
+
+def timed_async(event: Event | str, *, level: str = "basic"):
+    """Decorator: time an async coroutine and emit an event on return."""
+
+    def _wrap(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+        @functools.wraps(fn)
+        async def inner(*args: Any, **kwargs: Any) -> Any:
+            with PerfTimer(event, level=level):
+                return await fn(*args, **kwargs)
+        return inner
+
+    return _wrap
+
+
+__all__ = [
+    "Event",
+    "PerfTimer",
+    "milestone",
+    "perf_enabled",
+    "perf_event",
+    "timed",
+    "timed_async",
+]
+
+
+@contextmanager
+def _noop() -> Iterator[None]:
+    yield

openspeech/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility helpers for OpenSpeech."""
+
+from openspeech.utils.audio_playback import list_output_devices, play_audio
+
+__all__ = ["list_output_devices", "play_audio"]