dlogify 0.1.0__py3-none-any.whl

dlogify/__init__.py

@@ -0,0 +1,160 @@
+"""dlogify: send Python logs and uncaught exceptions to Logify.
+
+    import dlogify
+    dlogify.init()
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from typing import Optional
+
+from . import _singleton
+from ._client import Client
+from ._diagnostics import Diagnostics, is_flag
+from ._version import VERSION as __version__
+from .handler import LogifyHandler
+
+__all__ = [
+    "init",
+    "trace",
+    "debug",
+    "info",
+    "warn",
+    "warning",
+    "error",
+    "fatal",
+    "critical",
+    "log",
+    "capture_exception",
+    "flush",
+    "shutdown",
+    "Client",
+    "LogifyHandler",
+    "__version__",
+]
+
+_noted_before_init = False
+
+
+def _active() -> Optional[Client]:
+    global _noted_before_init
+    client = _singleton.current
+    if client is None and not _noted_before_init:
+        _noted_before_init = True
+        try:
+            Diagnostics(is_flag(os.environ.get("LOGIFY_DEBUG"))).debug("a log call before init() was dropped")
+        except Exception:
+            pass
+    return client
+
+
+def init(
+    *,
+    api_key: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    service: Optional[str] = None,
+    environment: Optional[str] = None,
+    release: Optional[str] = None,
+    min_level: Optional[str] = None,
+    capture_logging: bool = True,
+    capture_uncaught: bool = True,
+    attributes: Optional[Mapping[str, object]] = None,
+    max_queue_size: Optional[int] = None,
+    disabled: Optional[bool] = None,
+    debug: Optional[bool] = None,
+) -> None:
+    """Starts the client: captures logging and uncaught exceptions unless turned off.
+    Safe to call from any thread; a second call is ignored."""
+    try:
+        with _singleton.lock:
+            existing = _singleton.current
+            if existing is not None:
+                existing.diagnostics.debug("init() was called again; ignored")
+                return
+            _singleton.current = Client(
+                api_key=api_key,
+                endpoint=endpoint,
+                service=service,
+                environment=environment,
+                release=release,
+                min_level=min_level,
+                capture_logging=capture_logging,
+                capture_uncaught=capture_uncaught,
+                attributes=attributes,
+                max_queue_size=max_queue_size,
+                disabled=disabled,
+                debug=debug,
+            )
+    except Exception:
+        pass  # init() never raises
+
+
+def trace(message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+    client = _active()
+    if client is not None:
+        client.trace(message, exc=exc, attributes=attributes)
+
+
+def debug(message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+    client = _active()
+    if client is not None:
+        client.debug(message, exc=exc, attributes=attributes)
+
+
+def info(message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+    client = _active()
+    if client is not None:
+        client.info(message, exc=exc, attributes=attributes)
+
+
+def warn(message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+    client = _active()
+    if client is not None:
+        client.warn(message, exc=exc, attributes=attributes)
+
+
+warning = warn
+
+
+def error(message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+    client = _active()
+    if client is not None:
+        client.error(message, exc=exc, attributes=attributes)
+
+
+def fatal(message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+    client = _active()
+    if client is not None:
+        client.fatal(message, exc=exc, attributes=attributes)
+
+
+critical = fatal
+
+
+def log(level: str, message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+    client = _active()
+    if client is not None:
+        client.log(level, message, exc=exc, attributes=attributes)
+
+
+def capture_exception(exc: Optional[BaseException] = None, *, attributes: Optional[Mapping[str, object]] = None) -> None:
+    client = _active()
+    if client is not None:
+        client.capture_exception(exc, attributes=attributes)
+
+
+def flush(timeout: float = 2.0) -> None:
+    client = _singleton.current
+    if client is not None:
+        client.flush(timeout)
+
+
+def shutdown(timeout: float = 2.0) -> None:
+    """Flushes, stops and restores what init() installed; init() may run again."""
+    with _singleton.lock:
+        client = _singleton.current
+        _singleton.current = None
+    if client is not None:
+        client.shutdown(timeout)

dlogify/__main__.py

@@ -0,0 +1,3 @@
+from .run.cli import main
+
+main()

dlogify/_capture_logging.py

@@ -0,0 +1,56 @@
+"""init() hands every logging record to its LogifyHandler by wrapping
+Logger.callHandlers instead of adding a handler to the root logger: a root
+logger without handlers keeps logging.basicConfig() and logging.lastResort
+working (spec D3)."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Callable
+
+_lock = threading.Lock()
+_handlers: list[logging.Handler] = []
+# The wrapper we installed last, while Logger.callHandlers is still it.
+_installed: "Callable | None" = None
+
+
+def _wrap(previous: Callable) -> Callable:
+    def call_handlers(self: logging.Logger, record: logging.LogRecord) -> None:
+        try:
+            previous(self, record)
+        finally:
+            # Another library may have wrapped us and been wrapped again: each
+            # record reaches our handlers once.
+            if not getattr(record, "_dlogify_seen", False):
+                try:
+                    record._dlogify_seen = True
+                    for handler in tuple(_handlers):
+                        if record.levelno >= handler.level:
+                            handler.handle(record)
+                except Exception:
+                    pass  # never break the application's logging call
+
+    call_handlers._dlogify_previous = previous  # type: ignore[attr-defined]
+    return call_handlers
+
+
+def install_logging_capture(handler: logging.Handler) -> Callable[[], None]:
+    global _installed
+    with _lock:
+        current = logging.Logger.callHandlers
+        if not hasattr(current, "_dlogify_previous"):
+            _installed = _wrap(current)
+            logging.Logger.callHandlers = _installed  # type: ignore[method-assign]
+        _handlers.append(handler)
+
+    def undo() -> None:
+        global _installed
+        with _lock:
+            if handler in _handlers:
+                _handlers.remove(handler)
+            if not _handlers and _installed is not None and logging.Logger.callHandlers is _installed:
+                logging.Logger.callHandlers = _installed._dlogify_previous  # type: ignore[attr-defined,method-assign]
+                _installed = None
+
+    return undo

dlogify/_client.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import json
+import math
+import os
+import sys
+import threading
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+from ._capture_logging import install_logging_capture
+from ._config import ResolvedConfig, disabled_config, resolve_config
+from ._diagnostics import Diagnostics, describe_error
+from ._encode import resource_attributes
+from ._exporter import Exporter
+from ._guard import guarded
+from ._hooks import ExitBudget, install_exit_flush, install_uncaught_capture
+from ._levels import LEVELNO, Level, level_from_word, level_rank
+from ._record import (
+    LogRecord,
+    exception_attributes,
+    exception_title,
+    finalize_record,
+    normalize_attributes,
+    normalize_value,
+    now_unix_nano,
+)
+from ._version import USER_AGENT
+from .handler import LogifyHandler
+
+DEFAULT_FLUSH_TIMEOUT = 2.0
+
+
+@dataclass
+class Internals:
+    """Not part of the documented API: tests and `logify run` use it."""
+
+    env: Optional[Mapping[str, str]] = None
+    cwd: Optional[str] = None
+    user_agent: Optional[str] = None
+    exporter: dict[str, Any] = field(default_factory=dict)
+
+
+def _valid_timeout(timeout: object) -> float:
+    if isinstance(timeout, (int, float)) and not isinstance(timeout, bool) and math.isfinite(timeout) and timeout >= 0:
+        return float(timeout)
+    return DEFAULT_FLUSH_TIMEOUT
+
+
+def _as_text(value: object) -> str:
+    if isinstance(value, str):
+        return value
+    normalized = normalize_value(value)
+    if normalized is None:
+        return ""
+    return normalized if isinstance(normalized, str) else json.dumps(normalized)
+
+
+class Client:
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        service: Optional[str] = None,
+        environment: Optional[str] = None,
+        release: Optional[str] = None,
+        min_level: Optional[str] = None,
+        capture_logging: bool = True,
+        capture_uncaught: bool = True,
+        attributes: Optional[Mapping[str, object]] = None,
+        max_queue_size: Optional[int] = None,
+        disabled: Optional[bool] = None,
+        debug: Optional[bool] = None,
+        _internals: Optional[Internals] = None,
+    ) -> None:
+        internals = _internals or Internals()
+        options = {
+            "api_key": api_key,
+            "endpoint": endpoint,
+            "service": service,
+            "environment": environment,
+            "release": release,
+            "min_level": min_level,
+            "capture_logging": capture_logging,
+            "capture_uncaught": capture_uncaught,
+            "attributes": attributes,
+            "max_queue_size": max_queue_size,
+            "disabled": disabled,
+            "debug": debug,
+        }
+        try:
+            env = os.environ if internals.env is None else internals.env
+            cwd = os.getcwd() if internals.cwd is None else internals.cwd
+            config, warnings = resolve_config(options, env, cwd)
+        except Exception as err:
+            config, warnings = disabled_config(), [f"invalid configuration ({describe_error(err)}); Logify is disabled"]
+        self.config: ResolvedConfig = config
+        self.diagnostics = Diagnostics(config.debug)
+        self._exporter: Optional[Exporter] = None
+        # Undo steps for everything this client installed, run by shutdown().
+        self._undo: list[Callable[[], None]] = []
+        self._lock = threading.Lock()
+        self._shut_down = False
+        self._closed = False
+        for warning in warnings:
+            self.diagnostics.warn(warning)
+        if not config.enabled:
+            return
+        try:
+            self._exporter = Exporter(
+                url=config.logs_url,
+                api_key=config.api_key,
+                user_agent=internals.user_agent or USER_AGENT,
+                resource=resource_attributes(
+                    service=config.service, environment=config.environment, release=config.release, attributes=config.attributes
+                ),
+                max_queue_size=config.max_queue_size,
+                diagnostics=self.diagnostics,
+                **internals.exporter,
+            )
+            self._install()
+        except Exception as err:
+            self.diagnostics.warn(f"could not start: {describe_error(err)}")
+
+    def _install(self) -> None:
+        """Installs the captures the configuration asks for."""
+        budget = ExitBudget()
+        self._undo.append(install_exit_flush(self, budget))
+        if self.config.capture_logging:
+            self._undo.append(install_logging_capture(LogifyHandler(LEVELNO[self.config.min_level], client=self)))
+        if self.config.capture_uncaught:
+            self._undo.append(install_uncaught_capture(self, budget))
+
+    def trace(self, message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+        self.log("trace", message, exc=exc, attributes=attributes)
+
+    def debug(self, message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+        self.log("debug", message, exc=exc, attributes=attributes)
+
+    def info(self, message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+        self.log("info", message, exc=exc, attributes=attributes)
+
+    def warn(self, message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+        self.log("warn", message, exc=exc, attributes=attributes)
+
+    warning = warn
+
+    def error(self, message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+        self.log("error", message, exc=exc, attributes=attributes)
+
+    def fatal(self, message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None) -> None:
+        self.log("fatal", message, exc=exc, attributes=attributes)
+
+    critical = fatal
+
+    def log(
+        self, level: str, message: object, *, exc: Optional[BaseException] = None, attributes: Optional[Mapping[str, object]] = None
+    ) -> None:
+        try:
+            if self._exporter is None:
+                return
+            lvl = level_from_word(level) if isinstance(level, str) else None
+            if lvl is None:
+                self.diagnostics.debug(f"unknown level {json.dumps(level) if isinstance(level, str) else repr(level)}; logged as info")
+                lvl = "info"
+            if not self._accepts(lvl):
+                return
+            body = _as_text(message)
+            record_attributes: dict[str, object] = {}
+            if isinstance(exc, BaseException):
+                exception = exception_attributes(exc)
+                record_attributes.update(exception)
+                if not body:
+                    body = exception_title(exception["exception.type"], exception["exception.message"])
+            normalize_attributes(attributes, record_attributes)
+            self._emit("logify", lvl, body, record_attributes)
+        except Exception as err:
+            self.diagnostics.debug(f"dropped a record: {describe_error(err)}")
+
+    def capture_exception(self, exc: Optional[BaseException] = None, *, attributes: Optional[Mapping[str, object]] = None) -> None:
+        """Level error; the body is "<type>: <message>". Without exc, the exception being handled."""
+        try:
+            if self._exporter is None:
+                return
+            if exc is None:
+                exc = sys.exc_info()[1]
+            if not isinstance(exc, BaseException):
+                self.diagnostics.debug("capture_exception() without an exception; ignored")
+                return
+            exception = exception_attributes(exc)
+            record_attributes: dict[str, object] = dict(exception)
+            normalize_attributes(attributes, record_attributes)
+            self._emit("logify", "error", exception_title(exception["exception.type"], exception["exception.message"]), record_attributes)
+        except Exception as err:
+            self.diagnostics.debug(f"dropped a record: {describe_error(err)}")
+
+    def _emit(
+        self, scope: str, level: Optional[Level], body: str, attributes: dict[str, object], time_unix_nano: Optional[str] = None
+    ) -> None:
+        """Internal entry for captures and `logify run`: applies min_level, the
+        size cuts and the times, then queues the record."""
+        exporter = self._exporter
+        if exporter is None or self._closed or not self._accepts(level):
+            return
+        try:
+            observed = now_unix_nano()
+            with guarded():
+                exporter.enqueue(finalize_record(LogRecord(scope, time_unix_nano or observed, observed, level, body, attributes)))
+        except Exception as err:
+            self.diagnostics.debug(f"dropped a record: {describe_error(err)}")
+
+    def flush(self, timeout: float = DEFAULT_FLUSH_TIMEOUT) -> None:
+        try:
+            if self._exporter is not None:
+                self._exporter.flush(_valid_timeout(timeout))
+        except Exception as err:
+            self.diagnostics.debug(f"flush failed: {describe_error(err)}")
+
+    def shutdown(self, timeout: float = DEFAULT_FLUSH_TIMEOUT) -> None:
+        """Flushes, stops the export thread and restores everything this client installed."""
+        with self._lock:
+            if self._shut_down:
+                return
+            self._shut_down = True
+        self.flush(timeout)
+        self._closed = True
+        if self._exporter is not None:
+            self._exporter.close()
+        while self._undo:
+            undo = self._undo.pop()
+            try:
+                undo()
+            except Exception:
+                pass  # restoring is best effort
+
+    def _accepts(self, level: Optional[Level]) -> bool:
+        return level_rank(level) >= level_rank(self.config.min_level)

dlogify/_config.py

@@ -0,0 +1,194 @@
+"""docs/12 §1: option > environment variable > default. Never raises for bad
+values: it falls back to the default and returns a warning."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.parse
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Optional
+
+from ._diagnostics import is_flag
+from ._levels import Level, is_level
+from ._record import AttributeValue, normalize_attributes
+
+DEFAULT_ENDPOINT = "https://api.dlogify.com"
+DEFAULT_MAX_QUEUE_SIZE = 2000
+
+
+@dataclass(frozen=True)
+class ResolvedConfig:
+    api_key: str
+    endpoint: str
+    logs_url: str
+    service: str
+    environment: str
+    release: str
+    min_level: Level
+    capture_logging: bool
+    capture_uncaught: bool
+    attributes: dict[str, AttributeValue] = field(default_factory=dict)
+    max_queue_size: int = DEFAULT_MAX_QUEUE_SIZE
+    enabled: bool = False
+    debug: bool = False
+
+
+def resolve_config(options: Mapping[str, object], env: Mapping[str, str], cwd: str) -> tuple[ResolvedConfig, list[str]]:
+    warnings: list[str] = []
+
+    def from_env(name: str) -> Optional[str]:
+        value = env.get(name)
+        value = value.strip() if isinstance(value, str) else ""
+        return value or None
+
+    def read(option: str, name: str) -> Optional[str]:
+        value = options.get(option)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+        return from_env(name)
+
+    def option_flag(option: str) -> Optional[bool]:
+        value = options.get(option)
+        if value is None or isinstance(value, bool):
+            return value
+        warnings.append(f"invalid {option} {value!r} (expected True or False); ignored")
+        return None
+
+    def flag(option: str, name: str) -> bool:
+        value = option_flag(option)
+        return value if value is not None else is_flag(env.get(name))
+
+    debug = flag("debug", "LOGIFY_DEBUG")
+    enabled = not flag("disabled", "LOGIFY_DISABLED")
+    api_key = read("api_key", "LOGIFY_API_KEY") or ""
+    if enabled and not api_key:
+        enabled = False
+        warnings.append("LOGIFY_API_KEY is not set; Logify is disabled")
+    elif enabled and not (api_key.isascii() and api_key.isprintable()):
+        enabled = False
+        warnings.append("LOGIFY_API_KEY has characters an HTTP header cannot carry; Logify is disabled")
+
+    endpoint = DEFAULT_ENDPOINT
+    raw_endpoint = read("endpoint", "LOGIFY_ENDPOINT")
+    if raw_endpoint is not None:
+        parsed = _parse_endpoint(raw_endpoint)
+        if parsed:
+            endpoint = parsed
+        else:
+            warnings.append(f"invalid endpoint {json.dumps(raw_endpoint)}; using {DEFAULT_ENDPOINT}")
+
+    min_level: Level = "info"
+    raw_level = read("min_level", "LOGIFY_MIN_LEVEL")
+    if raw_level is not None:
+        if is_level(raw_level.lower()):
+            min_level = raw_level.lower()  # type: ignore[assignment]
+        else:
+            warnings.append(f"unknown level {json.dumps(raw_level.lower())}; using info")
+
+    max_queue_size = DEFAULT_MAX_QUEUE_SIZE
+    raw_size = options.get("max_queue_size")
+    if raw_size is not None:
+        if isinstance(raw_size, int) and not isinstance(raw_size, bool) and raw_size > 0:
+            max_queue_size = raw_size
+        else:
+            warnings.append(f"invalid max_queue_size {raw_size!r}; using {DEFAULT_MAX_QUEUE_SIZE}")
+
+    config = ResolvedConfig(
+        api_key=api_key,
+        endpoint=endpoint,
+        logs_url=f"{endpoint}/v1/logs",
+        service=read("service", "LOGIFY_SERVICE") or from_env("OTEL_SERVICE_NAME") or project_name(cwd) or "unknown_service",
+        environment=read("environment", "LOGIFY_ENVIRONMENT") or "default",
+        release=read("release", "LOGIFY_RELEASE") or "",
+        min_level=min_level,
+        capture_logging=option_flag("capture_logging") is not False,
+        capture_uncaught=option_flag("capture_uncaught") is not False,
+        attributes=normalize_attributes(options.get("attributes")),
+        max_queue_size=max_queue_size,
+        enabled=enabled,
+        debug=debug,
+    )
+    return config, warnings
+
+
+def disabled_config() -> ResolvedConfig:
+    """Used when resolution itself fails."""
+    return ResolvedConfig(
+        api_key="",
+        endpoint=DEFAULT_ENDPOINT,
+        logs_url=f"{DEFAULT_ENDPOINT}/v1/logs",
+        service="unknown_service",
+        environment="default",
+        release="",
+        min_level="info",
+        capture_logging=False,
+        capture_uncaught=False,
+    )
+
+
+def _parse_endpoint(raw: str) -> Optional[str]:
+    if any(char.isspace() for char in raw):
+        return None
+    try:
+        parts = urllib.parse.urlsplit(raw)
+        parts.port  # raises ValueError for a port out of range
+    except ValueError:
+        return None
+    if parts.scheme.lower() not in ("http", "https") or not parts.hostname or parts.query or parts.fragment:
+        return None
+    if "?" in raw or "#" in raw:
+        return None
+    return raw.rstrip("/")
+
+
+def project_name(start: str) -> Optional[str]:
+    """The [project] name of the nearest pyproject.toml, walking up from start."""
+    directory = os.path.abspath(start)
+    while True:
+        try:
+            with open(os.path.join(directory, "pyproject.toml"), "rb") as file:
+                data = file.read()
+        except OSError:
+            data = None
+        if data is not None:
+            return _project_name_from_toml(data.decode("utf-8", "replace"))
+        parent = os.path.dirname(directory)
+        if parent == directory:
+            return None
+        directory = parent
+
+
+def _project_name_from_toml(text: str) -> Optional[str]:
+    try:
+        import tomllib
+    except ImportError:  # Python 3.10
+        return scan_project_name(text)
+    try:
+        name = tomllib.loads(text).get("project", {}).get("name")
+    except Exception:
+        return None
+    return name if isinstance(name, str) and name else None
+
+
+_TABLE = re.compile(r"^\s*\[\s*([^\]]+?)\s*\]\s*(?:#.*)?$")
+_NAME = re.compile(r"""^\s*name\s*=\s*(?:"([^"\\]*)"|'([^']*)')\s*(?:#.*)?$""")
+
+
+def scan_project_name(text: str) -> Optional[str]:
+    """A minimal reader for Python 3.10, which has no tomllib: the `name` key of
+    the [project] table, as a basic or literal string on one line."""
+    in_project = False
+    for line in text.splitlines():
+        table = _TABLE.match(line)
+        if table:
+            in_project = table.group(1) == "project"
+            continue
+        if in_project:
+            match = _NAME.match(line)
+            if match:
+                name = match.group(1) if match.group(1) is not None else match.group(2)
+                return name or None
+    return None