errorgap 0.1.0__tar.gz → 0.2.0__tar.gz

errorgap-0.2.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.2.0 — 2026-10-03
+
+- APM: `track_transaction` / `track_job` context managers, `notify_transaction`,
+  and `SpanCollector` for DB and HTTP spans; enabled with `apm_enabled=True`,
+  sampled by `apm_sample_rate`.
+- Errors reported during a transaction carry its id as
+  `context.transaction_id` (held in a `ContextVar`), linking each error to
+  the request or job that raised it.
+- `errorgap.wsgi.ErrorgapMiddleware` times WSGI requests; `errorgap.flask.init_app`
+  installs it and groups requests by URL rule.
+- Requests record the browser SDK's `x-errorgap-trace` header as the
+  transaction's `trace_id`, linking browser API calls to server requests.
+
+## 0.1.1 — 2026-07-18
+
+- Include bounded inline source excerpts for readable application and dependency
+  traceback frames so
+  Errorgap can render highlighted source without a repository integration.
+- Order traceback frames innermost-first so frame 0 and group fingerprints use
+  the actual exception site.

{errorgap-0.1.0 → errorgap-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: errorgap
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python notifier for Errorgap error tracking.
 Project-URL: Homepage, https://github.com/errorgaphq/errorgap-python
 Project-URL: Source, https://github.com/errorgaphq/errorgap-python
@@ -37,7 +37,8 @@ Description-Content-Type: text/markdown
 # errorgap
 
 Python notifier for [Errorgap](https://errorgap.com). Captures exceptions,
-normalizes tracebacks, and ships notices to an Errorgap server. Single
+normalizes tracebacks with bounded source excerpts for readable frames, and ships
+notices to an Errorgap server. Single
 package covers plain Python, Django, Flask, and FastAPI.
 
 ## Install
@@ -106,6 +107,59 @@ app = Flask(__name__)
 init_app(app)
 ```
 
+`init_app` also times each request as an APM transaction (sent with
+`apm_enabled=True`) grouped by its URL rule (`/orders/<int:id>`), and errors
+raised during the request carry its transaction id. Record spans from a view
+with `errorgap.flask.spans()`:
+
+```python
+from errorgap.flask import spans
+
+@app.route("/orders/<int:order_id>")
+def order(order_id):
+    started = time.perf_counter()
+    row = db.execute("SELECT * FROM orders WHERE id = %s", (order_id,)).fetchone()
+    spans().database("SELECT * FROM orders WHERE id = %s", (time.perf_counter() - started) * 1000)
+    return row
+```
+
+## WSGI
+
+Any WSGI app gets the same request transactions from
+`errorgap.wsgi.ErrorgapMiddleware`. Set `environ["errorgap.route"]` to the
+matched route template to group requests (otherwise the raw path is used).
+
+```python
+from errorgap.wsgi import ErrorgapMiddleware
+
+application = ErrorgapMiddleware(application)
+```
+
+## Transactions and jobs
+
+```python
+with errorgap.track_transaction("GET", "/orders/{id}", "/orders/123") as txn:
+    txn.spans.database("SELECT * FROM orders WHERE id = 123", 4.2)
+    txn.status_code = 200
+
+with errorgap.track_job("ReceiptJob", queue="mailers") as txn:
+    send_receipt()
+```
+
+Both time the block and deliver on exit even if it raises. Errors reported
+inside carry the transaction id (`context.transaction_id`), so errorgap shows
+the error a request raised on its trace. The id lives in a `ContextVar`, so
+concurrent threads and asyncio tasks never share one;
+`errorgap.current_transaction_id()` returns the id in effect.
+
+## Browser trace links
+
+When the errorgap browser SDK (`@errorgap/browser` 0.3+) is on the page, its
+API calls send an `x-errorgap-trace` header. The WSGI middleware (and so
+`init_app`) records it, and `track_transaction(..., trace_id=header)` accepts
+it, so errorgap's browser Performance view links each call to the server
+request that answered it. Malformed values are ignored.
+
 ## FastAPI
 
 ```python
@@ -125,10 +179,12 @@ app.add_middleware(ErrorgapMiddleware)
 | `project_id` | `ERRORGAP_PROJECT_ID` | Optional, embedded in payload |
 | `api_key` | `ERRORGAP_API_KEY` | Sent as `x-errorgap-project-key` |
 | `environment` | `ERRORGAP_ENVIRONMENT`, `ENV`, or `development` | |
-| `root_directory` | `os.getcwd()` | Used to mark frames as `in_app` |
+| `root_directory` | `os.getcwd()` | Marks application frames; readable dependency frames also include bounded source excerpts |
 | `async_` | `True` | Background-thread delivery |
 | `logger` | `logging.getLogger("errorgap")` | Pass `None` to silence |
 | `filter_keys` | `("password", "token", ...)` | Substring match, case-insensitive |
+| `apm_enabled` | `False` | Send APM transactions |
+| `apm_sample_rate` | `1.0` | Fraction of transactions sent (errors are unaffected) |
 | `capture_globals` | `True` | Install `sys.excepthook` |
 
 ## Graceful shutdown

{errorgap-0.1.0 → errorgap-0.2.0}/README.md

@@ -1,7 +1,8 @@
 # errorgap
 
 Python notifier for [Errorgap](https://errorgap.com). Captures exceptions,
-normalizes tracebacks, and ships notices to an Errorgap server. Single
+normalizes tracebacks with bounded source excerpts for readable frames, and ships
+notices to an Errorgap server. Single
 package covers plain Python, Django, Flask, and FastAPI.
 
 ## Install
@@ -70,6 +71,59 @@ app = Flask(__name__)
 init_app(app)
 ```
 
+`init_app` also times each request as an APM transaction (sent with
+`apm_enabled=True`) grouped by its URL rule (`/orders/<int:id>`), and errors
+raised during the request carry its transaction id. Record spans from a view
+with `errorgap.flask.spans()`:
+
+```python
+from errorgap.flask import spans
+
+@app.route("/orders/<int:order_id>")
+def order(order_id):
+    started = time.perf_counter()
+    row = db.execute("SELECT * FROM orders WHERE id = %s", (order_id,)).fetchone()
+    spans().database("SELECT * FROM orders WHERE id = %s", (time.perf_counter() - started) * 1000)
+    return row
+```
+
+## WSGI
+
+Any WSGI app gets the same request transactions from
+`errorgap.wsgi.ErrorgapMiddleware`. Set `environ["errorgap.route"]` to the
+matched route template to group requests (otherwise the raw path is used).
+
+```python
+from errorgap.wsgi import ErrorgapMiddleware
+
+application = ErrorgapMiddleware(application)
+```
+
+## Transactions and jobs
+
+```python
+with errorgap.track_transaction("GET", "/orders/{id}", "/orders/123") as txn:
+    txn.spans.database("SELECT * FROM orders WHERE id = 123", 4.2)
+    txn.status_code = 200
+
+with errorgap.track_job("ReceiptJob", queue="mailers") as txn:
+    send_receipt()
+```
+
+Both time the block and deliver on exit even if it raises. Errors reported
+inside carry the transaction id (`context.transaction_id`), so errorgap shows
+the error a request raised on its trace. The id lives in a `ContextVar`, so
+concurrent threads and asyncio tasks never share one;
+`errorgap.current_transaction_id()` returns the id in effect.
+
+## Browser trace links
+
+When the errorgap browser SDK (`@errorgap/browser` 0.3+) is on the page, its
+API calls send an `x-errorgap-trace` header. The WSGI middleware (and so
+`init_app`) records it, and `track_transaction(..., trace_id=header)` accepts
+it, so errorgap's browser Performance view links each call to the server
+request that answered it. Malformed values are ignored.
+
 ## FastAPI
 
 ```python
@@ -89,10 +143,12 @@ app.add_middleware(ErrorgapMiddleware)
 | `project_id` | `ERRORGAP_PROJECT_ID` | Optional, embedded in payload |
 | `api_key` | `ERRORGAP_API_KEY` | Sent as `x-errorgap-project-key` |
 | `environment` | `ERRORGAP_ENVIRONMENT`, `ENV`, or `development` | |
-| `root_directory` | `os.getcwd()` | Used to mark frames as `in_app` |
+| `root_directory` | `os.getcwd()` | Marks application frames; readable dependency frames also include bounded source excerpts |
 | `async_` | `True` | Background-thread delivery |
 | `logger` | `logging.getLogger("errorgap")` | Pass `None` to silence |
 | `filter_keys` | `("password", "token", ...)` | Substring match, case-insensitive |
+| `apm_enabled` | `False` | Send APM transactions |
+| `apm_sample_rate` | `1.0` | Fraction of transactions sent (errors are unaffected) |
 | `capture_globals` | `True` | Install `sys.excepthook` |
 
 ## Graceful shutdown

{errorgap-0.1.0 → errorgap-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "errorgap"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python notifier for Errorgap error tracking."
 readme = "README.md"
 license = { text = "MIT" }

{errorgap-0.1.0 → errorgap-0.2.0}/src/errorgap/__init__.py

@@ -1,15 +1,26 @@
 from __future__ import annotations
 
-from typing import Any, Dict, Optional
+import contextlib
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterator, Optional
 
+from .apm import TRACE_HEADER, Span, SpanCollector, Transaction, browser_trace_id, normalize_sql
 from .client import Client, DeliveryResult
 from .configuration import Configuration
 from .handlers import install_excepthook, uninstall_excepthook
+from .transaction_context import current_transaction_id, new_transaction_id, transaction_scope
 from .version import VERSION
 
 __all__ = [
     "init",
     "notify",
+    "notify_transaction",
+    "track_transaction",
+    "track_job",
+    "current_transaction_id",
+    "transaction_scope",
+    "browser_trace_id",
     "flush",
     "shutdown",
     "configuration",
@@ -17,6 +28,11 @@ __all__ = [
     "Configuration",
     "Client",
     "DeliveryResult",
+    "Span",
+    "SpanCollector",
+    "Transaction",
+    "TRACE_HEADER",
+    "normalize_sql",
     "VERSION",
 ]
 
@@ -35,6 +51,8 @@ def init(
     async_: Optional[bool] = None,
     filter_keys: Optional[tuple] = None,
     logger: Optional[Any] = None,
+    apm_enabled: Optional[bool] = None,
+    apm_sample_rate: Optional[float] = None,
     capture_globals: bool = True,
 ) -> None:
     """Configure the SDK and install global error hooks.
@@ -64,6 +82,10 @@ def init(
         overrides["filter_keys"] = filter_keys
     if logger is not None:
         overrides["logger"] = logger
+    if apm_enabled is not None:
+        overrides["apm_enabled"] = apm_enabled
+    if apm_sample_rate is not None:
+        overrides["apm_sample_rate"] = apm_sample_rate
 
     _configuration = Configuration(**overrides)
     _client.configure(_configuration)
@@ -92,6 +114,61 @@ def notify(
     )
 
 
+def notify_transaction(transaction: Transaction, sync: bool = False) -> DeliveryResult:
+    """Deliver a pre-measured APM transaction."""
+    return _client.notify_transaction(transaction, sync=sync)
+
+
+@contextlib.contextmanager
+def track_transaction(
+    method: Optional[str] = None,
+    path: Optional[str] = None,
+    path_raw: Optional[str] = None,
+    trace_id: Optional[str] = None,
+    kind: str = "web",
+) -> Iterator[Transaction]:
+    """Time the ``with`` block as an APM transaction and deliver it on exit,
+    even if the block raises. Errors reported inside it carry the
+    transaction's id. Yields the :class:`Transaction`: record spans on
+    ``txn.spans`` and set ``txn.status_code``. ``trace_id`` takes the raw
+    ``x-errorgap-trace`` header value and ignores anything but a UUID."""
+    txn = Transaction(
+        kind=kind,
+        id=new_transaction_id(),
+        trace_id=browser_trace_id(trace_id),
+        method=method,
+        path=path,
+        path_raw=path_raw,
+    )
+    with _timed(txn):
+        yield txn
+
+
+@contextlib.contextmanager
+def track_job(job_class: str, queue: str = "default") -> Iterator[Transaction]:
+    """Time the ``with`` block as a ``job`` transaction; see
+    :func:`track_transaction`."""
+    txn = Transaction(kind="job", id=new_transaction_id(), job_class=job_class, queue=queue)
+    with _timed(txn):
+        yield txn
+
+
+@contextlib.contextmanager
+def _timed(txn: Transaction) -> Iterator[None]:
+    txn.occurred_at = datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+    start = time.perf_counter()
+    try:
+        with transaction_scope(txn.id or new_transaction_id()):
+            yield
+    except BaseException:
+        if txn.kind == "web" and txn.status_code is None:
+            txn.status_code = 500
+        raise
+    finally:
+        txn.duration_ms = (time.perf_counter() - start) * 1000.0
+        _client.notify_transaction(txn)
+
+
 def flush(timeout: Optional[float] = None) -> None:
     _client.flush(timeout)
 

errorgap-0.2.0/src/errorgap/apm.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Union
+
+from .configuration import Configuration
+
+#: The header the errorgap browser SDK sends with API calls.
+TRACE_HEADER = "x-errorgap-trace"
+
+_UUID = re.compile(r"\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\Z")
+_STRING_LITERAL = re.compile(r"'(?:''|[^'])*'")
+_NUMBER = re.compile(r"\b\d+(?:\.\d+)?\b")
+_WHITESPACE = re.compile(r"\s+")
+
+
+def browser_trace_id(header: Union[str, bytes, None]) -> Optional[str]:
+    """The trace id in an ``x-errorgap-trace`` header value, lowercased, or
+    ``None`` unless it is a well-formed UUID."""
+    if isinstance(header, bytes):
+        header = header.decode("latin-1")
+    if not isinstance(header, str):
+        return None
+    value = header.strip().lower()
+    return value if _UUID.match(value) else None
+
+
+def normalize_sql(sql: str) -> str:
+    """Strip literals so query shapes aggregate: '…' and numbers become ?."""
+    sql = _STRING_LITERAL.sub("?", sql)
+    sql = _NUMBER.sub("?", sql)
+    return _WHITESPACE.sub(" ", sql).strip()
+
+
+@dataclass
+class Span:
+    kind: str
+    duration_ms: float
+    sql: Optional[str] = None
+    file: Optional[str] = None
+    line: Optional[int] = None
+    function: Optional[str] = None
+
+    def to_payload(self) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"kind": self.kind, "duration_ms": self.duration_ms}
+        if self.sql is not None:
+            payload["sql"] = self.sql
+        if self.file is not None:
+            payload["file"] = self.file
+        if self.line is not None:
+            payload["line"] = self.line
+        if self.function is not None:
+            payload["fn_name"] = self.function
+        return payload
+
+
+class SpanCollector:
+    """Collects the spans recorded while a transaction or job is in flight."""
+
+    def __init__(self) -> None:
+        self._spans: List[Span] = []
+
+    def add(self, span: Span) -> None:
+        self._spans.append(span)
+
+    def database(
+        self,
+        sql: str,
+        duration_ms: float,
+        file: Optional[str] = None,
+        line: Optional[int] = None,
+        function: Optional[str] = None,
+    ) -> None:
+        self.add(Span("db", duration_ms, normalize_sql(sql), file, line, function))
+
+    def external(
+        self,
+        duration_ms: float,
+        file: Optional[str] = None,
+        line: Optional[int] = None,
+        function: Optional[str] = None,
+    ) -> None:
+        self.add(Span("http", duration_ms, None, file, line, function))
+
+    def snapshot(self) -> List[Span]:
+        return list(self._spans)
+
+
+@dataclass
+class Transaction:
+    """An APM transaction: a web interaction (``kind="web"``) or a background
+    job (``kind="job"``)."""
+
+    kind: str = "web"
+    #: Links the errors raised during this transaction to it.
+    id: Optional[str] = None
+    #: The browser's ``x-errorgap-trace`` header (see :func:`browser_trace_id`).
+    trace_id: Optional[str] = None
+    method: Optional[str] = None
+    #: Normalized route template used for grouping, e.g. ``/orders/<int:id>``.
+    path: Optional[str] = None
+    #: Concrete path for one request, e.g. ``/orders/123``.
+    path_raw: Optional[str] = None
+    status_code: Optional[int] = None
+    duration_ms: float = 0.0
+    environment: Optional[str] = None
+    #: ISO-8601; defaults to now.
+    occurred_at: Optional[str] = None
+    spans: SpanCollector = field(default_factory=SpanCollector)
+    job_class: Optional[str] = None
+    queue: Optional[str] = None
+
+    def to_payload(self, configuration: Configuration) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {
+            "kind": self.kind,
+            "duration_ms": self.duration_ms,
+            "environment": self.environment or configuration.environment,
+            "occurred_at": self.occurred_at or _now(),
+            "spans": [span.to_payload() for span in self.spans.snapshot()],
+        }
+        for key in ("id", "trace_id", "method", "path", "path_raw", "status_code", "job_class", "queue"):
+            value = getattr(self, key)
+            if value is not None:
+                payload[key] = value
+        return payload
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")

errorgap-0.2.0/src/errorgap/backtrace.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import os
+import traceback
+from typing import Any, Dict, List, Optional
+
+SOURCE_CONTEXT_RADIUS = 6
+MAX_SOURCE_LINE_CHARS = 400
+
+
+def parse_backtrace(exc: BaseException, root_directory: str) -> List[Dict[str, Any]]:
+    frames: List[Dict[str, Any]] = []
+    # traceback.extract_tb returns oldest -> newest. Errorgap frame index 0 is
+    # the innermost frame where the exception was raised.
+    tb_frames = reversed(traceback.extract_tb(exc.__traceback__))
+
+    for index, frame in enumerate(tb_frames):
+        file = frame.filename
+        in_app = _is_in_app(file, root_directory)
+        normalized: Dict[str, Any] = {
+            "file": _relative_file(file, root_directory),
+            "line": frame.lineno,
+            "function": frame.name,
+            "in_app": in_app,
+            "index": index,
+        }
+        source = _source_excerpt(file, frame.lineno)
+        if source is not None:
+            normalized["source"] = source
+        frames.append(normalized)
+
+    return frames
+
+
+def _relative_file(file: Optional[str], root: str) -> Optional[str]:
+    if not file:
+        return file
+    if not root:
+        return file
+    normalized = root if root.endswith(os.sep) else root + os.sep
+    if file.startswith(normalized):
+        return file[len(normalized):]
+    return file
+
+
+def _is_in_app(file: Optional[str], root: str) -> bool:
+    if not file or not root:
+        return False
+    if "site-packages" in file:
+        return False
+    if file.startswith("<"):
+        return False
+    return file.startswith(root)
+
+
+def _source_excerpt(file: str, line: int) -> Optional[Dict[str, Any]]:
+    if line < 1:
+        return None
+    start_line = max(1, line - SOURCE_CONTEXT_RADIUS)
+    end_line = line + SOURCE_CONTEXT_RADIUS
+    lines: List[str] = []
+    target_found = False
+
+    try:
+        with open(file, encoding="utf-8", errors="replace") as source_file:
+            for number, text in enumerate(source_file, start=1):
+                if number < start_line:
+                    continue
+                if number > end_line:
+                    break
+                lines.append(text.rstrip("\r\n")[:MAX_SOURCE_LINE_CHARS])
+                if number == line:
+                    target_found = True
+    except OSError:
+        return None
+
+    if not lines or not target_found:
+        return None
+    return {"start_line": start_line, "lines": lines}

{errorgap-0.1.0 → errorgap-0.2.0}/src/errorgap/client.py

@@ -3,14 +3,17 @@ from __future__ import annotations
 import json
 import logging
 import queue
+import random
 import threading
 from dataclasses import dataclass
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Tuple
 from urllib import error as urlerror
 from urllib import request as urlrequest
 
+from .apm import Transaction
 from .configuration import Configuration
 from .notice import build_notice
+from .transaction_context import current_transaction_id
 from .version import VERSION
 
 
@@ -29,7 +32,7 @@ class DeliveryResult:
 class Client:
     def __init__(self, configuration: Configuration):
         self._configuration = configuration
-        self._queue: "queue.Queue[Optional[Dict[str, Any]]]" = queue.Queue()
+        self._queue: "queue.Queue[Optional[Tuple[str, Dict[str, Any]]]]" = queue.Queue()
         self._worker: Optional[threading.Thread] = None
         self._lock = threading.Lock()
 
@@ -51,6 +54,9 @@ class Client:
     ) -> DeliveryResult:
         try:
             self._configuration.validate()
+            transaction_id = current_transaction_id()
+            if transaction_id and "transaction_id" not in (context or {}):
+                context = {**(context or {}), "transaction_id": transaction_id}
             notice = build_notice(
                 exc,
                 self._configuration,
@@ -67,12 +73,37 @@ class Client:
             return self.deliver(notice)
 
         self._ensure_worker()
-        self._queue.put(notice)
+        self._queue.put(("notices", notice))
+        return DeliveryResult(queued=True, status=202)
+
+    def notify_transaction(self, transaction: Transaction, sync: bool = False) -> DeliveryResult:
+        """Deliver an APM transaction. Dropped unless ``apm_enabled``, and
+        sampled by ``apm_sample_rate``."""
+        try:
+            self._configuration.validate()
+            if not self._configuration.apm_enabled:
+                return DeliveryResult(status=204)
+            rate = self._configuration.apm_sample_rate
+            if not (rate >= 1 or (rate > 0 and random.random() < rate)):
+                return DeliveryResult(status=204)
+            payload = transaction.to_payload(self._configuration)
+        except Exception as caught:  # noqa: BLE001 — SDK must not raise
+            self._log(caught)
+            return DeliveryResult(error=caught)
+
+        if sync or not self._configuration.async_:
+            return self._post("transactions", payload)
+
+        self._ensure_worker()
+        self._queue.put(("transactions", payload))
         return DeliveryResult(queued=True, status=202)
 
     def deliver(self, notice: Dict[str, Any]) -> DeliveryResult:
-        url = _notices_url(self._configuration)
-        body = json.dumps(notice).encode("utf-8")
+        return self._post("notices", notice)
+
+    def _post(self, resource: str, payload: Dict[str, Any]) -> DeliveryResult:
+        url = _project_url(self._configuration, resource)
+        body = json.dumps(payload).encode("utf-8")
         headers = {
             "Content-Type": "application/json",
             "User-Agent": f"errorgap-python/{VERSION}",
@@ -130,7 +161,8 @@ class Client:
             try:
                 if item is None:
                     return
-                self.deliver(item)
+                resource, payload = item
+                self._post(resource, payload)
             finally:
                 self._queue.task_done()
 
@@ -147,9 +179,9 @@ class Client:
                 pass
 
 
-def _notices_url(configuration: Configuration) -> str:
+def _project_url(configuration: Configuration, resource: str) -> str:
     base = configuration.endpoint.rstrip("/")
-    return f"{base}/api/projects/{configuration.project_slug}/notices"
+    return f"{base}/api/projects/{configuration.project_slug}/{resource}"
 
 
 def _wait_join(q: "queue.Queue[Any]", timeout: float) -> None:

{errorgap-0.1.0 → errorgap-0.2.0}/src/errorgap/flask.py

@@ -1,21 +1,35 @@
 from __future__ import annotations
 
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 from . import notify
+from .apm import SpanCollector
+from .wsgi import ROUTE_KEY, TRANSACTION_KEY, ErrorgapMiddleware
 
 
 def init_app(app: Any) -> None:
     """Register Errorgap with a Flask application.
 
     Subscribes to Flask's ``got_request_exception`` signal so all unhandled
-    exceptions raised inside a request are reported.
+    exceptions raised inside a request are reported, and wraps the app in
+    :class:`~errorgap.wsgi.ErrorgapMiddleware` so each request is an APM
+    transaction (sent with ``apm_enabled``) grouped by its URL rule, and errors
+    carry its transaction id.
     """
     try:
-        from flask import got_request_exception
+        from flask import got_request_exception, request
     except ImportError as exc:  # pragma: no cover
         raise RuntimeError("Flask is required to use errorgap.flask.init_app") from exc
 
+    if not isinstance(app.wsgi_app, ErrorgapMiddleware):
+        app.wsgi_app = ErrorgapMiddleware(app.wsgi_app)
+
+    @app.before_request
+    def _errorgap_route() -> None:
+        rule = getattr(request, "url_rule", None)
+        if rule is not None:
+            request.environ[ROUTE_KEY] = rule.rule
+
     def _on_exception(sender: Any, exception: BaseException, **_: Any) -> None:
         try:
             from flask import request
@@ -38,6 +52,17 @@ def init_app(app: Any) -> None:
     got_request_exception.connect(_on_exception, app, weak=False)
 
 
+def spans() -> Optional[SpanCollector]:
+    """The span collector for the current request's transaction, for
+    recording DB and outbound HTTP spans from views."""
+    from flask import has_request_context, request
+
+    if not has_request_context():
+        return None
+    txn = request.environ.get(TRANSACTION_KEY)
+    return txn.spans if txn is not None else None
+
+
 def _context(request: Any) -> Dict[str, Any]:
     return {
         "url": getattr(request, "url", None),

errorgap-0.2.0/src/errorgap/transaction_context.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import contextlib
+import uuid
+from contextvars import ContextVar
+from typing import Iterator, Optional
+
+# The APM transaction the current thread or task is running in, so errors
+# reported during it carry its id as ``context.transaction_id`` and errorgap
+# links each error to the request or job that raised it. A ContextVar follows
+# awaits and never leaks into a concurrent request or thread.
+_current: ContextVar[Optional[str]] = ContextVar("errorgap_transaction_id", default=None)
+
+
+def current_transaction_id() -> Optional[str]:
+    """The id of the transaction running now, if any."""
+    return _current.get()
+
+
+def new_transaction_id() -> str:
+    """A new random transaction id (a UUID)."""
+    return str(uuid.uuid4())
+
+
+@contextlib.contextmanager
+def transaction_scope(transaction_id: str) -> Iterator[str]:
+    """Make ``transaction_id`` current for the ``with`` block."""
+    token = _current.set(transaction_id)
+    try:
+        yield transaction_id
+    finally:
+        _current.reset(token)

errorgap-0.2.0/src/errorgap/version.py

@@ -0,0 +1 @@
+VERSION = "0.2.0"

errorgap-0.2.0/src/errorgap/wsgi.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable, Iterable, Iterator, Optional
+
+from .apm import Transaction, browser_trace_id
+from .transaction_context import _current, new_transaction_id
+
+#: WSGI environ key a framework integration sets to the matched route
+#: template (for example Flask's ``/orders/<int:id>``), used to group requests.
+ROUTE_KEY = "errorgap.route"
+#: WSGI environ key holding the request's :class:`Transaction`, for recording
+#: spans from views: ``environ["errorgap.transaction"].spans.database(...)``.
+TRANSACTION_KEY = "errorgap.transaction"
+
+
+class ErrorgapMiddleware:
+    """WSGI middleware that times each request as an APM transaction.
+
+    Errors reported while the request runs carry its transaction id, and the
+    errorgap browser SDK's ``x-errorgap-trace`` header links the browser's
+    view of the call to it. Transactions are sent only with ``apm_enabled``.
+    """
+
+    def __init__(self, app: Callable[..., Iterable[bytes]]) -> None:
+        self.app = app
+
+    def __call__(self, environ: dict, start_response: Callable[..., Any]) -> Iterable[bytes]:
+        txn = Transaction(
+            kind="web",
+            id=new_transaction_id(),
+            trace_id=browser_trace_id(environ.get("HTTP_X_ERRORGAP_TRACE")),
+            method=environ.get("REQUEST_METHOD"),
+            path_raw=environ.get("PATH_INFO") or "/",
+            occurred_at=datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+        )
+        environ[TRANSACTION_KEY] = txn
+        start = time.perf_counter()
+
+        def _start_response(status: str, headers: Any, exc_info: Any = None) -> Any:
+            try:
+                txn.status_code = int(status.split(" ", 1)[0])
+            except (ValueError, IndexError):
+                pass
+            return start_response(status, headers, exc_info) if exc_info else start_response(status, headers)
+
+        token = _current.set(txn.id)
+        try:
+            body = self.app(environ, _start_response)
+        except BaseException:
+            txn.status_code = 500
+            _current.reset(token)
+            _finish(txn, environ, start)
+            raise
+        _current.reset(token)
+        return _ClosingIterator(body, txn, environ, start)
+
+
+class _ClosingIterator:
+    """Keeps the transaction current while the response body is produced, and
+    records it once the server closes the response."""
+
+    def __init__(self, body: Iterable[bytes], txn: Transaction, environ: dict, start: float) -> None:
+        self._body = body
+        self._iter: Optional[Iterator[bytes]] = None
+        self._txn = txn
+        self._environ = environ
+        self._start = start
+        self._closed = False
+
+    def __iter__(self) -> "_ClosingIterator":
+        return self
+
+    def __next__(self) -> bytes:
+        if self._iter is None:
+            self._iter = iter(self._body)
+        token = _current.set(self._txn.id)
+        try:
+            return next(self._iter)
+        except StopIteration:
+            raise
+        except BaseException:
+            self._txn.status_code = 500
+            raise
+        finally:
+            _current.reset(token)
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            close = getattr(self._body, "close", None)
+            if close is not None:
+                close()
+        finally:
+            _finish(self._txn, self._environ, self._start)
+
+
+def _finish(txn: Transaction, environ: dict, start: float) -> None:
+    import errorgap
+
+    txn.duration_ms = (time.perf_counter() - start) * 1000.0
+    txn.path = environ.get(ROUTE_KEY) or txn.path_raw
+    errorgap.notify_transaction(txn)
+
+
+__all__ = ["ErrorgapMiddleware", "ROUTE_KEY", "TRANSACTION_KEY"]

errorgap-0.2.0/tests/test_apm.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import threading
+
+import pytest
+
+import errorgap
+from errorgap import browser_trace_id, current_transaction_id
+from errorgap.wsgi import ROUTE_KEY, ErrorgapMiddleware
+
+UUID = "0192f3c4-7a1b-4c2d-9e3f-0123456789ab"
+
+
+@pytest.fixture
+def apm(ingestor, reset_errorgap):
+    errorgap.init(
+        endpoint=ingestor.endpoint,
+        project_slug="demo",
+        async_=False,
+        capture_globals=False,
+        apm_enabled=True,
+    )
+    return ingestor
+
+
+def _by_resource(ingestor, resource):
+    return [r.body for r in ingestor.requests if r.path.endswith("/" + resource)]
+
+
+def test_browser_trace_id_accepts_only_uuids():
+    assert browser_trace_id(" 0192F3C4-7A1B-4C2D-9E3F-0123456789AB ") == UUID
+    assert browser_trace_id(UUID.encode()) == UUID
+    assert browser_trace_id("not-a-uuid") is None
+    assert browser_trace_id(UUID + "0") is None
+    assert browser_trace_id(None) is None
+
+
+def test_track_job_links_errors_and_records_spans(apm):
+    with errorgap.track_job("ReceiptJob", queue="mailers") as txn:
+        txn.spans.database("SELECT * FROM receipts WHERE id = 7", 3.5)
+        errorgap.notify(RuntimeError("smtp down"))
+        seen = current_transaction_id()
+    assert current_transaction_id() is None
+
+    [job] = _by_resource(apm, "transactions")
+    assert job["kind"] == "job"
+    assert job["job_class"] == "ReceiptJob"
+    assert job["queue"] == "mailers"
+    assert job["id"] == seen
+    assert job["spans"][0]["sql"] == "SELECT * FROM receipts WHERE id = ?"
+    [notice] = _by_resource(apm, "notices")
+    assert notice["context"]["transaction_id"] == seen
+
+
+def test_track_transaction_records_failure_and_trace(apm):
+    with pytest.raises(ValueError):
+        with errorgap.track_transaction("GET", "/orders/{id}", "/orders/7", trace_id=UUID.upper()):
+            raise ValueError("boom")
+    [txn] = _by_resource(apm, "transactions")
+    assert txn["status_code"] == 500
+    assert txn["trace_id"] == UUID
+    assert txn["id"] != txn["trace_id"]
+
+
+def test_transactions_are_dropped_unless_apm_is_enabled(ingestor, reset_errorgap):
+    errorgap.init(endpoint=ingestor.endpoint, project_slug="demo", async_=False, capture_globals=False)
+    with errorgap.track_transaction("GET", "/", "/"):
+        pass
+    assert _by_resource(ingestor, "transactions") == []
+
+
+def test_threads_never_share_a_transaction_id(apm):
+    seen = {}
+
+    def work(n):
+        with errorgap.track_job("Job%d" % n):
+            seen[n] = current_transaction_id()
+
+    threads = [threading.Thread(target=work, args=(n,)) for n in range(3)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+    assert len(set(seen.values())) == 3
+
+
+def test_wsgi_middleware_records_the_request(apm):
+    def app(environ, start_response):
+        environ[ROUTE_KEY] = "/orders/<id>"
+        errorgap.notify(RuntimeError("card declined"))
+        start_response("201 Created", [("Content-Type", "text/plain")])
+        return [b"ok"]
+
+    wrapped = ErrorgapMiddleware(app)
+    environ = {"REQUEST_METHOD": "POST", "PATH_INFO": "/orders/7", "HTTP_X_ERRORGAP_TRACE": UUID}
+    body = wrapped(environ, lambda status, headers: None)
+    assert b"".join(body) == b"ok"
+    body.close()
+
+    [txn] = _by_resource(apm, "transactions")
+    assert txn["method"] == "POST"
+    assert txn["path"] == "/orders/<id>"
+    assert txn["path_raw"] == "/orders/7"
+    assert txn["status_code"] == 201
+    assert txn["trace_id"] == UUID
+    [notice] = _by_resource(apm, "notices")
+    assert notice["context"]["transaction_id"] == txn["id"]
+    assert current_transaction_id() is None
+
+
+def test_wsgi_middleware_records_a_raising_app(apm):
+    def app(environ, start_response):
+        raise RuntimeError("kaboom")
+
+    with pytest.raises(RuntimeError):
+        ErrorgapMiddleware(app)({"REQUEST_METHOD": "GET", "PATH_INFO": "/x", "HTTP_X_ERRORGAP_TRACE": "nope"}, None)
+    [txn] = _by_resource(apm, "transactions")
+    assert txn["status_code"] == 500
+    assert txn["path"] == "/x"
+    assert "trace_id" not in txn

errorgap-0.2.0/tests/test_backtrace.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import os
+
+from errorgap.backtrace import (
+    MAX_SOURCE_LINE_CHARS,
+    SOURCE_CONTEXT_RADIUS,
+    _source_excerpt,
+    parse_backtrace,
+)
+
+
+def _raise_and_capture() -> Exception:
+    try:
+        raise ValueError("boom")
+    except Exception as exc:
+        return exc
+
+
+def test_parses_frames():
+    exc = _raise_and_capture()
+    frames = parse_backtrace(exc, os.getcwd())
+    assert len(frames) >= 1
+    top = frames[0]
+    assert top["function"] == "_raise_and_capture"
+    assert top["line"] > 0
+    assert "test_backtrace" in (top["file"] or "")
+    assert top["index"] == 0
+
+
+def test_in_app_marks_files_under_root():
+    exc = _raise_and_capture()
+    frames = parse_backtrace(exc, os.getcwd())
+    assert frames[0]["in_app"] is True
+
+
+def test_empty_for_exception_without_traceback():
+    exc = ValueError("no tb")
+    assert parse_backtrace(exc, os.getcwd()) == []
+
+
+def _inner_failure() -> None:
+    raise RuntimeError("inner boom")
+
+
+def _outer_failure() -> None:
+    _inner_failure()
+
+
+def test_innermost_frame_is_first_and_includes_source_context():
+    try:
+        _outer_failure()
+    except RuntimeError as exc:
+        frames = parse_backtrace(exc, os.getcwd())
+
+    assert frames[0]["function"] == "_inner_failure"
+    assert frames[1]["function"] == "_outer_failure"
+    source = frames[0]["source"]
+    target_offset = frames[0]["line"] - source["start_line"]
+    assert 'raise RuntimeError("inner boom")' in source["lines"][target_offset]
+
+
+def test_attaches_source_to_readable_vendor_frames():
+    exc = _raise_and_capture()
+    frames = parse_backtrace(exc, "/path/that/does/not/contain/tests")
+    assert frames[0]["in_app"] is False
+    source = frames[0]["source"]
+    target_offset = frames[0]["line"] - source["start_line"]
+    assert 'raise ValueError("boom")' in source["lines"][target_offset]
+
+
+def test_source_excerpt_is_bounded(tmp_path):
+    source_file = tmp_path / "app.py"
+    source_file.write_text("\n".join(["x" * 500] * 30), encoding="utf-8")
+
+    source = _source_excerpt(str(source_file), 15)
+
+    assert source is not None
+    assert source["start_line"] == 15 - SOURCE_CONTEXT_RADIUS
+    assert len(source["lines"]) == SOURCE_CONTEXT_RADIUS * 2 + 1
+    assert all(len(line) == MAX_SOURCE_LINE_CHARS for line in source["lines"])

errorgap-0.2.0/tests/test_flask.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import pytest
+
+flask = pytest.importorskip("flask")
+
+from flask import Flask
+
+import errorgap
+from errorgap.flask import init_app
+
+
+def test_flask_signal_reports_exception(ingestor, reset_errorgap):
+    errorgap.init(
+        endpoint=ingestor.endpoint,
+        project_slug="demo",
+        api_key="flk_test",
+        async_=False,
+        capture_globals=False,
+    )
+
+    app = Flask(__name__)
+    init_app(app)
+
+    @app.route("/boom")
+    def boom():
+        raise RuntimeError("flask-boom")
+
+    client = app.test_client()
+    response = client.get("/boom?x=1")
+    assert response.status_code == 500
+
+    errorgap.flush(timeout=5)
+    assert len(ingestor.requests) == 1
+    body = ingestor.requests[0].body
+    assert body["errors"][0]["type"] == "RuntimeError"
+    assert body["errors"][0]["message"] == "flask-boom"
+    assert body["context"]["action"] == "GET"
+
+
+def test_flask_requests_are_transactions_linked_to_their_errors(ingestor, reset_errorgap):
+    from errorgap.flask import spans
+
+    errorgap.init(
+        endpoint=ingestor.endpoint,
+        project_slug="demo",
+        async_=False,
+        capture_globals=False,
+        apm_enabled=True,
+    )
+
+    app = Flask(__name__)
+    init_app(app)
+
+    @app.route("/orders/<int:order_id>")
+    def order(order_id):
+        spans().database("SELECT * FROM orders WHERE id = %d" % order_id, 1.5)
+        raise RuntimeError("flask-boom")
+
+    response = app.test_client().get(
+        "/orders/7", headers={"x-errorgap-trace": "0192F3C4-7A1B-4C2D-9E3F-0123456789AB"}
+    )
+    assert response.status_code == 500
+    response.close()  # WSGI servers close the response; the transaction is recorded then
+
+    errorgap.flush(timeout=5)
+    [txn] = [r.body for r in ingestor.requests if r.path.endswith("/transactions")]
+    [notice] = [r.body for r in ingestor.requests if r.path.endswith("/notices")]
+    assert txn["path"] == "/orders/<int:order_id>"
+    assert txn["path_raw"] == "/orders/7"
+    assert txn["status_code"] == 500
+    assert txn["trace_id"] == "0192f3c4-7a1b-4c2d-9e3f-0123456789ab"
+    assert txn["spans"][0]["sql"] == "SELECT * FROM orders WHERE id = ?"
+    assert notice["context"]["transaction_id"] == txn["id"]

errorgap-0.1.0/src/errorgap/backtrace.py

@@ -1,45 +0,0 @@
-from __future__ import annotations
-
-import os
-import traceback
-from typing import Any, Dict, List, Optional
-
-
-def parse_backtrace(exc: BaseException, root_directory: str) -> List[Dict[str, Any]]:
-    frames: List[Dict[str, Any]] = []
-    tb_frames = traceback.extract_tb(exc.__traceback__)
-
-    for index, frame in enumerate(tb_frames):
-        file = frame.filename
-        frames.append(
-            {
-                "file": _relative_file(file, root_directory),
-                "line": frame.lineno,
-                "function": frame.name,
-                "in_app": _is_in_app(file, root_directory),
-                "index": index,
-            }
-        )
-
-    return frames
-
-
-def _relative_file(file: Optional[str], root: str) -> Optional[str]:
-    if not file:
-        return file
-    if not root:
-        return file
-    normalized = root if root.endswith(os.sep) else root + os.sep
-    if file.startswith(normalized):
-        return file[len(normalized):]
-    return file
-
-
-def _is_in_app(file: Optional[str], root: str) -> bool:
-    if not file or not root:
-        return False
-    if "site-packages" in file:
-        return False
-    if file.startswith("<"):
-        return False
-    return file.startswith(root)

errorgap-0.1.0/src/errorgap/version.py

@@ -1 +0,0 @@
-VERSION = "0.1.0"

errorgap-0.1.0/tests/test_backtrace.py

@@ -1,34 +0,0 @@
-from __future__ import annotations
-
-import os
-
-from errorgap.backtrace import parse_backtrace
-
-
-def _raise_and_capture() -> Exception:
-    try:
-        raise ValueError("boom")
-    except Exception as exc:
-        return exc
-
-
-def test_parses_frames():
-    exc = _raise_and_capture()
-    frames = parse_backtrace(exc, os.getcwd())
-    assert len(frames) >= 1
-    top = frames[0]
-    assert top["function"] == "_raise_and_capture"
-    assert top["line"] > 0
-    assert "test_backtrace" in (top["file"] or "")
-    assert top["index"] == 0
-
-
-def test_in_app_marks_files_under_root():
-    exc = _raise_and_capture()
-    frames = parse_backtrace(exc, os.getcwd())
-    assert frames[0]["in_app"] is True
-
-
-def test_empty_for_exception_without_traceback():
-    exc = ValueError("no tb")
-    assert parse_backtrace(exc, os.getcwd()) == []

errorgap-0.1.0/tests/test_flask.py

@@ -1,38 +0,0 @@
-from __future__ import annotations
-
-import pytest
-
-flask = pytest.importorskip("flask")
-
-from flask import Flask
-
-import errorgap
-from errorgap.flask import init_app
-
-
-def test_flask_signal_reports_exception(ingestor, reset_errorgap):
-    errorgap.init(
-        endpoint=ingestor.endpoint,
-        project_slug="demo",
-        api_key="flk_test",
-        async_=False,
-        capture_globals=False,
-    )
-
-    app = Flask(__name__)
-    init_app(app)
-
-    @app.route("/boom")
-    def boom():
-        raise RuntimeError("flask-boom")
-
-    client = app.test_client()
-    response = client.get("/boom?x=1")
-    assert response.status_code == 500
-
-    errorgap.flush(timeout=5)
-    assert len(ingestor.requests) == 1
-    body = ingestor.requests[0].body
-    assert body["errors"][0]["type"] == "RuntimeError"
-    assert body["errors"][0]["message"] == "flask-boom"
-    assert body["context"]["action"] == "GET"