mobius-logging-py 1.0.0__py3-none-any.whl

mobius_logging/__init__.py

@@ -0,0 +1,80 @@
+"""Mobius Logging for Python.
+
+Python port of the Java Mobius logging library: standardized logging context,
+method observation, sensitive-data masking, OpenTelemetry trace sync, JSON
+logging and a Kafka schema-event producer for FastAPI / Starlette services.
+"""
+from __future__ import annotations
+
+from . import context, fields
+from .context import (
+    clear,
+    correlation_id,
+    ensure_correlation_id,
+    field,
+    get,
+    init,
+    log_type,
+    put,
+    requester_type,
+    resource_id,
+    resource_type,
+    restore,
+    snapshot,
+    sync_trace_from_opentelemetry,
+    tenant_id,
+    transaction_id,
+)
+from .kafka_context import apply_consumer_record, producer_headers
+from .kafka_producer import (
+    KafkaLogProducer,
+    LogEventSender,
+    PyKafkaProducerClientSender,
+    get_log_producer,
+    set_log_producer,
+)
+from .log_type import LogType
+from .logging_config import configure_platform_logging
+from .masking import init_custom_keys, mask, mask_map
+from .middleware import PlatformLoggingMiddleware
+from .observed import observed
+from .bootstrap import setup_logging
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "context",
+    "fields",
+    "LogType",
+    "PlatformLoggingMiddleware",
+    "observed",
+    "setup_logging",
+    "configure_platform_logging",
+    "KafkaLogProducer",
+    "LogEventSender",
+    "PyKafkaProducerClientSender",
+    "set_log_producer",
+    "get_log_producer",
+    "producer_headers",
+    "apply_consumer_record",
+    "init_custom_keys",
+    "mask",
+    "mask_map",
+    # context functions
+    "put",
+    "get",
+    "field",
+    "init",
+    "clear",
+    "snapshot",
+    "restore",
+    "log_type",
+    "tenant_id",
+    "resource_id",
+    "resource_type",
+    "correlation_id",
+    "transaction_id",
+    "requester_type",
+    "ensure_correlation_id",
+    "sync_trace_from_opentelemetry",
+]

mobius_logging/bootstrap.py

@@ -0,0 +1,120 @@
+"""One-call bootstrap for FastAPI services.
+
+Wires logging configuration, sensitive-key registration, the schema producer
+and the request middleware in a single call - the rough equivalent of the
+Java auto-configuration classes (which Spring applies automatically; Python
+has no auto-config, so this is explicit).
+
+Example::
+
+    from kafka_producer_client import KafkaProducerConfig
+    from mobius_logging import setup_logging
+
+    setup_logging(
+        app,
+        service_name="orders-service",
+        profile="prod",
+        sensitive_keys=["session_id", "refresh_token"],
+        kafka_config=KafkaProducerConfig(
+            bootstrap_servers="broker:9092",
+            default_topic="construct-data-1",
+        ),
+    )
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Iterable, Optional
+
+from . import masking
+from .kafka_producer import (
+    KafkaLogProducer,
+    LogEventSender,
+    PyKafkaProducerClientSender,
+    set_log_producer,
+)
+from .logging_config import configure_platform_logging
+from .middleware import PlatformLoggingMiddleware
+
+log = logging.getLogger(__name__)
+
+
+def setup_logging(
+    app: Optional[Any] = None,
+    *,
+    service_name: str = "unknown-service",
+    profile: Optional[str] = None,
+    sensitive_keys: Optional[Iterable[str]] = None,
+    kafka_config: Optional[Any] = None,
+    kafka_producer: Optional[Any] = None,
+    kafka_sender: Optional[LogEventSender] = None,
+    enable_file: bool = True,
+) -> Optional[KafkaLogProducer]:
+    """Configure the library and (optionally) register FastAPI middleware.
+
+    The schema producer is resolved in this order:
+
+    1. ``kafka_sender`` - any object with ``send(value, *, topic)``;
+    2. ``kafka_producer`` - a ``py-kafka-producer-client`` ``KafkaProducerClient``
+       instance, wrapped automatically;
+    3. ``kafka_config`` - a ``KafkaProducerConfig``; the client's singleton is
+       configured and used (the default integration);
+    4. the already-configured ``py-kafka-producer-client`` singleton, if the app
+       called ``configure_kafka_producer(...)`` itself.
+
+    If none resolve, ``@observed`` simply skips schema publishing.
+
+    Returns the registered :class:`KafkaLogProducer`, if any.
+    """
+    configure_platform_logging(service_name, profile, enable_file=enable_file)
+    masking.init_custom_keys(sensitive_keys)
+
+    sender = _resolve_sender(kafka_sender, kafka_producer, kafka_config)
+
+    producer: Optional[KafkaLogProducer] = None
+    if sender is not None:
+        producer = KafkaLogProducer(sender, service_name)
+        set_log_producer(producer)
+    else:
+        log.warning(
+            "mobius-logging: no Kafka producer resolved; @observed will not "
+            "publish schema events. Pass kafka_config/kafka_producer/kafka_sender."
+        )
+
+    if app is not None:
+        app.add_middleware(PlatformLoggingMiddleware, service_name=service_name)
+
+    return producer
+
+
+def _resolve_sender(
+    kafka_sender: Optional[LogEventSender],
+    kafka_producer: Optional[Any],
+    kafka_config: Optional[Any],
+) -> Optional[LogEventSender]:
+    if kafka_sender is not None:
+        return kafka_sender
+    if kafka_producer is not None:
+        return PyKafkaProducerClientSender(kafka_producer)
+
+    # Default: integrate with the internal py-kafka-producer-client singleton.
+    try:
+        from kafka_producer_client.action_logger import (
+            configure_kafka_producer,
+            get_kafka_producer,
+        )
+    except ImportError:
+        log.warning("mobius-logging: py-kafka-producer-client not installed.")
+        return None
+
+    try:
+        if kafka_config is not None:
+            configure_kafka_producer(kafka_config)
+        return PyKafkaProducerClientSender(get_kafka_producer())
+    except Exception:  # noqa: BLE001 - producer is optional, never crash setup
+        log.warning(
+            "mobius-logging: could not initialize py-kafka-producer-client "
+            "(was configure_kafka_producer/kafka_config provided?).",
+            exc_info=True,
+        )
+        return None

mobius_logging/constants.py

@@ -0,0 +1,32 @@
+"""Platform constants. Mirrors the Java ``PlatformConstant``.
+
+The Kafka topic, schema id and tenant id are kept identical to the Java
+library on purpose: Python services emit into the same schema pipeline.
+"""
+from __future__ import annotations
+
+import re
+
+SCHEMA_VERSION = "mobius.log.v1"
+
+# Masking
+EMAIL_RE = re.compile(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,6}$")
+# Mask every word char that is followed by at least 4 more word chars,
+# i.e. keep the last 4 characters visible. Matches the Java MASKING_REGEX.
+MASKING_RE = re.compile(r"\w(?=\w{4})")
+MASKING_PATTERN = "*****"
+AT_SYMBOL = "@"
+STAR = "*"
+
+# Kafka schema pipeline (must match the Java library)
+TOPIC = "construct-data-1"
+TENANT_ID = "2cf76e5f-26ad-4f2c-bccc-f4bc1e7bfb64"
+SCHEMA_ID = "6a2f9b55f7827435c6ff87c4"
+
+# Legacy -> canonical key remapping applied before shipping to the schema.
+SANITIZE_KEYS = {
+    "agentId": "agent_id",
+    "userId": "user_id",
+    "tenantId": "tenant_id",
+    "txnId": "txn_id",
+}

mobius_logging/context.py

@@ -0,0 +1,140 @@
+"""Logging context store - the Python analog of SLF4J's MDC.
+
+Java uses ``org.slf4j.MDC`` (a thread-local). Python's stdlib ``logging`` has
+no MDC, so we back the context with a :class:`contextvars.ContextVar`. That
+gives correct propagation for both threads and ``asyncio`` tasks (each request
+handled by FastAPI runs in its own context).
+
+All mutations are copy-on-write: we never mutate the dict stored in the
+ContextVar in place, because child tasks inherit the *same* dict reference and
+in-place mutation would leak across tasks.
+"""
+from __future__ import annotations
+
+import contextvars
+import uuid
+from typing import Dict, Optional
+
+from . import fields
+from .constants import SCHEMA_VERSION
+
+_context: contextvars.ContextVar[Optional[Dict[str, str]]] = contextvars.ContextVar(
+    "mobius_log_context", default=None
+)
+
+
+def _current() -> Dict[str, str]:
+    return _context.get() or {}
+
+
+def put(key: str, value: Optional[str]) -> None:
+    """Store a field. No-op when the value is ``None`` or blank (matches Java)."""
+    if value is None:
+        return
+    value = str(value)
+    if not value.strip():
+        return
+    updated = dict(_current())
+    updated[key] = value
+    _context.set(updated)
+
+
+def get(key: str) -> Optional[str]:
+    return _current().get(key)
+
+
+def copy() -> Dict[str, str]:
+    """Return a shallow copy of the current context (never the live dict)."""
+    return dict(_current())
+
+
+# ``snapshot`` is an alias kept for parity with the Java naming.
+snapshot = copy
+
+
+def restore(context: Optional[Dict[str, str]]) -> None:
+    _context.set(dict(context) if context else {})
+
+
+def remove(*keys: str) -> None:
+    current = _current()
+    if not any(k in current for k in keys):
+        return
+    updated = dict(current)
+    for key in keys:
+        updated.pop(key, None)
+    _context.set(updated)
+
+
+def clear() -> None:
+    _context.set({})
+
+
+def init() -> None:
+    put(fields.SCHEMA_VERSION, SCHEMA_VERSION)
+
+
+# --- convenience setters (mirror PlatformLogContext) ---
+
+def log_type(value) -> None:
+    if value is None:
+        return
+    # Accept LogType or raw string.
+    put(fields.LOG_TYPE, getattr(value, "value", value))
+
+
+def resource_id(value: Optional[str]) -> None:
+    put(fields.RESOURCE_ID, value)
+
+
+def resource_type(value: Optional[str]) -> None:
+    put(fields.RESOURCE_TYPE, value)
+
+
+def correlation_id(value: Optional[str]) -> None:
+    put(fields.CORRELATION_ID, value)
+
+
+def transaction_id(value: Optional[str]) -> None:
+    put(fields.TRANSACTION_ID, value)
+
+
+def requester_type(value: Optional[str]) -> None:
+    put(fields.REQUESTER_TYPE, value)
+
+
+def tenant_id(value: Optional[str]) -> None:
+    put(fields.TENANT_ID, value)
+
+
+def field(key: str, value: Optional[str]) -> None:
+    put(key, value)
+
+
+def ensure_correlation_id() -> str:
+    """Guarantee a ``correlation_id`` exists, generating one when missing.
+
+    NOTE: the Java implementation has an inverted condition and only
+    regenerates when one *already* exists; this is the corrected behaviour.
+    Returns the effective correlation id.
+    """
+    existing = get(fields.CORRELATION_ID)
+    if existing and existing.strip():
+        return existing
+    generated = str(uuid.uuid4())
+    put(fields.CORRELATION_ID, generated)
+    return generated
+
+
+def sync_trace_from_opentelemetry() -> None:
+    """Copy the current valid OpenTelemetry span context into the log context."""
+    try:
+        from opentelemetry import trace  # type: ignore
+    except ImportError:
+        return
+    span = trace.get_current_span()
+    ctx = span.get_span_context()
+    if ctx is None or not ctx.is_valid:
+        return
+    put(fields.TRACE_ID, format(ctx.trace_id, "032x"))
+    put(fields.SPAN_ID, format(ctx.span_id, "016x"))

mobius_logging/fields.py

@@ -0,0 +1,83 @@
+"""Centralized MDC-style field names.
+
+Mirrors ``PlatformLogFields`` from the Java Mobius logging library so events
+emitted by Python services share the exact same field vocabulary.
+"""
+from __future__ import annotations
+
+# --- envelope ---
+SCHEMA_VERSION = "schema_version"
+TIMESTAMP = "timestamp"
+ID = "id"
+SERVICE_NAME = "service_name"
+LOG_TYPE = "log_type"
+EVENT_TYPE = "event_type"
+RESOURCE_TYPE = "resource_type"
+RESOURCE_ID = "resource_id"
+OUTCOME = "outcome"
+METHOD_DURATION_MS = "method_duration_ms"
+EXCEPTION_TYPE = "exception_type"
+EXCEPTION_MESSAGE = "exception_message"
+
+# --- trace / correlation ---
+TRACE_ID = "trace_id"
+SPAN_ID = "span_id"
+CORRELATION_ID = "correlation_id"
+CAUSATION_ID = "causation_id"
+TRANSACTION_ID = "txn_id"
+
+# --- identity ---
+PARENT_TENANT_ID = "parent_tenant_id"
+TENANT_ID = "tenant_id"
+TENANT_USER_ID = "tenant_user_id"
+CONSUMER_ID = "consumer_id"
+AGENT_ID = "agent_id"
+AGENT_USER_ID = "agent_user_id"
+REQUESTER_TYPE = "requester_type"
+
+# --- http ---
+HTTP_DURATION_MS = "http_duration_ms"
+HTTP_METHOD = "http_method"
+HTTP_PATH = "http_path"
+HTTP_STATUS = "http_status"
+APP_ID = "app_id"
+PLATFORM_ID = "platform_id"
+
+# --- code location ---
+CLASS_NAME = "class_name"
+METHOD_NAME = "method_name"
+
+# --- workflow ---
+WORKFLOW_ENGINE = "workflow_engine"
+PROCESS_INSTANCE_ID = "process_instance_id"
+PROCESS_DEFINITION_ID = "process_definition_id"
+ACTIVITY_ID = "activity_id"
+BUSINESS_KEY = "business_key"
+
+# --- kafka ---
+KAFKA_TOPIC = "kafka_topic"
+KAFKA_PARTITION = "kafka_partition"
+KAFKA_OFFSET = "kafka_offset"
+
+# --- database ---
+DB_DURATION_MS = "db_duration_ms"
+DB_SYSTEM = "db_system"
+DB_NAME = "db_name"
+DB_DATASOURCE = "db_datasource"
+DB_OPERATION = "db_operation"
+DB_STATEMENT_TYPE = "db_statement_type"
+DB_SQL_TEMPLATE = "db_sql_template"
+DB_SQL_HASH = "db_sql_hash"
+DB_TABLE = "db_table"
+DB_ROW_COUNT = "db_row_count"
+DB_BATCH_SIZE = "db_batch_size"
+DB_OUTCOME = "db_outcome"
+
+# Fields copied into Kafka headers by the producer/consumer helpers.
+KAFKA_PROPAGATED_FIELDS = (
+    TRACE_ID,
+    SPAN_ID,
+    CORRELATION_ID,
+    CAUSATION_ID,
+    TENANT_ID,
+)

mobius_logging/kafka_context.py

@@ -0,0 +1,57 @@
+"""Kafka context propagation helpers - analog of the Java
+``PlatformKafkaProducerContext`` / ``PlatformKafkaConsumerContext``.
+
+Python Kafka clients represent headers as a list of ``(key, bytes)`` tuples
+(confluent-kafka, aiokafka, kafka-python all accept this shape), so these
+helpers work with that representation rather than a specific client type.
+"""
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Optional, Tuple
+
+from . import context, fields
+
+Header = Tuple[str, bytes]
+
+
+def producer_headers(existing: Optional[Iterable[Header]] = None) -> List[Header]:
+    """Return headers augmented with the propagated context fields.
+
+    Pass the result as the ``headers=`` argument when producing a record::
+
+        producer.send(topic, value, headers=producer_headers())
+    """
+    headers: List[Header] = list(existing or [])
+    present = {k for k, _ in headers}
+    for field in fields.KAFKA_PROPAGATED_FIELDS:
+        if field in present:
+            continue
+        value = context.get(field)
+        if value:
+            headers.append((field, value.encode("utf-8")))
+    return headers
+
+
+def apply_consumer_record(
+    headers: Optional[Iterable[Header]],
+    topic: Optional[str] = None,
+    partition: Optional[int] = None,
+    offset: Optional[int] = None,
+) -> None:
+    """Populate the log context from an incoming record's headers + metadata."""
+    header_map: Dict[str, bytes] = {}
+    for key, value in headers or []:
+        header_map[key] = value  # last write wins, mirrors lastHeader()
+
+    for field in fields.KAFKA_PROPAGATED_FIELDS:
+        raw = header_map.get(field)
+        if raw is not None:
+            decoded = raw.decode("utf-8") if isinstance(raw, (bytes, bytearray)) else str(raw)
+            context.put(field, decoded)
+
+    if topic is not None:
+        context.put(fields.KAFKA_TOPIC, topic)
+    if partition is not None:
+        context.put(fields.KAFKA_PARTITION, str(partition))
+    if offset is not None:
+        context.put(fields.KAFKA_OFFSET, str(offset))

mobius_logging/kafka_producer.py

@@ -0,0 +1,127 @@
+"""Schema event producer. Mirrors the Java ``KafkaLogProducer``.
+
+The Java version depends directly on ``kafka-wrapper-lib`` and a Spring
+``KafkaTemplate``. To keep this library framework- and client-agnostic, the
+producer here depends only on a small :class:`LogEventSender` protocol. Mobius
+FastAPI services use ``py-kafka-producer-client``; wrap it with
+:class:`PyKafkaProducerClientSender` (or any object exposing ``send``).
+
+Sending is best-effort and runs on a background thread pool so it never blocks
+the request path (the Java method is ``@Async``). Failures are logged, never
+raised.
+"""
+from __future__ import annotations
+
+import logging
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+from . import constants, context, fields, masking
+
+log = logging.getLogger(__name__)
+
+_executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix="mobius-log-producer")
+
+
+@runtime_checkable
+class LogEventSender(Protocol):
+    """Anything able to publish a dict event to a topic.
+
+    Matches the ``py-kafka-producer-client`` shape: ``value`` is a dict and
+    ``topic`` is keyword-only.
+    """
+
+    def send(self, value: Dict[str, Any], *, topic: str) -> Any:  # pragma: no cover
+        ...
+
+
+class PyKafkaProducerClientSender:
+    """Adapter for the internal ``py-kafka-producer-client`` (>=0.1.7).
+
+    Targets its signature::
+
+        producer.send(value: dict, *, topic: str | None = None,
+                      key=None, headers=None, on_delivery=None) -> None
+
+    so ``value`` is passed as a dict and ``topic`` as a keyword argument.
+    """
+
+    def __init__(self, producer: Any) -> None:
+        self._producer = producer
+
+    def send(self, value: Dict[str, Any], *, topic: str) -> Any:
+        return self._producer.send(value, topic=topic)
+
+
+@dataclass
+class DataIngestionOperation:
+    """Mirrors the Java ``DataIngestionOperation`` payload envelope."""
+
+    actionType: str
+    object: Dict[str, str]
+    id: str
+    schemaId: str
+    tenantId: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+class KafkaLogProducer:
+    def __init__(self, sender: LogEventSender, service_name: str) -> None:
+        self._sender = sender
+        self._service_name = service_name
+
+    def send_to_schema(self) -> None:
+        """Snapshot the current context and ship it to the schema topic."""
+        context_map = masking.mask_map(context.copy())
+        if not context_map:
+            return
+
+        event_id = str(uuid.uuid4())
+        context_map[fields.SERVICE_NAME] = self._service_name
+        context_map[fields.ID] = event_id
+        self._sanitize(context_map)
+
+        payload = DataIngestionOperation(
+            actionType="CREATE",
+            object=context_map,
+            id=event_id,
+            schemaId=constants.SCHEMA_ID,
+            tenantId=constants.TENANT_ID,
+        )
+        # Fire and forget; capture the already-built payload by value.
+        _executor.submit(self._send, payload.to_dict())
+
+    def _send(self, value: Dict[str, Any]) -> None:
+        try:
+            self._sender.send(value, topic=constants.TOPIC)
+        except Exception:  # noqa: BLE001 - never break the caller
+            log.warning("Failed to publish log event to schema topic", exc_info=True)
+
+    @staticmethod
+    def _sanitize(context_map: Dict[str, str]) -> None:
+        context_map[fields.TIMESTAMP] = datetime.now(timezone.utc).isoformat()
+        for legacy in ("uri", "method", "bagentId", "requestId"):
+            context_map.pop(legacy, None)
+        for legacy_key, canonical_key in constants.SANITIZE_KEYS.items():
+            if legacy_key in context_map:
+                context_map[canonical_key] = context_map.pop(legacy_key)
+
+
+# --- module-level default producer (set at app startup) ---
+
+_default_producer: Optional[KafkaLogProducer] = None
+
+
+def set_log_producer(producer: Optional[KafkaLogProducer]) -> None:
+    """Register the producer used by the ``@observed`` decorator."""
+    global _default_producer
+    _default_producer = producer
+
+
+def get_log_producer() -> Optional[KafkaLogProducer]:
+    return _default_producer

mobius_logging/log_type.py

@@ -0,0 +1,20 @@
+"""Log categories. Mirrors the Java ``LogType`` enum."""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class LogType(str, Enum):
+    APPLICATION = "application_log"
+    AUDIT = "audit_log"
+    SECURITY = "security_log"
+    WORKFLOW = "workflow_log"
+    DEPLOYMENT = "deployment_log"
+    POLICY = "policy_log"
+    INFRASTRUCTURE = "infrastructure_log"
+    INTEGRATION = "integration_log"
+    DATABASE = "database_log"
+
+    def value_(self) -> str:
+        """Explicit accessor to parallel the Java ``value()`` method."""
+        return self.value

mobius_logging/logging_config.py

@@ -0,0 +1,122 @@
+"""Logging bootstrap - the Python analog of the Java ``LogbackConfigurator``.
+
+Configures the root logger with:
+- a context-injecting filter so every record carries the current log context;
+- JSON console output for ``staging`` / ``prod`` / ``production`` profiles, and
+  a human-readable pattern otherwise;
+- a daily rotating file handler under ``logs/<service>.log``;
+- reduced noise levels for chatty third-party loggers.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from datetime import datetime, timezone
+from logging.handlers import TimedRotatingFileHandler
+from pathlib import Path
+from typing import Optional
+
+from . import context
+
+_PROD_PROFILES = {"staging", "prod", "production"}
+
+# Standard LogRecord attributes we never treat as "context" fields.
+_RESERVED = set(
+    vars(logging.makeLogRecord({})).keys()
+) | {"message", "asctime", "taskName"}
+
+_TEXT_FORMAT = (
+    "%(asctime)s [%(threadName)s] "
+    "[txn:%(txn_id)s] [tenant:%(tenant_id)s] [trace:%(trace_id)s] "
+    "%(levelname)-5s %(name)s - %(message)s"
+)
+
+
+class ContextInjectingFilter(logging.Filter):
+    """Copies the current log context onto every record.
+
+    Mirrors how Logback reads MDC: makes context fields available to the
+    formatter (e.g. ``%(trace_id)s``) and to the JSON encoder.
+    """
+
+    # Fields surfaced in the text pattern; default to NA when absent.
+    _PATTERN_DEFAULTS = {"txn_id": "NA", "tenant_id": "NA", "trace_id": "NA"}
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        ctx = context.copy()
+        record._mobius_context = ctx  # used by JsonFormatter
+        for key, default in self._PATTERN_DEFAULTS.items():
+            if not hasattr(record, key):
+                setattr(record, key, ctx.get(key, default))
+        return True
+
+
+class JsonFormatter(logging.Formatter):
+    def __init__(self, service_name: str) -> None:
+        super().__init__()
+        self.service_name = service_name
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "ts": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "level": record.levelname,
+            "service": self.service_name,
+            "logger": record.name,
+            "thread": record.threadName,
+            "msg": record.getMessage(),
+        }
+        payload.update(getattr(record, "_mobius_context", {}))
+        if record.exc_info:
+            payload["exception"] = self.formatException(record.exc_info)
+        return json.dumps(payload, default=str)
+
+
+def configure_platform_logging(
+    service_name: Optional[str] = None,
+    profile: Optional[str] = None,
+    *,
+    log_dir: str = "logs",
+    enable_file: bool = True,
+) -> None:
+    service_name = service_name or os.getenv("SPRING_APPLICATION_NAME", "unknown-service")
+    profile = profile or os.getenv("APP_PROFILE", "")
+    is_prod = profile.lower() in _PROD_PROFILES
+
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+
+    context_filter = ContextInjectingFilter()
+
+    console = logging.StreamHandler()
+    console.addFilter(context_filter)
+    console.setFormatter(
+        JsonFormatter(service_name) if is_prod else logging.Formatter(_TEXT_FORMAT)
+    )
+    root.addHandler(console)
+
+    if enable_file:
+        Path(log_dir).mkdir(parents=True, exist_ok=True)
+        file_handler = TimedRotatingFileHandler(
+            filename=os.path.join(log_dir, f"{service_name}.log"),
+            when="midnight",
+            backupCount=30,
+            encoding="utf-8",
+        )
+        file_handler.addFilter(context_filter)
+        file_handler.setFormatter(
+            JsonFormatter(service_name) if is_prod else logging.Formatter(_TEXT_FORMAT)
+        )
+        root.addHandler(file_handler)
+
+    for noisy in (
+        "kafka",
+        "pymongo",
+        "neo4j",
+        "uvicorn.access",
+        "asyncio",
+    ):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+    logging.getLogger("mobius_logging").setLevel(logging.INFO)

mobius_logging/masking.py

@@ -0,0 +1,78 @@
+"""Sensitive-data masking. Mirrors the Java ``SensitiveDataMasker``.
+
+Keys are matched case-insensitively against a default set plus any custom
+keys registered via :func:`init_custom_keys`.
+"""
+from __future__ import annotations
+
+from typing import Dict, Iterable, Optional
+
+from . import constants
+
+_DEFAULT_SENSITIVE = frozenset(
+    {
+        "password",
+        "token",
+        "secret",
+        "authorization",
+        "cookie",
+        "apikey",
+        "privatekey",
+        "kubeconfig",
+    }
+)
+
+_custom_sensitive: set[str] = set()
+
+
+def init_custom_keys(custom_keys: Optional[Iterable[str]]) -> None:
+    if not custom_keys:
+        return
+    for key in custom_keys:
+        if key and key.strip():
+            _custom_sensitive.add(key.strip().lower())
+
+
+def mask_map(input_map: Optional[Dict[str, str]]) -> Dict[str, str]:
+    if not input_map:
+        return {}
+    return {key: mask(key, value) for key, value in input_map.items()}
+
+
+def mask(key: Optional[str], value: Optional[str]) -> Optional[str]:
+    if key is None or value is None:
+        return value
+    lower = key.lower()
+    if lower in _DEFAULT_SENSITIVE or lower in _custom_sensitive:
+        return _attribute_masking(value)
+    return value
+
+
+def _attribute_masking(value) -> str:
+    text = str(value)
+    if is_email(text):
+        return _mask_email(text)
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return constants.MASKING_PATTERN
+    return _mask_generic(text)
+
+
+def _mask_generic(value: str) -> str:
+    if len(value) <= 4:
+        return constants.MASKING_PATTERN
+    return constants.MASKING_RE.sub(constants.STAR, value)
+
+
+def is_email(value: str) -> bool:
+    return bool(constants.EMAIL_RE.match(value))
+
+
+def _mask_email(email: str) -> str:
+    at_index = email.find(constants.AT_SYMBOL)
+    if at_index <= 1:
+        return email
+    local = email[:at_index]
+    domain = email[at_index:]
+    if len(local) <= 4:
+        return local[0] + constants.MASKING_PATTERN + domain
+    return local[:2] + constants.MASKING_PATTERN + local[-2:] + domain

mobius_logging/middleware.py

@@ -0,0 +1,65 @@
+"""FastAPI / Starlette ASGI middleware - the Python analog of the Java
+``PlatformLoggingFilter`` servlet filter.
+
+Implemented as a pure ASGI middleware (not Starlette's ``BaseHTTPMiddleware``)
+so the context it seeds shares the same ``contextvars`` context as the route
+handler. ``BaseHTTPMiddleware`` runs the downstream app in a separate task and
+would not propagate the context reliably.
+
+Add it as early as possible in the stack to mirror the Java filter's
+``HIGHEST_PRECEDENCE + 10`` ordering::
+
+    app.add_middleware(PlatformLoggingMiddleware, service_name="orders-service")
+"""
+from __future__ import annotations
+
+import logging
+import time
+
+from . import context, fields
+
+log = logging.getLogger(__name__)
+
+
+class PlatformLoggingMiddleware:
+    def __init__(self, app, service_name: str = "unknown-service") -> None:
+        self.app = app
+        self.service_name = service_name
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        start = time.monotonic()
+        method = scope.get("method", "")
+        path = scope.get("path", "")
+
+        context.clear()
+        context.init()
+        context.put(fields.SERVICE_NAME, self.service_name)
+        context.put(fields.HTTP_METHOD, method)
+        context.put(fields.HTTP_PATH, path)
+        context.sync_trace_from_opentelemetry()
+        context.ensure_correlation_id()
+
+        status_code = {"value": 0}
+
+        async def send_wrapper(message):
+            if message["type"] == "http.response.start":
+                status_code["value"] = message["status"]
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_wrapper)
+        finally:
+            duration_ms = int((time.monotonic() - start) * 1000)
+            log.info(
+                "HTTP request completed, Http Method=%s, Http Path=%s, "
+                "Http Status=%s, Http Duration(ms)=%s",
+                method,
+                path,
+                status_code["value"],
+                duration_ms,
+            )
+            context.clear()

mobius_logging/observed.py

@@ -0,0 +1,115 @@
+"""``@observed`` decorator - the Python analog of the Java ``@PlatformObserved``
+AOP aspect.
+
+Wraps a function (sync or async) and records:
+``log_type``, ``event_type``, ``resource_type``, ``class_name``,
+``method_name``, ``outcome``, ``method_duration_ms`` and, on failure,
+``exception_type`` / ``exception_message``. After completion it ships the
+context to the schema producer.
+
+Unlike the Java aspect, which calls ``MDC.clear()`` afterwards, this restores
+the context snapshot taken before the call - so fields seeded by the request
+middleware survive for later logging in the same request.
+"""
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+import time
+from typing import Callable, Optional, TypeVar
+
+from . import context, fields
+from .kafka_producer import get_log_producer
+from .log_type import LogType
+from .masking import mask_map
+
+log = logging.getLogger(__name__)
+
+F = TypeVar("F", bound=Callable)
+
+
+def observed(
+    event_type: str,
+    log_type: LogType = LogType.APPLICATION,
+    resource_type: str = "",
+    log_success: bool = True,
+    log_failure: bool = True,
+) -> Callable[[F], F]:
+    def decorator(func: F) -> F:
+        class_name = getattr(func, "__qualname__", func.__name__)
+        # Drop the trailing ".<method>" to approximate the declaring type name.
+        declaring = class_name.rsplit(".", 1)[0] if "." in class_name else func.__module__
+        method_name = func.__name__
+
+        def _enter(start: float) -> None:
+            context.log_type(log_type)
+            context.put(fields.EVENT_TYPE, event_type)
+            if resource_type:
+                context.put(fields.RESOURCE_TYPE, resource_type)
+            context.put(fields.CLASS_NAME, declaring)
+            context.put(fields.METHOD_NAME, method_name)
+
+        def _success(start: float) -> None:
+            context.put(fields.OUTCOME, "success")
+            context.put(fields.METHOD_DURATION_MS, str(_elapsed_ms(start)))
+            if log_success:
+                log.info("%s, succeeded, context=%s", event_type, mask_map(context.copy()))
+
+        def _failure(start: float, exc: BaseException) -> None:
+            context.put(fields.OUTCOME, "failure")
+            context.put(fields.METHOD_DURATION_MS, str(_elapsed_ms(start)))
+            context.put(fields.EXCEPTION_TYPE, type(exc).__name__)
+            context.put(fields.EXCEPTION_MESSAGE, str(exc))
+            if log_failure:
+                log.error(
+                    "%s, failed, context=%s", event_type, mask_map(context.copy()), exc_info=exc
+                )
+
+        def _finally(snapshot) -> None:
+            producer = get_log_producer()
+            if producer is not None:
+                producer.send_to_schema()
+            context.restore(snapshot)
+
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                snapshot = context.copy()
+                start = time.monotonic()
+                _enter(start)
+                try:
+                    result = await func(*args, **kwargs)
+                    _success(start)
+                    return result
+                except BaseException as exc:  # noqa: BLE001 - re-raised below
+                    _failure(start, exc)
+                    raise
+                finally:
+                    _finally(snapshot)
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            snapshot = context.copy()
+            start = time.monotonic()
+            _enter(start)
+            try:
+                result = func(*args, **kwargs)
+                _success(start)
+                return result
+            except BaseException as exc:  # noqa: BLE001 - re-raised below
+                _failure(start, exc)
+                raise
+            finally:
+                _finally(snapshot)
+
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def _elapsed_ms(start: float) -> int:
+    return int((time.monotonic() - start) * 1000)

mobius_logging_py-1.0.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: mobius-logging-py
+Version: 1.0.0
+Summary: Standardized logging context, observation, masking and Kafka schema events for Mobius Python (FastAPI) services.
+Author: Mobius Platform
+Keywords: logging,observability,fastapi,mobius,kafka
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: py-kafka-producer-client>=0.1.7
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Provides-Extra: fastapi
+Requires-Dist: starlette>=0.27; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: starlette>=0.27; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+Requires-Dist: opentelemetry-api>=1.20; extra == "dev"
+
+# Mobius Logging for Python
+
+Python port of the Java Mobius logging library. It standardizes logging context
+for Mobius **FastAPI / Starlette** services: a contextvars-based context store
+(the analog of SLF4J MDC), a request middleware, an `@observed` method
+decorator, sensitive-data masking, OpenTelemetry trace sync, JSON logging, and
+a Kafka schema-event producer.
+
+Schema constants (Kafka topic `construct-data-1`, schema id, tenant id, and
+`schema_version=mobius.log.v1`) are **identical to the Java library**, so events
+from Python services land in the same pipeline.
+
+Requires Python 3.10+.
+
+## Install
+
+```bash
+pip install mobius-logging-py
+
+# or directly from git
+pip install "mobius-logging-py @ git+https://<your-git-host>/mobius-logging-py.git@v1.0.0"
+```
+
+The import package is `mobius_logging` (e.g. `from mobius_logging import setup_logging`).
+
+Optional extras: `mobius-logging-py[otel]` (OpenTelemetry trace sync),
+`mobius-logging-py[fastapi]` (Starlette middleware).
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from mobius_logging import setup_logging, observed, LogType
+from py_kafka_producer_client import Producer  # your internal client
+
+app = FastAPI()
+
+setup_logging(
+    app,
+    service_name="orders-service",
+    profile="prod",                       # json logs for staging/prod/production
+    sensitive_keys=["session_id", "refresh_token"],
+    kafka_producer=Producer(...),         # wrapped in PyKafkaProducerClientSender
+)
+
+@app.post("/orders")
+@observed(event_type="order.create", log_type=LogType.AUDIT, resource_type="order")
+async def create_order(order_id: str):
+    ...
+```
+
+`setup_logging` is the one-call equivalent of Java's Spring auto-configuration
+(Python has no auto-config, so wiring is explicit). It configures logging,
+registers custom sensitive keys, builds the schema producer, and adds the
+request middleware.
+
+## Java → Python mapping
+
+| Java Mobius logging library | Python (`mobius_logging`) |
+| --- | --- |
+| SLF4J `MDC` | `contextvars.ContextVar` (`context.py`) |
+| `PlatformLogContext` | `mobius_logging.context` functions |
+| `PlatformLogFields` | `mobius_logging.fields` |
+| `LogType` enum | `LogType` enum |
+| `PlatformLoggingFilter` (servlet) | `PlatformLoggingMiddleware` (ASGI) |
+| `@PlatformObserved` + AOP aspect | `@observed` decorator |
+| `KafkaLogProducer` (`KafkaTemplate`) | `KafkaLogProducer` + `LogEventSender` |
+| `PlatformKafka*Context` | `producer_headers` / `apply_consumer_record` |
+| `SensitiveDataMasker` | `mobius_logging.masking` |
+| `LogbackConfigurator` | `configure_platform_logging` |
+| Spring auto-config classes | `setup_logging` (explicit) |
+
+Out of scope for v1 (present in Java): JDBC/JPA, MongoDB, and Camunda logging.
+
+## Context API
+
+```python
+from mobius_logging import context, LogType
+
+context.init()                       # sets schema_version
+context.tenant_id("tenant-123")
+context.log_type(LogType.AUDIT)
+context.resource_type("order")
+context.resource_id("order-789")
+context.field("custom_key", "value")
+context.ensure_correlation_id()      # generates one if missing
+context.sync_trace_from_opentelemetry()
+
+snap = context.snapshot()
+try:
+    context.put("event_type", "order.approved")
+finally:
+    context.restore(snap)
+```
+
+> Note: Java's `ensureCorrelationId()` has an inverted condition and only
+> regenerates when one already exists. This port fixes that — it generates a
+> correlation id when none is present.
+
+## `@observed`
+
+Works on sync and async functions. Adds `log_type`, `event_type`,
+`resource_type`, `class_name`, `method_name`, `outcome`, `method_duration_ms`,
+and `exception_type`/`exception_message` on failure. After completion it ships
+the context to the schema producer (if one is registered), then restores the
+pre-call context snapshot (Java clears MDC instead).
+
+```python
+@observed(event_type="order.create", resource_type="order")
+def create_order(order_id: str): ...
+```
+
+## Kafka
+
+### Schema event producer
+
+The producer depends only on a small protocol, so the library has no hard Kafka
+dependency. It matches the `py-kafka-producer-client` (>=0.1.7) signature — the
+event is a dict and `topic` is keyword-only:
+
+```python
+class LogEventSender(Protocol):
+    def send(self, value: dict, *, topic: str) -> Any: ...
+```
+
+For the internal `py-kafka-producer-client`, pass the client to
+`setup_logging(kafka_producer=...)` or wrap it directly:
+
+```python
+from mobius_logging import KafkaLogProducer, PyKafkaProducerClientSender, set_log_producer
+
+producer = KafkaLogProducer(PyKafkaProducerClientSender(client), "orders-service")
+set_log_producer(producer)
+```
+
+`PyKafkaProducerClientSender` calls `client.send(value, topic=...)`, passing the
+`DataIngestionOperation` envelope as a dict (the client serializes it). To use a
+different client, pass any object exposing `send(value, *, topic)` as
+`kafka_sender=`.
+
+Sending runs on a background thread pool (best-effort, never raises, never
+blocks the request) — the analog of the Java `@Async` method.
+
+### Context propagation
+
+```python
+from mobius_logging import producer_headers, apply_consumer_record
+
+# producer side
+client.send(topic, value, headers=producer_headers())
+
+# consumer side
+apply_consumer_record(record.headers(), topic=record.topic(),
+                      partition=record.partition(), offset=record.offset())
+```
+
+Propagated header fields: `trace_id`, `span_id`, `correlation_id`,
+`causation_id`, `tenant_id`. Consumer also sets `kafka_topic`,
+`kafka_partition`, `kafka_offset`.
+
+## Logging output
+
+`configure_platform_logging(service_name, profile)` installs a root handler that
+injects the current context onto every record. Profiles `staging`/`prod`/
+`production` emit JSON; others use a readable text pattern. A daily-rotating
+file handler writes to `logs/<service>.log` (30 days retained).
+
+In JSON mode every context field is included automatically. For the text
+pattern, `txn_id`, `tenant_id`, and `trace_id` are surfaced inline.
+
+## Sensitive data masking
+
+```python
+from mobius_logging import mask, mask_map, init_custom_keys
+
+init_custom_keys(["session_id", "refresh_token"])
+mask("authorization", token)      # masked
+mask_map(context.copy())          # masks all sensitive keys in a dict
+```
+
+Default sensitive keys: `password`, `token`, `secret`, `authorization`,
+`cookie`, `apikey`, `privatekey`, `kubeconfig`. Matching is case-insensitive.
+Masking keeps the last 4 characters of generic values and partially masks
+emails — identical behaviour to the Java masker.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```

mobius_logging_py-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+mobius_logging/__init__.py,sha256=Nzeo7kcPYZGjCIPITS83ocVr4hUFPhsrbr_6WOM1nFU,1834
+mobius_logging/bootstrap.py,sha256=FVyZfY588AVMfS0PM1aRWc1wYUiNU7IZs2Zej54g8is,4071
+mobius_logging/constants.py,sha256=GnWlAex64LZFY6b8wp2kpNifLlXo5JZRJdVhID5dChw,989
+mobius_logging/context.py,sha256=uv9Xdqfvo538JYyaBayo2jz91AbJtU9YE_9xWujUEXs,3739
+mobius_logging/fields.py,sha256=qABpjvdBnEy5dqJyzQJP99ARSkR5hKP9xfW_ufwZmuM,2108
+mobius_logging/kafka_context.py,sha256=xSGcFcXA9FZKtL2Tvff_oSjWo6mq474ZLlU88xOyQeg,2035
+mobius_logging/kafka_producer.py,sha256=GdJTv7EwZSS_YQrAHVjn3NLheKAjvL6wwHx6HEdKoTA,4257
+mobius_logging/log_type.py,sha256=TVER4tnwn2eL9iq0ZXI8jVM1ltYy4gSokuSqxD7QXTQ,560
+mobius_logging/logging_config.py,sha256=INbV3QgwutaGE_gA2kIDAPux0Ybvq5w90zDjQGzFVYw,4076
+mobius_logging/masking.py,sha256=1IlMrAiHvpr5tj0ybKZvRjcSL0Hjnqj2LJrYRavhk4w,2080
+mobius_logging/middleware.py,sha256=E58IczBr2IBfgEm5BTfdxPLzDUGsRvW8_4bCmAGGPME,2134
+mobius_logging/observed.py,sha256=3JoP-SGpcdbrYWeu77I2-0msGlVwVReNihM9n4J0JT4,4105
+mobius_logging/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mobius_logging_py-1.0.0.dist-info/METADATA,sha256=qSkVnyMaD8O3nSdjbzYpYv4i9O0ARUHjUgBeuflJReo,7340
+mobius_logging_py-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mobius_logging_py-1.0.0.dist-info/top_level.txt,sha256=Eyjhd5Fjq0KaedkHPPqaWgFPqSpHnx7Ks6lSA6Pc5VA,15
+mobius_logging_py-1.0.0.dist-info/RECORD,,

mobius_logging_py-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mobius_logging_py-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mobius_logging