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

haiway/__init__.py

@@ -1,22 +1,25 @@
 from haiway.context import (
     Disposable,
     Disposables,
-    MetricsContext,
-    MetricsHandler,
-    MetricsRecording,
-    MetricsScopeEntering,
-    MetricsScopeExiting,
     MissingContext,
     MissingState,
+    Observability,
+    ObservabilityAttribute,
+    ObservabilityAttributesRecording,
+    ObservabilityContext,
+    ObservabilityEventRecording,
+    ObservabilityLevel,
+    ObservabilityLogRecording,
+    ObservabilityMetricRecording,
+    ObservabilityScopeEntering,
+    ObservabilityScopeExiting,
     ScopeContext,
     ScopeIdentifier,
     StateContext,
     ctx,
 )
 from haiway.helpers import (
-    ArgumentsTrace,
-    MetricsHolder,
-    MetricsLogger,
+    LoggerObservability,
     ResultTrace,
     asynchronous,
     cache,
@@ -60,9 +63,8 @@ from haiway.utils import (
     without_missing,
 )
 
-__all__ = [
+__all__ = (
     "MISSING",
-    "ArgumentsTrace",
     "AsyncQueue",
     "AsyncStream",
     "AttributePath",
@@ -71,16 +73,20 @@ __all__ = [
     "DefaultValue",
     "Disposable",
     "Disposables",
-    "MetricsContext",
-    "MetricsHandler",
-    "MetricsHolder",
-    "MetricsLogger",
-    "MetricsRecording",
-    "MetricsScopeEntering",
-    "MetricsScopeExiting",
+    "LoggerObservability",
     "Missing",
     "MissingContext",
     "MissingState",
+    "Observability",
+    "ObservabilityAttribute",
+    "ObservabilityAttributesRecording",
+    "ObservabilityContext",
+    "ObservabilityEventRecording",
+    "ObservabilityLevel",
+    "ObservabilityLogRecording",
+    "ObservabilityMetricRecording",
+    "ObservabilityScopeEntering",
+    "ObservabilityScopeExiting",
     "ResultTrace",
     "ScopeContext",
     "ScopeIdentifier",
@@ -116,4 +122,4 @@ __all__ = [
     "when_missing",
     "without_missing",
     "wrap_async",
-]
+)

haiway/context/__init__.py

@@ -1,28 +1,38 @@
 from haiway.context.access import ScopeContext, ctx
 from haiway.context.disposables import Disposable, Disposables
 from haiway.context.identifier import ScopeIdentifier
-from haiway.context.metrics import (
-    MetricsContext,
-    MetricsHandler,
-    MetricsRecording,
-    MetricsScopeEntering,
-    MetricsScopeExiting,
+from haiway.context.observability import (
+    Observability,
+    ObservabilityAttribute,
+    ObservabilityAttributesRecording,
+    ObservabilityContext,
+    ObservabilityEventRecording,
+    ObservabilityLevel,
+    ObservabilityLogRecording,
+    ObservabilityMetricRecording,
+    ObservabilityScopeEntering,
+    ObservabilityScopeExiting,
 )
 from haiway.context.state import StateContext
 from haiway.context.types import MissingContext, MissingState
 
-__all__ = [
+__all__ = (
     "Disposable",
     "Disposables",
-    "MetricsContext",
-    "MetricsHandler",
-    "MetricsRecording",
-    "MetricsScopeEntering",
-    "MetricsScopeExiting",
     "MissingContext",
     "MissingState",
+    "Observability",
+    "ObservabilityAttribute",
+    "ObservabilityAttributesRecording",
+    "ObservabilityContext",
+    "ObservabilityEventRecording",
+    "ObservabilityLevel",
+    "ObservabilityLogRecording",
+    "ObservabilityMetricRecording",
+    "ObservabilityScopeEntering",
+    "ObservabilityScopeExiting",
     "ScopeContext",
     "ScopeIdentifier",
     "StateContext",
     "ctx",
-]
+)

haiway/context/access.py

@@ -18,17 +18,19 @@ from typing import Any, final, overload
 
 from haiway.context.disposables import Disposable, Disposables
 from haiway.context.identifier import ScopeIdentifier
-from haiway.context.logging import LoggerContext
-from haiway.context.metrics import MetricsContext, MetricsHandler
+from haiway.context.observability import (
+    Observability,
+    ObservabilityAttribute,
+    ObservabilityContext,
+    ObservabilityLevel,
+)
 from haiway.context.state import ScopeState, StateContext
 from haiway.context.tasks import TaskGroupContext
 from haiway.state import State
 from haiway.utils import mimic_function
 from haiway.utils.stream import AsyncStream
 
-__all__ = [
-    "ctx",
-]
+__all__ = ("ctx",)
 
 
 @final
@@ -36,8 +38,7 @@ class ScopeContext:
     __slots__ = (
         "_disposables",
         "_identifier",
-        "_logger_context",
-        "_metrics_context",
+        "_observability_context",
         "_state_context",
         "_task_group_context",
     )
@@ -45,11 +46,10 @@ class ScopeContext:
     def __init__(
         self,
         label: str,
-        logger: Logger | None,
         task_group: TaskGroup | None,
         state: tuple[State, ...],
         disposables: Disposables | None,
-        metrics: MetricsHandler | None,
+        observability: Observability | Logger | None,
     ) -> None:
         self._identifier: ScopeIdentifier
         object.__setattr__(
@@ -57,23 +57,6 @@ class ScopeContext:
             "_identifier",
             ScopeIdentifier.scope(label),
         )
-        self._logger_context: LoggerContext
-        object.__setattr__(
-            self,
-            "_logger_context",
-            LoggerContext(
-                self._identifier,
-                logger=logger,
-            ),
-        )
-        self._task_group_context: TaskGroupContext | None
-        object.__setattr__(
-            self,
-            "_task_group_context",
-            TaskGroupContext(task_group=task_group)
-            if task_group is not None or self._identifier.is_root
-            else None,
-        )
         # prepare state context to capture current state
         self._state_context: StateContext
         object.__setattr__(
@@ -87,16 +70,24 @@ class ScopeContext:
             "_disposables",
             disposables,
         )
-        self._metrics_context: MetricsContext
+        self._observability_context: ObservabilityContext
         object.__setattr__(
             self,
-            "_metrics_context",
-            # pre-building metrics context to ensure nested context registering
-            MetricsContext.scope(
+            "_observability_context",
+            # pre-building observability context to ensure nested context registering
+            ObservabilityContext.scope(
                 self._identifier,
-                metrics=metrics,
+                observability=observability,
             ),
         )
+        self._task_group_context: TaskGroupContext | None
+        object.__setattr__(
+            self,
+            "_task_group_context",
+            TaskGroupContext(task_group=task_group)
+            if task_group is not None or self._identifier.is_root
+            else None,
+        )
 
     def __setattr__(
         self,
@@ -123,9 +114,8 @@ class ScopeContext:
         ), "Can't enter synchronous context with task group"
         assert self._disposables is None, "Can't enter synchronous context with disposables"  # nosec: B101
         self._identifier.__enter__()
-        self._logger_context.__enter__()
+        self._observability_context.__enter__()
         self._state_context.__enter__()
-        self._metrics_context.__enter__()
 
         return self._identifier.trace_id
 
@@ -135,24 +125,16 @@ class ScopeContext:
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
-        self._metrics_context.__exit__(
-            exc_type=exc_type,
-            exc_val=exc_val,
-            exc_tb=exc_tb,
-        )
-
         self._state_context.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
             exc_tb=exc_tb,
         )
-
-        self._logger_context.__exit__(
+        self._observability_context.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
             exc_tb=exc_tb,
         )
-
         self._identifier.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
@@ -161,7 +143,7 @@ class ScopeContext:
 
     async def __aenter__(self) -> str:
         self._identifier.__enter__()
-        self._logger_context.__enter__()
+        self._observability_context.__enter__()
 
         if task_group := self._task_group_context:
             await task_group.__aenter__()
@@ -183,7 +165,6 @@ class ScopeContext:
             )
 
         self._state_context.__enter__()
-        self._metrics_context.__enter__()
 
         return self._identifier.trace_id
 
@@ -207,19 +188,13 @@ class ScopeContext:
                 exc_tb=exc_tb,
             )
 
-        self._metrics_context.__exit__(
-            exc_type=exc_type,
-            exc_val=exc_val,
-            exc_tb=exc_tb,
-        )
-
         self._state_context.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
             exc_tb=exc_tb,
         )
 
-        self._logger_context.__exit__(
+        self._observability_context.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
             exc_tb=exc_tb,
@@ -288,9 +263,8 @@ class ctx:
         /,
         *state: State,
         disposables: Disposables | Iterable[Disposable] | None = None,
-        logger: Logger | None = None,
         task_group: TaskGroup | None = None,
-        metrics: MetricsHandler | None = None,
+        observability: Observability | Logger | None = None,
     ) -> ScopeContext:
         """
         Prepare scope context with given parameters. When called within an existing context\
@@ -310,18 +284,14 @@ class ctx:
              be added to the scope state. Using asynchronous context is required if any disposables\
              were provided.
 
-        logger: Logger | None
-            logger used within the scope context, when not provided current logger will be used\
-             if any, otherwise the logger with the scope name will be requested.
-
         task_group: TaskGroup | None
             task group used for spawning and joining tasks within the context. Root scope will
              always have task group created even when not set.
 
-        metrics_store: MetricsStore | None = None
-            metrics storage solution responsible for recording and storing metrics.\
-             Metrics recroding will be ignored if storage is not provided.
-            Assigning metrics_store within existing context will result in an error.
+        observability: Observability | Logger | None = None
+            observability solution responsible for recording and storing metrics, logs and events.\
+             Assigning observability within existing context will result in an error.
+            When not provided, logger with the scope name will be requested and used.
 
         Returns
         -------
@@ -343,11 +313,10 @@ class ctx:
 
         return ScopeContext(
             label=label,
-            logger=logger,
             task_group=task_group,
             state=state,
             disposables=resolved_disposables,
-            metrics=metrics,
+            observability=observability,
         )
 
     @staticmethod
@@ -492,33 +461,13 @@ class ctx:
             default=default,
         )
 
-    @staticmethod
-    def record(
-        metric: State,
-        /,
-    ) -> None:
-        """
-        Record metric within current scope context.
-
-        Parameters
-        ----------
-        metric: State
-            value of metric to be recorded. When a metric implements __add__ it will be added to\
-             current value if any, otherwise subsequent calls may replace existing value.
-
-        Returns
-        -------
-        None
-        """
-
-        MetricsContext.record(metric)
-
     @staticmethod
     def log_error(
         message: str,
         /,
         *args: Any,
         exception: BaseException | None = None,
+        **extra: Any,
     ) -> None:
         """
         Log using ERROR level within current scope context. When there is no current scope\
@@ -540,10 +489,12 @@ class ctx:
         None
         """
 
-        LoggerContext.log_error(
+        ObservabilityContext.record_log(
+            ObservabilityLevel.ERROR,
             message,
             *args,
             exception=exception,
+            **extra,
         )
 
     @staticmethod
@@ -552,6 +503,7 @@ class ctx:
         /,
         *args: Any,
         exception: Exception | None = None,
+        **extra: Any,
     ) -> None:
         """
         Log using WARNING level within current scope context. When there is no current scope\
@@ -573,10 +525,12 @@ class ctx:
         None
         """
 
-        LoggerContext.log_warning(
+        ObservabilityContext.record_log(
+            ObservabilityLevel.WARNING,
             message,
             *args,
             exception=exception,
+            **extra,
         )
 
     @staticmethod
@@ -584,6 +538,7 @@ class ctx:
         message: str,
         /,
         *args: Any,
+        **extra: Any,
     ) -> None:
         """
         Log using INFO level within current scope context. When there is no current scope\
@@ -602,9 +557,12 @@ class ctx:
         None
         """
 
-        LoggerContext.log_info(
+        ObservabilityContext.record_log(
+            ObservabilityLevel.INFO,
             message,
             *args,
+            exception=None,
+            **extra,
         )
 
     @staticmethod
@@ -613,6 +571,7 @@ class ctx:
         /,
         *args: Any,
         exception: Exception | None = None,
+        **extra: Any,
     ) -> None:
         """
         Log using DEBUG level within current scope context. When there is no current scope\
@@ -634,8 +593,85 @@ class ctx:
         None
         """
 
-        LoggerContext.log_debug(
-            message,
-            *args,
-            exception=exception,
+        ObservabilityContext.record_log(
+            ObservabilityLevel.DEBUG, message, *args, exception=exception, **extra
+        )
+
+    @staticmethod
+    def event(
+        event: State,
+        /,
+        *,
+        level: ObservabilityLevel = ObservabilityLevel.INFO,
+        **extra: Any,
+    ) -> None:
+        """
+        Record event within current scope context.
+
+        Parameters
+        ----------
+        event: State
+            contents of event to be recorded.
+
+        Returns
+        -------
+        None
+        """
+
+        ObservabilityContext.record_event(
+            event,
+            level=level,
+            **extra,
+        )
+
+    @staticmethod
+    def metric(
+        metric: str,
+        /,
+        *,
+        value: float | int,
+        unit: str | None = None,
+        **extra: Any,
+    ) -> None:
+        """
+        Record metric within current scope context.
+
+        Parameters
+        ----------
+        metric: State
+            name of metric to be recorded.
+        value: float | int
+            value of metric to be recorded.
+        unit: str | None = None
+            unit of metric to be recorded.
+
+        Returns
+        -------
+        None
+        """
+
+        ObservabilityContext.record_metric(
+            metric,
+            value=value,
+            unit=unit,
+            **extra,
+        )
+
+    @staticmethod
+    def attributes(**attributes: ObservabilityAttribute) -> None:
+        """
+        Record attributes within current scope context.
+
+        Parameters
+        ----------
+        **attributes: ObservabilityAttribute,
+            attributes to be recorded within current context.
+
+        Returns
+        -------
+        None
+        """
+
+        ObservabilityContext.record_attributes(
+            **attributes,
         )

haiway/context/disposables.py

@@ -7,10 +7,10 @@ from typing import Any, final
 
 from haiway.state import State
 
-__all__ = [
+__all__ = (
     "Disposable",
     "Disposables",
-]
+)
 
 type Disposable = AbstractAsyncContextManager[Iterable[State] | State | None]
 

haiway/context/identifier.py

@@ -3,9 +3,7 @@ from types import TracebackType
 from typing import Any, Self, final
 from uuid import uuid4
 
-__all__ = [
-    "ScopeIdentifier",
-]
+__all__ = ("ScopeIdentifier",)
 
 
 @final
@@ -33,10 +31,11 @@ class ScopeIdentifier:
         except LookupError:
             # create root scope when missing
             trace_id: str = uuid4().hex
+            scope_id: str = uuid4().hex
             return cls(
                 label=label,
-                scope_id=uuid4().hex,
-                parent_id=trace_id,  # trace_id is parent_id for root
+                scope_id=scope_id,
+                parent_id=scope_id,  # own id is parent_id for root
                 trace_id=trace_id,
             )