haiway 0.17.0__py3-none-any.whl → 0.18.0__py3-none-any.whl

haiway/helpers/observability.py

@@ -0,0 +1,219 @@
+from logging import Logger
+from time import monotonic
+from typing import Any
+
+from haiway.context import Observability, ObservabilityLevel, ScopeIdentifier
+from haiway.state import State
+
+__all__ = ("LoggerObservability",)
+
+
+class ScopeStore:
+    __slots__ = (
+        "_completed",
+        "_exited",
+        "entered",
+        "identifier",
+        "nested",
+        "store",
+    )
+
+    def __init__(
+        self,
+        identifier: ScopeIdentifier,
+        /,
+    ) -> None:
+        self.identifier: ScopeIdentifier = identifier
+        self.nested: list[ScopeStore] = []
+        self.entered: float = monotonic()
+        self._exited: float | None = None
+        self._completed: float | None = None
+        self.store: list[str] = []
+
+    @property
+    def time(self) -> float:
+        return (self._completed or monotonic()) - self.entered
+
+    @property
+    def exited(self) -> bool:
+        return self._exited is not None
+
+    def exit(self) -> None:
+        assert self._exited is None  # nosec: B101
+        self._exited = monotonic()
+
+    @property
+    def completed(self) -> bool:
+        return self._completed is not None and all(nested.completed for nested in self.nested)
+
+    def try_complete(self) -> bool:
+        if self._exited is None:
+            return False  # not elegible for completion yet
+
+        if self._completed is not None:
+            return False  # already completed
+
+        if not all(nested.completed for nested in self.nested):
+            return False  # nested not completed
+
+        self._completed = monotonic()
+        return True  # successfully completed
+
+
+def LoggerObservability(  # noqa: C901
+    logger: Logger,
+    /,
+    *,
+    summarize_context: bool = __debug__,
+) -> Observability:
+    root_scope: ScopeIdentifier | None = None
+    scopes: dict[str, ScopeStore] = {}
+
+    def log_recording(
+        scope: ScopeIdentifier,
+        /,
+        level: ObservabilityLevel,
+        message: str,
+        *args: Any,
+        exception: BaseException | None,
+    ) -> None:
+        assert root_scope is not None  # nosec: B101
+        assert scope.scope_id in scopes  # nosec: B101
+
+        logger.log(
+            level,
+            f"{scope.unique_name} {message}",
+            *args,
+            exc_info=exception,
+        )
+
+    def event_recording(
+        scope: ScopeIdentifier,
+        /,
+        *,
+        level: ObservabilityLevel,
+        event: State,
+    ) -> None:
+        assert root_scope is not None  # nosec: B101
+        assert scope.scope_id in scopes  # nosec: B101
+
+        event_str: str = f"Event:\n{event.to_str(pretty=True)}"
+        if summarize_context:  # store only for summary
+            scopes[scope.scope_id].store.append(event_str)
+
+        logger.log(
+            level,
+            f"{scope.unique_name} {event_str}",
+        )
+
+    def metric_recording(
+        scope: ScopeIdentifier,
+        /,
+        *,
+        metric: str,
+        value: float | int,
+        unit: str | None,
+    ) -> None:
+        assert root_scope is not None  # nosec: B101
+        assert scope.scope_id in scopes  # nosec: B101
+
+        metric_str: str = f"Metric - {metric}:{value}{unit or ''}"
+        if summarize_context:  # store only for summary
+            scopes[scope.scope_id].store.append(metric_str)
+
+        logger.log(
+            ObservabilityLevel.INFO,
+            f"{scope.unique_name} {metric_str}",
+        )
+
+    def scope_entering[Metric: State](
+        scope: ScopeIdentifier,
+        /,
+    ) -> None:
+        assert scope.scope_id not in scopes  # nosec: B101
+        scope_store: ScopeStore = ScopeStore(scope)
+        scopes[scope.scope_id] = scope_store
+
+        logger.log(
+            ObservabilityLevel.INFO,
+            f"{scope.unique_name} Entering scope: {scope.label}",
+        )
+
+        nonlocal root_scope
+        if root_scope is None:
+            root_scope = scope
+
+        else:
+            scopes[scope.parent_id].nested.append(scope_store)
+
+    def scope_exiting[Metric: State](
+        scope: ScopeIdentifier,
+        /,
+        *,
+        exception: BaseException | None,
+    ) -> None:
+        nonlocal root_scope
+        nonlocal scopes
+        assert root_scope is not None  # nosec: B101
+        assert scope.scope_id in scopes  # nosec: B101
+
+        scopes[scope.scope_id].exit()
+
+        if not scopes[scope.scope_id].try_complete():
+            return  # not completed yet or already completed
+
+        logger.log(
+            ObservabilityLevel.INFO,
+            f"{scope.unique_name} Exiting scope: {scope.label}",
+        )
+        metric_str: str = f"Metric - scope_time:{scopes[scope.scope_id].time:.3f}s"
+        if summarize_context:  # store only for summary
+            scopes[scope.scope_id].store.append(metric_str)
+
+        logger.log(
+            ObservabilityLevel.INFO,
+            f"{scope.unique_name} {metric_str}",
+        )
+
+        # try complete parent scopes
+        parent_id: str = scope.parent_id
+        while scopes[parent_id].try_complete():
+            parent_id = scopes[parent_id].identifier.parent_id
+
+        # check for root completion
+        if scopes[root_scope.scope_id].completed:
+            if summarize_context:
+                logger.log(
+                    ObservabilityLevel.DEBUG,
+                    f"Observability summary:\n{_tree_summary(scopes[root_scope.scope_id])}",
+                )
+
+            # finished root - cleanup state
+            root_scope = None
+            scopes = {}
+
+    return Observability(
+        log_recording=log_recording,
+        event_recording=event_recording,
+        metric_recording=metric_recording,
+        scope_entering=scope_entering,
+        scope_exiting=scope_exiting,
+    )
+
+
+def _tree_summary(scope_store: ScopeStore) -> str:
+    elements: list[str] = [
+        f"┍━ {scope_store.identifier.label} [{scope_store.identifier.scope_id}]:"
+    ]
+    for element in scope_store.store:
+        if not element:
+            continue  # skip empty
+
+        elements.append(f"┝ {element.replace('\n', '\n|  ')}")
+
+    for nested in scope_store.nested:
+        nested_summary: str = _tree_summary(nested)
+
+        elements.append(f"|  {nested_summary.replace('\n', '\n|  ')}")
+
+    return "\n".join(elements) + "\n┕━"

haiway/helpers/retries.py

@@ -6,9 +6,7 @@ from typing import Any, cast, overload
 from haiway.context import ctx
 from haiway.utils import mimic_function
 
-__all__ = [
-    "retry",
-]
+__all__ = ("retry",)
 
 
 @overload

haiway/helpers/throttling.py

@@ -11,9 +11,7 @@ from typing import Any, cast, overload
 
 from haiway.utils.mimic import mimic_function
 
-__all__ = [
-    "throttle",
-]
+__all__ = ("throttle",)
 
 
 @overload

haiway/helpers/timeouted.py

@@ -4,9 +4,7 @@ from typing import Any
 
 from haiway.utils.mimic import mimic_function
 
-__all__ = [
-    "timeout",
-]
+__all__ = ("timeout",)
 
 
 def timeout[**Args, Result](

haiway/helpers/tracing.py

@@ -1,5 +1,5 @@
 from asyncio import iscoroutinefunction
-from collections.abc import Callable, Coroutine, Mapping, Sequence
+from collections.abc import Callable, Coroutine, Sequence
 from typing import Any, Self, cast, overload
 
 from haiway.context import ctx
@@ -7,34 +7,42 @@ from haiway.state import State
 from haiway.types import MISSING, Missing
 from haiway.utils import mimic_function
 
-__all__ = [
+__all__ = (
     "ArgumentsTrace",
     "ResultTrace",
     "traced",
-]
+)
 
 
 class ArgumentsTrace(State):
     if __debug__:
 
         @classmethod
-        def of(cls, *args: Any, **kwargs: Any) -> Self:
+        def of(
+            cls,
+            *args: Any,
+            **kwargs: Any,
+        ) -> Self:
             return cls(
-                args=args if args else MISSING,
-                kwargs=kwargs if kwargs else MISSING,
+                args=[f"{arg}" for arg in args] if args else MISSING,
+                kwargs=[f"{key}:{arg}" for key, arg in kwargs.items()] if kwargs else MISSING,
             )
 
     else:  # remove tracing for non debug runs to prevent accidental secret leaks
 
         @classmethod
-        def of(cls, *args: Any, **kwargs: Any) -> Self:
+        def of(
+            cls,
+            *args: Any,
+            **kwargs: Any,
+        ) -> Self:
             return cls(
                 args=MISSING,
                 kwargs=MISSING,
             )
 
-    args: Sequence[Any] | Missing
-    kwargs: Mapping[str, Any] | Missing
+    args: Sequence[str] | Missing
+    kwargs: Sequence[str] | Missing
 
 
 class ResultTrace(State):
@@ -46,7 +54,7 @@ class ResultTrace(State):
             value: Any,
             /,
         ) -> Self:
-            return cls(result=value)
+            return cls(result=f"{value}")
 
     else:  # remove tracing for non debug runs to prevent accidental secret leaks
 
@@ -58,7 +66,7 @@ class ResultTrace(State):
         ) -> Self:
             return cls(result=MISSING)
 
-    result: Any | Missing
+    result: str | Missing
 
 
 @overload
@@ -120,14 +128,14 @@ def _traced_sync[**Args, Result](
         **kwargs: Args.kwargs,
     ) -> Result:
         with ctx.scope(label):
-            ctx.record(ArgumentsTrace.of(*args, **kwargs))
+            ctx.event(ArgumentsTrace.of(*args, **kwargs))
             try:
                 result: Result = function(*args, **kwargs)
-                ctx.record(ResultTrace.of(result))
+                ctx.event(ResultTrace.of(result))
                 return result
 
             except BaseException as exc:
-                ctx.record(ResultTrace.of(f"{type(exc)}: {exc}"))
+                ctx.event(ResultTrace.of(f"{type(exc)}: {exc}"))
                 raise exc
 
     return mimic_function(
@@ -146,14 +154,14 @@ def _traced_async[**Args, Result](
         **kwargs: Args.kwargs,
     ) -> Result:
         with ctx.scope(label):
-            ctx.record(ArgumentsTrace.of(*args, **kwargs))
+            ctx.event(ArgumentsTrace.of(*args, **kwargs))
             try:
                 result: Result = await function(*args, **kwargs)
-                ctx.record(ResultTrace.of(result))
+                ctx.event(ResultTrace.of(result))
                 return result
 
             except BaseException as exc:
-                ctx.record(ResultTrace.of(f"{type(exc)}: {exc}"))
+                ctx.event(ResultTrace.of(f"{type(exc)}: {exc}"))
                 raise exc
 
     return mimic_function(

haiway/opentelemetry/__init__.py

@@ -0,0 +1,3 @@
+from haiway.opentelemetry.observability import OpenTelemetry
+
+__all__ = ("OpenTelemetry",)