owl24-py 0.1.0__tar.gz

owl24_py-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+.env*
+# .env.example files are committed templates, not secrets - without this
+# negation the blanket .env* rule above hides them from every `git status`/
+# `git add`, so they silently never get committed (verified: none of the
+# .env.example files across clientservers/, py-server/, or java-server/
+# were actually tracked, despite being referenced as the setup reference
+# throughout).
+!.env.example
+!**/.env.example
+BackendCollector/data*
+BackendCollector/queries*
+
+# Java / Maven build output
+target/
+*.class
+
+# Python build/cache output
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+venv/

owl24_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Madnands5
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

owl24_py-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: owl24-py
+Version: 0.1.0
+Summary: Custom owl24 OpenTelemetry wrapper with data masking
+Project-URL: Homepage, https://owl24.dev
+Project-URL: Repository, https://github.com/Madnands5/owl24
+Author: Madnands5
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apm,logging,monitoring,observability,opentelemetry,owl24,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Requires-Dist: opentelemetry-api<2.0.0,>=1.39.0
+Requires-Dist: opentelemetry-exporter-otlp<2.0.0,>=1.39.0
+Requires-Dist: opentelemetry-instrumentation-system-metrics>=0.65b0
+Requires-Dist: opentelemetry-sdk<2.0.0,>=1.39.0
+Provides-Extra: django
+Requires-Dist: opentelemetry-instrumentation-django>=0.65b0; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.65b0; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: opentelemetry-instrumentation-flask>=0.65b0; extra == 'flask'
+Provides-Extra: requests
+Requires-Dist: opentelemetry-instrumentation-requests>=0.65b0; extra == 'requests'
+Description-Content-Type: text/markdown
+
+# owl24-py
+
+Python SDK for [owl24](https://owl24.dev) — one line of code to send logs, traces, and metrics to your owl24 dashboard, built on OpenTelemetry.
+
+## Install
+
+```bash
+pip install owl24-py
+```
+
+## Usage
+
+```python
+import os
+from owl24_py import Owl24
+
+Owl24.init(os.getenv("OWL24_API_KEY"), "my-service-name")
+```
+
+That's it — `Owl24.init(...)` wires up an OpenTelemetry tracer/meter/logger provider pointed at your owl24 ingest endpoint, and patches Python's `logging` module so `logging.info(...)`, `logging.error(...)`, etc. are automatically sent to your dashboard alongside the current trace/span ID.
+
+### Options
+
+```python
+Owl24.init(
+    api_key=None,                     # or set OWL24_API_KEY / OBSERVE_API_KEY env var
+    service_name="dice-server",
+    export_interval_millis=3000,
+    disable_console_bridge=False,     # set True to stop auto-forwarding logging.* calls
+    disable_crash_capture=False,      # set True to disable uncaught-exception capture
+    export_timeout_millis=5000,
+    disable_auto_instrumentation=False, # set True to skip Flask/Django/FastAPI/requests auto-tracing
+)
+```
+
+Telemetry is always sent to `https://ingest.owl24.dev` — owl24's ingest endpoint isn't configurable, since it's a fixed part of the hosted service (only the API key is per-customer).
+
+## What it does
+
+- **Logs**: patches the root `logging` logger — every `logging.*` call is forwarded as a structured log, tagged with the active trace/span ID if one exists.
+- **Traces**: sets up an OpenTelemetry `TracerProvider` exporting via OTLP/HTTP. Spans you create manually, or automatically via Flask/Django/FastAPI/`requests` (see below), are masked and exported.
+- **Host metrics**: CPU, memory, and network metrics are collected and exported automatically via `opentelemetry-instrumentation-system-metrics` — no setup required.
+- **Crash capture**: installs a `sys.excepthook` and `threading.excepthook` so uncaught exceptions (main thread and background threads) are captured as FATAL-severity log events and flushed before the process exits.
+- **PII masking**: emails, credit-card-shaped numbers, phone numbers, and bearer tokens are scrubbed from span attributes and log bodies before they ever leave your process.
+
+## Automatic HTTP tracing
+
+Install the extra for whichever framework/library you use, and `Owl24.init()` will automatically create spans for incoming requests (Flask/Django/FastAPI) or outgoing calls (`requests`) — no other code changes needed:
+
+```bash
+pip install "owl24-py[flask]"      # Flask
+pip install "owl24-py[django]"     # Django
+pip install "owl24-py[fastapi]"    # FastAPI
+pip install "owl24-py[requests]"   # outgoing requests via the `requests` library
+```
+
+None of these are installed by default — `pip install owl24-py` alone still gives you logs, host metrics, crash capture, and manually-created spans, with zero extra framework dependencies pulled in.
+
+### Flask and FastAPI: call `Owl24.init()` before importing the framework
+
+For Flask and FastAPI specifically (not Django - see below), `Owl24.init()` must run **before your own code does `from flask import Flask` or `from fastapi import FastAPI`**:
+
+```python
+from owl24_py import Owl24
+Owl24.init(api_key, "my-service")
+
+from flask import Flask   # import AFTER init() - this is the part that matters
+app = Flask(__name__)
+```
+
+Getting this backwards doesn't raise an error or a warning - it just silently produces zero traces, ever, for that service. Why: Flask/FastAPI's instrumentation works by reassigning the framework's own `Flask`/`FastAPI` class in its module (e.g. `flask.Flask = _InstrumentedFlask`) - if your code already did `from flask import Flask` and bound that name to the original class before `Owl24.init()` runs, that name keeps pointing at the unpatched original forever; reassigning `flask.Flask` afterward can't reach back and fix an already-bound reference. (Using `import flask` and calling `flask.Flask(...)` instead of `from flask import Flask` sidesteps this entirely, since that always resolves the class fresh - but `Owl24.init()` first is the simpler rule to just always follow.)
+
+**Django doesn't have this restriction** - its instrumentation works by inserting into Django's `settings.MIDDLEWARE`, which Django resolves lazily when it actually starts handling requests, not by reassigning a class. Import order doesn't matter for Django.
+
+## License
+
+MIT — see [LICENSE](https://github.com/Madnands5/owl24/blob/main/packages/owl24-py/LICENSE).

owl24_py-0.1.0/README.md

@@ -0,0 +1,77 @@
+# owl24-py
+
+Python SDK for [owl24](https://owl24.dev) — one line of code to send logs, traces, and metrics to your owl24 dashboard, built on OpenTelemetry.
+
+## Install
+
+```bash
+pip install owl24-py
+```
+
+## Usage
+
+```python
+import os
+from owl24_py import Owl24
+
+Owl24.init(os.getenv("OWL24_API_KEY"), "my-service-name")
+```
+
+That's it — `Owl24.init(...)` wires up an OpenTelemetry tracer/meter/logger provider pointed at your owl24 ingest endpoint, and patches Python's `logging` module so `logging.info(...)`, `logging.error(...)`, etc. are automatically sent to your dashboard alongside the current trace/span ID.
+
+### Options
+
+```python
+Owl24.init(
+    api_key=None,                     # or set OWL24_API_KEY / OBSERVE_API_KEY env var
+    service_name="dice-server",
+    export_interval_millis=3000,
+    disable_console_bridge=False,     # set True to stop auto-forwarding logging.* calls
+    disable_crash_capture=False,      # set True to disable uncaught-exception capture
+    export_timeout_millis=5000,
+    disable_auto_instrumentation=False, # set True to skip Flask/Django/FastAPI/requests auto-tracing
+)
+```
+
+Telemetry is always sent to `https://ingest.owl24.dev` — owl24's ingest endpoint isn't configurable, since it's a fixed part of the hosted service (only the API key is per-customer).
+
+## What it does
+
+- **Logs**: patches the root `logging` logger — every `logging.*` call is forwarded as a structured log, tagged with the active trace/span ID if one exists.
+- **Traces**: sets up an OpenTelemetry `TracerProvider` exporting via OTLP/HTTP. Spans you create manually, or automatically via Flask/Django/FastAPI/`requests` (see below), are masked and exported.
+- **Host metrics**: CPU, memory, and network metrics are collected and exported automatically via `opentelemetry-instrumentation-system-metrics` — no setup required.
+- **Crash capture**: installs a `sys.excepthook` and `threading.excepthook` so uncaught exceptions (main thread and background threads) are captured as FATAL-severity log events and flushed before the process exits.
+- **PII masking**: emails, credit-card-shaped numbers, phone numbers, and bearer tokens are scrubbed from span attributes and log bodies before they ever leave your process.
+
+## Automatic HTTP tracing
+
+Install the extra for whichever framework/library you use, and `Owl24.init()` will automatically create spans for incoming requests (Flask/Django/FastAPI) or outgoing calls (`requests`) — no other code changes needed:
+
+```bash
+pip install "owl24-py[flask]"      # Flask
+pip install "owl24-py[django]"     # Django
+pip install "owl24-py[fastapi]"    # FastAPI
+pip install "owl24-py[requests]"   # outgoing requests via the `requests` library
+```
+
+None of these are installed by default — `pip install owl24-py` alone still gives you logs, host metrics, crash capture, and manually-created spans, with zero extra framework dependencies pulled in.
+
+### Flask and FastAPI: call `Owl24.init()` before importing the framework
+
+For Flask and FastAPI specifically (not Django - see below), `Owl24.init()` must run **before your own code does `from flask import Flask` or `from fastapi import FastAPI`**:
+
+```python
+from owl24_py import Owl24
+Owl24.init(api_key, "my-service")
+
+from flask import Flask   # import AFTER init() - this is the part that matters
+app = Flask(__name__)
+```
+
+Getting this backwards doesn't raise an error or a warning - it just silently produces zero traces, ever, for that service. Why: Flask/FastAPI's instrumentation works by reassigning the framework's own `Flask`/`FastAPI` class in its module (e.g. `flask.Flask = _InstrumentedFlask`) - if your code already did `from flask import Flask` and bound that name to the original class before `Owl24.init()` runs, that name keeps pointing at the unpatched original forever; reassigning `flask.Flask` afterward can't reach back and fix an already-bound reference. (Using `import flask` and calling `flask.Flask(...)` instead of `from flask import Flask` sidesteps this entirely, since that always resolves the class fresh - but `Owl24.init()` first is the simpler rule to just always follow.)
+
+**Django doesn't have this restriction** - its instrumentation works by inserting into Django's `settings.MIDDLEWARE`, which Django resolves lazily when it actually starts handling requests, not by reassigning a class. Import order doesn't matter for Django.
+
+## License
+
+MIT — see [LICENSE](https://github.com/Madnands5/owl24/blob/main/packages/owl24-py/LICENSE).

owl24_py-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "owl24-py"
+version = "0.1.0"
+description = "Custom owl24 OpenTelemetry wrapper with data masking"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+    { name = "Madnands5" }
+]
+keywords = ["observability", "opentelemetry", "apm", "tracing", "logging", "monitoring", "owl24"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    # Floor raised to 1.39 (not the original 1.27): that's the release where
+    # opentelemetry.sdk._logs.LogRecord was removed in favor of passing
+    # kwargs directly to Logger.emit(), which is what telemetry.py now does
+    # - older versions don't support that emit() signature.
+    "opentelemetry-api>=1.39.0,<2.0.0",
+    "opentelemetry-sdk>=1.39.0,<2.0.0",
+    "opentelemetry-exporter-otlp>=1.39.0,<2.0.0",
+    # Host metrics (CPU/memory/network) - the Python equivalent of
+    # owl24-js's @opentelemetry/host-metrics and owl24-java's
+    # runtime-telemetry-java8. A hard dependency (unlike the framework
+    # instrumentations below) since it's universal - no per-framework
+    # variance, so there's no reason to make it opt-in.
+    "opentelemetry-instrumentation-system-metrics>=0.65b0"
+]
+
+# Optional auto-tracing for common frameworks/libraries - not hard
+# dependencies, since forcing e.g. Flask onto a Django or plain-script user
+# would be dead weight. Each one is also try/except-guarded at import time
+# in telemetry.py, so init() still works fine with none of these installed
+# (falls back to logs-only + manual spans, same as today) - installing the
+# extra is what turns on automatic HTTP span creation for that library.
+[project.optional-dependencies]
+flask = ["opentelemetry-instrumentation-flask>=0.65b0"]
+django = ["opentelemetry-instrumentation-django>=0.65b0"]
+fastapi = ["opentelemetry-instrumentation-fastapi>=0.65b0"]
+requests = ["opentelemetry-instrumentation-requests>=0.65b0"]
+
+[project.urls]
+Homepage = "https://owl24.dev"
+Repository = "https://github.com/Madnands5/owl24"

owl24_py-0.1.0/src/owl24_py/__init__.py

@@ -0,0 +1 @@
+from .telemetry import Owl24

owl24_py-0.1.0/src/owl24_py/telemetry.py

@@ -0,0 +1,397 @@
+import os
+import re
+import sys
+import json
+import logging
+import signal
+import threading
+import traceback
+from typing import Any
+from types import MappingProxyType
+
+# This module's own print statements use emoji (see below) - on Windows,
+# the console's default codepage (cp1252) can't encode them, which throws
+# a UnicodeEncodeError right on the *success* print at the end of init()'s
+# try-block - meaning init() silently reported "Init failed" even when
+# everything actually succeeded. Forcing UTF-8 here (guarded: reconfigure()
+# doesn't exist on every stream type, and this must never itself crash the
+# import) fixes that instead of stripping the emoji.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+from opentelemetry import trace, metrics
+from opentelemetry.sdk.resources import Resource, SERVICE_NAME, SERVICE_VERSION
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry._logs import SeverityNumber, set_logger_provider
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.instrumentation.system_metrics import SystemMetricsInstrumentor
+
+# Best-effort auto-tracing for whichever of these the host app already has
+# installed - mirrors owl24-js's getNodeAutoInstrumentations() "instrument
+# whatever's present" behavior, without making any of them a hard dependency
+# of this package (see the `[project.optional-dependencies]` extras in
+# pyproject.toml). Each import is independently guarded: a host app with
+# none of these installed still gets logs + manual spans + host metrics,
+# exactly as before.
+_AUTO_INSTRUMENTORS = []
+try:
+    from opentelemetry.instrumentation.flask import FlaskInstrumentor
+    _AUTO_INSTRUMENTORS.append(("flask", FlaskInstrumentor))
+except ImportError:
+    pass
+try:
+    from opentelemetry.instrumentation.django import DjangoInstrumentor
+    _AUTO_INSTRUMENTORS.append(("django", DjangoInstrumentor))
+except ImportError:
+    pass
+try:
+    from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+    _AUTO_INSTRUMENTORS.append(("fastapi", FastAPIInstrumentor))
+except ImportError:
+    pass
+try:
+    from opentelemetry.instrumentation.requests import RequestsInstrumentor
+    _AUTO_INSTRUMENTORS.append(("requests", RequestsInstrumentor))
+except ImportError:
+    pass
+
+# Maps Python's stdlib level names to the OTLP SeverityNumber enum - the log
+# bridge previously stored logging._levelToName's raw string here (wrong
+# type for this field, and a private stdlib internal besides).
+_PYTHON_TO_OTEL_SEVERITY = {
+    "DEBUG": SeverityNumber.DEBUG,
+    "INFO": SeverityNumber.INFO,
+    "WARNING": SeverityNumber.WARN,
+    "ERROR": SeverityNumber.ERROR,
+    "CRITICAL": SeverityNumber.FATAL,
+}
+
+
+MASK_PATTERNS = {
+    "email": re.compile(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"),
+    "creditCard": re.compile(r"\b(?:\d[ -]*?){13,16}\b"),
+    "phone": re.compile(r"(\+?\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}"),
+    "bearerToken": re.compile(r"Bearer\s+[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.?[A-Za-z0-9-_.+/=]*")
+}
+
+def mask_sensitive_data(text: str) -> str:
+    if not isinstance(text, str):
+        return text
+    text = MASK_PATTERNS["email"].sub("[EMAIL_MASKED]", text)
+    text = MASK_PATTERNS["creditCard"].sub("[CARD_MASKED]", text)
+    text = MASK_PATTERNS["phone"].sub("[PHONE_MASKED]", text)
+    text = MASK_PATTERNS["bearerToken"].sub("[TOKEN_MASKED]", text)
+    return text
+
+def safe_serialize(obj: Any) -> str:
+    try:
+        return json.dumps(obj, default=lambda o: "[Unserializable Object]")
+    except ValueError:
+        return "[Circular]"
+    except Exception:
+        return "[Unserializable Object]"
+
+class _MaskedReadableSpan:
+    """Duck-typed proxy around a real ReadableSpan: delegates every
+    attribute except `.attributes` to the wrapped span unchanged, and
+    returns a masked copy for `.attributes`. The OTLP exporter's encoder
+    only ever reads `sdk_span.attributes` (type-hinted as ReadableSpan, but
+    never isinstance-checked), so this duck typing is enough for it to
+    treat this exactly like a real span.
+    """
+
+    def __init__(self, wrapped, masked_attributes):
+        self._wrapped = wrapped
+        self._masked_attributes = masked_attributes
+
+    def __getattr__(self, name):
+        return getattr(self._wrapped, name)
+
+    @property
+    def attributes(self):
+        return self._masked_attributes
+
+
+class MaskingSpanExporter(SpanExporter):
+    """Wraps a SpanExporter and masks string span attributes before they
+    reach the real exporter - closes the masking gap for auto-instrumented
+    spans (http.url query strings, db.statement literals, etc.), which
+    never went through mask_sensitive_data before (only the logging bridge
+    above did).
+
+    This masks into a *copy* rather than mutating the original span's
+    attributes in place (the approach used by owl24-js's equivalent
+    MaskingSpanProcessor, and originally attempted here too) because the
+    current OTel Python SDK makes a span's attributes hard-immutable the
+    moment end() is called (`self._attributes._immutable = True`, set
+    before any processor's on_end() even runs) - verified live: mutating
+    either the public `.attributes` property (a fresh MappingProxyType each
+    time) or the private `._attributes` BoundedAttributes both raise
+    TypeError, unconditionally, for every span. There's no supported way to
+    mutate a span after it ends in this SDK version, so masking has to
+    happen at the exporter boundary instead, the same place owl24-java's
+    equivalent gap gets closed (its ReadOnlySpan is sealed against external
+    implementations too, for a different underlying reason).
+    """
+
+    def __init__(self, wrapped):
+        self._wrapped = wrapped
+
+    def export(self, spans):
+        masked_spans = []
+        for span in spans:
+            try:
+                original_attrs = dict(span.attributes or {})
+                masked_attrs = {
+                    key: (mask_sensitive_data(value) if isinstance(value, str) else value)
+                    for key, value in original_attrs.items()
+                }
+                masked_spans.append(_MaskedReadableSpan(span, MappingProxyType(masked_attrs)))
+            except Exception as e:
+                print(f"❌ Owl24 Masking Error: {e}", file=sys.stderr)
+                masked_spans.append(span)
+        return self._wrapped.export(masked_spans)
+
+    def shutdown(self):
+        return self._wrapped.shutdown()
+
+    def force_flush(self, timeout_millis=30000):
+        force_flush_fn = getattr(self._wrapped, "force_flush", None)
+        return force_flush_fn(timeout_millis) if force_flush_fn else True
+
+
+# Logger name prefixes excluded from the console bridge - the exporters
+# themselves (and the HTTP libraries they use) log through this same root
+# logger when a request fails/retries. Without this exclusion, a failed
+# export logs a warning through `logging`, the bridge captures that warning
+# and tries to export IT too, which can itself fail and log another
+# warning, recursively - verified live: this hung a real crash-capture
+# flush indefinitely (no bound at all, worse than just being slow) once the
+# ingest endpoint was unreachable, which is exactly the moment a crash
+# handler needs to be reliable.
+_EXCLUDED_LOGGER_PREFIXES = ("opentelemetry", "urllib3", "requests")
+
+
+class MaskingAndOtelHandler(logging.Handler):
+    def __init__(self, otel_logger):
+        super().__init__()
+        self.otel_logger = otel_logger
+
+    def emit(self, record):
+        if record.name.startswith(_EXCLUDED_LOGGER_PREFIXES):
+            return
+        try:
+            msg = record.getMessage()
+            body = safe_serialize(msg) if isinstance(msg, (dict, list)) else str(msg)
+            masked_body = mask_sensitive_data(body)
+            
+            current_span = trace.get_current_span()
+            span_context = current_span.get_span_context() if current_span else None
+            
+            trace_id = format(span_context.trace_id, '032x') if span_context and span_context.trace_id else None
+            span_id = format(span_context.span_id, '016x') if span_context and span_context.span_id else None
+
+            level_name = logging.getLevelName(record.levelno)
+            # Passed as kwargs directly (not a constructed LogRecord - that
+            # class was removed from opentelemetry-sdk in 1.39, which
+            # `Logger.emit()` builds internally from these same kwargs).
+            self.otel_logger.emit(
+                timestamp=int(record.created * 1e9),
+                body=masked_body,
+                severity_number=_PYTHON_TO_OTEL_SEVERITY.get(level_name, SeverityNumber.INFO),
+                severity_text=level_name,
+                attributes={
+                    "manual.trace_id": trace_id,
+                    "manual.span_id": span_id,
+                    "is_winston": "false"
+                }
+            )
+        except Exception as e:
+            print(f"❌ Owl24 Bridge Error: {e}", file=sys.stderr)
+
+class Owl24:
+    _tracer_provider = None
+    _meter_provider = None
+    _logger_provider = None
+    _crash_capture_registered = False
+    _original_excepthook = None
+    _original_threading_excepthook = None
+    _system_metrics_instrumentor = None
+    _active_auto_instrumentors = []
+
+    @classmethod
+    def _record_fatal(cls, origin, exc_type, exc_value, exc_tb):
+        """Logs a FATAL-severity event for an uncaught exception and forces
+        a bounded-time flush - without this, a crash on the main thread
+        (which Python will exit right after, once the excepthook returns)
+        could exit before the batch processor's own timer ever fires, and
+        the crash telemetry would never actually be sent.
+        """
+        try:
+            message = "".join(traceback.format_exception(exc_type, exc_value, exc_tb))
+            if cls._logger_provider:
+                otel_logger = cls._logger_provider.get_logger("crash-capture")
+                otel_logger.emit(
+                    body=mask_sensitive_data(f"[{origin}] {message}"),
+                    severity_number=SeverityNumber.FATAL,
+                    severity_text="FATAL",
+                    attributes={"error.type": origin},
+                )
+                cls._logger_provider.force_flush(timeout_millis=5000)
+            if cls._tracer_provider:
+                cls._tracer_provider.force_flush(timeout_millis=5000)
+        except Exception as e:
+            print(f"❌ [Owl24] Failed to record crash event: {e}", file=sys.stderr)
+
+    @classmethod
+    def _setup_crash_capture(cls):
+        if cls._crash_capture_registered:
+            return
+        cls._crash_capture_registered = True
+
+        cls._original_excepthook = sys.excepthook
+
+        def excepthook(exc_type, exc_value, exc_tb):
+            cls._record_fatal("uncaught_exception", exc_type, exc_value, exc_tb)
+            # Chain to the previous hook (Python's default one, unless
+            # something else already replaced it) so the normal traceback
+            # still prints and the interpreter still exits as it always
+            # would - this only adds capture+flush, it doesn't change
+            # whether/how the process exits.
+            (cls._original_excepthook or sys.__excepthook__)(exc_type, exc_value, exc_tb)
+
+        sys.excepthook = excepthook
+
+        # An uncaught exception in a background thread only kills that
+        # thread by default, not the process - still worth capturing since
+        # it's telemetry the app would otherwise lose entirely.
+        if hasattr(threading, "excepthook"):
+            cls._original_threading_excepthook = threading.excepthook
+
+            def threading_excepthook(args):
+                cls._record_fatal("uncaught_exception_thread", args.exc_type, args.exc_value, args.exc_traceback)
+                (cls._original_threading_excepthook or threading.__excepthook__)(args)
+
+            threading.excepthook = threading_excepthook
+
+    @classmethod
+    def init(cls, api_key=None, service_name="dice-server", export_interval_millis=3000,
+             disable_console_bridge=False, disable_crash_capture=False, export_timeout_millis=5000,
+             disable_auto_instrumentation=False):
+        resolved_api_key = api_key or os.getenv("owl24_API_KEY") or os.getenv("OBSERVE_API_KEY")
+        user_email = os.getenv("owl24_USER_EMAIL") or os.getenv("OBSERVE_USER_EMAIL") or "unknown@local.dev"
+        # Hardcoded, not configurable: owl24 is a fully-hosted service with
+        # one fixed ingest endpoint - unlike the API key (which is
+        # per-customer) or user email, there's nothing for a caller to
+        # legitimately point this at instead.
+        ingest_base_url = "https://ingest.owl24.dev"
+
+        if not resolved_api_key:
+            print("❌ [Owl24] API Key required.", file=sys.stderr)
+            return
+
+        # Any failure below (bad ingest URL, exporter/provider construction
+        # error) must not crash the host application - an observability
+        # SDK failing to initialize should degrade to a no-op, not take the
+        # customer's app down with it.
+        try:
+            headers = {"x-api-key": resolved_api_key, "x-user-email": user_email}
+            resource = Resource.create({
+                SERVICE_NAME: service_name,
+                SERVICE_VERSION: "0.1.0",
+            })
+
+            # Explicit per-attempt timeout on every exporter - without this,
+            # each export attempt falls back to the OTel SDK's own default
+            # (10s), and a single unreachable-endpoint retry can then run
+            # well past force_flush()'s own timeout_millis (that timeout
+            # only bounds "wait for the worker to report back", not an
+            # export call already in flight). This is what makes
+            # _record_fatal's crash-time flush actually bounded - verified
+            # live: without this, a crash-capture flush against an
+            # unreachable endpoint hung past 12s despite a 5s force_flush
+            # timeout.
+            export_timeout_seconds = export_timeout_millis / 1000
+
+            cls._tracer_provider = TracerProvider(resource=resource)
+            trace_exporter = OTLPSpanExporter(endpoint=f"{ingest_base_url}/v1/traces", headers=headers, timeout=export_timeout_seconds)
+            cls._tracer_provider.add_span_processor(
+                BatchSpanProcessor(MaskingSpanExporter(trace_exporter), schedule_delay_millis=export_interval_millis)
+            )
+            trace.set_tracer_provider(cls._tracer_provider)
+
+            metric_exporter = OTLPMetricExporter(endpoint=f"{ingest_base_url}/v1/metrics", headers=headers, timeout=export_timeout_seconds)
+            reader = PeriodicExportingMetricReader(metric_exporter, export_interval_millis=export_interval_millis)
+            cls._meter_provider = MeterProvider(resource=resource, metric_readers=[reader])
+            metrics.set_meter_provider(cls._meter_provider)
+
+            # Host metrics (CPU/memory/network) - the Python equivalent of
+            # owl24-js's HostMetrics and owl24-java's runtime-telemetry-java8
+            # observers. Unlike those, this was previously entirely missing:
+            # a MeterProvider was wired up but nothing ever created a metric
+            # instrument, so no metrics data was ever actually produced.
+            cls._system_metrics_instrumentor = SystemMetricsInstrumentor()
+            cls._system_metrics_instrumentor.instrument()
+
+            if not disable_auto_instrumentation:
+                for name, instrumentor_cls in _AUTO_INSTRUMENTORS:
+                    try:
+                        instance = instrumentor_cls()
+                        instance.instrument()
+                        cls._active_auto_instrumentors.append(instance)
+                    except Exception as auto_instrument_error:
+                        print(f"⚠️ [Owl24] Auto-instrumentation for '{name}' failed: {auto_instrument_error}", file=sys.stderr)
+
+            cls._logger_provider = LoggerProvider(resource=resource)
+            log_exporter = OTLPLogExporter(endpoint=f"{ingest_base_url}/v1/logs", headers=headers, timeout=export_timeout_seconds)
+            cls._logger_provider.add_log_record_processor(
+                BatchLogRecordProcessor(log_exporter, schedule_delay_millis=export_interval_millis)
+            )
+            set_logger_provider(cls._logger_provider)
+
+            if not disable_console_bridge:
+                otel_logger = cls._logger_provider.get_logger("console-bridge")
+                root_logger = logging.getLogger()
+                root_logger.setLevel(logging.INFO)
+                root_logger.addHandler(MaskingAndOtelHandler(otel_logger))
+
+            if not disable_crash_capture:
+                cls._setup_crash_capture()
+
+            print(f"🚀 [Owl24] Universal APM Active: {service_name}")
+        except Exception as e:
+            print(f"❌ [Owl24] Init failed: {e}", file=sys.stderr)
+
+    @classmethod
+    def shutdown(cls):
+        print("Shutting down telemetry...")
+        if cls._tracer_provider: cls._tracer_provider.shutdown()
+        if cls._logger_provider: cls._logger_provider.shutdown()
+        if cls._meter_provider: cls._meter_provider.shutdown()
+        if cls._system_metrics_instrumentor:
+            try:
+                cls._system_metrics_instrumentor.uninstrument()
+            except Exception as e:
+                print(f"❌ [Owl24] Failed to uninstrument system metrics: {e}", file=sys.stderr)
+        for instrumentor in cls._active_auto_instrumentors:
+            try:
+                instrumentor.uninstrument()
+            except Exception as e:
+                print(f"❌ [Owl24] Failed to uninstrument {instrumentor}: {e}", file=sys.stderr)
+        cls._active_auto_instrumentors = []
+
+def handle_sigterm(signum, frame):
+    Owl24.shutdown()
+    sys.exit(0)
+
+signal.signal(signal.SIGTERM, handle_sigterm)