initial import

Signed-off-by: Damien Degois <[email protected]>

Author: babs

.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: "Build and release"
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-release:
+    runs-on: "ubuntu-latest"
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+
+      - name: Install requirements
+        run: |
+          pip install --upgrade pip
+          pip install -r requirements-release.txt
+
+      - name: Build
+        run: |
+          VERSION=${GITHUB_REF_NAME##v}
+          echo VERSION=$VERSION
+          echo $VERSION > VERSION
+          python -m build -s -w
+
+      - name: Publish package distributions to ${{ vars.PYPI_REPOSITORY }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ vars.PYPI_REPOSITORY }}
+
+      - name: Create release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ github.ref_name }}
+        run: |
+          gh release create "$tag" \
+              --repo="$GITHUB_REPOSITORY" \
+              --title="${GITHUB_REPOSITORY#*/} ${tag}" \
+              --generate-notes

.gitignore

@@ -0,0 +1,11 @@
+dist
+build
+fastapi_structured_logging.egg-info
+venv
+__pycache__
+.mypy_cache/
+*.pyc
+.vscode
+.coverage
+cov.xml
+VERSION

.pre-commit-config.yaml

@@ -0,0 +1,67 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+- repo: https://github.com/psf/black
+  rev: 22.3.0
+  hooks:
+  - id: black
+    args: [--safe, --line-length=110]
+
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v3.2.0
+  hooks:
+  - id: trailing-whitespace
+  - id: end-of-file-fixer
+  - id: check-yaml
+    args: [--allow-multiple-documents]
+  - id: check-toml
+  - id: check-added-large-files
+  - id: check-merge-conflict
+  - id: detect-private-key
+  - id: debug-statements
+    language_version: python3
+
+- repo: https://github.com/PyCQA/flake8
+  rev: 5.0.4
+  hooks:
+  - id: flake8
+    args: [--max-line-length, "110"]
+    language_version: python3
+
+
+- repo: https://github.com/asottile/reorder_python_imports
+  rev: v2.6.0
+  hooks:
+  - id: reorder-python-imports
+    args: ["--application-directories=.:src", "--py36-plus"]
+
+- repo: https://github.com/asottile/pyupgrade
+  rev: v2.29.0
+  hooks:
+  - id: pyupgrade
+    args: [--py36-plus]
+
+- repo: https://github.com/Yelp/detect-secrets
+  rev: v1.3.0
+  hooks:
+  - id: detect-secrets
+
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v0.910
+  hooks:
+  - id: mypy
+    files: ^(src/|examples/)
+    args:
+      - --check-untyped-defs
+      - --disallow-any-generics
+      - --ignore-missing-imports
+      - --no-implicit-optional
+      - --show-error-codes
+      - --strict-equality
+      - --warn-redundant-casts
+      - --warn-return-any
+      - --warn-unreachable
+      - --warn-unused-configs
+      - --no-implicit-reexport
+    additional_dependencies:
+      - types-orjson

README.md

@@ -0,0 +1,105 @@
+# fastapi-structured-logging
+
+fastapi-structured-logging
+
+fastapi-structured-logging is a lightweight Python module that provides structured logging utilities and a configurable FastAPI access logging middleware. It configures `structlog` for JSON or console output, enriches log events with OpenTelemetry trace and span identifiers, and exposes an `AccessLogMiddleware` that can record request method, path, query parameters, client IP, user agent, status codes, processing time and more.
+
+The middleware supports filtering, trusted-proxy handling, custom fields and messages, and integrates cleanly with existing Python logging to produce consistent, machine-readable access logs for observability and tracing.
+
+## Usage
+
+```python
+from fastapi import FastAPI
+
+import fastapi_structured_logging
+
+# Set output to text if stdout is a tty, structured json if not
+fastapi_structured_logging.setup_logging()
+
+logger = fastapi_structured_logging.get_logger()
+
+app = FastAPI()
+
+app.add_middleware(fastapi_structured_logging.AccessLogMiddleware)
+
+```
+
+## Configuration Options
+
+The library provides extensive configuration options to customize logging and access logging behavior.
+
+### setup_logging() Options
+
+- `json_logs` (Optional[bool]): Forces JSON output if True, console output if False. Defaults to JSON if stdout is not a tty (e.g., in containers or files). Example: `setup_logging(json_logs=True)` for always JSON logs.
+- `log_level` (str): Sets the logging level (e.g., "DEBUG", "INFO", "WARNING"). Defaults to "INFO". Example: `setup_logging(log_level="DEBUG")` to enable debug logging.
+
+### AccessLogMiddleware Options
+
+The middleware can be configured via an `AccessLogConfig` object passed to the middleware constructor. Example:
+
+```python
+from fastapi_structured_logging import AccessLogConfig
+
+config = AccessLogConfig(
+    log_level="info",
+    include_user_agent=False,
+    exclude_paths={"/health"},
+    custom_fields={"app_version": "1.0.0"}
+)
+app.add_middleware(fastapi_structured_logging.AccessLogMiddleware, config=config)
+```
+
+Key options include:
+
+- `enabled` (bool): Enables or disables access logging. Default: True.
+- `log_level` (str): Log level for access logs ("debug", "info", etc.). Default: "info".
+- `include_*` flags: Control which fields are logged, such as `include_method` (request method), `include_path` (request path), `include_query_params` (query parameters), `include_client_ip` (client IP), `include_user_agent` (user agent string), `include_forwarded_headers` (proxy headers), `include_status_code` (response status), `include_process_time` (processing time in ms), `include_content_length` (response content length), `include_referer` (referer header). All default to True except `include_referer` (False).
+- `exclude_*` sets: Filter out logs for specific paths (`exclude_paths`), methods (`exclude_methods`), status codes (`exclude_status_codes`), or paths only if status is 200 or 404 (`exclude_paths_if_ok_or_missing`).
+- `min_process_time` / `max_process_time` (Optional[float]): Only log requests with processing time within these bounds (in seconds).
+- `custom_message` (str): Custom log message. Default: "Access".
+- `custom_fields` (Dict[str, Any]): Additional fields to include in every log entry. Example: `{"app_version": "1.0.0"}`.
+- `logger_name` (str): Name of the logger to use. Default: "access_log".
+- `trusted_proxy` (List[str]): List of CIDR ranges for trusted proxies to extract real client IP. Example: `["10.0.0.0/8", "192.168.0.0/16"]`.
+
+## Convenience functions
+
+- `setup_logging()` initialize `structlog` to use line logging if stdout is a tty or JSONL if not (file, container output etc...)
+
+- `get_logger()` return a `structlog` logger
+
+- `json_serializer()` for fast serialization in `orjson`
+
+    ```python
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_exception_handler(request: Request, exc: RequestValidationError):
+        exc_str = f"{exc}".replace("\n", " ").replace("   ", " ")
+        logger.error("validation exception", validation_error=json_serializer(exc.errors()))
+        content = {"status_code": 10422, "message": exc_str, "data": None}
+        return JSONResponse(content=content, status_code=status.HTTP_422_UNPROCESSABLE_ENTITY)
+
+    ```
+
+## Setup dev env
+
+```bash
+uv venv
+uv pip install -r requirements-dev.txt
+pre-commit install
+```
+
+## Test
+
+```bash
+. venv/bin/activate
+uv pip install -e .[full]
+pytest --cov-report html --cov-report term --cov-report xml:cov.xml
+```
+
+## Build
+
+```bash
+echo x.y.z > VERSION
+uv pip install -r requirements-release.txt
+uv run python -m build -s -w
+```

examples/README.md

@@ -0,0 +1,120 @@
+# fastapi-structured-logging Example
+
+This example demonstrates how to integrate structured logging into a FastAPI application using the `fastapi-structured-logging` library. It showcases:
+
+- Setting up structured logging with JSON output
+- Adding access log middleware for request logging
+- Custom exception handling with structured error logging
+- Basic FastAPI endpoints with contextual logging
+
+## Prerequisites
+
+- Python 3.9+
+- [uv](https://github.com/astral-sh/uv) package manager
+
+## Installation
+
+1. Create a virtual environment:
+
+    ```bash
+    uv venv
+    ```
+
+2. Install dependencies:
+
+    ```bash
+    uv pip install -r requirements.txt
+    ```
+
+3. Install OpenTelemetry auto-instrumentation:
+
+    ```bash
+    uv run opentelemetry-bootstrap -a requirements | uv pip install --requirement -
+    ```
+
+## Integration
+
+```python
+from fastapi import FastAPI
+
+import fastapi_structured_logging
+
+# Set output to text if stdout is a tty, structured json if not
+fastapi_structured_logging.setup_logging()
+
+logger = fastapi_structured_logging.get_logger()
+
+app = FastAPI()
+
+app.add_middleware(fastapi_structured_logging.AccessLogMiddleware)
+
+```
+
+## Running the Example
+
+Run the FastAPI application with OpenTelemetry instrumentation:
+
+```bash
+uv run opentelemetry-instrument uvicorn example1:app
+```
+
+The server will start on `http://0.0.0.0:8000`.
+
+## Testing the Example
+
+- Visit `http://localhost:8000/` for the root endpoint
+- Visit `http://localhost:8000/hello?who=World` for the hello endpoint
+- Try invalid requests to see validation error logging
+
+## Expected Output
+
+When running, you'll see structured JSON logs for:
+
+- HTTP requests (via middleware)
+- Endpoint-specific messages
+- Error handling
+
+Example log output (formatted for readability):
+
+### Application log
+
+```json
+{
+    "context_info1": "value1",
+    "context_info2": "value2",
+    "trace_id": "4c2c057a18cfff3a0709e2c04454a60d",
+    "span_id": "25d9ce4aab9e8ad9",
+    "method": "GET",
+    "client_ip": "127.0.0.1",
+    "path": "/hello",
+    "user_agent": "curl/8.5.0",
+    "remote_host": "127.0.0.1",
+    "query_params": "who=a",
+    "logger": "example1",
+    "level": "info",
+    "timestamp": "2025-10-01T06:16:28.707054Z",
+    "message": "log line message"
+}
+```
+
+### Access log
+
+```json
+{
+    "status_code": 200,
+    "process_time_ms": 0.985861,
+    "content_length": 21,
+    "trace_id": "4c2c057a18cfff3a0709e2c04454a60d",
+    "span_id": "25d9ce4aab9e8ad9",
+    "method": "GET",
+    "client_ip": "127.0.0.1",
+    "path": "/hello",
+    "user_agent": "curl/8.5.0",
+    "remote_host": "127.0.0.1",
+    "query_params": "who=a",
+    "logger": "access_log",
+    "level": "info",
+    "timestamp": "2025-10-01T06:16:28.707480Z",
+    "message": "Access"
+}
+```

examples/example1.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+import uvicorn
+from fastapi import FastAPI
+
+import fastapi_structured_logging
+
+# Set output to text if stdout is a tty, structured json if not
+fastapi_structured_logging.setup_logging()
+
+logger = fastapi_structured_logging.get_logger()
+
+app = FastAPI()
+
+app.add_middleware(fastapi_structured_logging.AccessLogMiddleware)
+
+
+@app.get("/")
+async def root():
+    logger.info("Handling root endpoint accessed")
+    return {"message": "Hello World"}
+
+
+@app.get("/hello")
+def hello(who: str):
+    logger.info(
+        "log line message",
+        context_info1="value1",
+        context_info2="value2",
+    )
+    return {"message": f"Hello {who}"}
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)

examples/requirements.txt

@@ -0,0 +1,7 @@
+-r ../requirements.txt
+uvicorn[standard]
+opentelemetry-api
+opentelemetry-sdk
+opentelemetry-distro
+opentelemetry-exporter-otlp
+..