road24-artifacthub 0.1.0__py3-none-any.whl

road24_artifacthub-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: road24-artifacthub
+Version: 0.1.0
+Summary: Shared logging and metrics library for Road24 FastAPI microservices
+Requires-Python: >=3.12
+Requires-Dist: build>=1.4.0
+Requires-Dist: prometheus-client>=0.20.0
+Requires-Dist: twine>=6.2.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Requires-Dist: httpx>=0.27.0; extra == 'all'
+Requires-Dist: redis>=5.0.0; extra == 'all'
+Requires-Dist: sqlalchemy>=2.0.45; extra == 'all'
+Requires-Dist: starlette>=0.27.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: faker>=25.0.0; extra == 'dev'
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: redis>=5.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: sqlalchemy>=2.0.45; extra == 'dev'
+Requires-Dist: starlette>=0.27.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Requires-Dist: starlette>=0.27.0; extra == 'fastapi'
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.27.0; extra == 'httpx'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0.45; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# road24-artifacthub
+
+Shared logging and metrics SDK for Road24 microservices. Provides structured JSON logging, Prometheus metrics, and framework-specific integrations following a Sentry SDK-like pattern.
+
+## Installation
+
+```bash
+# Core library
+pip install road24-artifacthub
+
+# With all integrations
+pip install road24-artifacthub[all]
+
+# Development (includes test tools)
+pip install road24-artifacthub[dev]
+```
+
+## Quick Start
+
+```python
+import road24_sdk
+from fastapi import FastAPI
+from road24_sdk.integrations.fastapi import FastApiLoggingIntegration
+from road24_sdk.integrations.httpx import HttpxLoggingIntegration
+from road24_sdk.integrations.redis import RedisLoggingIntegration
+from road24_sdk.integrations.sqlalchemy import SqlalchemyLoggingIntegration
+
+road24_sdk.init(
+    service_name="my-service",
+    log_level="INFO",
+    integrations=[
+        FastApiLoggingIntegration(),
+        HttpxLoggingIntegration(),
+        SqlalchemyLoggingIntegration(),
+        RedisLoggingIntegration(),
+    ],
+)
+
+# FastAPI still requires .setup(app) since it needs the app instance
+app = FastAPI()
+FastApiLoggingIntegration().setup(app)
+
+# All other clients are auto-instrumented — no .setup() needed
+client = AsyncClient(timeout=Timeout(25.0))  # already instrumented
+```
+
+## Available Integrations
+
+| Integration | Extra | Description |
+|---|---|---|
+| `FastApiLoggingIntegration` | `fastapi` | Inbound HTTP request/response logging and metrics |
+| `HttpxLoggingIntegration` | `httpx` | Outbound HTTP request/response logging and metrics |
+| `SqlalchemyLoggingIntegration` | `sqlalchemy` | Database query logging and metrics |
+| `RedisLoggingIntegration` | `redis` | Redis command logging and metrics |
+
+Pass integrations to `init()` for automatic class-level patching. All new client instances are auto-instrumented.
+
+The `.setup(client)` method is still available for per-instance patching (backwards compatible):
+
+```python
+# Per-instance patching (still works)
+client = AsyncClient(timeout=Timeout(25.0))
+HttpxLoggingIntegration().setup(client)
+```
+
+## Manual Testing
+
+Standalone scripts to inspect structured JSON logs and metrics (no server needed):
+
+```bash
+make test-logs-http-input    # Inbound HTTP request log
+make test-logs-http-output   # Outbound HTTPX request log
+make test-metrics-http       # Prometheus metrics after HTTP calls
+make test-logs-redis         # Redis command logs (SET, GET, HSET, etc.)
+make test-logs-db            # DB query logs (SELECT, INSERT, UPDATE, DELETE)
+```
+
+## Development
+
+```bash
+make install    # Install all dependencies (requires uv)
+make test       # Run tests with coverage
+make lint       # Lint with ruff
+make format     # Format with ruff
+make check      # Lint + test
+```

road24_artifacthub-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+road24_sdk/__init__.py,sha256=BAqBQRTI5hwt4sewrvnFzpyl9E_FTRiKYbgqZsj3bKg,1444
+road24_sdk/_formatter.py,sha256=OgiVmVidAWzP3VPQuW_WxJynyU7LFBobecXV026CKrA,5495
+road24_sdk/_sanitizer.py,sha256=RxllcSa0QZC4e500hhMDotMZau9MnmAJUr7YbcZlmr0,1957
+road24_sdk/_schemas.py,sha256=HOlBsIZSN2sm3s2MMbp-JoGGju_jjgZPmm8uNc4BCeI,3026
+road24_sdk/_types.py,sha256=OfRdYJhIAeMOtjPPCx-W9vXXAxYvuKjq37NzCubWIg8,1071
+road24_sdk/integrations/__init__.py,sha256=uCtjD-5z2lQYA1j4jN9pFw1azS095L7BVtoxzz-Rl3c,497
+road24_sdk/integrations/_base.py,sha256=IePXuVsvKmDDf3Aq411KzurXkkq5opelz9nqeXeCr2o,489
+road24_sdk/integrations/fastapi.py,sha256=7DN5jwR4SWMNKSDWu4yYecCP8w0pgktKqeuLMliBHB8,8677
+road24_sdk/integrations/httpx.py,sha256=TZySabu04UnUk0Q7LUlszQzTqpj_lZOvqPHN4QOdCT8,4223
+road24_sdk/integrations/redis.py,sha256=KvLilhaZywGSrUJ4hL7T5BqfKGZWxSYQ7BADRVS5Fq0,7401
+road24_sdk/integrations/sqlalchemy.py,sha256=WOhFpUt7RfknhJL253MxNif16OKK8GJlXQ87sDsN9WQ,5055
+road24_sdk/metrics/__init__.py,sha256=vvXfTFdHYnYHkN9REgqvqiGsTkXnszVKXnqHkb5C1FQ,257
+road24_sdk/metrics/db.py,sha256=Lqqy7k1qF8D9sdxEl4qDP5pwqVHXgo1ucDHgUYD4exs,780
+road24_sdk/metrics/http.py,sha256=Ynbf-IvJwkzU6G2eRNWf99CH8ef-iR7CxfEvHR66OvQ,949
+road24_sdk/metrics/redis.py,sha256=qdDuG-2px7_Hp1eiFRc4x8F0MG7KbcuiDiFxw8QsavA,805
+road24_artifacthub-0.1.0.dist-info/METADATA,sha256=DnB13VHVn2yG1vY2WoRwYoP9QJR_SbTledydFRCBa50,4131
+road24_artifacthub-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+road24_artifacthub-0.1.0.dist-info/RECORD,,

road24_artifacthub-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

road24_sdk/__init__.py

@@ -0,0 +1,65 @@
+import logging
+
+from road24_sdk._formatter import setup_logging
+from road24_sdk._types import (
+    ArtifactHubConfig,
+    DbOperation,
+    ExceptionType,
+    HttpDirection,
+    LogType,
+    RedisOperation,
+)
+from road24_sdk.integrations._base import Integration
+
+_config: ArtifactHubConfig | None = None
+_logger = logging.getLogger(__name__)
+
+
+def init(
+    service_name: str = "unknown",
+    log_level: str = "INFO",
+    debug: bool = False,
+    log_format: str = "json",
+    integrations: list[Integration] | None = None,
+) -> None:
+    global _config
+    resolved = integrations or []
+    _config = ArtifactHubConfig(
+        service_name=service_name,
+        log_level=log_level,
+        debug=debug,
+        log_format=log_format,
+        integrations=resolved,
+    )
+    setup_logging(
+        level=log_level,
+        service_name=service_name,
+        debug=debug,
+    )
+    for integration in resolved:
+        try:
+            integration.setup_once()
+        except Exception:
+            _logger.warning(
+                "Failed to setup integration %s",
+                type(integration).__name__,
+                exc_info=True,
+            )
+
+
+def configure() -> ArtifactHubConfig:
+    if _config is None:
+        return ArtifactHubConfig()
+    return _config
+
+
+__all__ = [
+    "ArtifactHubConfig",
+    "DbOperation",
+    "ExceptionType",
+    "HttpDirection",
+    "LogType",
+    "RedisOperation",
+    "configure",
+    "init",
+]

road24_sdk/_formatter.py

@@ -0,0 +1,213 @@
+import json
+import logging
+import sys
+from contextvars import ContextVar, Token
+from datetime import UTC, datetime
+from typing import Any
+
+from road24_sdk._schemas import ExceptionAttributes, LogRecord
+from road24_sdk._types import ExceptionType, LogType
+
+STANDARD_RECORD_ATTRS = {
+    "name",
+    "msg",
+    "args",
+    "created",
+    "filename",
+    "funcName",
+    "levelname",
+    "levelno",
+    "lineno",
+    "module",
+    "msecs",
+    "pathname",
+    "process",
+    "processName",
+    "relativeCreated",
+    "stack_info",
+    "exc_info",
+    "exc_text",
+    "thread",
+    "threadName",
+    "taskName",
+    "message",
+}
+
+ZERO_TRACE_ID = "0" * 32
+
+_trace_id: ContextVar[str] = ContextVar("trace_id", default="")
+
+_service_name: str = "unknown"
+
+SILENT_LOGGERS_DEBUG = [
+    "uvicorn.access",
+    "asyncio",
+]
+
+SILENT_LOGGERS_PROD = [
+    "uvicorn",
+    "uvicorn.access",
+    "uvicorn.error",
+    "uvicorn.asgi",
+    "sqlalchemy",
+    "sqlalchemy.engine",
+    "sqlalchemy.pool",
+    "httpx",
+    "httpcore",
+    "asyncio",
+]
+
+
+class LogFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        log_record = LogRecord(
+            timestamp=datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z",
+            trace_id=_trace_id.get() or ZERO_TRACE_ID,
+            log_level=record.levelname,
+            type=record.getMessage(),
+            service_name=_service_name,
+            attributes=self._build_attributes(record),
+        )
+        return json.dumps(log_record.as_dict(), ensure_ascii=False, default=str)
+
+    def _build_attributes(self, record: logging.LogRecord) -> dict[str, Any]:
+        attrs: dict[str, Any] = {
+            "logger_name": record.name,
+            "code_module": record.module,
+            "code_function": record.funcName,
+            "code_lineno": record.lineno,
+        }
+
+        attrs.update(
+            {
+                k: v
+                for k, v in record.__dict__.items()
+                if k not in STANDARD_RECORD_ATTRS and not k.startswith("_")
+            }
+        )
+
+        if record.exc_info and (exc_type := record.exc_info[0]):
+            attrs.update(
+                {
+                    "exception_type": exc_type.__name__,
+                    "exception_message": str(record.exc_info[1]),
+                    "exception_stacktrace": self.formatException(record.exc_info),
+                }
+            )
+
+        return attrs
+
+
+def set_trace_context(trace_id: str) -> Token[str]:
+    return _trace_id.set(trace_id)
+
+
+def clear_trace_context(token: Token[str] | None = None) -> None:
+    if token is not None:
+        _trace_id.reset(token)
+    else:
+        _trace_id.set("")
+
+
+def get_trace_id() -> str:
+    return _trace_id.get() or ZERO_TRACE_ID
+
+
+def setup_logging(
+    level: str = "INFO",
+    service_name: str = "unknown",
+    debug: bool = False,
+) -> None:
+    global _service_name
+    _service_name = service_name
+
+    log_level = getattr(logging, level.upper(), logging.INFO)
+
+    root_logger = logging.getLogger()
+    root_logger.setLevel(log_level)
+    root_logger.handlers.clear()
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(LogFormatter())
+    handler.setLevel(log_level)
+    root_logger.addHandler(handler)
+
+    _silence_libraries(debug, level)
+
+
+def _silence_libraries(debug: bool, level: str) -> None:
+    is_debug = debug or level.upper() == "DEBUG"
+
+    if is_debug:
+        loggers = SILENT_LOGGERS_DEBUG
+        silence_level = logging.WARNING
+    else:
+        loggers = SILENT_LOGGERS_PROD
+        silence_level = logging.CRITICAL
+
+    for name in loggers:
+        lib_logger = logging.getLogger(name)
+        lib_logger.setLevel(silence_level)
+        lib_logger.propagate = False
+
+
+class ExceptionLogger:
+    def log_http_error(
+        self,
+        method: str,
+        url: str,
+        path: str,
+        status_code: int,
+        detail: str,
+        exc: Exception,
+    ) -> None:
+        attrs = ExceptionAttributes(
+            exception_type=ExceptionType.HTTP,
+            error_class=type(exc).__name__,
+            error_message=detail,
+            status_code=status_code,
+            method=method,
+            url=url,
+            path=path,
+        )
+        logger = logging.getLogger(__name__)
+        logger.error(LogType.EXCEPTION, exc_info=exc, extra=attrs.as_dict())
+
+    def log_validation_error(
+        self,
+        method: str,
+        url: str,
+        path: str,
+        errors: list[Any],
+    ) -> None:
+        attrs = ExceptionAttributes(
+            exception_type=ExceptionType.VALIDATION,
+            error_class="RequestValidationError",
+            error_message=f"Validation error: {len(errors)} error(s)",
+            status_code=422,
+            method=method,
+            url=url,
+            path=path,
+            details=errors,
+        )
+        logger = logging.getLogger(__name__)
+        logger.warning(LogType.EXCEPTION, extra=attrs.as_dict())
+
+    def log_general_error(
+        self,
+        method: str,
+        url: str,
+        path: str,
+        exc: Exception,
+    ) -> None:
+        attrs = ExceptionAttributes(
+            exception_type=ExceptionType.GENERAL,
+            error_class=type(exc).__name__,
+            error_message=str(exc),
+            status_code=500,
+            method=method,
+            url=url,
+            path=path,
+        )
+        logger = logging.getLogger(__name__)
+        logger.error(LogType.EXCEPTION, exc_info=exc, extra=attrs.as_dict())

road24_sdk/_sanitizer.py

@@ -0,0 +1,61 @@
+import json
+import re
+from typing import Any
+
+SENSITIVE_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"password", re.IGNORECASE),
+    re.compile(r"token", re.IGNORECASE),
+    re.compile(r"secret", re.IGNORECASE),
+    re.compile(r"api[_-]?key", re.IGNORECASE),
+    re.compile(r"auth", re.IGNORECASE),
+    re.compile(r"credential", re.IGNORECASE),
+    re.compile(r"private[_-]?key", re.IGNORECASE),
+    re.compile(r"access[_-]?key", re.IGNORECASE),
+    re.compile(r"session[_-]?id", re.IGNORECASE),
+    re.compile(r"cookie", re.IGNORECASE),
+    re.compile(r"bearer", re.IGNORECASE),
+    re.compile(r"pin", re.IGNORECASE),
+    re.compile(r"cvv", re.IGNORECASE),
+    re.compile(r"card[_-]?number", re.IGNORECASE),
+)
+
+MASK = "***REDACTED***"
+
+
+def is_sensitive_key(key: str) -> bool:
+    return any(pattern.search(key) for pattern in SENSITIVE_PATTERNS)
+
+
+def sanitize_dict(data: dict[str, Any]) -> dict[str, Any]:
+    result = {}
+    for key, value in data.items():
+        if is_sensitive_key(key):
+            result[key] = MASK
+        elif isinstance(value, dict):
+            result[key] = sanitize_dict(value)
+        elif isinstance(value, list):
+            result[key] = [
+                sanitize_dict(item) if isinstance(item, dict) else item for item in value
+            ]
+        else:
+            result[key] = value
+    return result
+
+
+def sanitize_body(body: str) -> str:
+    if not body or not body.strip():
+        return body
+
+    try:
+        data = json.loads(body)
+        if isinstance(data, dict):
+            sanitized = sanitize_dict(data)
+            return json.dumps(sanitized, ensure_ascii=False)
+        if isinstance(data, list):
+            sanitized_list = [
+                sanitize_dict(item) if isinstance(item, dict) else item for item in data
+            ]
+            return json.dumps(sanitized_list, ensure_ascii=False)
+        return body
+    except (json.JSONDecodeError, TypeError):
+        return body

road24_sdk/_schemas.py

@@ -0,0 +1,117 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from road24_sdk._types import (
+    DbOperation,
+    ExceptionType,
+    HttpDirection,
+    RedisOperation,
+)
+
+
+@dataclass(slots=True)
+class LogRecord:
+    timestamp: str
+    trace_id: str
+    log_level: str
+    type: str
+    service_name: str
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "timestamp": self.timestamp,
+            "trace_id": self.trace_id,
+            "log_level": self.log_level,
+            "type": self.type,
+            "service_name": self.service_name,
+            "attributes": self.attributes,
+        }
+
+
+@dataclass(slots=True)
+class HttpAttributes:
+    direction: HttpDirection
+    method: str
+    url: str
+    target: str
+    status_code: int
+    duration_seconds: float
+    request_body: str = ""
+    response_body: str = ""
+    error_class: str = ""
+    error_message: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "direction": self.direction.value,
+            "method": self.method,
+            "url": self.url,
+            "target": self.target,
+            "status_code": self.status_code,
+            "duration_seconds": self.duration_seconds,
+            "request_body": self.request_body,
+            "response_body": self.response_body,
+        }
+        if self.error_class:
+            result["error_class"] = self.error_class
+            result["error_message"] = self.error_message
+        return result
+
+
+@dataclass(slots=True)
+class DbAttributes:
+    operation: DbOperation
+    table: str
+    duration_seconds: float
+    statement: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "operation": self.operation.value,
+            "table": self.table,
+            "duration_seconds": self.duration_seconds,
+            "statement": self.statement,
+        }
+
+
+@dataclass(slots=True)
+class RedisAttributes:
+    operation: RedisOperation
+    key: str
+    duration_seconds: float
+    command_args: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "operation": self.operation.value,
+            "key": self.key,
+            "duration_seconds": self.duration_seconds,
+            "command_args": self.command_args,
+        }
+
+
+@dataclass(slots=True)
+class ExceptionAttributes:
+    exception_type: ExceptionType
+    error_class: str
+    error_message: str
+    status_code: int
+    method: str
+    url: str
+    path: str
+    details: Any = None
+
+    def as_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "exception_type": self.exception_type.value,
+            "error_class": self.error_class,
+            "error_message": self.error_message,
+            "status_code": self.status_code,
+            "method": self.method,
+            "url": self.url,
+            "path": self.path,
+        }
+        if self.details is not None:
+            result["details"] = self.details
+        return result

road24_sdk/_types.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+@dataclass(slots=True)
+class ArtifactHubConfig:
+    service_name: str = "unknown"
+    log_level: str = "INFO"
+    debug: bool = False
+    log_format: str = "json"
+    integrations: list[Any] = field(default_factory=list)
+
+
+class LogType(StrEnum):
+    HTTP_REQUEST = "http_request"
+    DB_QUERY = "db_query"
+    REDIS_COMMAND = "redis_command"
+    EXCEPTION = "exception"
+
+
+class ExceptionType(StrEnum):
+    HTTP = "http"
+    VALIDATION = "validation"
+    GENERAL = "general"
+
+
+class HttpDirection(StrEnum):
+    INPUT = "input"
+    OUTPUT = "output"
+
+
+class DbOperation(StrEnum):
+    SELECT = "select"
+    INSERT = "insert"
+    UPDATE = "update"
+    DELETE = "delete"
+    OTHER = "other"
+
+
+class RedisOperation(StrEnum):
+    GET = "get"
+    SET = "set"
+    DELETE = "delete"
+    EXPIRE = "expire"
+    HGET = "hget"
+    HSET = "hset"
+    LPUSH = "lpush"
+    RPUSH = "rpush"
+    LPOP = "lpop"
+    RPOP = "rpop"
+    PUBLISH = "publish"
+    SUBSCRIBE = "subscribe"
+    OTHER = "other"

road24_sdk/integrations/__init__.py

@@ -0,0 +1,13 @@
+from road24_sdk.integrations._base import Integration
+from road24_sdk.integrations.fastapi import FastApiLoggingIntegration
+from road24_sdk.integrations.httpx import HttpxLoggingIntegration
+from road24_sdk.integrations.redis import RedisLoggingIntegration
+from road24_sdk.integrations.sqlalchemy import SqlalchemyLoggingIntegration
+
+__all__ = [
+    "FastApiLoggingIntegration",
+    "HttpxLoggingIntegration",
+    "Integration",
+    "RedisLoggingIntegration",
+    "SqlalchemyLoggingIntegration",
+]

road24_sdk/integrations/_base.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+
+
+class Integration(ABC):
+    @abstractmethod
+    def setup_once(self) -> None: ...
+
+    @classmethod
+    def _mark_setup_once(cls) -> bool:
+        flag = f"_setup_once_called_{cls.__name__}"
+        if getattr(cls, flag, False):
+            return True
+        setattr(cls, flag, True)
+        return False
+
+    @classmethod
+    def _reset_setup_once(cls) -> None:
+        flag = f"_setup_once_called_{cls.__name__}"
+        setattr(cls, flag, False)