metrixwire 0.2.1__py3-none-any.whl

metrixwire/__init__.py

@@ -0,0 +1,64 @@
+"""MetrixWire — zero-config APM SDK for Python.
+
+Call :func:`init` once, as early as possible in your process. Every HTTP request
+becomes a **trace**, and every database query, outbound HTTP call and cache op
+within it becomes a **span** — automatically, with no manual span API and no
+middleware to wire up (a generic WSGI middleware is available as an escape hatch
+for bare apps: ``metrixwire.wsgi.MetrixWireMiddleware``).
+
+    import metrixwire
+    metrixwire.init(api_key="mw_...")
+
+Non-blocking: traces are batched and sent off the request path on a background
+daemon thread with a short timeout; all transport errors are swallowed so
+monitoring never breaks or slows the host application.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .client import client
+
+__all__ = ["init", "capture_exception", "flush"]
+__version__ = "0.1.0"
+
+
+def init(
+    api_key: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    flush_interval_ms: Optional[int] = None,
+    enabled: Optional[bool] = None,
+    timeout_ms: Optional[int] = None,
+    max_batch: Optional[int] = None,
+    capture_source: Optional[bool] = None,
+) -> None:
+    """Initialise the SDK and install auto-instrumentation. Idempotent.
+
+    Any argument left as ``None`` falls back to an environment variable
+    (``METRIXWIRE_KEY``, ``METRIXWIRE_ENDPOINT``, ``METRIXWIRE_ENABLED``) and
+    then a default. A missing API key runs the SDK disabled rather than raising.
+    """
+    client.init(
+        api_key=api_key,
+        endpoint=endpoint,
+        flush_interval_ms=flush_interval_ms,
+        enabled=enabled,
+        timeout_ms=timeout_ms,
+        max_batch=max_batch,
+        capture_source=capture_source,
+    )
+
+
+def capture_exception(exc: BaseException) -> None:
+    """Attach an exception to the active trace and flag it as an error.
+
+    The single manual escape hatch — for frameworks that catch their own errors
+    before the SDK can observe them. Never throws.
+    """
+    client.capture_exception(exc)
+
+
+def flush() -> None:
+    """Flush any queued traces now (e.g. before a short-lived process exits)."""
+    client.flush()

metrixwire/client.py

@@ -0,0 +1,173 @@
+"""The SDK singleton + the internal trace lifecycle helpers used by patches.
+
+The SDK is zero-config: ``metrixwire.init()`` is called once and every request,
+database query, cache op and outbound HTTP call is instrumented automatically.
+There is no manual span API on the public surface — only a
+``capture_exception()`` escape hatch (mirroring Node/PHP) for frameworks that
+swallow their own errors. Everything here is defensive: instrumentation must
+never throw into the host application.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, Optional
+
+from .config import Config, build_config
+from .context import get_current_trace, reset_current_trace, set_current_trace
+from .transport import Transport
+from .trace import Span, Trace, exception_meta, iso_millis
+
+
+class _Client:
+    def __init__(self) -> None:
+        self.config: Optional[Config] = None
+        self.transport: Optional[Transport] = None
+
+    def init(self, **opts: Any) -> None:
+        if self.config is not None:
+            return  # already initialised — no-op
+        self.config = build_config(**opts)
+        self.transport = Transport(self.config)
+        if self.config.enabled:
+            self.transport.start()
+            self._install_patches()
+
+    def _install_patches(self) -> None:
+        # Import lazily so a broken/optional patch can never break init().
+        try:
+            from .patches import install_all
+
+            install_all(self)
+        except Exception:
+            pass
+
+    # ── trace lifecycle (internal — called by patches) ───────────────────────
+
+    def start_trace(self, route: str, method: Optional[str]) -> Optional[Trace]:
+        if not self._enabled():
+            return None
+        try:
+            now = time.time()
+            trace = Trace(
+                route=route,
+                method=method,
+                started_at=iso_millis(now),
+                start_monotonic=time.monotonic(),
+            )
+            token = set_current_trace(trace)
+            # Stash the reset token on the trace so finish_trace can restore.
+            trace.meta.setdefault("__internal__", {})
+            trace.meta["__internal__"]["token"] = token
+            return trace
+        except Exception:
+            return None
+
+    def finish_trace(
+        self,
+        trace: Optional[Trace],
+        status_code: int = 200,
+        response_bytes: int = 0,
+        memory_mb: int = 0,
+    ) -> None:
+        if trace is None or not self._enabled():
+            return
+        try:
+            trace.duration_ms = int(round((time.monotonic() - trace.start_monotonic) * 1000))
+            # captureException may have already flagged this as an error — keep it.
+            if status_code >= 500:
+                trace.status = "error"
+            if response_bytes and response_bytes > 0:
+                trace.meta["responseBytes"] = int(response_bytes)
+            if memory_mb and memory_mb > 0:
+                trace.meta["memoryMb"] = int(memory_mb)
+            self._enqueue(trace)
+        finally:
+            self._pop_trace(trace)
+
+    def _pop_trace(self, trace: Trace) -> None:
+        try:
+            internal = trace.meta.pop("__internal__", None)
+            token = internal.get("token") if internal else None
+            if token is not None:
+                reset_current_trace(token)
+        except Exception:
+            pass
+
+    def _enqueue(self, trace: Trace) -> None:
+        try:
+            # Strip internal bookkeeping before serializing.
+            trace.meta.pop("__internal__", None)
+            if self.transport is not None:
+                self.transport.enqueue(trace.to_dict())
+        except Exception:
+            pass
+
+    # ── span recording (internal — called by patches) ────────────────────────
+
+    def record_span(
+        self,
+        type: str,
+        description: str,
+        duration_ms: float,
+        source_location: Optional[str] = None,
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        if not self._enabled() or not description:
+            return
+        trace = get_current_trace()
+        if trace is None:
+            return
+        try:
+            now = time.time()
+            started_at = iso_millis(now - (duration_ms / 1000.0))
+            trace.add_span(
+                Span(
+                    type=type,
+                    description=description,
+                    started_at=started_at,
+                    duration_ms=int(round(max(0.0, duration_ms))),
+                    source_location=source_location,
+                    meta=meta or None,
+                )
+            )
+        except Exception:
+            pass
+
+    def capture_exception(self, exc: BaseException) -> None:
+        """Attach an exception to the active trace and flag it as an error.
+
+        The one public escape hatch — for frameworks that catch their own
+        errors before our patch can observe them. Never throws.
+        """
+        if not self._enabled():
+            return
+        trace = get_current_trace()
+        if trace is None or exc is None:
+            return
+        try:
+            em = exception_meta(exc)
+            if em:
+                trace.meta["exception"] = em
+            trace.status = "error"
+        except Exception:
+            pass
+
+    def flush(self) -> None:
+        try:
+            if self.transport is not None:
+                self.transport.flush()
+        except Exception:
+            pass
+
+    # ── helpers ──────────────────────────────────────────────────────────────
+
+    def _enabled(self) -> bool:
+        return bool(self.config and self.config.enabled)
+
+    def is_source_capture_on(self) -> bool:
+        return bool(self.config.capture_source) if self.config else True
+
+
+# Singleton — the SDK's internal surface (patches call into this).
+client = _Client()

metrixwire/config.py

@@ -0,0 +1,85 @@
+"""SDK configuration + env fallbacks.
+
+``init()`` reads these env vars when the matching argument is omitted:
+``METRIXWIRE_KEY``, ``METRIXWIRE_ENDPOINT``, ``METRIXWIRE_ENABLED``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+DEFAULT_ENDPOINT = "http://localhost:3000/ingest"
+DEFAULT_FLUSH_INTERVAL_MS = 5000
+DEFAULT_TIMEOUT_MS = 3000
+DEFAULT_MAX_BATCH = 20
+
+
+def _env(key: str) -> Optional[str]:
+    v = os.environ.get(key)
+    if v is None or v == "":
+        return None
+    return v
+
+
+def _env_bool(key: str) -> Optional[bool]:
+    v = _env(key)
+    if v is None:
+        return None
+    return v.strip().lower() in ("1", "true", "yes", "on")
+
+
+def normalize_endpoint(endpoint: str) -> str:
+    """Accept a base URL or the full ``/ingest`` URL.
+
+    If it doesn't already end with ``/ingest``, append it — identical to the
+    Node/PHP transports.
+    """
+    url = (endpoint or DEFAULT_ENDPOINT).rstrip("/")
+    if not url.endswith("/ingest"):
+        url += "/ingest"
+    return url
+
+
+@dataclass
+class Config:
+    api_key: str
+    endpoint: str
+    flush_interval_ms: int
+    enabled: bool
+    timeout_ms: int
+    max_batch: int
+    capture_source: bool
+
+
+def build_config(
+    api_key: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    flush_interval_ms: Optional[int] = None,
+    enabled: Optional[bool] = None,
+    timeout_ms: Optional[int] = None,
+    max_batch: Optional[int] = None,
+    capture_source: Optional[bool] = None,
+) -> Config:
+    """Merge explicit args, env fallbacks and defaults into a Config.
+
+    A missing API key means the SDK runs disabled (never throws) — matching the
+    other SDKs.
+    """
+    key = api_key if api_key is not None else (_env("METRIXWIRE_KEY") or "")
+    ep = endpoint if endpoint is not None else _env("METRIXWIRE_ENDPOINT")
+    want_enabled = enabled if enabled is not None else _env_bool("METRIXWIRE_ENABLED")
+    if want_enabled is None:
+        want_enabled = True
+
+    return Config(
+        api_key=key or "",
+        endpoint=normalize_endpoint(ep or DEFAULT_ENDPOINT),
+        flush_interval_ms=int(flush_interval_ms if flush_interval_ms is not None else DEFAULT_FLUSH_INTERVAL_MS),
+        # Disabled unless we actually have a key — never crash on a missing key.
+        enabled=bool(want_enabled) and bool(key),
+        timeout_ms=int(timeout_ms if timeout_ms is not None else DEFAULT_TIMEOUT_MS),
+        max_batch=int(max_batch if max_batch is not None else DEFAULT_MAX_BATCH),
+        capture_source=bool(capture_source) if capture_source is not None else True,
+    )

metrixwire/context.py

@@ -0,0 +1,36 @@
+"""The active-trace store, backed by :mod:`contextvars`.
+
+``contextvars`` gives us the right isolation semantics automatically: each
+thread and each asyncio task sees its own current trace, so concurrent requests
+(sync WSGI worker threads or async ASGI tasks) never bleed spans into each
+other. All accessors are defensive — instrumentation must never throw.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from typing import Optional
+
+from .trace import Trace
+
+_current_trace: "contextvars.ContextVar[Optional[Trace]]" = contextvars.ContextVar(
+    "metrixwire_current_trace", default=None
+)
+
+
+def get_current_trace() -> Optional[Trace]:
+    try:
+        return _current_trace.get()
+    except Exception:
+        return None
+
+
+def set_current_trace(trace: Optional[Trace]) -> "contextvars.Token":
+    return _current_trace.set(trace)
+
+
+def reset_current_trace(token: "contextvars.Token") -> None:
+    try:
+        _current_trace.reset(token)
+    except Exception:
+        pass

metrixwire/patches/__init__.py

@@ -0,0 +1,52 @@
+"""Auto-instrumentation registry.
+
+``install_all`` runs every patch in its own ``try/except`` so one broken or
+missing target can never stop the others — and never breaks ``init()``. Each
+patch is idempotent (guards against double-patching) and skips silently when its
+target library isn't importable.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, List
+
+
+def install_all(client: Any) -> None:
+    patchers: List[Callable[[Any], None]] = []
+
+    # Web frameworks (open one trace per request).
+    from . import flask_patch, django_patch, starlette_patch
+
+    patchers += [
+        flask_patch.install,
+        django_patch.install,
+        starlette_patch.install,
+    ]
+
+    # DB drivers (db_query spans).
+    from . import sqlite3_patch, psycopg2_patch, psycopg3_patch, pymysql_patch, mysqldb_patch
+
+    patchers += [
+        sqlite3_patch.install,
+        psycopg2_patch.install,
+        psycopg3_patch.install,
+        pymysql_patch.install,
+        mysqldb_patch.install,
+    ]
+
+    # Outbound HTTP (http_call spans).
+    from . import requests_patch, httpclient_patch
+
+    patchers += [requests_patch.install, httpclient_patch.install]
+
+    # Cache (custom span, kind=cache).
+    from . import redis_patch
+
+    patchers += [redis_patch.install]
+
+    for patcher in patchers:
+        try:
+            patcher(client)
+        except Exception:
+            # A single failing/absent target must never break the others.
+            pass

metrixwire/patches/db.py

@@ -0,0 +1,111 @@
+"""Shared helpers for the DB-driver patches.
+
+All drivers follow the DB-API 2.0 cursor protocol, so the timing / span-shape /
+transaction-detection logic is identical: time the ``execute``, read
+``cursor.rowcount``, capture the nearest user frame, and — when the statement is
+a ``COMMIT`` / ``BEGIN`` boundary — additionally emit a transaction span.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+from ..util import nearest_user_frame
+
+
+def _normalize_sql(sql: Any) -> str:
+    try:
+        text = sql.decode("utf-8", "replace") if isinstance(sql, (bytes, bytearray)) else str(sql)
+        return " ".join(text.split()).strip()
+    except Exception:
+        return ""
+
+
+def record_query(client: Any, sql: Any, duration_ms: float, rowcount: Optional[int]) -> None:
+    """Emit a ``db_query`` span for one executed statement."""
+    text = _normalize_sql(sql)
+    if not text:
+        return
+    meta = None
+    try:
+        if rowcount is not None and int(rowcount) >= 0:
+            meta = {"rowCount": int(rowcount)}
+    except Exception:
+        meta = None
+    source = nearest_user_frame() if client.is_source_capture_on() else None
+    client.record_span("db_query", text, duration_ms, source_location=source, meta=meta)
+
+
+# Per-connection transaction start time (monotonic). Keyed by id() of the
+# connection so we can time a BEGIN…COMMIT window opened via raw SQL. Weakly
+# scoped by best-effort cleanup on COMMIT/ROLLBACK.
+_txn_starts: "dict[int, float]" = {}
+
+
+def _txn_boundary(client: Any, conn_id: Optional[int], sql_text: str) -> None:
+    """Detect BEGIN / COMMIT / ROLLBACK issued as raw SQL and time the window.
+
+    Emits a ``custom`` transaction span (``meta.kind='transaction'``) when a
+    transaction closes, so the long_transaction detector can flag it.
+    """
+    if conn_id is None:
+        return
+    try:
+        head = sql_text.lstrip().upper()
+        if head.startswith("BEGIN") or head.startswith("START TRANSACTION"):
+            _txn_starts[conn_id] = time.monotonic()
+        elif head.startswith("COMMIT") or head.startswith("ROLLBACK") or head.startswith("END"):
+            start = _txn_starts.pop(conn_id, None)
+            if start is not None:
+                duration_ms = (time.monotonic() - start) * 1000.0
+                client.record_span(
+                    "custom", "DB transaction", duration_ms, meta={"kind": "transaction"}
+                )
+    except Exception:
+        pass
+
+
+def _conn_id(cursor: Any) -> Optional[int]:
+    try:
+        conn = getattr(cursor, "connection", None)
+        return id(conn) if conn is not None else None
+    except Exception:
+        return None
+
+
+def instrument_execute(client: Any, cursor: Any, original: Any, sql: Any, *args: Any, **kwargs: Any) -> Any:
+    """Time a cursor.execute/executemany call and record its span."""
+    start = time.monotonic()
+    try:
+        return original(cursor, sql, *args, **kwargs)
+    finally:
+        try:
+            duration_ms = (time.monotonic() - start) * 1000.0
+            rowcount = getattr(cursor, "rowcount", None)
+            record_query(client, sql, duration_ms, rowcount)
+            _txn_boundary(client, _conn_id(cursor), _normalize_sql(sql))
+        except Exception:
+            pass
+
+
+def instrument_commit(client: Any, conn: Any, original: Any, *args: Any, **kwargs: Any) -> Any:
+    """Wrap ``connection.commit()`` to time a transaction opened via the driver's
+    implicit/explicit begin. Emits a transaction span on commit."""
+    conn_id = id(conn)
+    start = _txn_starts.pop(conn_id, None)
+    result = original(conn, *args, **kwargs)
+    try:
+        if start is not None:
+            duration_ms = (time.monotonic() - start) * 1000.0
+            client.record_span("custom", "DB transaction", duration_ms, meta={"kind": "transaction"})
+    except Exception:
+        pass
+    return result
+
+
+def mark_txn_begin(conn: Any) -> None:
+    try:
+        _txn_starts.setdefault(id(conn), time.monotonic())
+    except Exception:
+        pass

metrixwire/patches/django_patch.py

@@ -0,0 +1,164 @@
+"""Django auto-instrumentation.
+
+We patch the WSGI and ASGI handler entry points
+(``WSGIHandler.__call__`` / ``ASGIHandler.__call__``) so a trace is opened per
+request. The route is refined to the resolver match (e.g. ``users/<int:id>``)
+via ``request.resolver_match`` when Django has resolved it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..util import memory_delta_mb, memory_snapshot
+from . import web
+
+_WSGI_PATCHED = False
+_ASGI_PATCHED = False
+
+
+def install(client: Any) -> None:
+    _install_wsgi(client)
+    _install_asgi(client)
+
+
+def _route_from_path(method: str, path: str) -> str:
+    """Resolve the URLconf pattern for a path (e.g. ``users/<int:id>/``).
+
+    Independent of the request object — resolves the path directly against
+    Django's resolver, which is stable and always available after setup.
+    """
+    try:
+        from django.urls import resolve
+
+        match = resolve(path)
+        route = getattr(match, "route", None)
+        if route:
+            return web.route_label(method, "/" + str(route).lstrip("/"))
+    except Exception:
+        pass
+    return web.route_label(method, path)
+
+
+def _install_wsgi(client: Any) -> None:
+    global _WSGI_PATCHED
+    if _WSGI_PATCHED:
+        return
+    try:
+        from django.core.handlers.wsgi import WSGIHandler
+    except Exception:
+        return
+
+    if getattr(WSGIHandler.__call__, "_metrixwire", False):
+        _WSGI_PATCHED = True
+        return
+
+    original = WSGIHandler.__call__
+
+    def __call__(self, environ, start_response):  # type: ignore[no-untyped-def]
+        method = environ.get("REQUEST_METHOD", "GET")
+        path = web.path_only(environ.get("PATH_INFO") or "/")
+        trace = client.start_trace(web.route_label(method, path), method)
+        if trace is None:
+            return original(self, environ, start_response)
+
+        start_mem = memory_snapshot()
+        state = {"status_code": 200, "bytes": 0}
+
+        def wrapped_start_response(status, headers, exc_info=None):  # type: ignore[no-untyped-def]
+            try:
+                state["status_code"] = int(str(status).split(" ", 1)[0])
+            except Exception:
+                pass
+            return start_response(status, headers, exc_info)
+
+        try:
+            response = original(self, environ, wrapped_start_response)
+        except Exception as exc:
+            client.capture_exception(exc)
+            client.finish_trace(trace, status_code=500, memory_mb=memory_delta_mb(start_mem))
+            raise
+
+        # Django returns an HttpResponse (iterable). Refine the route from it.
+        try:
+            status_code = int(getattr(response, "status_code", state["status_code"]))
+        except Exception:
+            status_code = state["status_code"]
+        try:
+            content = getattr(response, "content", b"")
+            byte_len = len(content) if content is not None else 0
+        except Exception:
+            byte_len = 0
+
+        trace.route = _route_from_path(method, path)
+        client.finish_trace(
+            trace, status_code=status_code, response_bytes=byte_len,
+            memory_mb=memory_delta_mb(start_mem),
+        )
+        return response
+
+    __call__._metrixwire = True  # type: ignore[attr-defined]
+    WSGIHandler.__call__ = __call__
+    _WSGI_PATCHED = True
+
+
+def _install_asgi(client: Any) -> None:
+    global _ASGI_PATCHED
+    if _ASGI_PATCHED:
+        return
+    try:
+        from django.core.handlers.asgi import ASGIHandler
+    except Exception:
+        return
+
+    if getattr(ASGIHandler.__call__, "_metrixwire", False):
+        _ASGI_PATCHED = True
+        return
+
+    original = ASGIHandler.__call__
+
+    async def __call__(self, scope, receive, send):  # type: ignore[no-untyped-def]
+        if scope.get("type") != "http":
+            return await original(self, scope, receive, send)
+
+        method = scope.get("method", "GET")
+        path = web.path_only(scope.get("path") or "/")
+        trace = client.start_trace(web.route_label(method, path), method)
+        if trace is None:
+            return await original(self, scope, receive, send)
+
+        start_mem = memory_snapshot()
+        state = {"status_code": 200, "bytes": 0}
+
+        async def wrapped_send(message):  # type: ignore[no-untyped-def]
+            try:
+                mtype = message.get("type")
+                if mtype == "http.response.start":
+                    state["status_code"] = int(message.get("status", 200))
+                elif mtype == "http.response.body":
+                    body = message.get("body") or b""
+                    try:
+                        state["bytes"] += len(body)
+                    except Exception:
+                        pass
+            except Exception:
+                pass
+            return await send(message)
+
+        try:
+            result = await original(self, scope, receive, wrapped_send)
+            trace.route = _route_from_path(method, path)
+            client.finish_trace(
+                trace, status_code=state["status_code"], response_bytes=state["bytes"],
+                memory_mb=memory_delta_mb(start_mem),
+            )
+            return result
+        except Exception as exc:
+            client.capture_exception(exc)
+            trace.route = _route_from_path(method, path)
+            client.finish_trace(trace, status_code=500, memory_mb=memory_delta_mb(start_mem))
+            raise
+
+    __call__._metrixwire = True  # type: ignore[attr-defined]
+    ASGIHandler.__call__ = __call__
+    _ASGI_PATCHED = True