elven-logs-interceptor-python 0.1.10__tar.gz → 0.1.12__tar.gz

{elven_logs_interceptor_python-0.1.10 → elven_logs_interceptor_python-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: elven-logs-interceptor-python
-Version: 0.1.10
+Version: 0.1.12
 Summary: Production-grade logs interceptor for Python with Loki transport, resilience, batching, and framework integrations.
 Author: Elven Observability
 License: MIT
@@ -132,12 +132,20 @@ data is explicitly required and approved.
 The package supports the Python `LOGS_*` configuration surface aligned with
 the JS v3 design where applicable.
 
-Required:
+Required for direct Loki mode:
 
 - `LOGS_URL`
 - `LOGS_TENANT`
 - `LOGS_APP_NAME`
 
+For collector-first mode, set `LOGS_EXPORTER=otlp` (or `collector`) and use
+`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`. In this mode `LOGS_URL`, `LOKI_URL`,
+`LOGS_TENANT` and `LOGS_TOKEN` are not required by the library. `LOGS_URL` is
+intentionally ignored in collector mode to avoid accidentally posting OTLP logs
+to a direct Loki `/loki/api/v1/push` endpoint. Put tenant or auth headers in
+`OTEL_EXPORTER_OTLP_HEADERS`/`LOGS_OTLP_HEADERS` if your collector gateway
+requires them.
+
 Core:
 
 - `LOGS_TOKEN`
@@ -146,6 +154,9 @@ Core:
 
 Transport:
 
+- `LOGS_EXPORTER` (`loki|otlp`, aliases: `collector`, `otel`)
+- `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` (collector logs endpoint, e.g. `http://collector:4318/v1/logs`)
+- `LOGS_OTLP_HEADERS` (comma-separated headers, e.g. `x-tenant=team-a`)
 - `LOGS_COMPRESSION` (`none|gzip|brotli|snappy`)
 - `LOGS_COMPRESSION_LEVEL`
 - `LOGS_COMPRESSION_THRESHOLD`

{elven_logs_interceptor_python-0.1.10 → elven_logs_interceptor_python-0.1.12}/README.md

@@ -71,12 +71,20 @@ data is explicitly required and approved.
 The package supports the Python `LOGS_*` configuration surface aligned with
 the JS v3 design where applicable.
 
-Required:
+Required for direct Loki mode:
 
 - `LOGS_URL`
 - `LOGS_TENANT`
 - `LOGS_APP_NAME`
 
+For collector-first mode, set `LOGS_EXPORTER=otlp` (or `collector`) and use
+`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`. In this mode `LOGS_URL`, `LOKI_URL`,
+`LOGS_TENANT` and `LOGS_TOKEN` are not required by the library. `LOGS_URL` is
+intentionally ignored in collector mode to avoid accidentally posting OTLP logs
+to a direct Loki `/loki/api/v1/push` endpoint. Put tenant or auth headers in
+`OTEL_EXPORTER_OTLP_HEADERS`/`LOGS_OTLP_HEADERS` if your collector gateway
+requires them.
+
 Core:
 
 - `LOGS_TOKEN`
@@ -85,6 +93,9 @@ Core:
 
 Transport:
 
+- `LOGS_EXPORTER` (`loki|otlp`, aliases: `collector`, `otel`)
+- `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` (collector logs endpoint, e.g. `http://collector:4318/v1/logs`)
+- `LOGS_OTLP_HEADERS` (comma-separated headers, e.g. `x-tenant=team-a`)
 - `LOGS_COMPRESSION` (`none|gzip|brotli|snappy`)
 - `LOGS_COMPRESSION_LEVEL`
 - `LOGS_COMPRESSION_THRESHOLD`

{elven_logs_interceptor_python-0.1.10 → elven_logs_interceptor_python-0.1.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "elven-logs-interceptor-python"
-version = "0.1.10"
+version = "0.1.12"
 description = "Production-grade logs interceptor for Python with Loki transport, resilience, batching, and framework integrations."
 readme = "README.md"
 requires-python = ">=3.10"

{elven_logs_interceptor_python-0.1.10 → elven_logs_interceptor_python-0.1.12}/src/logs_interceptor/__init__.py

@@ -88,9 +88,11 @@ def _coerce_config(user_config: LogsInterceptorConfig | dict[str, Any] | None) -
 
     return LogsInterceptorConfig(
         transport=TransportConfig(
+            exporter=_pick(transport_raw, "exporter", "exporter"),
             url=_pick(transport_raw, "url", "url", ""),
             tenant_id=_pick(transport_raw, "tenant_id", "tenantId", ""),
             auth_token=_pick(transport_raw, "auth_token", "authToken"),
+            headers=_pick(transport_raw, "headers", "headers"),
             timeout=_pick(transport_raw, "timeout", "timeout"),
             max_retries=_pick(transport_raw, "max_retries", "maxRetries"),
             retry_delay=_pick(transport_raw, "retry_delay", "retryDelay"),

{elven_logs_interceptor_python-0.1.10 → elven_logs_interceptor_python-0.1.12}/src/logs_interceptor/application/config_service.py

@@ -7,6 +7,7 @@ from ..config import (
     CircuitBreakerConfig,
     FilterConfig,
     IntegrationsConfig,
+    LogsExporterType,
     LogsInterceptorConfig,
     PerformanceConfig,
     ResolvedBufferConfig,
@@ -40,7 +41,7 @@ class ConfigService:
 
         if not config.transport.url:
             errors.append("Transport URL is required")
-        if not config.transport.tenant_id:
+        if ConfigService._resolve_exporter(config.transport.exporter) == "loki" and not config.transport.tenant_id:
             errors.append("Tenant ID is required")
         if not config.app_name:
             errors.append("App name is required")
@@ -125,6 +126,7 @@ class ConfigService:
         transport: TransportConfig,
         performance: PerformanceConfig | None,
     ) -> ResolvedTransportConfig:
+        exporter = ConfigService._resolve_exporter(transport.exporter)
         compression = "gzip"
         if transport.compression in (False, "none"):
             compression = "none"
@@ -139,6 +141,7 @@ class ConfigService:
             url=transport.url,
             tenant_id=transport.tenant_id,
             auth_token=transport.auth_token or "",
+            headers=transport.headers or {},
             timeout=transport.timeout if transport.timeout is not None else 10_000,
             max_retries=transport.max_retries if transport.max_retries is not None else 3,
             retry_delay=transport.retry_delay if transport.retry_delay is not None else 1_000,
@@ -175,8 +178,16 @@ class ConfigService:
                 if transport.enable_structured_metadata is None
                 else transport.enable_structured_metadata
             ),
+            exporter=exporter,
         )
 
+    @staticmethod
+    def _resolve_exporter(value: str | None) -> LogsExporterType:
+        normalized = (value or "loki").strip().lower()
+        if normalized in {"otlp", "collector", "otel"}:
+            return "otlp"
+        return "loki"
+
     @staticmethod
     def _resolve_buffer(buffer: BufferConfig | None) -> ResolvedBufferConfig:
         source = buffer or BufferConfig()

{elven_logs_interceptor_python-0.1.10 → elven_logs_interceptor_python-0.1.12}/src/logs_interceptor/config.py

@@ -8,13 +8,16 @@ from .types import LogLevel
 
 CompressionType = Literal["none", "gzip", "brotli", "snappy"]
 DLQType = Literal["memory", "file"]
+LogsExporterType = Literal["loki", "otlp"]
 
 
 @dataclass(slots=True)
 class TransportConfig:
+    exporter: LogsExporterType | str | None = None
     url: str = ""
     tenant_id: str = ""
     auth_token: str | None = None
+    headers: dict[str, str] | None = None
     timeout: int | None = None
     max_retries: int | None = None
     retry_delay: int | None = None
@@ -133,6 +136,8 @@ class ResolvedTransportConfig:
     enable_connection_pooling: bool
     max_sockets: int
     enable_structured_metadata: bool = False
+    exporter: LogsExporterType = "loki"
+    headers: dict[str, str] = field(default_factory=dict)
 
 
 @dataclass(slots=True)

{elven_logs_interceptor_python-0.1.10 → elven_logs_interceptor_python-0.1.12}/src/logs_interceptor/infrastructure/__init__.py

@@ -17,6 +17,7 @@ from .metrics import MetricsCollector
 from .transport import (
     LokiJsonTransport,
     LokiProtobufTransport,
+    OtlpJsonTransport,
     ResilientTransport,
     ResilientTransportConfig,
     TransportFactory,
@@ -41,6 +42,7 @@ __all__ = [
     "MetricsCollector",
     "LokiJsonTransport",
     "LokiProtobufTransport",
+    "OtlpJsonTransport",
     "ResilientTransport",
     "ResilientTransportConfig",
     "TransportFactory",

{elven_logs_interceptor_python-0.1.10 → elven_logs_interceptor_python-0.1.12}/src/logs_interceptor/infrastructure/transport/__init__.py

@@ -1,11 +1,13 @@
 from .loki_json_transport import LokiJsonTransport
 from .loki_protobuf_transport import LokiProtobufTransport
+from .otlp_json_transport import OtlpJsonTransport
 from .resilient_transport import ResilientTransport, ResilientTransportConfig
 from .transport_factory import TransportFactory
 
 __all__ = [
     "LokiJsonTransport",
     "LokiProtobufTransport",
+    "OtlpJsonTransport",
     "ResilientTransport",
     "ResilientTransportConfig",
     "TransportFactory",

elven_logs_interceptor_python-0.1.12/src/logs_interceptor/infrastructure/transport/otlp_json_transport.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from importlib import import_module
+from typing import Any, cast
+
+import httpx
+
+from ...config import ResolvedLogsInterceptorConfig
+from ...domain.entities import LogEntryEntity
+from ...types import TransportHealth, TransportMetrics
+from ...utils import get_distribution_version
+from ..internal_capture_guard import suppress_internal_log_capture
+
+try:
+    orjson = cast(Any, import_module("orjson"))
+except Exception:  # pragma: no cover - optional dependency
+    orjson = None
+
+_HEX_RE = re.compile(r"^[0-9a-fA-F]+$")
+_SEVERITY_NUMBER = {
+    "debug": 5,
+    "info": 9,
+    "warn": 13,
+    "error": 17,
+    "fatal": 21,
+}
+
+
+@dataclass(slots=True)
+class RetryableTransportError(Exception):
+    message: str
+    status_code: int | None = None
+    retryable: bool = False
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class OtlpJsonTransport:
+    """OTLP/HTTP JSON logs transport for collector-first deployments."""
+
+    def __init__(self, config: ResolvedLogsInterceptorConfig) -> None:
+        self._config = config
+        self._transport = config.transport
+        self._timeout = self._transport.timeout / 1000
+        limits = httpx.Limits(
+            max_keepalive_connections=self._transport.max_sockets,
+            max_connections=self._transport.max_sockets,
+        )
+        self._client: httpx.Client | None = None
+        if self._transport.enable_connection_pooling:
+            self._client = httpx.Client(timeout=self._timeout, limits=limits)
+
+        self._health: TransportHealth = {
+            "healthy": True,
+            "consecutive_failures": 0,
+        }
+        self._metrics: TransportMetrics = {
+            "total_sends": 0,
+            "successful_sends": 0,
+            "failed_sends": 0,
+            "avg_latency": 0.0,
+            "avg_compression_time": 0.0,
+            "avg_compression_ratio": 0.0,
+            "total_bytes_sent": 0,
+            "total_bytes_compressed": 0,
+        }
+
+    def send(self, entries: list[LogEntryEntity]) -> None:
+        if not entries:
+            return
+
+        start = time.perf_counter()
+        self._metrics["total_sends"] = self._metrics.get("total_sends", 0) + 1
+
+        try:
+            body = self._dumps(self._format_for_otlp(entries))
+            headers = {
+                "Content-Type": "application/json",
+                "User-Agent": (
+                    "elven-logs-interceptor-python/"
+                    f"{get_distribution_version('elven-logs-interceptor-python')}"
+                ),
+                **self._transport.headers,
+            }
+            if self._transport.auth_token:
+                headers["Authorization"] = f"Bearer {self._transport.auth_token}"
+
+            with suppress_internal_log_capture():
+                response = self._request(headers, body)
+
+            if response.status_code >= 300:
+                raise RetryableTransportError(
+                    message=f"OTLP logs endpoint responded with {response.status_code}: {response.text}",
+                    status_code=response.status_code,
+                    retryable=response.status_code == 429 or response.status_code >= 500,
+                )
+
+            latency = (time.perf_counter() - start) * 1000
+            self._record_success(latency)
+            self._metrics["total_bytes_sent"] = self._metrics.get("total_bytes_sent", 0) + len(body)
+            self._metrics["total_bytes_compressed"] = self._metrics.get("total_bytes_compressed", 0) + len(body)
+        except Exception as exc:
+            self._record_failure(exc)
+            raise
+
+    def _request(self, headers: dict[str, str], body: bytes) -> httpx.Response:
+        if self._client is not None:
+            return self._client.post(self._transport.url, headers=headers, content=body)
+
+        with httpx.Client(timeout=self._timeout) as client:
+            return client.post(self._transport.url, headers=headers, content=body)
+
+    def is_available(self) -> bool:
+        return bool(self._health.get("healthy", False))
+
+    def get_health(self) -> TransportHealth:
+        return cast(TransportHealth, dict(self._health))
+
+    def get_metrics(self) -> TransportMetrics:
+        return cast(TransportMetrics, dict(self._metrics))
+
+    def destroy(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def _record_success(self, duration_ms: float) -> None:
+        self._health = {
+            "healthy": True,
+            "consecutive_failures": 0,
+            "last_successful_send": time.time(),
+        }
+        successful = self._metrics.get("successful_sends", 0) + 1
+        self._metrics["successful_sends"] = successful
+        current_avg = float(self._metrics.get("avg_latency", 0.0))
+        self._metrics["avg_latency"] = ((current_avg * (successful - 1)) + duration_ms) / successful
+
+    def _record_failure(self, error: Exception) -> None:
+        failures = int(self._health.get("consecutive_failures", 0)) + 1
+        self._health = {
+            "healthy": False,
+            "consecutive_failures": failures,
+            "error_message": str(error),
+        }
+        self._metrics["failed_sends"] = self._metrics.get("failed_sends", 0) + 1
+
+    def _format_for_otlp(self, entries: list[LogEntryEntity]) -> dict[str, Any]:
+        return {
+            "resourceLogs": [
+                {
+                    "resource": {"attributes": self._resource_attributes()},
+                    "scopeLogs": [
+                        {
+                            "scope": {
+                                "name": "elven-logs-interceptor-python",
+                                "version": get_distribution_version("elven-logs-interceptor-python"),
+                            },
+                            "logRecords": [self._format_record(entry) for entry in entries],
+                        }
+                    ],
+                }
+            ]
+        }
+
+    def _resource_attributes(self) -> list[dict[str, Any]]:
+        attrs: dict[str, Any] = {
+            "service.name": self._config.app_name,
+            "service.version": self._config.version,
+            "deployment.environment": self._config.environment,
+            **self._config.labels,
+        }
+        return self._attributes(attrs)
+
+    def _format_record(self, entry: LogEntryEntity) -> dict[str, Any]:
+        record: dict[str, Any] = {
+            "timeUnixNano": str(self._timestamp_to_ns(entry.timestamp)),
+            "observedTimeUnixNano": str(int(time.time() * 1_000_000_000)),
+            "severityText": entry.level.upper(),
+            "severityNumber": _SEVERITY_NUMBER.get(entry.level, 9),
+            "body": {"stringValue": entry.message},
+            "attributes": self._entry_attributes(entry),
+        }
+        if entry.trace_id and self._valid_hex(entry.trace_id, 32):
+            record["traceId"] = entry.trace_id.lower()
+        if entry.span_id and self._valid_hex(entry.span_id, 16):
+            record["spanId"] = entry.span_id.lower()
+        return record
+
+    def _entry_attributes(self, entry: LogEntryEntity) -> list[dict[str, Any]]:
+        attrs: dict[str, Any] = {
+            "log.id": entry.id,
+            "log.level": entry.level,
+        }
+        if entry.request_id:
+            attrs["request.id"] = entry.request_id
+        if entry.context:
+            attrs["context"] = entry.context
+        if entry.metadata:
+            attrs["metadata"] = entry.metadata
+        if entry.labels:
+            attrs["labels"] = entry.labels
+        return self._attributes(attrs)
+
+    def _attributes(self, attrs: dict[str, Any]) -> list[dict[str, Any]]:
+        return [
+            {"key": str(key), "value": self._any_value(value)}
+            for key, value in attrs.items()
+            if value is not None
+        ]
+
+    def _any_value(self, value: Any) -> dict[str, Any]:
+        if isinstance(value, bool):
+            return {"boolValue": value}
+        if isinstance(value, int) and not isinstance(value, bool):
+            return {"intValue": str(value)}
+        if isinstance(value, float):
+            return {"doubleValue": value}
+        if isinstance(value, str):
+            return {"stringValue": value}
+        if isinstance(value, (list, tuple)):
+            return {"arrayValue": {"values": [self._any_value(item) for item in value]}}
+        if isinstance(value, dict):
+            return {
+                "kvlistValue": {
+                    "values": [
+                        {"key": str(key), "value": self._any_value(item)}
+                        for key, item in value.items()
+                        if item is not None
+                    ]
+                }
+            }
+        return {"stringValue": str(value)}
+
+    @staticmethod
+    def _valid_hex(value: str, length: int) -> bool:
+        return len(value) == length and bool(_HEX_RE.match(value)) and set(value) != {"0"}
+
+    @staticmethod
+    def _timestamp_to_ns(iso_timestamp: str) -> int:
+        try:
+            normalized = iso_timestamp.replace("Z", "+00:00")
+            dt_obj = datetime.fromisoformat(normalized)
+            if dt_obj.tzinfo is None:
+                dt_obj = dt_obj.replace(tzinfo=timezone.utc)
+            seconds = int(dt_obj.timestamp())
+            return (seconds * 1_000_000_000) + (dt_obj.microsecond * 1000)
+        except Exception:
+            return int(time.time() * 1_000_000_000)
+
+    @staticmethod
+    def _dumps(payload: Any) -> bytes:
+        if orjson is not None:
+            return cast(bytes, orjson.dumps(payload))
+        return json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode("utf-8")

{elven_logs_interceptor_python-0.1.10 → elven_logs_interceptor_python-0.1.12}/src/logs_interceptor/infrastructure/transport/transport_factory.py

@@ -5,6 +5,7 @@ from ...domain.interfaces import ICircuitBreaker, IDeadLetterQueue, ILogTranspor
 from ...utils import internal_debug, internal_warn
 from .loki_json_transport import LokiJsonTransport
 from .loki_protobuf_transport import LokiProtobufTransport
+from .otlp_json_transport import OtlpJsonTransport
 from .resilient_transport import ResilientTransport, ResilientTransportConfig
 
 
@@ -17,7 +18,10 @@ class TransportFactory:
     ) -> ILogTransport:
         base_transport: ILogTransport
 
-        if config.transport.compression == "snappy":
+        if config.transport.exporter == "otlp":
+            internal_debug("Selected OtlpJsonTransport")
+            base_transport = OtlpJsonTransport(config)
+        elif config.transport.compression == "snappy":
             try:
                 internal_debug("Selected LokiProtobufTransport")
                 base_transport = LokiProtobufTransport(config.transport)

{elven_logs_interceptor_python-0.1.10 → elven_logs_interceptor_python-0.1.12}/src/logs_interceptor/utils.py

@@ -75,6 +75,33 @@ def parse_float_range(value: str | None, default: float, min_value: float, max_v
     return parsed
 
 
+def _normalize_logs_exporter(value: str | None) -> str:
+    normalized = (value or "loki").strip().lower()
+    if normalized in {"otlp", "collector", "otel"}:
+        return "otlp"
+    return "loki"
+
+
+def _parse_kv_csv(raw: str | None) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    if not raw:
+        return headers
+    for item in raw.split(","):
+        if "=" not in item:
+            continue
+        key, value = item.split("=", 1)
+        key = key.strip()
+        if key:
+            headers[key] = value.strip()
+    return headers
+
+
+def _resolve_logs_url(env: Mapping[str, str], exporter: str) -> str:
+    if exporter != "otlp":
+        return env.get("LOGS_URL", "")
+    return env.get("OTEL_EXPORTER_OTLP_LOGS_ENDPOINT", "")
+
+
 def is_debug_enabled() -> bool:
     return parse_bool(os.getenv("LOGS_DEBUG"), False)
 
@@ -507,6 +534,15 @@ def load_config_from_env() -> LogsInterceptorConfig:
     if compression_value not in {"none", "gzip", "brotli", "snappy"}:
         compression_value = "gzip"
 
+    exporter = _normalize_logs_exporter(
+        env.get("LOGS_EXPORTER") or env.get("LOGS_TRANSPORT") or env.get("OTEL_LOGS_EXPORTER")
+    )
+    headers = {
+        **_parse_kv_csv(env.get("LOGS_HEADERS")),
+        **_parse_kv_csv(env.get("LOGS_OTLP_HEADERS")),
+        **(_parse_kv_csv(env.get("OTEL_EXPORTER_OTLP_HEADERS")) if exporter == "otlp" else {}),
+    }
+
     dlq_type_raw = (env.get("LOGS_DLQ_TYPE") or "memory").lower()
     dlq_type = dlq_type_raw
     if dlq_type not in {"memory", "file"}:
@@ -514,9 +550,11 @@ def load_config_from_env() -> LogsInterceptorConfig:
 
     cfg = LogsInterceptorConfig(
         transport=TransportConfig(
-            url=env.get("LOGS_URL", ""),
+            exporter=exporter,
+            url=_resolve_logs_url(env, exporter),
             tenant_id=env.get("LOGS_TENANT", ""),
             auth_token=env.get("LOGS_TOKEN"),
+            headers=headers or None,
             timeout=parse_int_range(env.get("LOGS_TIMEOUT"), 10_000, 0, 600_000),
             max_retries=parse_int_range(env.get("LOGS_MAX_RETRIES"), 3, 0, 20),
             retry_delay=parse_int_range(env.get("LOGS_RETRY_DELAY"), 1_000, 0, 120_000),