elven-logs-interceptor-python 0.1.2__py3-none-any.whl

elven_logs_interceptor_python-0.1.2.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,56 @@
+logs_interceptor/__init__.py,sha256=ABMJGimpNjQMn9BtSCkmvTpjlAKEKiw0r_gqj4uO3qk,12143
+logs_interceptor/config.py,sha256=AdRGtoZ_XG8CgC-yYC9O0a1h16bU5I0tL62NNoTgKcU,5057
+logs_interceptor/preload.py,sha256=8BQEpLibDCQJpm0PwSdvikEEbfGxZSms0ov2v9eQbiY,1735
+logs_interceptor/types.py,sha256=USRT-1t8K12nlyqFES38jOtvzi-ZU3wPgeAhIGssjcQ,1971
+logs_interceptor/utils.py,sha256=Mnnigx3WfC55ILDxJ872KB59T9hymHlO-Fv-FkM59dk,18232
+logs_interceptor/application/__init__.py,sha256=UeK-yoi200-4FryM-v2cCruTHe0Yjzbzyiiti4ZIwes,613
+logs_interceptor/application/config_service.py,sha256=zDvNsx3L5bNNCLavgquVdELwudO5kPqxc_AZRmoHMNM,10265
+logs_interceptor/application/log_service.py,sha256=Rorlfq_L1C0fs8661MP61toq7fTfVezR1NGUU8RXEXE,13699
+logs_interceptor/domain/__init__.py,sha256=01vyK7FVaGTaMbgjoBYD8SyQJ0oWMRpCqMNwNu_4pIE,474
+logs_interceptor/domain/entities.py,sha256=RleSeQmU5rK3Vv8onNYHFkDMXHdfjpE-6R0heLvdjTw,1158
+logs_interceptor/domain/interfaces.py,sha256=trFLzgauQdGRxMCdeVgli-fzvg_X8RKHtSjHSSyfMPQ,3787
+logs_interceptor/domain/value_objects.py,sha256=Z9yIMF6-kJLC9juO2rLCo5MRaUlqFG1deFtwvexrlmc,1130
+logs_interceptor/infrastructure/__init__.py,sha256=HSB0RlVGL_14SrwFOvC-Fnfqg35MPJlDBoFW0H0MLMc,1177
+logs_interceptor/infrastructure/buffer/__init__.py,sha256=paRwx_7lvJ8quGeOMdJdZeDEHRUBGEkg6923LH-DQmY,68
+logs_interceptor/infrastructure/buffer/memory_buffer.py,sha256=ZVRRJwROImAc3xVBR1NsovYq6vX5H8pIdO89esPx6L8,6437
+logs_interceptor/infrastructure/circuit_breaker/__init__.py,sha256=KKKX5AHbvkPoI6gO6o3e4xqS0ch9F0uk0PoZJGLEoWs,74
+logs_interceptor/infrastructure/circuit_breaker/circuit_breaker.py,sha256=8BZHFY1AjzWRnoGL1l47yrP1BEE-WEKLRGK1xanB_oM,3858
+logs_interceptor/infrastructure/compression/__init__.py,sha256=063D7o9SuB_42T6XxIaxXgfyvs3yu0svPBJ7Th-_K8I,372
+logs_interceptor/infrastructure/compression/base.py,sha256=DNgUfyPaONj9FkKnEeE4JOP0OspMZZRlbkkQMIq5t64,425
+logs_interceptor/infrastructure/compression/brotli_compressor.py,sha256=lYSReVzY2SsUvNJK8gHxfGbhTpgFgf3jH54pbIzDCVs,813
+logs_interceptor/infrastructure/compression/factory.py,sha256=BoRA-3Am8jqrYZOqrLGMzKdieJGRYKoh00Syb3znZxM,645
+logs_interceptor/infrastructure/compression/gzip_compressor.py,sha256=1cOO_GEQCaTQYjKmvpv-LfbJ9WN88ecjT_DkdIqGnmI,563
+logs_interceptor/infrastructure/compression/noop_compressor.py,sha256=GCxjF3NFMQvQokoMjCZS7vkS97bH5NjKo-SmNgdWgZE,283
+logs_interceptor/infrastructure/context/__init__.py,sha256=0jj06F58P3d0cK0xzW-TQUwQolmk-VM7-MmgPISo-zE,83
+logs_interceptor/infrastructure/context/context_provider.py,sha256=ntTK5QygprGgJPmBfXodJ57OlfDG_2uov8-w3exjAhw,1367
+logs_interceptor/infrastructure/dlq/__init__.py,sha256=BHmiKjxD2RfToQoYwwwpnQrZq7BjTEiOF3dYHsP6ouc,148
+logs_interceptor/infrastructure/dlq/file_dlq.py,sha256=YgI7800Gf8z6SvMDHplSmmAo_2Ea_fRcaYLEA3GCLOY,6184
+logs_interceptor/infrastructure/dlq/memory_dlq.py,sha256=2ekk4-IRLA5zt6nfE4LtwNenYqTU7KvIcy70z4dSVws,1714
+logs_interceptor/infrastructure/filter/__init__.py,sha256=j5x8PzlxkLQRuzQBV2TvR9MOgKbSY7s687j2XJEzPRc,59
+logs_interceptor/infrastructure/filter/log_filter.py,sha256=_xWK9OQS8avntzKk4COBtH8IWVlweaFX7-0RCZBwtPo,1839
+logs_interceptor/infrastructure/interceptors/__init__.py,sha256=vJ6b8mM_7xHgw0aw8IBJjy5d3Bml-DZRIK7zWTDvThc,86
+logs_interceptor/infrastructure/interceptors/runtime_interceptor.py,sha256=9LyqbnbACO0YSb8GRSa6fw6PDpLRJaQ0HpiyRdSUDCY,4482
+logs_interceptor/infrastructure/memory/__init__.py,sha256=hzGBIBZ7uWdEW5wY8NYITonz5BMXjn5msbJ7pgbccVs,99
+logs_interceptor/infrastructure/memory/memory_tracker.py,sha256=1LnkxeCPp8fpl2Bem6nT4O0hcbtiGTXak_kGj2bnsTc,2601
+logs_interceptor/infrastructure/metrics/__init__.py,sha256=2eCe6cjBoqNTB4AmatfLogzxLiZH3rUsgA1TOPUJu5w,80
+logs_interceptor/infrastructure/metrics/metrics_collector.py,sha256=aU8X7npzc0LTtExVpbCsT84dWjy5lk9IsHPNdB2JBI0,3862
+logs_interceptor/infrastructure/transport/__init__.py,sha256=VOjWlaP7swEYL0Vp2RJMPXIbEU5dS5C76Haz9Ail6ig,387
+logs_interceptor/infrastructure/transport/loki_json_transport.py,sha256=7_ZX7Tkg_FqXk545T1o8bHj8G69Uo4h9TbchCGce5Yw,8806
+logs_interceptor/infrastructure/transport/loki_protobuf_transport.py,sha256=D10_IdUOdHsSoPr2zT0jLTFHimRwB28-Ykda5QO0FhE,8158
+logs_interceptor/infrastructure/transport/resilient_transport.py,sha256=sFGvUCAGLhw2pbIRYVZxj2m2pHCcHEiGVQqZKAQ9avM,5728
+logs_interceptor/infrastructure/transport/transport_factory.py,sha256=wgRnwhMOmM6zgQmZiL3HehkYX8cf0lAxdybQMpOx5W0,1530
+logs_interceptor/infrastructure/workers/__init__.py,sha256=bsSn5S7sl5Mq0hh5QjD3y-ThEqWjZDcTGrVPX44Mxpk,94
+logs_interceptor/infrastructure/workers/worker_pool.py,sha256=zVStQELQVmjUOnj41K-U1XZmziGkX-b9a2KAzFS4tas,1738
+logs_interceptor/integrations/__init__.py,sha256=ahZMYjrtL954TR9Hg-bD8sQCafkoLVsyz66tmlRhweU,434
+logs_interceptor/integrations/celery.py,sha256=RmvBgXQbaami459ixcVs0rxhPx3yc7-2NbSbGpN49K0,1853
+logs_interceptor/integrations/django.py,sha256=lPj_rvxOXoz62udqjP2NlAqaCxUFQ_ZYWjP5eRrNNV8,1291
+logs_interceptor/integrations/fastapi.py,sha256=UvzCt7o3OU7o6cqjsC4aj1p6ZN12tGzm8V9Hi78o51o,1806
+logs_interceptor/integrations/flask.py,sha256=8XG_Wtnqc-XD8H27fZttxbONUvCFHn3ls7IqKQ_iBZs,1670
+logs_interceptor/integrations/logging_handler.py,sha256=CxN0kRUuITC4c3aKPQfq7bL6r_VdX3CPhhegkaWz1QM,1340
+logs_interceptor/integrations/loguru.py,sha256=Tz7ivaVdQr7H5f0jwaPewU9cPEodCTNMCxNQexqL5u4,1074
+logs_interceptor/integrations/structlog.py,sha256=7TFT-4s7D8ER5_Tg9F1r8XhJGRCuKZcwMMIRc8RhSkU,700
+logs_interceptor/presentation/__init__.py,sha256=_U16fFB-s0ub0Tl1rfAK4zvzANQRD3KO81ni0qynjRA,114
+logs_interceptor/presentation/factory.py,sha256=rvPU1kaQcgQlCZ8iPrwZQG7U70FukNjwaIe9eHzE2WY,4473
+elven_logs_interceptor_python-0.1.2.dist-info/METADATA,sha256=D5RLzXt3_hF7m9c_tswYkxCyzznGZMccYJS8CyO1alM,6498
+elven_logs_interceptor_python-0.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+elven_logs_interceptor_python-0.1.2.dist-info/RECORD,,

elven_logs_interceptor_python-0.1.2.dist-info/WHEEL

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

logs_interceptor/__init__.py

@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from .application import ConfigService
+from .config import (
+    BufferConfig,
+    CircuitBreakerConfig,
+    DeadLetterQueueConfig,
+    FilterConfig,
+    IntegrationsConfig,
+    LogsInterceptorConfig,
+    PerformanceConfig,
+    TransportConfig,
+)
+from .domain.interfaces import ILogger
+from .integrations import (
+    CelerySignals,
+    DjangoMiddleware,
+    FastAPIMiddleware,
+    FlaskExtension,
+    LoggingHandler,
+    LoguruSink,
+    StructlogProcessor,
+)
+from .presentation import LogsInterceptorFactory
+from .types import HealthStatus, LoggerMetrics, LogLevel
+from .utils import internal_debug, internal_error, load_config_from_env, merge_configs, parse_bool
+
+__all__ = [
+    "init",
+    "get_logger",
+    "is_initialized",
+    "destroy",
+    "adestroy",
+    "logger",
+    "LogsInterceptorConfig",
+    "TransportConfig",
+    "BufferConfig",
+    "FilterConfig",
+    "CircuitBreakerConfig",
+    "DeadLetterQueueConfig",
+    "PerformanceConfig",
+    "IntegrationsConfig",
+    "LoggingHandler",
+    "FastAPIMiddleware",
+    "DjangoMiddleware",
+    "FlaskExtension",
+    "CelerySignals",
+    "StructlogProcessor",
+    "LoguruSink",
+]
+
+
+@dataclass(slots=True)
+class _RuntimeState:
+    logger: ILogger
+    runtime_interceptor: Any | None = None
+
+
+_global_runtime: _RuntimeState | None = None
+
+
+def _pick(config: dict[str, Any], snake: str, camel: str, default: Any = None) -> Any:
+    if snake in config:
+        return config[snake]
+    if camel in config:
+        return config[camel]
+    return default
+
+
+def _coerce_config(user_config: LogsInterceptorConfig | dict[str, Any] | None) -> LogsInterceptorConfig:
+    if user_config is None:
+        return LogsInterceptorConfig()
+    if isinstance(user_config, LogsInterceptorConfig):
+        return user_config
+
+    transport_raw = _pick(user_config, "transport", "transport", {}) or {}
+    buffer_raw = _pick(user_config, "buffer", "buffer")
+    filter_raw = _pick(user_config, "filter", "filter")
+    cb_raw = _pick(user_config, "circuit_breaker", "circuitBreaker")
+    perf_raw = _pick(user_config, "performance", "performance")
+    dlq_raw = _pick(user_config, "dead_letter_queue", "deadLetterQueue")
+    integrations_raw = _pick(user_config, "integrations", "integrations")
+
+    return LogsInterceptorConfig(
+        transport=TransportConfig(
+            url=_pick(transport_raw, "url", "url", ""),
+            tenant_id=_pick(transport_raw, "tenant_id", "tenantId", ""),
+            auth_token=_pick(transport_raw, "auth_token", "authToken"),
+            timeout=_pick(transport_raw, "timeout", "timeout"),
+            max_retries=_pick(transport_raw, "max_retries", "maxRetries"),
+            retry_delay=_pick(transport_raw, "retry_delay", "retryDelay"),
+            compression=_pick(transport_raw, "compression", "compression"),
+            compression_level=_pick(transport_raw, "compression_level", "compressionLevel"),
+            compression_threshold=_pick(transport_raw, "compression_threshold", "compressionThreshold"),
+            use_workers=_pick(transport_raw, "use_workers", "useWorkers"),
+            max_workers=_pick(transport_raw, "max_workers", "maxWorkers"),
+            worker_timeout=_pick(transport_raw, "worker_timeout", "workerTimeout"),
+            enable_connection_pooling=_pick(
+                transport_raw, "enable_connection_pooling", "enableConnectionPooling"
+            ),
+            max_sockets=_pick(transport_raw, "max_sockets", "maxSockets"),
+        ),
+        app_name=_pick(user_config, "app_name", "appName", ""),
+        version=_pick(user_config, "version", "version"),
+        environment=_pick(user_config, "environment", "environment"),
+        labels=_pick(user_config, "labels", "labels"),
+        dynamic_labels=_pick(user_config, "dynamic_labels", "dynamicLabels"),
+        buffer=(
+            BufferConfig(
+                max_size=_pick(buffer_raw, "max_size", "maxSize") if buffer_raw else None,
+                flush_interval=_pick(buffer_raw, "flush_interval", "flushInterval")
+                if buffer_raw
+                else None,
+                max_age=_pick(buffer_raw, "max_age", "maxAge") if buffer_raw else None,
+                auto_flush=_pick(buffer_raw, "auto_flush", "autoFlush") if buffer_raw else None,
+                max_memory_mb=_pick(buffer_raw, "max_memory_mb", "maxMemoryMB")
+                if buffer_raw
+                else None,
+            )
+            if buffer_raw
+            else None
+        ),
+        filter=(
+            FilterConfig(
+                levels=_pick(filter_raw, "levels", "levels"),
+                patterns=_pick(filter_raw, "patterns", "patterns"),
+                sampling_rate=_pick(filter_raw, "sampling_rate", "samplingRate"),
+                max_message_length=_pick(filter_raw, "max_message_length", "maxMessageLength"),
+                sanitize=_pick(filter_raw, "sanitize", "sanitize"),
+                sensitive_patterns=_pick(filter_raw, "sensitive_patterns", "sensitivePatterns"),
+            )
+            if filter_raw
+            else None
+        ),
+        circuit_breaker=(
+            CircuitBreakerConfig(
+                enabled=_pick(cb_raw, "enabled", "enabled"),
+                failure_threshold=_pick(cb_raw, "failure_threshold", "failureThreshold"),
+                reset_timeout=_pick(cb_raw, "reset_timeout", "resetTimeout"),
+                half_open_requests=_pick(cb_raw, "half_open_requests", "halfOpenRequests"),
+            )
+            if cb_raw
+            else None
+        ),
+        integrations=(IntegrationsConfig() if integrations_raw is not None else None),
+        performance=(
+            PerformanceConfig(
+                use_workers=_pick(perf_raw, "use_workers", "useWorkers"),
+                max_concurrent_flushes=_pick(perf_raw, "max_concurrent_flushes", "maxConcurrentFlushes"),
+                compression_level=_pick(perf_raw, "compression_level", "compressionLevel"),
+                max_workers=_pick(perf_raw, "max_workers", "maxWorkers"),
+                worker_timeout=_pick(perf_raw, "worker_timeout", "workerTimeout"),
+            )
+            if perf_raw
+            else None
+        ),
+        dead_letter_queue=(
+            DeadLetterQueueConfig(
+                enabled=_pick(dlq_raw, "enabled", "enabled"),
+                type=_pick(dlq_raw, "type", "type"),
+                max_size=_pick(dlq_raw, "max_size", "maxSize"),
+                max_file_size_mb=_pick(dlq_raw, "max_file_size_mb", "maxFileSizeMB"),
+                max_retries=_pick(dlq_raw, "max_retries", "maxRetries"),
+                base_path=_pick(dlq_raw, "base_path", "basePath"),
+            )
+            if dlq_raw
+            else None
+        ),
+        enable_metrics=_pick(user_config, "enable_metrics", "enableMetrics"),
+        enable_health_check=_pick(user_config, "enable_health_check", "enableHealthCheck"),
+        intercept_console=_pick(user_config, "intercept_console", "interceptConsole"),
+        preserve_original_console=_pick(
+            user_config,
+            "preserve_original_console",
+            "preserveOriginalConsole",
+        ),
+        debug=_pick(user_config, "debug", "debug"),
+        silent_errors=_pick(user_config, "silent_errors", "silentErrors"),
+    )
+
+
+def init(user_config: LogsInterceptorConfig | dict[str, Any] | None = None) -> ILogger:
+    global _global_runtime
+
+    env_config = load_config_from_env()
+    if user_config is None:
+        merged_config = env_config
+    else:
+        coerced_user = _coerce_config(user_config)
+        merged_config = merge_configs(coerced_user, env_config)
+
+    errors = ConfigService.validate(merged_config)
+    if errors:
+        raise ValueError("Configuration errors:\n" + "\n".join(errors))
+
+    resolved = ConfigService.resolve(merged_config)
+
+    previous = _global_runtime
+    if previous is not None:
+        if previous.runtime_interceptor is not None:
+            previous.runtime_interceptor.restore()
+        try:
+            previous.logger.destroy()
+        except Exception:
+            pass
+
+    runtime = LogsInterceptorFactory.create(resolved)
+    _global_runtime = _RuntimeState(
+        logger=runtime.logger,
+        runtime_interceptor=runtime.runtime_interceptor,
+    )
+
+    return runtime.logger
+
+
+def get_logger() -> ILogger:
+    if _global_runtime is None:
+        raise RuntimeError("LogsInterceptor not initialized. Call init() first.")
+    return _global_runtime.logger
+
+
+def is_initialized() -> bool:
+    return _global_runtime is not None
+
+
+def destroy() -> None:
+    global _global_runtime
+
+    if _global_runtime is None:
+        return
+
+    runtime = _global_runtime
+    _global_runtime = None
+
+    if runtime.runtime_interceptor is not None:
+        runtime.runtime_interceptor.restore()
+
+    runtime.logger.destroy()
+
+
+async def adestroy() -> None:
+    await asyncio.to_thread(destroy)
+
+
+class _GlobalLoggerProxy:
+    def debug(self, message: str, context: dict[str, Any] | None = None) -> None:
+        if _global_runtime is not None:
+            _global_runtime.logger.debug(message, context)
+
+    def info(self, message: str, context: dict[str, Any] | None = None) -> None:
+        if _global_runtime is not None:
+            _global_runtime.logger.info(message, context)
+
+    def warn(self, message: str, context: dict[str, Any] | None = None) -> None:
+        if _global_runtime is not None:
+            _global_runtime.logger.warn(message, context)
+
+    def error(self, message: str, context: dict[str, Any] | None = None) -> None:
+        if _global_runtime is not None:
+            _global_runtime.logger.error(message, context)
+
+    def fatal(self, message: str, context: dict[str, Any] | None = None) -> None:
+        if _global_runtime is not None:
+            _global_runtime.logger.fatal(message, context)
+
+    def log(self, level: LogLevel, message: str, context: dict[str, Any] | None = None) -> None:
+        if _global_runtime is not None:
+            _global_runtime.logger.log(level, message, context)
+
+    def track_event(self, event_name: str, properties: dict[str, Any] | None = None) -> None:
+        if _global_runtime is not None:
+            _global_runtime.logger.track_event(event_name, properties)
+
+    def with_context(self, context: dict[str, Any], fn: Any) -> Any:
+        if _global_runtime is None:
+            raise RuntimeError("LogsInterceptor not initialized")
+        return _global_runtime.logger.with_context(context, fn)
+
+    async def with_context_async(self, context: dict[str, Any], fn: Any) -> Any:
+        if _global_runtime is None:
+            raise RuntimeError("LogsInterceptor not initialized")
+        return await _global_runtime.logger.with_context_async(context, fn)
+
+    def flush(self) -> None:
+        if _global_runtime is not None:
+            _global_runtime.logger.flush()
+
+    async def aflush(self) -> None:
+        if _global_runtime is not None:
+            await _global_runtime.logger.aflush()
+
+    def get_metrics(self) -> LoggerMetrics:
+        if _global_runtime is None:
+            raise RuntimeError("LogsInterceptor not initialized")
+        return _global_runtime.logger.get_metrics()
+
+    def get_health(self) -> HealthStatus:
+        if _global_runtime is None:
+            raise RuntimeError("LogsInterceptor not initialized")
+        return _global_runtime.logger.get_health()
+
+    def destroy(self) -> None:
+        destroy()
+
+    async def adestroy(self) -> None:
+        await adestroy()
+
+
+logger = _GlobalLoggerProxy()
+
+
+def _auto_init_if_enabled() -> None:
+    if not parse_bool(os.getenv("LOGS_AUTO_INIT"), False):
+        return
+
+    env_config = load_config_from_env()
+    if not env_config.transport.url or not env_config.transport.tenant_id or not env_config.app_name:
+        internal_debug("Auto-init skipped due to missing required LOGS_* variables")
+        return
+
+    try:
+        init(env_config)
+        internal_debug("Auto-initialized from LOGS_* environment variables")
+    except Exception as exc:
+        internal_error("Auto-initialization failed", exc)
+
+
+_auto_init_if_enabled()

logs_interceptor/application/__init__.py

@@ -0,0 +1,27 @@
+from ..config import (
+    BufferConfig,
+    CircuitBreakerConfig,
+    DeadLetterQueueConfig,
+    FilterConfig,
+    IntegrationsConfig,
+    LogsInterceptorConfig,
+    PerformanceConfig,
+    ResolvedLogsInterceptorConfig,
+    TransportConfig,
+)
+from .config_service import ConfigService
+from .log_service import LogService
+
+__all__ = [
+    "ConfigService",
+    "LogService",
+    "LogsInterceptorConfig",
+    "ResolvedLogsInterceptorConfig",
+    "TransportConfig",
+    "BufferConfig",
+    "FilterConfig",
+    "CircuitBreakerConfig",
+    "DeadLetterQueueConfig",
+    "PerformanceConfig",
+    "IntegrationsConfig",
+]