watchdock-errors 0.2.2__tar.gz → 0.2.4__tar.gz

{watchdock_errors-0.2.2/src/watchdock_errors.egg-info → watchdock_errors-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: watchdock-errors
-Version: 0.2.2
+Version: 0.2.4
 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.2 → watchdock_errors-0.2.4}/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.2 → watchdock_errors-0.2.4}/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, 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, 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.2 → watchdock_errors-0.2.4}/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")
 
@@ -13,7 +13,9 @@ def build_event(
     exc: BaseException | None,
     config: SDKConfig,
     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.
@@ -22,6 +24,9 @@ def build_event(
     """
     now = datetime.datetime.now(datetime.timezone.utc).isoformat()
 
+    if level is None:
+        level = "error" if exc is not None else "info"
+
     if exc is not None:
         exception_data = {
             "type": type(exc).__name__,
@@ -41,6 +46,7 @@ def build_event(
         "project_key": config.api_key,
         "timestamp": now,
         "environment": config.environment,
+        "level": level,
         "title": title,
         "sdk": {
             "name": config.sdk_name,
@@ -56,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.2.2 → watchdock_errors-0.2.4}/src/watchdock_errors/utils.py

@@ -31,3 +31,30 @@ def get_server_info() -> dict:
         "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.2 → watchdock_errors-0.2.4/src/watchdock_errors.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: watchdock-errors
-Version: 0.2.2
+Version: 0.2.4
 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.4/src/watchdock_errors.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.2.4",
+  "distance": 0,
+  "node": "g8207b34ddbb2d7b5c9fe4f4df0960161f5b11709",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-11"
+}

{watchdock_errors-0.2.2 → watchdock_errors-0.2.4}/tests/test_event.py

@@ -30,6 +30,24 @@ def test_build_event_from_message(config):
     assert event is not None
     assert event["exception"]["message"] == "Stripe webhook failed"
     assert event["exception"]["type"] == "Message"
+    assert event["level"] == "info"
+
+
+def test_build_event_level_override(config):
+    event = build_event(None, config, message="disk almost full", level="warning")
+
+    assert event is not None
+    assert event["level"] == "warning"
+
+
+def test_build_event_exception_default_level(config):
+    try:
+        raise ValueError("bad")
+    except ValueError as exc:
+        event = build_event(exc, config)
+
+    assert event is not None
+    assert event["level"] == "error"
 
 
 def test_before_send_can_drop_event(config):
@@ -76,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.2.2/src/watchdock_errors.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.2.2",
-  "distance": 0,
-  "node": "gefdacc6610345ad37dfcfd533d1a97715e23d6bd",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-06-29"
-}