updates

Author: MehrazRumman

.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Docs
+
+on:
+  push:
+    paths:
+      - "docs/**"
+      - "README.md"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "README.md"
+      - ".github/workflows/docs.yml"
+
+jobs:
+  docs-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Verify docs layout
+        run: |
+          test -f README.md
+          test -d docs

.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    environment:
+      name: pypi
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/tests.yml

@@ -0,0 +1,40 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  tox:
+    name: Python ${{ matrix.python-version }} / ${{ matrix.toxenv }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.10"
+            toxenv: py310
+          - python-version: "3.11"
+            toxenv: py311
+          - python-version: "3.12"
+            toxenv: py312
+          - python-version: "3.13"
+            toxenv: py313
+          - python-version: "3.14"
+            toxenv: py314
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install tox
+        run: python -m pip install --upgrade pip tox
+
+      - name: Run tests via tox
+        run: tox -e ${{ matrix.toxenv }}

.gitignore

@@ -182,9 +182,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 
@@ -205,3 +205,4 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+.pre-commit-config.yaml

README.md

@@ -1,2 +1,2 @@
 # fastapi-observer
-FastApi Logs visualization 
+FastApi Logs visualization

fastapi_observer/__init__.py

@@ -1,3 +1,5 @@
 from .config import ObserverConfig
+from .logger import build_logger, log_event
+from .models import LogEvent
 
-__all__ = ["ObserverConfig"]
+__all__ = ["ObserverConfig", "LogEvent", "build_logger", "log_event"]

fastapi_observer/logger.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import json
+import logging
+from logging.handlers import RotatingFileHandler
+from typing import Any
+
+from .config import ObserverConfig
+from .models import LogEvent
+
+_BASE_RECORD_ATTRS = set(logging.makeLogRecord({}).__dict__.keys())
+_LEVEL_TO_INT: dict[str, int] = {
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+}
+
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "timestamp": self.formatTime(record, self.datefmt),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        for key, value in record.__dict__.items():
+            if key not in _BASE_RECORD_ATTRS and key != "message":
+                payload[key] = value
+        return json.dumps(payload, default=str)
+
+
+def build_logger(
+    config: ObserverConfig, *, logger_name: str = "fastapi_observer"
+) -> logging.Logger:
+    logger = logging.getLogger(logger_name)
+    logger.setLevel(config.log_level)
+    logger.propagate = False
+
+    logger.handlers.clear()
+    formatter = _build_formatter(config)
+
+    if "console" in config.handlers:
+        console_handler = logging.StreamHandler()
+        console_handler.setFormatter(formatter)
+        logger.addHandler(console_handler)
+
+    if "file" in config.handlers:
+        file_handler = RotatingFileHandler(
+            filename=config.file_path,
+            maxBytes=config.file_max_bytes,
+            backupCount=config.file_backup_count,
+            encoding="utf-8",
+        )
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
+    return logger
+
+
+def log_event(logger: logging.Logger, config: ObserverConfig, event: LogEvent) -> None:
+    level = _LEVEL_TO_INT.get(event.level, logging.INFO)
+    payload = event.to_payload(
+        service_name=config.service_name,
+        environment=config.environment,
+    )
+    logger.log(level, event.message, extra={"event": payload})
+
+
+def _build_formatter(config: ObserverConfig) -> logging.Formatter:
+    if config.log_format == "json":
+        return JsonFormatter()
+    return logging.Formatter(
+        fmt="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+
+__all__ = ["build_logger", "log_event", "JsonFormatter"]

fastapi_observer/models.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+from .config import LogLevel
+
+
+class LogEvent(BaseModel):
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    level: LogLevel = "INFO"
+    message: str
+    method: str
+    path: str
+    status_code: int | None = None
+    duration_ms: float | None = None
+    correlation_id: str | None = None
+    error: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"str_strip_whitespace": True}
+
+    @field_validator("method")
+    @classmethod
+    def _normalize_method(cls, value: str) -> str:
+        method = value.upper()
+        if not method:
+            raise ValueError("method must be non-empty")
+        return method
+
+    @field_validator("path")
+    @classmethod
+    def _normalize_path(cls, value: str) -> str:
+        if not value:
+            raise ValueError("path must be non-empty")
+        path = value if value.startswith("/") else f"/{value}"
+        if len(path) > 1 and path.endswith("/"):
+            path = path.rstrip("/")
+        return path
+
+    @field_validator("duration_ms")
+    @classmethod
+    def _validate_duration(cls, value: float | None) -> float | None:
+        if value is not None and value < 0:
+            raise ValueError("duration_ms must be non-negative")
+        return value
+
+    def to_payload(self, *, service_name: str, environment: str) -> dict[str, Any]:
+        return {
+            "timestamp": self.timestamp.isoformat(),
+            "service_name": service_name,
+            "environment": environment,
+            "level": self.level,
+            "message": self.message,
+            "method": self.method,
+            "path": self.path,
+            "status_code": self.status_code,
+            "duration_ms": self.duration_ms,
+            "correlation_id": self.correlation_id,
+            "error": self.error,
+            "metadata": self.metadata,
+        }
+
+
+__all__ = ["LogEvent"]

pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastapi-observer"
+version = "0.1.0"
+description = "Logging and observability helpers for FastAPI applications."
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+license = { file = "LICENSE" }
+authors = [{ name = "fastapi-observer maintainers" }]
+dependencies = [
+  "pydantic>=2.0,<3.0",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.0",
+]
+dev = [
+  "pre-commit>=3.7",
+  "black>=24.10",
+]
+
+[tool.setuptools.packages.find]
+include = ["fastapi_observer*"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]

setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()