elven-logs-interceptor-python 0.1.2__tar.gz

elven_logs_interceptor_python-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: ci
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Typecheck
+        run: mypy src
+      - name: Tests
+        run: pytest

elven_logs_interceptor_python-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: Target repository
+        required: true
+        default: testpypi
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Quality gates
+        run: |
+          python -m ruff check .
+          python -m mypy src
+          python -m pytest -q
+
+      - name: Build package
+        run: |
+          rm -rf build dist
+          python -m build
+          python -m twine check dist/*
+
+      - name: Publish to TestPyPI
+        if: ${{ inputs.repository == 'testpypi' }}
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        run: |
+          if [ -z "${TWINE_PASSWORD}" ]; then
+            echo "Missing secret TEST_PYPI_API_TOKEN"
+            exit 1
+          fi
+          python -m twine upload --repository-url https://test.pypi.org/legacy/ --skip-existing dist/*
+
+      - name: Publish to PyPI
+        if: ${{ inputs.repository == 'pypi' }}
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          if [ -z "${TWINE_PASSWORD}" ]; then
+            echo "Missing secret PYPI_API_TOKEN"
+            exit 1
+          fi
+          python -m twine upload --repository-url https://upload.pypi.org/legacy/ --skip-existing dist/*

elven_logs_interceptor_python-0.1.2/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.venv/
+.env
+.DS_Store
+.logs-interceptor-dlq/
+build/
+dist/
+test-apps/**/.env

elven_logs_interceptor_python-0.1.2/ARCHITECTURE.md

@@ -0,0 +1,36 @@
+# Clean Architecture - elven-logs-interceptor-python
+
+This project follows Clean Architecture and SOLID principles.
+
+## Layers
+
+- `domain/`: entities, value objects, interfaces/protocols.
+- `application/`: orchestration use-cases (`ConfigService`, `LogService`).
+- `infrastructure/`: concrete implementations (transport, buffer, filter, circuit breaker, DLQ, interceptors).
+- `presentation/`: object graph factory and runtime wiring.
+
+## Core Flow
+
+1. User logs through API (`logger.info`, etc).
+2. `LogService` builds `LogEntryEntity` with context and dynamic labels.
+3. `LogFilter` applies level checks, sampling, sanitization.
+4. `MemoryBuffer` stores entries with bounded-memory policies.
+5. Flush pipeline pushes batches to `ResilientTransport`.
+6. `ResilientTransport` applies retry + circuit breaker + DLQ fallback.
+7. Loki receives logs through JSON or Snappy path.
+
+## Resilience
+
+- Retry with exponential backoff + jitter.
+- Circuit breaker with closed/open/half-open states.
+- DLQ with bounded memory/file storage and drop-oldest policy.
+
+## Runtime Model
+
+- Sync-first API for app safety.
+- Async wrappers (`aflush`, `adestroy`) via thread offload.
+- Background flush workers capped by `max_concurrent_flushes`.
+
+## Extensibility
+
+Add a new transport by implementing `ILogTransport` contract and wiring it in `TransportFactory`.

elven_logs_interceptor_python-0.1.2/Makefile

@@ -0,0 +1,34 @@
+PYTHON ?= python3
+
+.PHONY: install-dev lint typecheck test qa build clean publish-dry-run publish-testpypi publish-pypi
+
+install-dev:
+	$(PYTHON) -m pip install -e ".[dev]"
+
+lint:
+	$(PYTHON) -m ruff check .
+
+typecheck:
+	$(PYTHON) -m mypy src
+
+test:
+	$(PYTHON) -m pytest -q
+
+qa: lint typecheck test
+
+clean:
+	rm -rf build dist
+	find . -maxdepth 1 -type d -name "*.egg-info" -exec rm -rf {} +
+
+build: clean
+	$(PYTHON) -m build
+	$(PYTHON) -m twine check dist/*
+
+publish-dry-run:
+	./scripts/publish.sh --dry-run
+
+publish-testpypi:
+	./scripts/publish.sh --repository testpypi
+
+publish-pypi:
+	./scripts/publish.sh --repository pypi

elven_logs_interceptor_python-0.1.2/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: elven-logs-interceptor-python
+Version: 0.1.2
+Summary: Production-grade logs interceptor for Python with Loki transport, resilience, batching, and framework integrations.
+Author: Elven Observability
+License: MIT
+Keywords: clean-architecture,interceptor,logging,logs,loki,observability,resilience
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: typing-extensions>=4.12.0
+Provides-Extra: all
+Requires-Dist: brotli>=1.1.0; extra == 'all'
+Requires-Dist: celery>=5.4.0; extra == 'all'
+Requires-Dist: django>=4.2; extra == 'all'
+Requires-Dist: fastapi>=0.111.0; extra == 'all'
+Requires-Dist: flask>=3.0.0; extra == 'all'
+Requires-Dist: loguru>=0.7.2; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.24.0; extra == 'all'
+Requires-Dist: orjson>=3.10.0; extra == 'all'
+Requires-Dist: protobuf>=5.0.0; extra == 'all'
+Requires-Dist: python-snappy>=0.7.1; extra == 'all'
+Requires-Dist: starlette>=0.37.0; extra == 'all'
+Requires-Dist: structlog>=24.0.0; extra == 'all'
+Provides-Extra: celery
+Requires-Dist: celery>=5.4.0; extra == 'celery'
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.111.0; extra == 'fastapi'
+Requires-Dist: starlette>=0.37.0; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=3.0.0; extra == 'flask'
+Provides-Extra: loguru
+Requires-Dist: loguru>=0.7.2; extra == 'loguru'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.24.0; extra == 'otel'
+Provides-Extra: perf
+Requires-Dist: brotli>=1.1.0; extra == 'perf'
+Requires-Dist: orjson>=3.10.0; extra == 'perf'
+Requires-Dist: protobuf>=5.0.0; extra == 'perf'
+Requires-Dist: python-snappy>=0.7.1; extra == 'perf'
+Provides-Extra: structlog
+Requires-Dist: structlog>=24.0.0; extra == 'structlog'
+Description-Content-Type: text/markdown
+
+# elven-logs-interceptor-python
+
+High-performance, production-ready log interceptor for Python with Loki transport, batching, compression, circuit breaker, DLQ, and framework integrations.
+
+## Installation
+
+```bash
+pip install elven-logs-interceptor-python
+```
+
+With all extras:
+
+```bash
+pip install "elven-logs-interceptor-python[all]"
+```
+
+## Quick Start
+
+```python
+from logs_interceptor import init, logger
+
+init(
+    {
+        "appName": "billing-service",
+        "interceptConsole": True,
+        "transport": {
+            "url": "https://loki.example.com/loki/api/v1/push",
+            "tenantId": "tenant-a",
+            "authToken": "token",
+            "compression": "gzip",
+        },
+    }
+)
+
+logger.info("service started", {"port": 3000})
+```
+
+## Environment Variables
+
+The package supports all `LOGS_*` variables from the JS v3 design.
+
+Required:
+
+- `LOGS_URL`
+- `LOGS_TENANT`
+- `LOGS_APP_NAME`
+
+Core:
+
+- `LOGS_TOKEN`
+- `LOGS_APP_VERSION`
+- `LOGS_ENVIRONMENT`
+
+Transport:
+
+- `LOGS_COMPRESSION` (`none|gzip|brotli|snappy`)
+- `LOGS_COMPRESSION_LEVEL`
+- `LOGS_COMPRESSION_THRESHOLD`
+- `LOGS_USE_WORKERS`
+- `LOGS_MAX_WORKERS`
+- `LOGS_WORKER_TIMEOUT`
+- `LOGS_CONNECTION_POOLING`
+- `LOGS_MAX_SOCKETS`
+- `LOGS_TIMEOUT`
+- `LOGS_MAX_RETRIES`
+- `LOGS_RETRY_DELAY`
+
+Buffer:
+
+- `LOGS_BUFFER_MAX_SIZE`
+- `LOGS_BUFFER_FLUSH_INTERVAL`
+- `LOGS_BUFFER_MAX_MEMORY_MB`
+- `LOGS_BUFFER_MAX_AGE`
+- `LOGS_BUFFER_AUTO_FLUSH`
+
+Filter:
+
+- `LOGS_FILTER_LEVELS`
+- `LOGS_FILTER_SAMPLING_RATE`
+- `LOGS_FILTER_SANITIZE`
+- `LOGS_FILTER_MAX_MESSAGE_LENGTH`
+
+Circuit Breaker:
+
+- `LOGS_CIRCUIT_BREAKER_ENABLED`
+- `LOGS_CIRCUIT_BREAKER_FAILURE_THRESHOLD`
+- `LOGS_CIRCUIT_BREAKER_RESET_TIMEOUT`
+- `LOGS_CIRCUIT_BREAKER_HALF_OPEN_REQUESTS`
+
+DLQ:
+
+- `LOGS_DLQ_ENABLED`
+- `LOGS_DLQ_TYPE` (`memory|file`)
+- `LOGS_DLQ_MAX_SIZE`
+- `LOGS_DLQ_MAX_RETRIES`
+- `LOGS_DLQ_BASE_PATH`
+
+Runtime:
+
+- `LOGS_MAX_CONCURRENT_FLUSHES`
+- `LOGS_INTERCEPT_CONSOLE`
+- `LOGS_PRESERVE_ORIGINAL_CONSOLE`
+- `LOGS_ENABLE_METRICS`
+- `LOGS_ENABLE_HEALTH_CHECK`
+- `LOGS_DEBUG`
+- `LOGS_SILENT_ERRORS`
+- `LOGS_ENABLED`
+- `LOGS_AUTO_INIT`
+- `LOGS_ENABLE_EXPERIMENTAL_PROTOBUF` (optional, enables experimental snappy/protobuf transport path)
+
+Labels:
+
+- Prefix `LOGS_LABEL_*` (example: `LOGS_LABEL_SERVICE=billing`)
+
+## Public API
+
+- `init(config)`
+- `get_logger()`
+- `is_initialized()`
+- `destroy()`
+- `adestroy()`
+- `logger` proxy with `debug/info/warn/error/fatal/log/track_event/flush/aflush/get_metrics/get_health/destroy/adestroy/with_context/with_context_async`
+
+Python import remains:
+
+```python
+import logs_interceptor
+```
+
+## Integrations
+
+- Python `logging` (`LoggingHandler`)
+- FastAPI / Starlette (`FastAPIMiddleware`)
+- Django (`DjangoMiddleware`)
+- Flask (`FlaskExtension`)
+- Celery (`CelerySignals`)
+- structlog (`StructlogProcessor`)
+- loguru (`LoguruSink`)
+
+## Auto Init
+
+Set `LOGS_AUTO_INIT=true` and import the package.
+
+Preload mode:
+
+```bash
+python -m logs_interceptor.preload
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+mypy src
+pytest
+```
+
+## Deploy / Publish
+
+Local publish script:
+
+```bash
+./scripts/publish.sh --repository testpypi --dry-run
+./scripts/publish.sh --repository testpypi
+./scripts/publish.sh --repository pypi
+```
+
+Token environment variables used by default:
+
+- `TEST_PYPI_API_TOKEN` for `--repository testpypi`
+- `PYPI_API_TOKEN` for `--repository pypi`
+
+Optional script flags:
+
+- `--skip-checks` (skip lint/type/test)
+- `--skip-build` (skip build/twine check)
+- `--token-env CUSTOM_VAR` (custom token env var name)
+- `--no-skip-existing` (upload fails if version already exists)
+
+Makefile shortcuts:
+
+```bash
+make qa
+make publish-dry-run
+make publish-testpypi
+make publish-pypi
+```
+
+GitHub Actions publish workflow:
+
+- File: `.github/workflows/publish.yml`
+- Trigger: manual (`workflow_dispatch`)
+- Inputs: `repository = testpypi | pypi`
+- Required secrets:
+  - `TEST_PYPI_API_TOKEN`
+  - `PYPI_API_TOKEN`
+
+## License
+
+MIT

elven_logs_interceptor_python-0.1.2/README.md

@@ -0,0 +1,201 @@
+# elven-logs-interceptor-python
+
+High-performance, production-ready log interceptor for Python with Loki transport, batching, compression, circuit breaker, DLQ, and framework integrations.
+
+## Installation
+
+```bash
+pip install elven-logs-interceptor-python
+```
+
+With all extras:
+
+```bash
+pip install "elven-logs-interceptor-python[all]"
+```
+
+## Quick Start
+
+```python
+from logs_interceptor import init, logger
+
+init(
+    {
+        "appName": "billing-service",
+        "interceptConsole": True,
+        "transport": {
+            "url": "https://loki.example.com/loki/api/v1/push",
+            "tenantId": "tenant-a",
+            "authToken": "token",
+            "compression": "gzip",
+        },
+    }
+)
+
+logger.info("service started", {"port": 3000})
+```
+
+## Environment Variables
+
+The package supports all `LOGS_*` variables from the JS v3 design.
+
+Required:
+
+- `LOGS_URL`
+- `LOGS_TENANT`
+- `LOGS_APP_NAME`
+
+Core:
+
+- `LOGS_TOKEN`
+- `LOGS_APP_VERSION`
+- `LOGS_ENVIRONMENT`
+
+Transport:
+
+- `LOGS_COMPRESSION` (`none|gzip|brotli|snappy`)
+- `LOGS_COMPRESSION_LEVEL`
+- `LOGS_COMPRESSION_THRESHOLD`
+- `LOGS_USE_WORKERS`
+- `LOGS_MAX_WORKERS`
+- `LOGS_WORKER_TIMEOUT`
+- `LOGS_CONNECTION_POOLING`
+- `LOGS_MAX_SOCKETS`
+- `LOGS_TIMEOUT`
+- `LOGS_MAX_RETRIES`
+- `LOGS_RETRY_DELAY`
+
+Buffer:
+
+- `LOGS_BUFFER_MAX_SIZE`
+- `LOGS_BUFFER_FLUSH_INTERVAL`
+- `LOGS_BUFFER_MAX_MEMORY_MB`
+- `LOGS_BUFFER_MAX_AGE`
+- `LOGS_BUFFER_AUTO_FLUSH`
+
+Filter:
+
+- `LOGS_FILTER_LEVELS`
+- `LOGS_FILTER_SAMPLING_RATE`
+- `LOGS_FILTER_SANITIZE`
+- `LOGS_FILTER_MAX_MESSAGE_LENGTH`
+
+Circuit Breaker:
+
+- `LOGS_CIRCUIT_BREAKER_ENABLED`
+- `LOGS_CIRCUIT_BREAKER_FAILURE_THRESHOLD`
+- `LOGS_CIRCUIT_BREAKER_RESET_TIMEOUT`
+- `LOGS_CIRCUIT_BREAKER_HALF_OPEN_REQUESTS`
+
+DLQ:
+
+- `LOGS_DLQ_ENABLED`
+- `LOGS_DLQ_TYPE` (`memory|file`)
+- `LOGS_DLQ_MAX_SIZE`
+- `LOGS_DLQ_MAX_RETRIES`
+- `LOGS_DLQ_BASE_PATH`
+
+Runtime:
+
+- `LOGS_MAX_CONCURRENT_FLUSHES`
+- `LOGS_INTERCEPT_CONSOLE`
+- `LOGS_PRESERVE_ORIGINAL_CONSOLE`
+- `LOGS_ENABLE_METRICS`
+- `LOGS_ENABLE_HEALTH_CHECK`
+- `LOGS_DEBUG`
+- `LOGS_SILENT_ERRORS`
+- `LOGS_ENABLED`
+- `LOGS_AUTO_INIT`
+- `LOGS_ENABLE_EXPERIMENTAL_PROTOBUF` (optional, enables experimental snappy/protobuf transport path)
+
+Labels:
+
+- Prefix `LOGS_LABEL_*` (example: `LOGS_LABEL_SERVICE=billing`)
+
+## Public API
+
+- `init(config)`
+- `get_logger()`
+- `is_initialized()`
+- `destroy()`
+- `adestroy()`
+- `logger` proxy with `debug/info/warn/error/fatal/log/track_event/flush/aflush/get_metrics/get_health/destroy/adestroy/with_context/with_context_async`
+
+Python import remains:
+
+```python
+import logs_interceptor
+```
+
+## Integrations
+
+- Python `logging` (`LoggingHandler`)
+- FastAPI / Starlette (`FastAPIMiddleware`)
+- Django (`DjangoMiddleware`)
+- Flask (`FlaskExtension`)
+- Celery (`CelerySignals`)
+- structlog (`StructlogProcessor`)
+- loguru (`LoguruSink`)
+
+## Auto Init
+
+Set `LOGS_AUTO_INIT=true` and import the package.
+
+Preload mode:
+
+```bash
+python -m logs_interceptor.preload
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+mypy src
+pytest
+```
+
+## Deploy / Publish
+
+Local publish script:
+
+```bash
+./scripts/publish.sh --repository testpypi --dry-run
+./scripts/publish.sh --repository testpypi
+./scripts/publish.sh --repository pypi
+```
+
+Token environment variables used by default:
+
+- `TEST_PYPI_API_TOKEN` for `--repository testpypi`
+- `PYPI_API_TOKEN` for `--repository pypi`
+
+Optional script flags:
+
+- `--skip-checks` (skip lint/type/test)
+- `--skip-build` (skip build/twine check)
+- `--token-env CUSTOM_VAR` (custom token env var name)
+- `--no-skip-existing` (upload fails if version already exists)
+
+Makefile shortcuts:
+
+```bash
+make qa
+make publish-dry-run
+make publish-testpypi
+make publish-pypi
+```
+
+GitHub Actions publish workflow:
+
+- File: `.github/workflows/publish.yml`
+- Trigger: manual (`workflow_dispatch`)
+- Inputs: `repository = testpypi | pypi`
+- Required secrets:
+  - `TEST_PYPI_API_TOKEN`
+  - `PYPI_API_TOKEN`
+
+## License
+
+MIT

elven_logs_interceptor_python-0.1.2/examples/basic_app.py

@@ -0,0 +1,18 @@
+from logs_interceptor import init
+
+init(
+    {
+        "appName": "my-service",
+        "interceptConsole": True,
+        "transport": {
+            "url": "http://localhost:3100/loki/api/v1/push",
+            "tenantId": "my-tenant",
+            "compression": "gzip",
+            "enableConnectionPooling": True,
+        },
+        "deadLetterQueue": {"enabled": True, "type": "file"},
+        "circuitBreaker": {"enabled": True},
+    }
+)
+
+print("service started")

elven_logs_interceptor_python-0.1.2/examples/fastapi_integration.py

@@ -0,0 +1,26 @@
+from fastapi import FastAPI
+
+from logs_interceptor import init, logger
+from logs_interceptor.integrations import FastAPIMiddleware
+
+init(
+    {
+        "transport": {
+            "url": "http://localhost:3100/loki/api/v1/push",
+            "tenantId": "my-tenant",
+            "compression": "brotli",
+        },
+        "appName": "my-api",
+        "interceptConsole": True,
+        "deadLetterQueue": {"enabled": True, "type": "file"},
+    }
+)
+
+app = FastAPI()
+app.add_middleware(FastAPIMiddleware, logger=logger)
+
+
+@app.get("/ping")
+def ping() -> dict[str, str]:
+    logger.info("ping called")
+    return {"message": "pong"}