otel-log 0.1.0__tar.gz

otel_log-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: otel-log
+Version: 0.1.0
+Summary: OpenTelemetry Standard Log Format library for Python
+Requires-Python: >=3.9
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: jsonschema>=4.0; extra == "dev"

otel_log-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "otel-log"
+version = "0.1.0"
+description = "OpenTelemetry Standard Log Format library for Python"
+requires-python = ">=3.9"
+dependencies = [
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
+    "opentelemetry-exporter-otlp>=1.20.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "hypothesis>=6.0",
+    "jsonschema>=4.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

otel_log-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

otel_log-0.1.0/src/otel_log/__init__.py

@@ -0,0 +1,22 @@
+"""OpenTelemetry Standard Log Format library for Python."""
+
+from .handler import OTelLoggingHandler
+from .log_formatter import LogFormatter
+from .log_record import LogRecord
+from .otlp_exporter import ExporterConfig, OTLPExporter
+from .resource_provider import ResourceConfig, ResourceProvider
+from .severity_mapper import SeverityMapper
+from .trace_context import TraceContext, TraceContextExtractor
+
+__all__ = [
+    "LogRecord",
+    "LogFormatter",
+    "OTelLoggingHandler",
+    "OTLPExporter",
+    "ExporterConfig",
+    "SeverityMapper",
+    "TraceContext",
+    "TraceContextExtractor",
+    "ResourceConfig",
+    "ResourceProvider",
+]

otel_log-0.1.0/src/otel_log/handler.py

@@ -0,0 +1,181 @@
+"""OTelLoggingHandler: Python logging.Handler producing OTel-compliant JSON logs.
+
+Subclasses ``logging.Handler`` and wires together LogFormatter, SeverityMapper,
+TraceContextExtractor, and ResourceProvider to produce structured JSON log
+output conforming to the Standard Log Format schema.
+
+Supports configuration via ResourceConfig or environment variables:
+    OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION, OTEL_DEPLOYMENT_ENVIRONMENT
+
+When an OTLPExporter is provided (or auto-configured via OTEL_EXPORTER_OTLP_ENDPOINT),
+each emitted record is forwarded to the exporter.  Otherwise, JSON is written to
+the configured stream (console-only mode).
+
+Requirements: 5.1-5.5, 9.1
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import traceback
+from datetime import datetime, timezone
+from typing import Any, Dict, IO, Optional
+
+from .log_formatter import LogFormatter
+from .log_record import LogRecord
+from .otlp_exporter import ExporterConfig, OTLPExporter
+from .resource_provider import ResourceConfig, ResourceProvider
+from .severity_mapper import SeverityMapper
+from .trace_context import TraceContextExtractor
+
+
+class OTelLoggingHandler(logging.Handler):
+    """Python logging.Handler that produces OTel-compliant JSON logs.
+
+    Each emitted ``logging.LogRecord`` is mapped to an OTel ``LogRecord``,
+    serialized to JSON via ``LogFormatter``, and either:
+      - forwarded to the configured ``OTLPExporter`` (when set), or
+      - written as JSON to the configured stream (console-only mode).
+
+    Environment variable overrides (take precedence over ResourceConfig):
+        - ``OTEL_SERVICE_NAME``          -> ``service.name``
+        - ``OTEL_SERVICE_VERSION``       -> ``service.version``
+        - ``OTEL_DEPLOYMENT_ENVIRONMENT``-> ``deployment.environment``
+        - ``OTEL_EXPORTER_OTLP_ENDPOINT``-> auto-configure OTLPExporter when
+                                           no explicit exporter is provided
+    """
+
+    def __init__(
+        self,
+        resource_config: Optional[ResourceConfig] = None,
+        stream: Optional[IO] = None,
+        level: int = logging.NOTSET,
+        exporter: Optional[OTLPExporter] = None,
+    ) -> None:
+        super().__init__(level)
+        self._stream = stream or sys.stderr
+        self._formatter_component = LogFormatter()
+        self._severity_mapper = SeverityMapper()
+        self._trace_extractor = TraceContextExtractor()
+
+        # Build resource config with env var overrides
+        config = resource_config or ResourceConfig()
+        config = self._apply_env_overrides(config)
+        self._resource_provider = ResourceProvider(config)
+
+        # Exporter: use explicit exporter, or auto-configure from env var.
+        if exporter is not None:
+            self._exporter: Optional[OTLPExporter] = exporter
+        else:
+            endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "")
+            if endpoint:
+                self._exporter = OTLPExporter(ExporterConfig(endpoint=endpoint, protocol="http"))
+            else:
+                self._exporter = None
+
+    @staticmethod
+    def _apply_env_overrides(config: ResourceConfig) -> ResourceConfig:
+        """Apply environment variable overrides to a ResourceConfig."""
+        service_name = os.environ.get("OTEL_SERVICE_NAME")
+        service_version = os.environ.get("OTEL_SERVICE_VERSION")
+        deployment_env = os.environ.get("OTEL_DEPLOYMENT_ENVIRONMENT")
+
+        return ResourceConfig(
+            service_name=service_name if service_name else config.service_name,
+            service_version=service_version if service_version else config.service_version,
+            deployment_environment=deployment_env if deployment_env else config.deployment_environment,
+            custom_attributes=config.custom_attributes,
+        )
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Emit a logging.LogRecord as OTel-compliant JSON.
+
+        Steps:
+            1. Map Python log level to SeverityNumber/SeverityText
+            2. Extract trace context from active OTel span
+            3. Build LogRecord with resource attributes
+            4. Handle exc_info (exception type, message, stacktrace)
+            5. Serialize to JSON via LogFormatter
+            6. Export via OTLPExporter (if configured) or write to stream
+        """
+        try:
+            # 1. Map severity
+            severity_number = self._severity_mapper.to_severity_number(record.levelno)
+            severity_text = self._severity_mapper.to_severity_text(record.levelno)
+
+            # 2. Extract trace context
+            trace_ctx = self._trace_extractor.extract()
+
+            # 3. Build resource
+            resource = self._resource_provider.get_resource()
+
+            # 4. Build attributes from extra fields and exc_info
+            attributes = self._build_attributes(record)
+
+            # 5. Build OTel LogRecord
+            timestamp = datetime.fromtimestamp(record.created, tz=timezone.utc)
+            otel_record = LogRecord(
+                timestamp=timestamp,
+                observed_timestamp=timestamp,
+                severity_text=severity_text,
+                severity_number=severity_number,
+                body=record.getMessage(),
+                resource=resource,
+                attributes=attributes if attributes else None,
+                trace_id=trace_ctx.trace_id if trace_ctx else None,
+                span_id=trace_ctx.span_id if trace_ctx else None,
+                trace_flags=trace_ctx.trace_flags if trace_ctx else None,
+            )
+
+            # 6. Export or write to stream
+            if self._exporter is not None:
+                self._exporter.export([otel_record])
+            else:
+                json_line = self._formatter_component.serialize(otel_record)
+                self._stream.write(json_line + "\n")
+                self._stream.flush()
+        except Exception:
+            self.handleError(record)
+
+    def _build_attributes(self, record: logging.LogRecord) -> Optional[Dict[str, Any]]:
+        """Build attributes dict from logging.LogRecord extras and exc_info.
+
+        Extracts extra attributes set on the record (beyond standard fields)
+        and, when exc_info is present, adds exception.type, exception.message,
+        and exception.stacktrace per OTel semantic conventions.
+        """
+        attrs: Dict[str, Any] = {}
+
+        # Collect extra attributes (non-standard fields on the LogRecord)
+        _STANDARD_ATTRS = {
+            "name", "msg", "args", "created", "relativeCreated", "exc_info",
+            "exc_text", "stack_info", "lineno", "funcName", "pathname",
+            "filename", "module", "thread", "threadName", "process",
+            "processName", "levelname", "levelno", "msecs", "message",
+            "taskName",
+        }
+        for key, value in record.__dict__.items():
+            if key.startswith("_") or key in _STANDARD_ATTRS:
+                continue
+            # Skip empty string keys per Req 11.4
+            if not key:
+                continue
+            attrs[key] = value
+
+        # Handle exc_info -> exception attributes (Req 5.5)
+        if record.exc_info and record.exc_info[0] is not None:
+            exc_type, exc_value, exc_tb = record.exc_info
+            attrs["exception.type"] = (
+                exc_type.__name__ if hasattr(exc_type, "__name__") else str(exc_type)
+            )
+            attrs["exception.message"] = str(exc_value) if exc_value else ""
+            if exc_tb is not None:
+                attrs["exception.stacktrace"] = "".join(
+                    traceback.format_exception(exc_type, exc_value, exc_tb)
+                )
+            else:
+                attrs["exception.stacktrace"] = ""
+
+        return attrs if attrs else None

otel_log-0.1.0/src/otel_log/log_formatter.py

@@ -0,0 +1,239 @@
+"""LogFormatter: serialize LogRecord to JSON and parse JSON back to LogRecord."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from .log_record import LogRecord
+
+# JSON schema field name mapping: Python attribute -> JSON key
+_FIELD_TO_KEY = {
+    "timestamp": "Timestamp",
+    "observed_timestamp": "ObservedTimestamp",
+    "severity_text": "SeverityText",
+    "severity_number": "SeverityNumber",
+    "body": "Body",
+    "resource": "Resource",
+    "instrumentation_scope": "InstrumentationScope",
+    "attributes": "Attributes",
+    "trace_id": "TraceId",
+    "span_id": "SpanId",
+    "trace_flags": "TraceFlags",
+    "event_name": "EventName",
+}
+
+_KEY_TO_FIELD = {v: k for k, v in _FIELD_TO_KEY.items()}
+
+# Required JSON keys per schema
+_REQUIRED_KEYS = {"Timestamp", "SeverityText", "SeverityNumber", "Body", "Resource"}
+
+_VALID_SEVERITY_TEXTS = {"TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"}
+
+
+def _encode_value(value: Any) -> Any:
+    """Encode a value for JSON serialization, handling AnyValue types.
+
+    If a value cannot be serialized (e.g. circular reference),
+    return "[unserializable]".
+    """
+    if value is None:
+        return None
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, dict):
+        return {k: _encode_value(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_encode_value(item) for item in value]
+    # Fallback for unserializable types
+    try:
+        json.dumps(value)
+        return value
+    except (TypeError, ValueError, OverflowError):
+        return "[unserializable]"
+
+
+def _format_timestamp(dt: datetime) -> str:
+    """Format a datetime as ISO 8601 UTC string."""
+    # Ensure UTC
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    else:
+        dt = dt.astimezone(timezone.utc)
+    return dt.isoformat().replace("+00:00", "Z")
+
+
+def _parse_timestamp(value: str) -> datetime:
+    """Parse an ISO 8601 timestamp string to a UTC datetime."""
+    # Handle 'Z' suffix
+    s = value.replace("Z", "+00:00")
+    return datetime.fromisoformat(s).astimezone(timezone.utc)
+
+
+class LogFormatter:
+    """Serializes LogRecord to JSON and parses JSON back to LogRecord.
+
+    Conforms to the Standard Log Format JSON schema.
+    """
+
+    @staticmethod
+    def serialize(record: LogRecord) -> str:
+        """Serialize a LogRecord to a JSON string.
+
+        - Omits fields that are None/null.
+        - Encodes timestamps as ISO 8601 UTC.
+        - Handles AnyValue types in Body and Attributes.
+        - Falls back to "[unserializable]" for values that can't be serialized.
+        """
+        data: Dict[str, Any] = {}
+
+        # Timestamp (required by schema)
+        if record.timestamp is not None:
+            data["Timestamp"] = _format_timestamp(record.timestamp)
+
+        # ObservedTimestamp (optional)
+        if record.observed_timestamp is not None:
+            data["ObservedTimestamp"] = _format_timestamp(record.observed_timestamp)
+
+        # SeverityText (required)
+        data["SeverityText"] = record.severity_text
+
+        # SeverityNumber (required)
+        data["SeverityNumber"] = record.severity_number
+
+        # Body (required)
+        data["Body"] = _encode_value(record.body)
+
+        # Resource (required)
+        data["Resource"] = _encode_value(record.resource)
+
+        # InstrumentationScope (optional)
+        if record.instrumentation_scope is not None:
+            data["InstrumentationScope"] = _encode_value(record.instrumentation_scope)
+
+        # Attributes (optional)
+        if record.attributes is not None:
+            data["Attributes"] = _encode_value(record.attributes)
+
+        # Trace context — omit if absent (Req 1.4)
+        if record.trace_id is not None:
+            data["TraceId"] = record.trace_id
+        if record.span_id is not None:
+            data["SpanId"] = record.span_id
+        if record.trace_flags is not None:
+            data["TraceFlags"] = record.trace_flags
+
+        # EventName (optional)
+        if record.event_name is not None:
+            data["EventName"] = record.event_name
+
+        return json.dumps(data, separators=(",", ":"))
+
+    @staticmethod
+    def parse(json_str: str) -> LogRecord:
+        """Parse a JSON string into a LogRecord.
+
+        Raises ValueError with a descriptive message for invalid input.
+        """
+        # Parse JSON
+        try:
+            data = json.loads(json_str)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON: {e}") from e
+
+        if not isinstance(data, dict):
+            raise ValueError("JSON root must be an object")
+
+        # Validate required fields
+        for key in _REQUIRED_KEYS:
+            if key not in data:
+                raise ValueError(f"Missing required field: {key}")
+
+        # Validate no unknown fields
+        allowed_keys = set(_KEY_TO_FIELD.keys())
+        unknown = set(data.keys()) - allowed_keys
+        if unknown:
+            raise ValueError(f"Unknown fields: {', '.join(sorted(unknown))}")
+
+        # Validate SeverityText
+        severity_text = data["SeverityText"]
+        if not isinstance(severity_text, str):
+            raise ValueError(f"SeverityText must be a string, got {type(severity_text).__name__}")
+        if severity_text not in _VALID_SEVERITY_TEXTS:
+            raise ValueError(
+                f"Invalid SeverityText: '{severity_text}'. "
+                f"Must be one of: {', '.join(sorted(_VALID_SEVERITY_TEXTS))}"
+            )
+
+        # Validate SeverityNumber
+        severity_number = data["SeverityNumber"]
+        if not isinstance(severity_number, int) or isinstance(severity_number, bool):
+            raise ValueError(f"SeverityNumber must be an integer, got {type(severity_number).__name__}")
+        if not (0 <= severity_number <= 24):
+            raise ValueError(f"SeverityNumber must be 0-24, got {severity_number}")
+
+        # Validate Resource
+        resource = data["Resource"]
+        if not isinstance(resource, dict):
+            raise ValueError(f"Resource must be an object, got {type(resource).__name__}")
+        if "service.name" not in resource:
+            raise ValueError("Resource must contain 'service.name'")
+
+        # Parse timestamps
+        timestamp: Optional[datetime] = None
+        if "Timestamp" in data:
+            try:
+                timestamp = _parse_timestamp(data["Timestamp"])
+            except (ValueError, TypeError) as e:
+                raise ValueError(f"Invalid Timestamp format: {e}") from e
+
+        observed_timestamp: Optional[datetime] = None
+        if "ObservedTimestamp" in data:
+            try:
+                observed_timestamp = _parse_timestamp(data["ObservedTimestamp"])
+            except (ValueError, TypeError) as e:
+                raise ValueError(f"Invalid ObservedTimestamp format: {e}") from e
+
+        # Validate trace context formats if present
+        trace_id = data.get("TraceId")
+        if trace_id is not None:
+            if not isinstance(trace_id, str) or len(trace_id) != 32:
+                raise ValueError(f"TraceId must be a 32-character hex string, got '{trace_id}'")
+
+        span_id = data.get("SpanId")
+        if span_id is not None:
+            if not isinstance(span_id, str) or len(span_id) != 16:
+                raise ValueError(f"SpanId must be a 16-character hex string, got '{span_id}'")
+
+        trace_flags = data.get("TraceFlags")
+        if trace_flags is not None:
+            if not isinstance(trace_flags, str) or len(trace_flags) != 2:
+                raise ValueError(f"TraceFlags must be a 2-character hex string, got '{trace_flags}'")
+
+        # Validate InstrumentationScope
+        instrumentation_scope = data.get("InstrumentationScope")
+        if instrumentation_scope is not None and not isinstance(instrumentation_scope, dict):
+            raise ValueError(
+                f"InstrumentationScope must be an object, got {type(instrumentation_scope).__name__}"
+            )
+
+        # Validate Attributes
+        attributes = data.get("Attributes")
+        if attributes is not None and not isinstance(attributes, dict):
+            raise ValueError(f"Attributes must be an object, got {type(attributes).__name__}")
+
+        return LogRecord(
+            timestamp=timestamp,
+            observed_timestamp=observed_timestamp,
+            severity_text=severity_text,
+            severity_number=severity_number,
+            body=data["Body"],
+            resource=resource,
+            instrumentation_scope=instrumentation_scope,
+            attributes=attributes,
+            trace_id=trace_id,
+            span_id=span_id,
+            trace_flags=trace_flags,
+            event_name=data.get("EventName"),
+        )

otel_log-0.1.0/src/otel_log/log_record.py

@@ -0,0 +1,34 @@
+"""LogRecord dataclass representing an OpenTelemetry log entry."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+# AnyValue type: string, int, float, bool, list, dict, or None
+AnyValue = Union[str, int, float, bool, List[Any], Dict[str, Any], None]
+
+VALID_SEVERITY_TEXTS = frozenset({"TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"})
+
+
+@dataclass
+class LogRecord:
+    """Canonical in-memory representation of an OTel log entry.
+
+    Fields align with the OpenTelemetry Log Data Model and the
+    Standard Log Format JSON schema.
+    """
+
+    severity_text: str = "INFO"
+    severity_number: int = 9
+    body: Any = ""
+    resource: Dict[str, AnyValue] = field(default_factory=lambda: {"service.name": "unknown_service"})
+    timestamp: Optional[datetime] = None
+    observed_timestamp: Optional[datetime] = None
+    instrumentation_scope: Optional[Dict[str, str]] = None
+    attributes: Optional[Dict[str, AnyValue]] = None
+    trace_id: Optional[str] = None
+    span_id: Optional[str] = None
+    trace_flags: Optional[str] = None
+    event_name: Optional[str] = None

otel_log-0.1.0/src/otel_log/otlp_exporter.py

@@ -0,0 +1,204 @@
+"""OTLPExporter: exports LogRecords to an OpenTelemetry Collector.
+
+Supports gRPC and HTTP protocols with batch export, exponential backoff retry,
+and graceful fallback to stdout when the SDK is unavailable or no endpoint is
+configured.
+
+Requirements: 9.1-9.6
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from .log_formatter import LogFormatter
+from .log_record import LogRecord
+
+
+@dataclass
+class ExporterConfig:
+    """Configuration for OTLPExporter.
+
+    Attributes:
+        endpoint:          OTLP collector endpoint URL (e.g. "http://localhost:4317").
+                           When empty, falls back to console (stdout) mode.
+        protocol:          Transport protocol — "grpc" or "http" (default "grpc").
+        headers:           Optional dict of HTTP/gRPC headers (e.g. auth tokens).
+        tls_cert_path:     Optional path to a TLS certificate file.
+        batch_size:        Maximum number of records per export batch (default 512).
+        flush_interval_ms: Interval in milliseconds between automatic flushes (default 5000).
+        max_retries:       Maximum number of retry attempts on failure (default 3).
+        retry_backoff_ms:  Base backoff in milliseconds for exponential retry (default 1000).
+    """
+
+    endpoint: str = ""
+    protocol: str = "grpc"
+    headers: Optional[Dict[str, str]] = None
+    tls_cert_path: Optional[str] = None
+    batch_size: int = 512
+    flush_interval_ms: int = 5000
+    max_retries: int = 3
+    retry_backoff_ms: int = 1000
+
+
+class OTLPExporter:
+    """Exports LogRecords to an OpenTelemetry Collector via OTLP.
+
+    When an endpoint is configured, attempts to use the OTel SDK exporters
+    (opentelemetry-exporter-otlp-proto-grpc for gRPC,
+    opentelemetry-exporter-otlp-proto-http for HTTP).
+
+    If the SDK is unavailable or no endpoint is configured, falls back to
+    writing JSON-serialized records to stdout (console-only mode).
+
+    Retry behaviour:
+        On export failure, retries up to ``config.max_retries`` times with
+        exponential backoff starting at ``config.retry_backoff_ms`` ms.
+        After exhausting retries, records are dropped and a warning is written
+        to stderr.  The exporter never raises exceptions to the caller.
+    """
+
+    def __init__(self, config: Optional[ExporterConfig] = None) -> None:
+        self._config = config or ExporterConfig()
+        self._formatter = LogFormatter()
+        self._pending: List[LogRecord] = []
+        self._sdk_exporter = None  # lazy-initialised on first export
+
+        # Attempt to initialise the SDK exporter if an endpoint is provided.
+        if self._config.endpoint:
+            self._sdk_exporter = self._init_sdk_exporter()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def export(self, records: List[LogRecord]) -> bool:
+        """Export a list of LogRecords, batching by configured batch_size.
+
+        Returns True when all batches were exported successfully, False if any
+        batch failed after exhausting retries (records are dropped in that case).
+        """
+        if not records:
+            return True
+
+        all_ok = True
+        # Split into batches of at most batch_size.
+        for i in range(0, len(records), self._config.batch_size):
+            batch = records[i : i + self._config.batch_size]
+            ok = self._export_batch(batch)
+            if not ok:
+                all_ok = False
+        return all_ok
+
+    def shutdown(self) -> None:
+        """Flush pending records and shut down the exporter."""
+        self.force_flush()
+        if self._sdk_exporter is not None:
+            try:
+                self._sdk_exporter.shutdown()
+            except Exception:
+                pass
+
+    def force_flush(self) -> None:
+        """Immediately flush any pending records."""
+        if self._pending:
+            pending = list(self._pending)
+            self._pending.clear()
+            self.export(pending)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _export_batch(self, batch: List[LogRecord]) -> bool:
+        """Export a single batch with retry/backoff.  Returns True on success."""
+        if self._sdk_exporter is not None:
+            return self._export_via_sdk(batch)
+        # Console fallback: write JSON to stdout.
+        self._console_export(batch)
+        return True
+
+    def _export_via_sdk(self, batch: List[LogRecord]) -> bool:
+        """Try to export via the SDK exporter with exponential backoff."""
+        backoff_ms = self._config.retry_backoff_ms
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                result = self._sdk_exporter.export(batch)
+                # OTel SDK returns ExportResult enum; SUCCESS == 0.
+                if hasattr(result, "value"):
+                    if result.value == 0:
+                        return True
+                    # Non-success result — retry.
+                else:
+                    # If no value attribute, treat as success.
+                    return True
+            except Exception as exc:
+                if attempt == self._config.max_retries:
+                    sys.stderr.write(
+                        f"[OTLPExporter] Export failed after {self._config.max_retries} retries, "
+                        f"dropping {len(batch)} records. Last error: {exc}\n"
+                    )
+                    return False
+            if attempt < self._config.max_retries:
+                time.sleep(backoff_ms / 1000.0)
+                backoff_ms *= 2  # exponential backoff
+        # Exhausted retries.
+        sys.stderr.write(
+            f"[OTLPExporter] Export failed after {self._config.max_retries} retries, "
+            f"dropping {len(batch)} records.\n"
+        )
+        return False
+
+    def _console_export(self, batch: List[LogRecord]) -> None:
+        """Write JSON-serialized records to stdout (console-only mode)."""
+        for record in batch:
+            try:
+                json_line = self._formatter.serialize(record)
+                sys.stdout.write(json_line + "\n")
+            except Exception as exc:
+                sys.stderr.write(f"[OTLPExporter] Serialization error: {exc}\n")
+
+    def _init_sdk_exporter(self):
+        """Attempt to initialise an OTel SDK exporter.
+
+        Returns the exporter instance on success, or None if the SDK is not
+        available (console-only fallback).
+        """
+        protocol = self._config.protocol.lower()
+        endpoint = self._config.endpoint
+        headers = self._config.headers or {}
+
+        if protocol == "grpc":
+            return self._init_grpc_exporter(endpoint, headers)
+        else:
+            return self._init_http_exporter(endpoint, headers)
+
+    def _init_grpc_exporter(self, endpoint: str, headers: Dict[str, str]):
+        try:
+            from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (
+                OTLPLogExporter,
+            )
+            return OTLPLogExporter(endpoint=endpoint, headers=headers)
+        except ImportError:
+            sys.stderr.write(
+                "[OTLPExporter] opentelemetry-exporter-otlp-proto-grpc not available; "
+                "falling back to console mode.\n"
+            )
+            return None
+
+    def _init_http_exporter(self, endpoint: str, headers: Dict[str, str]):
+        try:
+            from opentelemetry.exporter.otlp.proto.http._log_exporter import (
+                OTLPLogExporter,
+            )
+            return OTLPLogExporter(endpoint=endpoint, headers=headers)
+        except ImportError:
+            sys.stderr.write(
+                "[OTLPExporter] opentelemetry-exporter-otlp-proto-http not available; "
+                "falling back to console mode.\n"
+            )
+            return None

otel_log-0.1.0/src/otel_log/resource_provider.py

@@ -0,0 +1,72 @@
+"""ResourceProvider for managing OTel resource attributes.
+
+Provides resource attributes (service.name, service.version,
+deployment.environment, and custom attributes) that are attached to every
+LogRecord produced by the logging bridge.
+
+If ``service.name`` is not supplied, it defaults to ``"unknown_service"``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class ResourceConfig:
+    """Configuration for resource attributes.
+
+    Attributes:
+        service_name:           Service name (default ``"unknown_service"``).
+        service_version:        Optional service version string.
+        deployment_environment: Optional deployment environment (e.g. ``"production"``).
+        custom_attributes:      Optional dict of additional resource key-value pairs.
+    """
+
+    service_name: str = "unknown_service"
+    service_version: Optional[str] = None
+    deployment_environment: Optional[str] = None
+    custom_attributes: Optional[Dict[str, Any]] = None
+
+
+class ResourceProvider:
+    """Builds resource attribute dicts from a :class:`ResourceConfig`.
+
+    Always includes ``service.name`` in the returned resource dict.
+    Optional fields are included only when set.  Custom attributes are
+    merged in and can use arbitrary keys.
+    """
+
+    def __init__(self, config: Optional[ResourceConfig] = None) -> None:
+        self._config = config or ResourceConfig()
+
+    @property
+    def config(self) -> ResourceConfig:
+        """Return the current resource configuration."""
+        return self._config
+
+    def get_resource(self) -> Dict[str, Any]:
+        """Return resource attributes dict.
+
+        The dict always contains ``"service.name"``.  ``"service.version"``
+        and ``"deployment.environment"`` are included when configured.
+        Any ``custom_attributes`` are merged into the result.
+
+        Returns:
+            A dict of resource attribute key-value pairs.
+        """
+        resource: Dict[str, Any] = {
+            "service.name": self._config.service_name,
+        }
+
+        if self._config.service_version is not None:
+            resource["service.version"] = self._config.service_version
+
+        if self._config.deployment_environment is not None:
+            resource["deployment.environment"] = self._config.deployment_environment
+
+        if self._config.custom_attributes:
+            resource.update(self._config.custom_attributes)
+
+        return resource

otel_log-0.1.0/src/otel_log/severity_mapper.py

@@ -0,0 +1,127 @@
+"""SeverityMapper for mapping Python logging levels to OTel severity values.
+
+Maps Python's standard logging levels to OpenTelemetry SeverityNumber ranges
+and SeverityText values per the OTel Log Data Model specification.
+
+Mapping table:
+    Python Level    | SeverityText | SeverityNumber
+    NOTSET (0)      | TRACE        | 1
+    DEBUG (10)      | DEBUG        | 5
+    INFO (20)       | INFO         | 9
+    WARNING (30)    | WARN         | 13
+    ERROR (40)      | ERROR        | 17
+    CRITICAL (50)   | FATAL        | 21
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Tuple
+
+# Standard Python logging levels mapped to (SeverityNumber, SeverityText).
+# Each maps to the lowest value in the OTel range for that severity band.
+_PYTHON_LEVEL_MAP: dict[int, tuple[int, str]] = {
+    logging.NOTSET: (1, "TRACE"),      # NOTSET=0  -> TRACE range 1-4
+    logging.DEBUG: (5, "DEBUG"),       # DEBUG=10  -> DEBUG range 5-8
+    logging.INFO: (9, "INFO"),         # INFO=20   -> INFO range 9-12
+    logging.WARNING: (13, "WARN"),     # WARNING=30 -> WARN range 13-16
+    logging.ERROR: (17, "ERROR"),      # ERROR=40  -> ERROR range 17-20
+    logging.CRITICAL: (21, "FATAL"),   # CRITICAL=50 -> FATAL range 21-24
+}
+
+# Sorted standard levels for closest-match lookup.
+_SORTED_LEVELS = sorted(_PYTHON_LEVEL_MAP.keys())
+
+# Recognized severity strings (case-insensitive) to (SeverityNumber, SeverityText).
+_SEVERITY_STRING_MAP: dict[str, tuple[int, str]] = {
+    "TRACE": (1, "TRACE"),
+    "DEBUG": (5, "DEBUG"),
+    "INFO": (9, "INFO"),
+    "WARN": (13, "WARN"),
+    "WARNING": (13, "WARN"),
+    "ERROR": (17, "ERROR"),
+    "FATAL": (21, "FATAL"),
+    "CRITICAL": (21, "FATAL"),
+    # Python-specific level names
+    "NOTSET": (1, "TRACE"),
+}
+
+
+def _find_closest_level(python_level: int) -> int:
+    """Find the closest standard Python logging level to the given value."""
+    closest = _SORTED_LEVELS[0]
+    min_distance = abs(python_level - closest)
+    for level in _SORTED_LEVELS[1:]:
+        distance = abs(python_level - level)
+        if distance < min_distance:
+            min_distance = distance
+            closest = level
+        elif distance == min_distance and level < closest:
+            # Tie-break: prefer the lower standard level
+            closest = level
+    return closest
+
+
+class SeverityMapper:
+    """Maps between Python logging levels and OTel severity values."""
+
+    @staticmethod
+    def to_severity_number(python_level: int) -> int:
+        """Map a Python logging level (int) to an OTel SeverityNumber.
+
+        For standard levels (NOTSET, DEBUG, INFO, WARNING, ERROR, CRITICAL),
+        returns the lowest SeverityNumber in the corresponding OTel range.
+        For non-standard levels, finds the closest standard level and uses
+        its mapping.
+
+        Args:
+            python_level: A Python logging level integer.
+
+        Returns:
+            An OTel SeverityNumber (1-24).
+        """
+        if python_level in _PYTHON_LEVEL_MAP:
+            return _PYTHON_LEVEL_MAP[python_level][0]
+        closest = _find_closest_level(python_level)
+        return _PYTHON_LEVEL_MAP[closest][0]
+
+    @staticmethod
+    def to_severity_text(python_level: int) -> str:
+        """Map a Python logging level (int) to an OTel SeverityText.
+
+        For standard levels, returns the corresponding OTel SeverityText.
+        For non-standard levels, finds the closest standard level and uses
+        its mapping.
+
+        Args:
+            python_level: A Python logging level integer.
+
+        Returns:
+            An OTel SeverityText string (TRACE, DEBUG, INFO, WARN, ERROR, FATAL).
+        """
+        if python_level in _PYTHON_LEVEL_MAP:
+            return _PYTHON_LEVEL_MAP[python_level][1]
+        closest = _find_closest_level(python_level)
+        return _PYTHON_LEVEL_MAP[closest][1]
+
+    @staticmethod
+    def from_string(severity_str: str) -> Tuple[int, str]:
+        """Map a severity string to (SeverityNumber, SeverityText).
+
+        Recognizes standard OTel severity names (TRACE, DEBUG, INFO, WARN,
+        ERROR, FATAL) and Python-specific names (WARNING, CRITICAL, NOTSET),
+        case-insensitively.
+
+        For unrecognized strings, returns SeverityNumber 0 (UNSPECIFIED)
+        and preserves the original string as SeverityText.
+
+        Args:
+            severity_str: A severity level name string.
+
+        Returns:
+            A tuple of (SeverityNumber, SeverityText).
+        """
+        normalized = severity_str.strip().upper()
+        if normalized in _SEVERITY_STRING_MAP:
+            return _SEVERITY_STRING_MAP[normalized]
+        return (0, severity_str)

otel_log-0.1.0/src/otel_log/trace_context.py

@@ -0,0 +1,73 @@
+"""TraceContextExtractor for extracting trace context from the active OTel span.
+
+Extracts TraceId, SpanId, and TraceFlags from the current OpenTelemetry span
+context. Returns None when no active span exists or the OTel SDK is unavailable.
+
+Format requirements (per OTel spec):
+    TraceId:    32-character lowercase hexadecimal string
+    SpanId:     16-character lowercase hexadecimal string
+    TraceFlags:  2-character zero-padded hexadecimal string
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class TraceContext:
+    """Trace context extracted from an active OpenTelemetry span.
+
+    Attributes:
+        trace_id:    32-char lowercase hex string.
+        span_id:     16-char lowercase hex string.
+        trace_flags:  2-char zero-padded hex string.
+    """
+
+    trace_id: str
+    span_id: str
+    trace_flags: str
+
+
+class TraceContextExtractor:
+    """Extracts trace context from the active OpenTelemetry span."""
+
+    @staticmethod
+    def extract() -> Optional[TraceContext]:
+        """Extract trace context from the active OTel span.
+
+        Uses ``opentelemetry.trace.get_current_span()`` to obtain the active
+        span, then reads its SpanContext for TraceId, SpanId, and TraceFlags.
+
+        Returns:
+            A :class:`TraceContext` if a valid, recording span is active,
+            or ``None`` if no active span exists, the span context is invalid,
+            or the OpenTelemetry SDK is not installed.
+        """
+        try:
+            from opentelemetry import trace
+
+            span = trace.get_current_span()
+
+            # INVALID_SPAN or non-recording spans have no useful context
+            if span is None or not span.is_recording():
+                return None
+
+            ctx = span.get_span_context()
+            if ctx is None or not ctx.is_valid:
+                return None
+
+            # Format per OTel spec: lowercase hex, fixed width
+            trace_id = format(ctx.trace_id, "032x")
+            span_id = format(ctx.span_id, "016x")
+            trace_flags = format(ctx.trace_flags, "02x")
+
+            return TraceContext(
+                trace_id=trace_id,
+                span_id=span_id,
+                trace_flags=trace_flags,
+            )
+        except Exception:
+            # Gracefully handle missing SDK or any unexpected errors
+            return None

otel_log-0.1.0/src/otel_log.egg-info/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: otel-log
+Version: 0.1.0
+Summary: OpenTelemetry Standard Log Format library for Python
+Requires-Python: >=3.9
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: jsonschema>=4.0; extra == "dev"

otel_log-0.1.0/src/otel_log.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+pyproject.toml
+src/otel_log/__init__.py
+src/otel_log/handler.py
+src/otel_log/log_formatter.py
+src/otel_log/log_record.py
+src/otel_log/otlp_exporter.py
+src/otel_log/resource_provider.py
+src/otel_log/severity_mapper.py
+src/otel_log/trace_context.py
+src/otel_log.egg-info/PKG-INFO
+src/otel_log.egg-info/SOURCES.txt
+src/otel_log.egg-info/dependency_links.txt
+src/otel_log.egg-info/requires.txt
+src/otel_log.egg-info/top_level.txt

otel_log-0.1.0/src/otel_log.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

otel_log-0.1.0/src/otel_log.egg-info/requires.txt

@@ -0,0 +1,8 @@
+opentelemetry-api>=1.20.0
+opentelemetry-sdk>=1.20.0
+opentelemetry-exporter-otlp>=1.20.0
+
+[dev]
+pytest>=7.0
+hypothesis>=6.0
+jsonschema>=4.0

otel_log-0.1.0/src/otel_log.egg-info/top_level.txt

@@ -0,0 +1 @@
+otel_log