metrixwire 0.2.1__tar.gz

metrixwire-0.2.1/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+.env
+.env.local
+*.log
+.DS_Store
+apps/web/dist/
+.drizzle/
+vendor/
+sdks/php/composer.lock
+
+# Python bytecode cache
+__pycache__/
+*.pyc

metrixwire-0.2.1/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: metrixwire
+Version: 0.2.1
+Summary: Zero-config APM SDK for Python. Call init() once — every request, query, cache op and outbound HTTP call is instrumented automatically.
+Project-URL: Homepage, https://metrixwire.com
+Author: MetrixWire
+License: MIT
+Keywords: apm,monitoring,observability,tracing,zero-config
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: django; extra == 'dev'
+Requires-Dist: fastapi; extra == 'dev'
+Requires-Dist: flask; extra == 'dev'
+Requires-Dist: psycopg2-binary; extra == 'dev'
+Requires-Dist: redis; extra == 'dev'
+Requires-Dist: requests; extra == 'dev'
+Requires-Dist: starlette; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# metrixwire (Python)
+
+Zero-config APM SDK for **Python**. Call `init()` once — every request, database query, cache op and outbound HTTP call is instrumented automatically. There is no manual span API and no middleware to wire up. Non-blocking: if the MetrixWire endpoint is down, your app keeps running normally.
+
+## Installation
+
+```bash
+pip install metrixwire
+```
+
+Zero required dependencies — the core uses only the standard library.
+
+## Usage
+
+```python
+import metrixwire
+
+metrixwire.init(api_key="mw_...")
+```
+
+That's it. Do this once, as early as possible in your process (before your server starts). Every HTTP request becomes a **trace**, and every query / HTTP call / cache op within it becomes a **span**.
+
+### Auto-init as early as possible
+
+Import and init at the very top of your entry module (or a `sitecustomize.py` on your `PYTHONPATH`) so the patches are installed before your framework and drivers are used:
+
+```python
+# sitecustomize.py — or the first lines of your app's entry point
+import metrixwire
+metrixwire.init()  # reads METRIXWIRE_KEY / METRIXWIRE_ENDPOINT / METRIXWIRE_ENABLED from env
+```
+
+With no arguments, `init()` reads its config from the environment:
+
+| Env var | Purpose |
+|---|---|
+| `METRIXWIRE_KEY` | Project API key (required to enable) |
+| `METRIXWIRE_ENDPOINT` | Ingest URL — base or full `/ingest` (default `http://localhost:3000/ingest`) |
+| `METRIXWIRE_ENABLED` | `false` to disable entirely |
+
+A missing API key runs the SDK **disabled** — it never raises.
+
+## How the automatic tracing works
+
+A trace is opened for **every incoming request** by patching each framework's single entry point — no middleware, no per-route setup:
+
+| Framework | Traced automatically | How |
+|---|---|---|
+| **Flask** | ✅ | wraps `Flask.wsgi_app`; route from the matched URL rule (`/users/<id>`) |
+| **Django** | ✅ | patches `WSGIHandler.__call__` and `ASGIHandler.__call__`; route from the resolver match |
+| **FastAPI · Starlette** | ✅ | wraps `Starlette.__call__` (ASGI); route from the matched pattern (`/users/{id}`) |
+| **Bare / other WSGI** (`wsgiref`, …) | ✅ | wrap once with `metrixwire.wsgi.MetrixWireMiddleware` |
+
+For a bare or unsupported WSGI app:
+
+```python
+from metrixwire.wsgi import MetrixWireMiddleware
+app = MetrixWireMiddleware(app)
+```
+
+Each trace records the route, HTTP status, response byte size (for the large-response detector), memory growth (for the memory-spike detector), and any unhandled exception.
+
+## Automatically instrumented libraries
+
+Installed via `init()` — each is best-effort: if the library isn't importable it's skipped silently.
+
+| Library | Span | How |
+|---|---|---|
+| **psycopg2** | `db_query` (`rowCount`) | patches `psycopg2.extensions.cursor.execute`/`executemany` |
+| **psycopg (v3)** | `db_query` (`rowCount`) | patches `psycopg.Cursor.execute`/`executemany` |
+| **sqlite3** | `db_query` (`rowCount`) | patches `sqlite3.Cursor.execute`/`executemany` |
+| **PyMySQL · mysqlclient** | `db_query` (`rowCount`) | patches the driver's `Cursor.execute`/`executemany` |
+| **Django ORM · SQLAlchemy** | `db_query` | automatic — they run on the drivers above |
+| **requests** | `http_call` (`statusCode`) | patches `Session.request` |
+| **stdlib `http.client` / `urllib`** | `http_call` (`statusCode`) | patches `HTTPConnection.request`/`getresponse` |
+| **redis-py** | cache (`custom`, `kind=cache`) | patches `Redis.execute_command` (records hit/miss) |
+| **DB transactions** | `custom` (`kind=transaction`) | times `BEGIN…COMMIT` / `connection.commit()` |
+
+Database spans also capture a `sourceLocation` (`file.py:42`) pointing at the nearest application frame.
+
+## `init` options
+
+```python
+metrixwire.init(
+    api_key="mw_...",                        # required (or METRIXWIRE_KEY)
+    endpoint="http://localhost:3000/ingest",  # default; base URL is accepted too
+    flush_interval_ms=5000,                   # how often batches are sent
+    enabled=True,                             # set False to disable entirely
+    timeout_ms=3000,                          # send timeout (short, non-blocking)
+    max_batch=20,                             # flush immediately once this many are queued
+    capture_source=True,                      # capture the file:line a span originated from
+)
+```
+
+## Escape hatch
+
+Requests, queries, HTTP calls and cache ops are all captured automatically. The one manual helper — for frameworks that catch their own errors before the SDK sees them — is:
+
+```python
+import metrixwire
+
+try:
+    ...
+except Exception as e:
+    metrixwire.capture_exception(e)   # attach it to the active trace
+    raise
+```
+
+## Non-blocking behavior
+
+- Traces are batched and sent **off the request path** on a background daemon thread with a short timeout.
+- **All** transport errors are swallowed — instrumentation never throws into your app.
+- A final flush runs at process exit (`atexit`); you can also call `metrixwire.flush()` before a short-lived process exits.

metrixwire-0.2.1/README.md

@@ -0,0 +1,113 @@
+# metrixwire (Python)
+
+Zero-config APM SDK for **Python**. Call `init()` once — every request, database query, cache op and outbound HTTP call is instrumented automatically. There is no manual span API and no middleware to wire up. Non-blocking: if the MetrixWire endpoint is down, your app keeps running normally.
+
+## Installation
+
+```bash
+pip install metrixwire
+```
+
+Zero required dependencies — the core uses only the standard library.
+
+## Usage
+
+```python
+import metrixwire
+
+metrixwire.init(api_key="mw_...")
+```
+
+That's it. Do this once, as early as possible in your process (before your server starts). Every HTTP request becomes a **trace**, and every query / HTTP call / cache op within it becomes a **span**.
+
+### Auto-init as early as possible
+
+Import and init at the very top of your entry module (or a `sitecustomize.py` on your `PYTHONPATH`) so the patches are installed before your framework and drivers are used:
+
+```python
+# sitecustomize.py — or the first lines of your app's entry point
+import metrixwire
+metrixwire.init()  # reads METRIXWIRE_KEY / METRIXWIRE_ENDPOINT / METRIXWIRE_ENABLED from env
+```
+
+With no arguments, `init()` reads its config from the environment:
+
+| Env var | Purpose |
+|---|---|
+| `METRIXWIRE_KEY` | Project API key (required to enable) |
+| `METRIXWIRE_ENDPOINT` | Ingest URL — base or full `/ingest` (default `http://localhost:3000/ingest`) |
+| `METRIXWIRE_ENABLED` | `false` to disable entirely |
+
+A missing API key runs the SDK **disabled** — it never raises.
+
+## How the automatic tracing works
+
+A trace is opened for **every incoming request** by patching each framework's single entry point — no middleware, no per-route setup:
+
+| Framework | Traced automatically | How |
+|---|---|---|
+| **Flask** | ✅ | wraps `Flask.wsgi_app`; route from the matched URL rule (`/users/<id>`) |
+| **Django** | ✅ | patches `WSGIHandler.__call__` and `ASGIHandler.__call__`; route from the resolver match |
+| **FastAPI · Starlette** | ✅ | wraps `Starlette.__call__` (ASGI); route from the matched pattern (`/users/{id}`) |
+| **Bare / other WSGI** (`wsgiref`, …) | ✅ | wrap once with `metrixwire.wsgi.MetrixWireMiddleware` |
+
+For a bare or unsupported WSGI app:
+
+```python
+from metrixwire.wsgi import MetrixWireMiddleware
+app = MetrixWireMiddleware(app)
+```
+
+Each trace records the route, HTTP status, response byte size (for the large-response detector), memory growth (for the memory-spike detector), and any unhandled exception.
+
+## Automatically instrumented libraries
+
+Installed via `init()` — each is best-effort: if the library isn't importable it's skipped silently.
+
+| Library | Span | How |
+|---|---|---|
+| **psycopg2** | `db_query` (`rowCount`) | patches `psycopg2.extensions.cursor.execute`/`executemany` |
+| **psycopg (v3)** | `db_query` (`rowCount`) | patches `psycopg.Cursor.execute`/`executemany` |
+| **sqlite3** | `db_query` (`rowCount`) | patches `sqlite3.Cursor.execute`/`executemany` |
+| **PyMySQL · mysqlclient** | `db_query` (`rowCount`) | patches the driver's `Cursor.execute`/`executemany` |
+| **Django ORM · SQLAlchemy** | `db_query` | automatic — they run on the drivers above |
+| **requests** | `http_call` (`statusCode`) | patches `Session.request` |
+| **stdlib `http.client` / `urllib`** | `http_call` (`statusCode`) | patches `HTTPConnection.request`/`getresponse` |
+| **redis-py** | cache (`custom`, `kind=cache`) | patches `Redis.execute_command` (records hit/miss) |
+| **DB transactions** | `custom` (`kind=transaction`) | times `BEGIN…COMMIT` / `connection.commit()` |
+
+Database spans also capture a `sourceLocation` (`file.py:42`) pointing at the nearest application frame.
+
+## `init` options
+
+```python
+metrixwire.init(
+    api_key="mw_...",                        # required (or METRIXWIRE_KEY)
+    endpoint="http://localhost:3000/ingest",  # default; base URL is accepted too
+    flush_interval_ms=5000,                   # how often batches are sent
+    enabled=True,                             # set False to disable entirely
+    timeout_ms=3000,                          # send timeout (short, non-blocking)
+    max_batch=20,                             # flush immediately once this many are queued
+    capture_source=True,                      # capture the file:line a span originated from
+)
+```
+
+## Escape hatch
+
+Requests, queries, HTTP calls and cache ops are all captured automatically. The one manual helper — for frameworks that catch their own errors before the SDK sees them — is:
+
+```python
+import metrixwire
+
+try:
+    ...
+except Exception as e:
+    metrixwire.capture_exception(e)   # attach it to the active trace
+    raise
+```
+
+## Non-blocking behavior
+
+- Traces are batched and sent **off the request path** on a background daemon thread with a short timeout.
+- **All** transport errors are swallowed — instrumentation never throws into your app.
+- A final flush runs at process exit (`atexit`); you can also call `metrixwire.flush()` before a short-lived process exits.

metrixwire-0.2.1/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "metrixwire"
+version = "0.2.1"
+description = "Zero-config APM SDK for Python. Call init() once — every request, query, cache op and outbound HTTP call is instrumented automatically."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "MetrixWire" }]
+keywords = ["apm", "observability", "tracing", "monitoring", "zero-config"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Developers",
+  "Topic :: System :: Monitoring",
+]
+# The core has ZERO required runtime dependencies — it uses only the stdlib
+# (urllib, threading, queue, contextvars). Instrumentation of third-party
+# libraries is best-effort: if the library isn't importable, it's skipped.
+dependencies = []
+
+[project.optional-dependencies]
+# Purely for exercising the demos / integration testing — never required.
+dev = [
+  "flask",
+  "fastapi",
+  "starlette",
+  "django",
+  "psycopg2-binary",
+  "requests",
+  "redis",
+]
+
+[project.urls]
+Homepage = "https://metrixwire.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/metrixwire"]

metrixwire-0.2.1/src/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-0.2.1/src/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-0.2.1/src/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-0.2.1/src/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