monitaudit 0.1.0__py3-none-any.whl

monitaudit/__init__.py

@@ -0,0 +1,23 @@
+# src/monitaudit/__init__.py
+
+from __future__ import annotations
+
+from .logger import monitauditLogger
+from .models.context import LogContext
+from .models.monitaudit import Observability
+from .sinks import (
+    ConsoleSink,
+    DeltaSink,
+    FileSink,
+    JsonSink,
+)
+
+__all__ = [
+    "ConsoleSink",
+    "DeltaSink",
+    "FileSink",
+    "JsonSink",
+    "LogContext",
+    "Observability",
+    "monitauditLogger",
+]

monitaudit/constants.py

@@ -0,0 +1,15 @@
+# src/monitaudit/constants.py
+
+from __future__ import annotations
+
+
+FUNCTION_START = "function_start"
+FUNCTION_END = "function_end"
+FUNCTION_ERROR = "function_error"
+
+
+__all__ = [
+    "FUNCTION_START",
+    "FUNCTION_END",
+    "FUNCTION_ERROR",
+]

monitaudit/logger.py

@@ -0,0 +1,449 @@
+# src/monitaudit/logger.py
+
+from __future__ import annotations
+
+import inspect
+import sys
+import traceback
+from typing import Any, Literal, cast
+
+from monitaudit.models.base import BaseLog
+from monitaudit.models.context import LogContext
+from monitaudit.models.log import (
+    CriticalLog,
+    DebugLog,
+    ErrorLog,
+    InfoLog,
+    WarningLog,
+)
+from monitaudit.sinks.base import Sink
+from monitaudit.utilities.json_safe import json_safe_dict
+
+
+SinkFailureMode = Literal[
+    "continue",
+    "raise",
+]
+
+StandardLog = DebugLog | InfoLog | WarningLog
+StandardLogType = (
+    type[DebugLog]
+    | type[InfoLog]
+    | type[WarningLog]
+)
+
+ExceptionLog = ErrorLog | CriticalLog
+ExceptionLogType = (
+    type[ErrorLog]
+    | type[CriticalLog]
+)
+
+
+class monitauditLogger:
+    def __init__(
+        self,
+        context: LogContext,
+        *sinks: Sink,
+        sink_failure_mode: SinkFailureMode = "continue",
+    ) -> None:
+        self.context: LogContext = context
+        self.sinks: tuple[Sink, ...] = sinks
+        self.sink_failure_mode: SinkFailureMode = (
+            sink_failure_mode
+        )
+
+    def debug(
+        self,
+        message: str,
+        *,
+        call_id: str | None = None,
+        parent_call_id: str | None = None,
+        parameters: dict[str, Any] | None = None,
+        duration_ms: float | None = None,
+        module: str | None = None,
+        function: str | None = None,
+        **attributes: Any,
+    ) -> DebugLog:
+        return cast(
+            DebugLog,
+            self._log(
+                DebugLog,
+                message,
+                call_id=call_id,
+                parent_call_id=parent_call_id,
+                parameters=parameters,
+                duration_ms=duration_ms,
+                module=module,
+                function=function,
+                attributes=attributes,
+            ),
+        )
+
+    def info(
+        self,
+        message: str,
+        *,
+        call_id: str | None = None,
+        parent_call_id: str | None = None,
+        parameters: dict[str, Any] | None = None,
+        duration_ms: float | None = None,
+        module: str | None = None,
+        function: str | None = None,
+        **attributes: Any,
+    ) -> InfoLog:
+        return cast(
+            InfoLog,
+            self._log(
+                InfoLog,
+                message,
+                call_id=call_id,
+                parent_call_id=parent_call_id,
+                parameters=parameters,
+                duration_ms=duration_ms,
+                module=module,
+                function=function,
+                attributes=attributes,
+            ),
+        )
+
+    def warning(
+        self,
+        message: str,
+        *,
+        call_id: str | None = None,
+        parent_call_id: str | None = None,
+        parameters: dict[str, Any] | None = None,
+        duration_ms: float | None = None,
+        module: str | None = None,
+        function: str | None = None,
+        **attributes: Any,
+    ) -> WarningLog:
+        return cast(
+            WarningLog,
+            self._log(
+                WarningLog,
+                message,
+                call_id=call_id,
+                parent_call_id=parent_call_id,
+                parameters=parameters,
+                duration_ms=duration_ms,
+                module=module,
+                function=function,
+                attributes=attributes,
+            ),
+        )
+
+    def error(
+        self,
+        message: str,
+        *,
+        exception: BaseException | None = None,
+        call_id: str | None = None,
+        parent_call_id: str | None = None,
+        parameters: dict[str, Any] | None = None,
+        duration_ms: float | None = None,
+        module: str | None = None,
+        function: str | None = None,
+        **attributes: Any,
+    ) -> ErrorLog:
+        return cast(
+            ErrorLog,
+            self._log_exception(
+                ErrorLog,
+                message,
+                exception=exception,
+                call_id=call_id,
+                parent_call_id=parent_call_id,
+                parameters=parameters,
+                duration_ms=duration_ms,
+                module=module,
+                function=function,
+                attributes=attributes,
+            ),
+        )
+
+    def critical(
+        self,
+        message: str,
+        *,
+        exception: BaseException | None = None,
+        call_id: str | None = None,
+        parent_call_id: str | None = None,
+        parameters: dict[str, Any] | None = None,
+        duration_ms: float | None = None,
+        module: str | None = None,
+        function: str | None = None,
+        **attributes: Any,
+    ) -> CriticalLog:
+        return cast(
+            CriticalLog,
+            self._log_exception(
+                CriticalLog,
+                message,
+                exception=exception,
+                call_id=call_id,
+                parent_call_id=parent_call_id,
+                parameters=parameters,
+                duration_ms=duration_ms,
+                module=module,
+                function=function,
+                attributes=attributes,
+            ),
+        )
+
+    def _log(
+        self,
+        log_type: StandardLogType,
+        message: str,
+        *,
+        call_id: str | None,
+        parent_call_id: str | None,
+        parameters: dict[str, Any] | None,
+        duration_ms: float | None,
+        module: str | None,
+        function: str | None,
+        attributes: dict[str, Any],
+    ) -> StandardLog:
+        resolved_module, resolved_function = self._resolve_caller(
+            module=module,
+            function=function,
+        )
+
+        log = log_type(
+            message=message,
+            context=self.context,
+            call_id=call_id,
+            parent_call_id=parent_call_id,
+            parameters=self._prepare_parameters(
+                parameters
+            ),
+            duration_ms=duration_ms,
+            module=resolved_module,
+            function=resolved_function,
+            attributes=self._prepare_attributes(
+                attributes
+            ),
+        )
+
+        self._write(log)
+
+        return log
+
+    def _log_exception(
+        self,
+        log_type: ExceptionLogType,
+        message: str,
+        *,
+        exception: BaseException | None,
+        call_id: str | None,
+        parent_call_id: str | None,
+        parameters: dict[str, Any] | None,
+        duration_ms: float | None,
+        module: str | None,
+        function: str | None,
+        attributes: dict[str, Any],
+    ) -> ExceptionLog:
+        resolved_module, resolved_function = self._resolve_caller(
+            module=module,
+            function=function,
+        )
+
+        (
+            error_type,
+            error_message,
+            traceback_lines,
+        ) = self._serialize_exception(exception)
+
+        log = log_type(
+            message=message,
+            context=self.context,
+            call_id=call_id,
+            parent_call_id=parent_call_id,
+            parameters=self._prepare_parameters(
+                parameters
+            ),
+            duration_ms=duration_ms,
+            module=resolved_module,
+            function=resolved_function,
+            attributes=self._prepare_attributes(
+                attributes
+            ),
+            error_type=error_type,
+            error_message=error_message,
+            traceback=traceback_lines,
+        )
+
+        self._write(log)
+
+        return log
+
+    @staticmethod
+    def _prepare_parameters(
+        parameters: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        """
+        Convert parameters to JSON-safe values.
+
+        Parameter redaction and size limiting are performed by
+        Observability.trace(). This method provides the final safety
+        boundary before parameters are stored in the log model.
+        """
+        if not parameters:
+            return {}
+
+        return json_safe_dict(parameters)
+
+    @staticmethod
+    def _prepare_attributes(
+        attributes: dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Convert arbitrary structured attributes to JSON-safe values.
+
+        This protects all sinks from unsupported objects such as Path,
+        UUID, datetime, Enum, set, Pydantic models, and custom classes.
+        """
+        if not attributes:
+            return {}
+
+        return json_safe_dict(attributes)
+
+    @staticmethod
+    def _serialize_exception(
+        exception: BaseException | None,
+    ) -> tuple[
+        str | None,
+        str | None,
+        list[str],
+    ]:
+        """
+        Convert an exception into serialisable error fields.
+
+        The raw exception object is never stored in a log model or
+        passed to a sink.
+        """
+        if exception is None:
+            return None, None, []
+
+        return (
+            type(exception).__name__,
+            str(exception),
+            traceback.format_exception(
+                type(exception),
+                exception,
+                exception.__traceback__,
+            ),
+        )
+
+    @staticmethod
+    def _report_sink_failure(
+        *,
+        sink: Sink,
+        exception: Exception,
+    ) -> None:
+        print(
+            (
+                "monitaudit sink failure: "
+                f"{type(sink).__name__}: "
+                f"{type(exception).__name__}: "
+                f"{exception}"
+            ),
+            file=sys.stderr,
+        )
+
+    def _write(
+        self,
+        log: BaseLog,
+    ) -> None:
+        failures: list[
+            tuple[Sink, Exception]
+        ] = []
+
+        for sink in self.sinks:
+            try:
+                sink.write(log)
+
+            except Exception as exception:
+                failures.append(
+                    (
+                        sink,
+                        exception,
+                    )
+                )
+
+                self._report_sink_failure(
+                    sink=sink,
+                    exception=exception,
+                )
+
+        if (
+            failures
+            and self.sink_failure_mode == "raise"
+        ):
+            sink_names = ", ".join(
+                type(sink).__name__
+                for sink, _ in failures
+            )
+
+            raise RuntimeError(
+                f"monitaudit sink failure(s): {sink_names}"
+            ) from failures[0][1]
+
+    def _resolve_caller(
+        self,
+        *,
+        module: str | None,
+        function: str | None,
+    ) -> tuple[
+        str | None,
+        str | None,
+    ]:
+        if (
+            module is not None
+            and function is not None
+        ):
+            return module, function
+
+        (
+            detected_module,
+            detected_function,
+        ) = self._caller()
+
+        return (
+            module or detected_module,
+            function or detected_function,
+        )
+
+    @staticmethod
+    def _caller() -> tuple[
+        str | None,
+        str | None,
+    ]:
+        frame = inspect.currentframe()
+
+        if frame is None:
+            return None, None
+
+        try:
+            caller = frame.f_back
+
+            while caller is not None:
+                module = caller.f_globals.get(
+                    "__name__"
+                )
+                function = (
+                    caller.f_code.co_name
+                )
+
+                if module not in {
+                    __name__,
+                    "monitaudit.models.monitaudit",
+                }:
+                    return module, function
+
+                caller = caller.f_back
+
+            return None, None
+
+        finally:
+            del frame

monitaudit/models/__init__.py

@@ -0,0 +1,23 @@
+# src/monitaudit/models/__init__.py
+
+from __future__ import annotations
+
+from .base import BaseLog
+from .context import LogContext
+from .log import (
+    CriticalLog,
+    DebugLog,
+    ErrorLog,
+    InfoLog,
+    WarningLog,
+)
+
+__all__ = [
+    "BaseLog",
+    "CriticalLog",
+    "DebugLog",
+    "ErrorLog",
+    "InfoLog",
+    "LogContext",
+    "WarningLog",
+]

monitaudit/models/base.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from monitaudit.models.context import LogContext
+
+
+class BaseLog(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc)
+    )
+
+    level: str
+    message: str
+    context: LogContext
+
+    call_id: str | None = None
+    parent_call_id: str | None = None
+
+    parameters: dict[str, Any] = Field(default_factory=dict)
+
+    duration_ms: float | None = Field(default=None, ge=0)
+
+    module: str | None = None
+    function: str | None = None
+
+    attributes: dict[str, Any] = Field(default_factory=dict)

monitaudit/models/context.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class LogContext(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=True,
+    )
+
+    application: str = Field(min_length=1)
+    environment: str = Field(min_length=1)
+
+    correlation_id: str = Field(
+        default_factory=lambda: str(uuid4())
+    )
+
+    run_id: str | None = None
+
+    attributes: dict[str, Any] = Field(default_factory=dict)

monitaudit/models/log.py

@@ -0,0 +1,35 @@
+# src/monitaudit/models/log.py
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from monitaudit.models.base import BaseLog
+
+
+class DebugLog(BaseLog):
+    level: Literal["DEBUG"] = "DEBUG"
+
+
+class InfoLog(BaseLog):
+    level: Literal["INFO"] = "INFO"
+
+
+class WarningLog(BaseLog):
+    level: Literal["WARNING"] = "WARNING"
+
+
+class ErrorLog(BaseLog):
+    level: Literal["ERROR"] = "ERROR"
+    error_type: str | None = None
+    error_message: str | None = None
+    traceback: list[str] = Field( default_factory=list )
+
+
+class CriticalLog(BaseLog):
+    level: Literal["CRITICAL"] = "CRITICAL"
+    error_type: str | None = None
+    error_message: str | None = None
+    traceback: list[str] = Field( default_factory=list )