watchdock-errors 0.2.3__tar.gz → 0.3.0__tar.gz

{watchdock_errors-0.2.3/src/watchdock_errors.egg-info → watchdock_errors-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: watchdock-errors
-Version: 0.2.3
+Version: 0.3.0
 Summary: Application error tracking SDK for the Watchdock platform
 License: MIT
 Keywords: error-tracking,observability,watchdock
@@ -88,8 +88,30 @@ watchdock_errors.capture_exception(exc)
 
 # Capture a message
 watchdock_errors.capture_message("Stripe webhook signature invalid")
+
+# Capture a message with a custom level
+watchdock_errors.capture_message("Queue depth high", level="warning")
 ```
 
+### Event levels
+
+Every event carries a `level`. Exceptions default to `"error"`; messages default to `"info"` unless you pass `level` explicitly to `capture_message`.
+
+## Correlating with nginx requests
+
+If your app is behind nginx and you've added `$request_id` to your access log format (see the [nginx log collection docs](https://watchdock.cc/docs/nginx-log-collection)) and forwarded it to your app via `proxy_set_header X-Request-Id $request_id;`, this SDK automatically reads that header off every captured request and attaches it as `trace_id` — no code changes needed. This lets WatchDock link a failed request in your nginx access logs directly to the exception it produced.
+
+You can also pass `trace_id` explicitly, which takes priority over the auto-extracted value:
+
+```python
+watchdock_errors.capture_exception(exc, trace_id=my_trace_id)
+watchdock_errors.capture_message("Queue depth high", level="warning", trace_id=my_trace_id)
+```
+
+## SDK initialization
+
+When `init()` is called, the SDK sends a one-time, fire-and-forget ping to the platform (with the SDK version and environment) to register that it started up. This never blocks application startup and any failure is silently ignored.
+
 ## PII scrubbing
 
 By default, `Authorization`, `Cookie`, and `X-Api-Key` headers are stripped and the request body is not sent. Set `send_pii=True` to disable scrubbing.

{watchdock_errors-0.2.3 → watchdock_errors-0.3.0}/README.md

@@ -68,8 +68,30 @@ watchdock_errors.capture_exception(exc)
 
 # Capture a message
 watchdock_errors.capture_message("Stripe webhook signature invalid")
+
+# Capture a message with a custom level
+watchdock_errors.capture_message("Queue depth high", level="warning")
 ```
 
+### Event levels
+
+Every event carries a `level`. Exceptions default to `"error"`; messages default to `"info"` unless you pass `level` explicitly to `capture_message`.
+
+## Correlating with nginx requests
+
+If your app is behind nginx and you've added `$request_id` to your access log format (see the [nginx log collection docs](https://watchdock.cc/docs/nginx-log-collection)) and forwarded it to your app via `proxy_set_header X-Request-Id $request_id;`, this SDK automatically reads that header off every captured request and attaches it as `trace_id` — no code changes needed. This lets WatchDock link a failed request in your nginx access logs directly to the exception it produced.
+
+You can also pass `trace_id` explicitly, which takes priority over the auto-extracted value:
+
+```python
+watchdock_errors.capture_exception(exc, trace_id=my_trace_id)
+watchdock_errors.capture_message("Queue depth high", level="warning", trace_id=my_trace_id)
+```
+
+## SDK initialization
+
+When `init()` is called, the SDK sends a one-time, fire-and-forget ping to the platform (with the SDK version and environment) to register that it started up. This never blocks application startup and any failure is silently ignored.
+
 ## PII scrubbing
 
 By default, `Authorization`, `Cookie`, and `X-Api-Key` headers are stripped and the request body is not sent. Set `send_pii=True` to disable scrubbing.

{watchdock_errors-0.2.3 → watchdock_errors-0.3.0}/src/watchdock_errors/__init__.py

@@ -77,13 +77,21 @@ def init(
     _send_init_ping(_config)
 
 
-def capture_exception(exc: BaseException | None = None, request_context: dict | None = None) -> None:
+def capture_exception(
+    exc: BaseException | None = None,
+    request_context: dict | None = None,
+    trace_id: str | None = None,
+) -> None:
     """
     Capture an exception and send it to Watchdock.
 
     If ``exc`` is None the current exception from ``sys.exc_info()`` is used.
     Safe to call outside of an except block — does nothing if there is no
     active exception and ``exc`` is not provided.
+
+    ``trace_id`` correlates this event with the originating nginx request
+    (e.g. ``X-Request-Id``) and takes priority over any value auto-extracted
+    from ``request_context``'s headers if both are present.
     """
     if _client is None or _config is None:
         return
@@ -97,7 +105,7 @@ def capture_exception(exc: BaseException | None = None, request_context: dict |
 
     from .event import build_event
 
-    event = build_event(exc, _config, request_context=request_context)
+    event = build_event(exc, _config, request_context=request_context, trace_id=trace_id)
     if event is not None:
         logger.info("watchdock_errors: capturing exception — %s: %s", type(exc).__name__, exc)
         _client.capture(event)
@@ -105,14 +113,27 @@ def capture_exception(exc: BaseException | None = None, request_context: dict |
         logger.debug("watchdock_errors: event dropped by before_send hook")
 
 
-def capture_message(message: str, level: str = "info", request_context: dict | None = None) -> None:
-    """Capture an arbitrary message string and send it to Watchdock."""
+def capture_message(
+    message: str,
+    level: str = "info",
+    request_context: dict | None = None,
+    trace_id: str | None = None,
+) -> None:
+    """
+    Capture an arbitrary message string and send it to Watchdock.
+
+    ``trace_id`` correlates this event with the originating nginx request
+    (e.g. ``X-Request-Id``) and takes priority over any value auto-extracted
+    from ``request_context``'s headers if both are present.
+    """
     if _client is None or _config is None:
         return
 
     from .event import build_event
 
-    event = build_event(None, _config, message=message, level=level, request_context=request_context)
+    event = build_event(
+        None, _config, message=message, level=level, request_context=request_context, trace_id=trace_id
+    )
     if event is not None:
         logger.info("watchdock_errors: capturing message — %s", message)
         _client.capture(event)

{watchdock_errors-0.2.3 → watchdock_errors-0.3.0}/src/watchdock_errors/event.py

@@ -4,7 +4,7 @@ import datetime
 import logging
 
 from .config import SDKConfig
-from .utils import extract_stacktrace, get_server_info
+from .utils import extract_stacktrace, extract_trace_id, get_server_info
 
 logger = logging.getLogger("watchdock_errors")
 
@@ -15,6 +15,7 @@ def build_event(
     message: str | None = None,
     level: str | None = None,
     request_context: dict | None = None,
+    trace_id: str | None = None,
 ) -> dict | None:
     """
     Build a Watchdock error event payload.
@@ -61,6 +62,12 @@ def build_event(
     if config.server_name:
         event["server"]["server_name"] = config.server_name
 
+    resolved_trace_id = trace_id or (
+        extract_trace_id(request_context.get("request", {}).get("headers", {})) if request_context else None
+    )
+    if resolved_trace_id:
+        event["trace_id"] = resolved_trace_id
+
     if request_context:
         if config.send_pii:
             event["request"] = request_context.get("request", {})

watchdock_errors-0.3.0/src/watchdock_errors/utils.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import linecache
+import platform
+import socket
+import traceback
+
+
+#: Number of source lines captured on each side of the failing line. Matches the
+#: window the backend uses when it falls back to enriching frames itself, so a
+#: frame looks the same whether the context came from here or from the server.
+CONTEXT_LINES = 2
+
+
+def _source_context(filename: str, lineno: int) -> tuple[list[str], list[str]]:
+    """Read the source lines immediately before and after ``lineno``.
+
+    Returns ``(pre_context, post_context)``. We do this in the SDK, on the box
+    where the code actually runs, because the source is here — the backend can
+    only guess at it from its own filesystem, which is the wrong machine for any
+    real app. Out-of-range lines come back as empty strings so the two lists are
+    always the same length regardless of where in the file the error landed.
+    """
+    if not filename or not lineno:
+        return [], []
+
+    pre = [
+        linecache.getline(filename, i).rstrip("\n")
+        for i in range(max(1, lineno - CONTEXT_LINES), lineno)
+    ]
+    post = [
+        linecache.getline(filename, i).rstrip("\n")
+        for i in range(lineno + 1, lineno + CONTEXT_LINES + 1)
+    ]
+    return pre, post
+
+
+def extract_stacktrace(exc: BaseException) -> list[dict]:
+    """Extract structured stack frames from an exception."""
+    tb = exc.__traceback__
+    if tb is None:
+        return []
+
+    frames = []
+    for frame_summary in traceback.extract_tb(tb):
+        context_line = linecache.getline(frame_summary.filename, frame_summary.lineno).strip()
+        pre_context, post_context = _source_context(frame_summary.filename, frame_summary.lineno)
+        frames.append(
+            {
+                "filename": frame_summary.filename,
+                "function": frame_summary.name,
+                "lineno": frame_summary.lineno,
+                "context_line": context_line,
+                "pre_context": pre_context,
+                "post_context": post_context,
+            }
+        )
+    return frames
+
+
+def get_server_info() -> dict:
+    return {
+        "hostname": socket.gethostname(),
+        "python_version": platform.python_version(),
+    }
+
+
+def extract_trace_id(headers: dict | None) -> str | None:
+    """
+    Pull a correlation ID off incoming request headers so this event can be
+    linked back to the nginx access/error log line for the same request.
+
+    Prefers ``X-Request-Id`` (nginx's built-in ``$request_id``, zero extra
+    modules required) and falls back to the trace-id segment of a W3C
+    ``traceparent`` header if present.
+    """
+    if not headers:
+        return None
+
+    normalized = {str(k).lower(): v for k, v in headers.items()}
+
+    request_id = normalized.get("x-request-id")
+    if request_id:
+        return request_id
+
+    traceparent = normalized.get("traceparent")
+    if traceparent:
+        parts = traceparent.split("-")
+        if len(parts) >= 2 and parts[1]:
+            return parts[1]
+
+    return None

{watchdock_errors-0.2.3 → watchdock_errors-0.3.0/src/watchdock_errors.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: watchdock-errors
-Version: 0.2.3
+Version: 0.3.0
 Summary: Application error tracking SDK for the Watchdock platform
 License: MIT
 Keywords: error-tracking,observability,watchdock
@@ -88,8 +88,30 @@ watchdock_errors.capture_exception(exc)
 
 # Capture a message
 watchdock_errors.capture_message("Stripe webhook signature invalid")
+
+# Capture a message with a custom level
+watchdock_errors.capture_message("Queue depth high", level="warning")
 ```
 
+### Event levels
+
+Every event carries a `level`. Exceptions default to `"error"`; messages default to `"info"` unless you pass `level` explicitly to `capture_message`.
+
+## Correlating with nginx requests
+
+If your app is behind nginx and you've added `$request_id` to your access log format (see the [nginx log collection docs](https://watchdock.cc/docs/nginx-log-collection)) and forwarded it to your app via `proxy_set_header X-Request-Id $request_id;`, this SDK automatically reads that header off every captured request and attaches it as `trace_id` — no code changes needed. This lets WatchDock link a failed request in your nginx access logs directly to the exception it produced.
+
+You can also pass `trace_id` explicitly, which takes priority over the auto-extracted value:
+
+```python
+watchdock_errors.capture_exception(exc, trace_id=my_trace_id)
+watchdock_errors.capture_message("Queue depth high", level="warning", trace_id=my_trace_id)
+```
+
+## SDK initialization
+
+When `init()` is called, the SDK sends a one-time, fire-and-forget ping to the platform (with the SDK version and environment) to register that it started up. This never blocks application startup and any failure is silently ignored.
+
 ## PII scrubbing
 
 By default, `Authorization`, `Cookie`, and `X-Api-Key` headers are stripped and the request body is not sent. Set `send_pii=True` to disable scrubbing.

{watchdock_errors-0.2.3 → watchdock_errors-0.3.0}/src/watchdock_errors.egg-info/SOURCES.txt

@@ -19,4 +19,5 @@ src/watchdock_errors/integrations/__init__.py
 src/watchdock_errors/integrations/django.py
 src/watchdock_errors/integrations/fastapi.py
 tests/test_client.py
-tests/test_event.py
+tests/test_event.py
+tests/test_utils.py

{watchdock_errors-0.2.3 → watchdock_errors-0.3.0}/src/watchdock_errors.egg-info/scm_file_list.json

@@ -1,19 +1,20 @@
 {
   "files": [
+    ".gitignore",
     "README.md",
     "pyproject.toml",
-    ".gitignore",
-    "src/watchdock_errors/__init__.py",
+    "src/watchdock_errors/event.py",
+    "src/watchdock_errors/client.py",
     "src/watchdock_errors/config.py",
     "src/watchdock_errors/utils.py",
-    "src/watchdock_errors/client.py",
-    "src/watchdock_errors/event.py",
-    "src/watchdock_errors/integrations/__init__.py",
+    "src/watchdock_errors/__init__.py",
     "src/watchdock_errors/integrations/fastapi.py",
     "src/watchdock_errors/integrations/django.py",
-    "tests/test_client.py",
-    "tests/test_event.py",
+    "src/watchdock_errors/integrations/__init__.py",
+    ".github/workflows/ci.yml",
     ".github/workflows/release.yml",
-    ".github/workflows/ci.yml"
+    "tests/test_event.py",
+    "tests/test_client.py",
+    "tests/test_utils.py"
   ]
 }

watchdock_errors-0.3.0/src/watchdock_errors.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.3.0",
+  "distance": 0,
+  "node": "g711d547840b425c8a17c295e36cd0e731bdadbc4",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-22"
+}

{watchdock_errors-0.2.3 → watchdock_errors-0.3.0}/tests/test_event.py

@@ -94,3 +94,54 @@ def test_pii_headers_scrubbed_by_default(config):
 
     assert "Authorization" not in event["request"]["headers"]
     assert event["request"]["headers"]["Content-Type"] == "application/json"
+
+
+def test_trace_id_extracted_from_x_request_id_header(config):
+    req_ctx = {
+        "request": {
+            "method": "GET",
+            "url": "/checkout/",
+            "headers": {"X-Request-Id": "abc123"},
+        }
+    }
+
+    try:
+        raise ValueError("x")
+    except ValueError as exc:
+        event = build_event(exc, config, request_context=req_ctx)
+
+    assert event["trace_id"] == "abc123"
+
+
+def test_trace_id_falls_back_to_traceparent_header(config):
+    req_ctx = {
+        "request": {
+            "headers": {"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"},
+        }
+    }
+
+    event = build_event(None, config, message="hi", request_context=req_ctx)
+
+    assert event["trace_id"] == "4bf92f3577b34da6a3ce929d0e0e4736"
+
+
+def test_trace_id_absent_when_no_matching_header(config):
+    req_ctx = {"request": {"headers": {"Content-Type": "application/json"}}}
+
+    event = build_event(None, config, message="hi", request_context=req_ctx)
+
+    assert "trace_id" not in event
+
+
+def test_explicit_trace_id_wins_over_header_extraction(config):
+    req_ctx = {"request": {"headers": {"X-Request-Id": "from-header"}}}
+
+    event = build_event(None, config, message="hi", request_context=req_ctx, trace_id="explicit-id")
+
+    assert event["trace_id"] == "explicit-id"
+
+
+def test_explicit_trace_id_works_without_request_context(config):
+    event = build_event(None, config, message="hi", trace_id="explicit-id")
+
+    assert event["trace_id"] == "explicit-id"

watchdock_errors-0.3.0/tests/test_utils.py

@@ -0,0 +1,44 @@
+from watchdock_errors.utils import extract_stacktrace
+
+
+def _boom():
+    # This line and the two on either side are what the context capture should
+    # pick up. Keep the surrounding lines stable so the assertions below hold.
+    x = 1
+    raise ValueError("boom")  # <-- failing line
+    return x
+
+
+def test_extract_stacktrace_captures_source_context():
+    try:
+        _boom()
+    except ValueError as exc:
+        frames = extract_stacktrace(exc)
+
+    assert frames, "expected at least one frame"
+
+    # The frame for _boom is the one whose failing line raised.
+    boom_frame = next(f for f in frames if f["function"] == "_boom")
+
+    assert boom_frame["context_line"] == 'raise ValueError("boom")  # <-- failing line'
+    # Two lines before and two after, in order, with indentation preserved.
+    assert len(boom_frame["pre_context"]) == 2
+    assert len(boom_frame["post_context"]) == 2
+    # The line immediately before the raise is `x = 1` (indentation kept).
+    assert boom_frame["pre_context"][1] == "    x = 1"
+    # The line immediately after the raise is the return.
+    assert boom_frame["post_context"][0] == "    return x"
+
+
+def test_frames_always_have_context_keys():
+    try:
+        raise KeyError("missing")
+    except KeyError as exc:
+        frames = extract_stacktrace(exc)
+
+    for frame in frames:
+        assert "context_line" in frame
+        assert "pre_context" in frame
+        assert "post_context" in frame
+        assert isinstance(frame["pre_context"], list)
+        assert isinstance(frame["post_context"], list)

watchdock_errors-0.2.3/src/watchdock_errors/utils.py

@@ -1,33 +0,0 @@
-from __future__ import annotations
-
-import linecache
-import platform
-import socket
-import traceback
-
-
-def extract_stacktrace(exc: BaseException) -> list[dict]:
-    """Extract structured stack frames from an exception."""
-    tb = exc.__traceback__
-    if tb is None:
-        return []
-
-    frames = []
-    for frame_summary in traceback.extract_tb(tb):
-        context_line = linecache.getline(frame_summary.filename, frame_summary.lineno).strip()
-        frames.append(
-            {
-                "filename": frame_summary.filename,
-                "function": frame_summary.name,
-                "lineno": frame_summary.lineno,
-                "context_line": context_line,
-            }
-        )
-    return frames
-
-
-def get_server_info() -> dict:
-    return {
-        "hostname": socket.gethostname(),
-        "python_version": platform.python_version(),
-    }

watchdock_errors-0.2.3/src/watchdock_errors.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.2.3",
-  "distance": 0,
-  "node": "g552866cfdf269b7f1dd8cf126bc25eb5623849cb",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-07-01"
-}