cloud-dog-logging 0.4.0__py3-none-any.whl

cloud_dog_logging/GAPS.md

@@ -0,0 +1,38 @@
+# cloud_dog_logging PS-40 v2 Gaps
+
+Source lane: W28A-619  
+Status: Documentation-only gap note. No source changes made in this lane.
+
+The full package gap matrix is recorded at:
+
+```text
+cloud-dog-ai-platform-standards/working/evidence/W28A-619-log-standards-review/02-cloud-dog-log-gap-matrix.md
+```
+
+## Summary
+
+- Total reviewed rows: 47
+- Block rows: 5
+- Major rows: 34
+- Minor rows: 4
+- Present/no-gap rows: 4
+
+## Blockers Before PS-40 v2 Runtime Adoption
+
+| Gap | Evidence | Required fix lane |
+|---|---|---|
+| No canonical `span_id` context model/formatter/schema. | `audit_schema.py:138-160`, `json_formatter.py:251-260`, `correlation.py:32-58` | W28A-XYZ |
+| No per-surface API/WebUI/MCP/A2A handler/file configuration. | `config.py:56-93`, `__init__.py:198-223`, `__init__.py:359-382` | W28A-XYZ |
+| No `<service>.<surface>.log` path derivation from `log.dir`. | `config.py:61-63`, `__init__.py:200-223`, `__init__.py:364-375` | W28A-XYZ |
+| No outbound `X-Correlation-Id` / W3C `traceparent` injection helper. | `correlation.py:32-58` plus package source inspection | W28A-XYZ |
+| No job envelope helper for lifecycle correlation inheritance. | `correlation.py:32-58` plus package source inspection | W28A-XYZ |
+
+## Follow-on W28A-XYZ Must Cover
+
+1. Emit the complete PS-40 v2 canonical field set in both application and audit entries.
+2. Add per-surface file topology and `log.dir`-based path derivation.
+3. Add W3C trace context support including `trace_id`, `span_id`, inbound parsing, outbound forwarding, and job inheritance.
+4. Add explicit redaction presets for JWT, Vault token, OAuth token, API key, password, session cookie, and PII classes.
+5. Add automatic audit sub-channel routing for SECURITY/AUDIT/auth/rbac/config/security/denied/error events.
+6. Add forbidden-pattern lint helper and PS-40 v2 conformance tests.
+7. Update README, REQUIREMENTS, TESTS, and usage docs, then build/test/publish with evidence.

cloud_dog_logging/__init__.py

@@ -0,0 +1,406 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_logging — Public API
+#
+# Licence: Apache 2.0 — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Drop-in Python logging library implementing PS-40. Provides
+#   two mandatory log streams (audit + application), structured JSON output,
+#   correlation ID propagation, secret redaction, configurable rotation, and
+#   the public extension surface (LogRecord factory hook, JSON-field hook,
+#   declarative HandlerType enum) that lets services delete bespoke
+#   ``logger.py`` wrappers without losing functionality.
+# Related requirements: FR1.1, FR1.9, FR1.18, FR1.19, FR1.20, FR1.21, FR1.22, FR1.23, FR1.24
+# Related architecture: SA1, CC1.1, CC1.6, CC1.9
+
+"""cloud_dog_logging — PS-40 Logging & Observability for Cloud-Dog services."""
+
+from __future__ import annotations
+
+import atexit
+import logging
+from typing import Any, Callable
+
+from cloud_dog_logging.app_logger import AppLogger
+from cloud_dog_logging.audit_logger import AuditLogger
+from cloud_dog_logging.audit_schema import Actor, AuditEvent, Target
+from cloud_dog_logging.batching import BatchingSink
+from cloud_dog_logging.compat import setup_logger
+from cloud_dog_logging.config import LogConfig
+from cloud_dog_logging.correlation import (
+    clear_correlation_id,
+    get_correlation_id,
+    get_environment,
+    get_service_name,
+    get_service_instance,
+    set_correlation_id,
+    set_environment,
+    set_service_name,
+    set_service_instance,
+)
+from cloud_dog_logging.exceptions import format_exception
+from cloud_dog_logging.field_providers import (
+    FieldProvider,
+    clear_log_field_providers,
+    get_registered_field_providers,
+    register_log_field_provider,
+    unregister_log_field_provider,
+)
+from cloud_dog_logging.handler_types import HandlerType
+from cloud_dog_logging.middleware.audit import AuditMiddleware
+from cloud_dog_logging.formatters import (
+    JSONFieldProvider,
+    JSONFormatter,
+    TextFormatter,
+    add_json_field,
+    clear_json_fields,
+    get_registered_json_fields,
+    remove_json_field,
+)
+from cloud_dog_logging.handlers.dual_handler import DualHandler
+from cloud_dog_logging.handlers.rotating_file import ConfigurableRotatingHandler
+from cloud_dog_logging.handlers.stdout_handler import StdoutHandler
+from cloud_dog_logging.health.reporter import LogHealthReporter
+from cloud_dog_logging.integrity import AuditIntegrityVerifier
+from cloud_dog_logging.presets import BUILTIN_PRESETS, RedactionPreset, load_presets
+from cloud_dog_logging.redaction import RedactionEngine
+from cloud_dog_logging.sampling import SamplingFilter
+from cloud_dog_logging.signing import HMACSigner
+from cloud_dog_logging.sinks import AuditSink, DatabaseSink, FanOutSink, FileSink, StdoutSink
+from cloud_dog_logging.tool_events import log_tool_event
+
+__all__ = [
+    "AuditMiddleware",
+    "setup_logging",
+    "get_logger",
+    "get_audit_logger",
+    "setup_logger",
+    "log_tool_event",
+    "AppLogger",
+    "AuditLogger",
+    "Actor",
+    "AuditEvent",
+    "Target",
+    "LogConfig",
+    "RedactionEngine",
+    "RedactionPreset",
+    "BUILTIN_PRESETS",
+    "load_presets",
+    "SamplingFilter",
+    "BatchingSink",
+    "HMACSigner",
+    "AuditSink",
+    "FileSink",
+    "StdoutSink",
+    "DatabaseSink",
+    "FanOutSink",
+    "format_exception",
+    "JSONFormatter",
+    "TextFormatter",
+    "ConfigurableRotatingHandler",
+    "StdoutHandler",
+    "DualHandler",
+    "LogHealthReporter",
+    "AuditIntegrityVerifier",
+    "get_integrity_verifier",
+    "get_correlation_id",
+    "set_correlation_id",
+    "clear_correlation_id",
+    "get_service_name",
+    "get_service_instance",
+    "get_environment",
+    "set_service_name",
+    "set_service_instance",
+    "set_environment",
+    # Public extension surface (0.4.0):
+    "FieldProvider",
+    "register_log_field_provider",
+    "unregister_log_field_provider",
+    "clear_log_field_providers",
+    "get_registered_field_providers",
+    "JSONFieldProvider",
+    "add_json_field",
+    "remove_json_field",
+    "clear_json_fields",
+    "get_registered_json_fields",
+    "HandlerType",
+]
+
+__version__ = "0.4.0"
+
+_audit_logger: AuditLogger | None = None
+_redaction_engine: RedactionEngine | None = None
+_log_config: LogConfig | None = None
+_sampling_filter: SamplingFilter | None = None
+_integrity_verifier: AuditIntegrityVerifier | None = None
+_is_configured: bool = False
+
+
+def setup_logging(config: dict[str, Any] | Any | None = None) -> None:
+    """One-time logging setup from config dict or platform GlobalConfig."""
+    global _audit_logger, _redaction_engine, _log_config, _sampling_filter, _integrity_verifier, _is_configured
+
+    if _audit_logger is not None:
+        try:
+            _audit_logger.close()
+        except Exception:
+            pass
+    if _integrity_verifier is not None:
+        try:
+            _integrity_verifier.stop()
+        except Exception:
+            pass
+        _integrity_verifier = None
+
+    if config is None:
+        _log_config = LogConfig()
+    elif isinstance(config, dict):
+        _log_config = LogConfig.from_dict(config)
+    else:
+        _log_config = LogConfig.from_platform_config(config)
+
+    set_service_name(_log_config.service_name)
+    set_service_instance(_log_config.service_instance)
+    set_environment(_log_config.environment)
+
+    presets = _resolve_redaction_presets(config, _log_config)
+    _redaction_engine = RedactionEngine(
+        additional_patterns=_log_config.redaction_patterns if _log_config.redaction_patterns else None,
+        pii_enabled=_log_config.pii_redaction,
+        presets=presets,
+    )
+
+    if _log_config.log_format.lower() == "json":
+        formatter: logging.Formatter = JSONFormatter(
+            service_name=_log_config.service_name,
+            extra_fields=list(_log_config.extra_fields) if _log_config.extra_fields else None,
+        )
+    else:
+        formatter = TextFormatter(service_name=_log_config.service_name)
+
+    root_level = getattr(logging, _log_config.log_level.upper(), logging.INFO)
+    app_root = logging.getLogger()
+    app_root.setLevel(root_level)
+    app_root.handlers.clear()
+
+    handler_selection = _resolve_handler_selection(_log_config)
+
+    if "file" in handler_selection:
+        file_handler = ConfigurableRotatingHandler(
+            filename=_log_config.app_log_file,  # type: ignore[arg-type]
+            max_bytes=_log_config.rotation_max_bytes,
+            backup_count=_log_config.rotation_backup_count,
+            rotation_mode=_log_config.rotation_mode,
+            when=_log_config.rotation_when,
+            interval=_log_config.rotation_interval,
+            compress=_log_config.rotation_compress,
+            stream_name="application",
+        )
+        file_handler.setFormatter(formatter)
+        if "console" in handler_selection:
+            stdout_handler = StdoutHandler(stream_name="stdout")
+            stdout_handler.setFormatter(formatter)
+            dual = DualHandler(file_handler=file_handler, stream_handler=stdout_handler)
+            dual.setFormatter(formatter)
+            app_root.addHandler(dual)
+        else:
+            app_root.addHandler(file_handler)
+    elif "console" in handler_selection:
+        stdout_handler = StdoutHandler(stream_name="stdout")
+        stdout_handler.setFormatter(formatter)
+        app_root.addHandler(stdout_handler)
+
+    _sampling_filter = None
+    if _log_config.sampling_rates:
+        _sampling_filter = SamplingFilter(_log_config.sampling_rates)
+        for handler in app_root.handlers:
+            handler.addFilter(_sampling_filter)
+
+    audit_sink = _build_audit_sink(_log_config, on_audit_rotate=_on_audit_rotation)
+    signer = _build_signer(_log_config)
+    audit_py_logger = logging.getLogger("cloud_dog_logging.audit")
+    audit_py_logger.setLevel(logging.INFO)
+    audit_py_logger.propagate = False
+    if not audit_py_logger.handlers:
+        audit_py_logger.addHandler(logging.NullHandler())
+
+    _audit_logger = AuditLogger(
+        logger=audit_py_logger,
+        redaction_engine=_redaction_engine,
+        service_name=_log_config.service_name,
+        sink=audit_sink,
+        signer=signer,
+    )
+
+    if _log_config.integrity_enabled:
+        audit_path = _log_config.audit_log_file or "logs/audit.log.jsonl"
+        _integrity_verifier = AuditIntegrityVerifier(
+            audit_log_path=audit_path,
+            integrity_log_path=_log_config.integrity_log_file,
+            interval_seconds=_log_config.integrity_interval_seconds,
+            hash_algorithm=_log_config.integrity_hash_algorithm,
+            service_name=_log_config.service_name,
+            service_instance=_log_config.service_instance,
+            environment=_log_config.environment,
+        )
+        _integrity_verifier.start()
+
+    for logger_name, level_str in _log_config.level_overrides.items():
+        override_level = getattr(logging, level_str.upper(), None)
+        if override_level is not None:
+            logging.getLogger(logger_name).setLevel(override_level)
+
+    _is_configured = True
+
+
+def _resolve_handler_selection(log_config: LogConfig) -> set[str]:
+    """Resolve the set of active handler kinds from declarative + legacy knobs.
+
+    Behaviour matrix:
+
+    - If ``log_config.handlers`` is ``None`` (the legacy default) the return
+      preserves bit-for-bit the prior behaviour: ``{"file"}`` if
+      ``app_log_file`` is set, ``{"console"}`` if only ``console_output`` is
+      true, ``{"file", "console"}`` for the dual case, ``set()`` otherwise.
+    - If ``log_config.handlers`` is supplied the listed :class:`HandlerType`
+      members drive the selection. ``DUAL`` expands to ``{"file", "console"}``
+      and ``ROTATING`` is treated as an alias of ``FILE`` (the platform's
+      only file handler is already rotating). The legacy knobs still narrow
+      the selection so callers cannot ask for ``FILE`` without
+      ``app_log_file`` set or ``CONSOLE`` with ``console_output=False``.
+    """
+    legacy: set[str] = set()
+    if log_config.app_log_file:
+        legacy.add("file")
+    if log_config.console_output:
+        legacy.add("console")
+
+    if not log_config.handlers:
+        return legacy
+
+    declarative: set[str] = set()
+    for raw in log_config.handlers:
+        try:
+            kind = HandlerType.coerce(raw)
+        except ValueError:
+            continue
+        if kind in (HandlerType.FILE, HandlerType.ROTATING):
+            declarative.add("file")
+        elif kind is HandlerType.CONSOLE:
+            declarative.add("console")
+        elif kind is HandlerType.DUAL:
+            declarative.add("file")
+            declarative.add("console")
+
+    # Honour legacy guard: cannot emit to file without app_log_file configured.
+    if "file" in declarative and not log_config.app_log_file:
+        declarative.discard("file")
+    if "console" in declarative and not log_config.console_output:
+        # The declarative request wins for console — when the caller asked
+        # for CONSOLE explicitly, force-enable console output.
+        log_config.console_output = True
+
+    return declarative
+
+
+def get_logger(name: str, pii_redaction: bool = True) -> AppLogger:
+    """Get a configured application logger for the given module name."""
+    py_logger = logging.getLogger(name)
+
+    redaction = _redaction_engine
+    if redaction is None:
+        redaction = RedactionEngine(pii_enabled=pii_redaction)
+
+    return AppLogger(logger=py_logger, redaction_engine=redaction)
+
+
+def get_audit_logger() -> AuditLogger:
+    """Get the singleton audit logger for security events.
+
+    If ``setup_logging()`` has not been called yet, this performs a default
+    initialisation so that a ``FileSink`` writing to ``logs/audit.log.jsonl``
+    is available instead of the legacy NullHandler fallback.
+    """
+    global _audit_logger
+    if _audit_logger is None:
+        if not _is_configured:
+            setup_logging(None)
+        else:
+            py_logger = logging.getLogger("cloud_dog_logging.audit")
+            if not py_logger.handlers:
+                py_logger.addHandler(logging.NullHandler())
+            _audit_logger = AuditLogger(logger=py_logger)
+    return _audit_logger
+
+
+def get_integrity_verifier() -> AuditIntegrityVerifier | None:
+    """Get the audit integrity verifier when enabled."""
+    return _integrity_verifier
+
+
+def _on_audit_rotation(_meta: dict[str, object]) -> None:
+    verifier = get_integrity_verifier()
+    if verifier is not None:
+        verifier.compute_now(trigger="rotation")
+
+
+def _build_audit_sink(
+    log_config: LogConfig,
+    on_audit_rotate: Callable[[dict[str, object]], None] | None = None,
+) -> AuditSink:
+    sinks: list[AuditSink] = []
+    audit_path = log_config.audit_log_file or "logs/audit.log.jsonl"
+    sinks.append(
+        FileSink(
+            audit_path,
+            max_bytes=log_config.rotation_max_bytes,
+            backup_count=log_config.rotation_backup_count,
+            rotation_mode=log_config.rotation_mode,
+            when=log_config.rotation_when,
+            interval=log_config.rotation_interval,
+            compress=log_config.rotation_compress,
+            on_rotate=on_audit_rotate,
+        )
+    )
+    if log_config.console_output:
+        sinks.append(StdoutSink())
+
+    if len(sinks) == 1:
+        return sinks[0]
+    return FanOutSink(sinks)
+
+
+def _build_signer(log_config: LogConfig) -> HMACSigner | None:
+    if not log_config.audit_signing_enabled:
+        return None
+    return HMACSigner(log_config.audit_signing_key or "")
+
+
+def _resolve_redaction_presets(config: dict[str, Any] | Any | None, log_config: LogConfig) -> list[RedactionPreset]:
+    if isinstance(config, dict):
+        return load_presets(config)
+    return load_presets({"log": {"redaction": {"presets": log_config.redaction_presets}}})
+
+
+def _shutdown_integrity_verifier() -> None:
+    verifier = get_integrity_verifier()
+    if verifier is not None:
+        try:
+            verifier.stop()
+        except Exception:
+            pass
+
+
+atexit.register(_shutdown_integrity_verifier)

cloud_dog_logging/app_logger.py

@@ -0,0 +1,143 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_logging — Application logger (structured JSON, levels)
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Structured application logger with automatic correlation ID
+#   injection, secret redaction on extra fields, and configurable formatting.
+# Related requirements: FR1.4, FR1.6, FR1.9, FR1.13
+# Related architecture: CC1.1
+
+"""Structured application logger for cloud_dog_logging."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any
+
+from cloud_dog_logging.exceptions import format_exception
+from cloud_dog_logging.redaction import RedactionEngine
+
+
+class AppLogger:
+    """Structured application logger with redaction support.
+
+    Wraps a standard Python logger and applies secret redaction to all
+    extra fields before logging. Automatically includes correlation ID
+    via the configured formatter.
+
+    Args:
+        logger: The underlying Python logger.
+        redaction_engine: Redaction engine for extra fields. If None,
+            a default engine is created.
+
+    Related tests: UT1.7_AppLogger
+    """
+
+    def __init__(
+        self,
+        logger: logging.Logger,
+        redaction_engine: RedactionEngine | None = None,
+    ) -> None:
+        self._logger = logger
+        self._redaction = redaction_engine or RedactionEngine()
+
+    def _redact_extra(self, extra: dict[str, Any] | None) -> dict[str, Any]:
+        """Redact sensitive values from extra fields.
+
+        Args:
+            extra: The extra fields dictionary.
+
+        Returns:
+            A redacted copy of the extra fields.
+        """
+        if not extra:
+            return {}
+        return self._redaction.redact(extra)
+
+    def debug(self, msg: str, **extra: Any) -> None:
+        """Log a DEBUG-level message.
+
+        Args:
+            msg: The log message.
+            **extra: Additional context fields (will be redacted).
+        """
+        self._logger.debug(msg, extra=self._redact_extra(extra))
+
+    def info(self, msg: str, **extra: Any) -> None:
+        """Log an INFO-level message.
+
+        Args:
+            msg: The log message.
+            **extra: Additional context fields (will be redacted).
+        """
+        self._logger.info(msg, extra=self._redact_extra(extra))
+
+    def warning(self, msg: str, **extra: Any) -> None:
+        """Log a WARNING-level message.
+
+        Args:
+            msg: The log message.
+            **extra: Additional context fields (will be redacted).
+        """
+        self._logger.warning(msg, extra=self._redact_extra(extra))
+
+    def error(self, msg: str, **extra: Any) -> None:
+        """Log an ERROR-level message.
+
+        Args:
+            msg: The log message.
+            **extra: Additional context fields (will be redacted).
+        """
+        self._logger.error(msg, extra=self._redact_extra(extra))
+
+    def critical(self, msg: str, **extra: Any) -> None:
+        """Log a CRITICAL-level message.
+
+        Args:
+            msg: The log message.
+            **extra: Additional context fields (will be redacted).
+        """
+        self._logger.critical(msg, extra=self._redact_extra(extra))
+
+    def exception(self, msg: str, **extra: Any) -> None:
+        """Log an ERROR-level message with exception information.
+
+        Args:
+            msg: The log message.
+            **extra: Additional context fields (will be redacted).
+        """
+        _, exc_value, _ = sys.exc_info()
+        payload = dict(extra)
+        if isinstance(exc_value, BaseException):
+            payload["exception"] = format_exception(exc_value)
+        self._logger.error(msg, exc_info=True, extra=self._redact_extra(payload))
+
+    @property
+    def level(self) -> int:
+        """Return the effective log level."""
+        return self._logger.getEffectiveLevel()
+
+    @property
+    def name(self) -> str:
+        """Return the logger name."""
+        return self._logger.name
+
+    @property
+    def underlying_logger(self) -> logging.Logger:
+        """Return the underlying stdlib logger for advanced use."""
+        return self._logger