devbench 0.1.0__tar.gz

devbench-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RedpointRack LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devbench-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: devbench
+Version: 0.1.0
+Summary: Dev Bench server SDK for Python: errors, who was affected, and the server log lines of a failing request, for Django, FastAPI, Flask and Celery.
+Author: Dev Bench
+License-Expression: MIT
+Project-URL: Homepage, https://developerbench.com
+Project-URL: Source, https://github.com/pasperry/devbench-sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Framework :: Celery
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Dev Bench for Python
+
+Errors, who they hit, and the server log lines of the request that failed,
+from Django, FastAPI, Flask and Celery to Dev Bench. Zero runtime
+dependencies (the standard library only); Python 3.9+.
+
+## Install
+
+```sh
+pip install devbench
+```
+
+Set **one** value in the app's environment, the DSN `adt dsn create`
+printed for this environment:
+
+```sh
+DEVBENCH_DSN=https://<public>:<secret>@adt-ingest.onrender.com
+```
+
+Then add one line where your framework wants it.
+
+### Django
+
+In `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    "devbench.django",
+    # ...
+]
+```
+
+That is the whole install: at startup it puts its middleware first in
+`MIDDLEWARE` (not again if you list `devbench.django.middleware.DevbenchMiddleware`
+yourself), reports what Django answers with a 500, keeps log lines, and,
+when Celery is loaded, installs the Celery hooks. WSGI and ASGI. Django 4.2+.
+
+### FastAPI (and Starlette)
+
+```python
+from fastapi import FastAPI
+from devbench.fastapi import DevbenchMiddleware
+
+app = FastAPI()
+app.add_middleware(DevbenchMiddleware)
+```
+
+Async and sync endpoints alike. Any other ASGI app: `devbench.asgi.DevbenchMiddleware`.
+
+### Flask
+
+```python
+from flask import Flask
+from devbench.flask import Devbench
+
+app = Flask(__name__)
+Devbench(app)          # or: Devbench().init_app(app)
+```
+
+Any other WSGI app: `application = devbench.wsgi.DevbenchMiddleware(application)`.
+
+### Celery
+
+Under Django there is nothing to add. Otherwise, where your Celery app is
+created:
+
+```python
+import devbench.celery
+devbench.celery.install()
+```
+
+### Check it
+
+```sh
+python -m devbench test             # Django: python manage.py devbench_test
+# Dev Bench: checking the DSN against https://adt-ingest.onrender.com (service "acme_shop")
+#   HTTP 200: accepted - tenant "acme", environment "production". Nothing was recorded; real errors will appear as issues.
+```
+
+It prints the HTTP result, or says plainly what is wrong (`DEVBENCH_DSN is
+not set`, `HTTP 401: the key in DEVBENCH_DSN was rejected`, `could not reach
+…`) and exits non-zero. It records nothing.
+
+## Configuration
+
+All optional except the DSN.
+
+| Variable | Default | |
+|---|---|---|
+| `DEVBENCH_DSN` | — (falls back to `ADT_DSN`) | `https://<public>:<secret>@<host>[:port]` from `adt dsn create`. The server authenticates with the secret. Plain `http://` is accepted only for localhost. Unset: nothing is sent (there is no sidecar mode). |
+| `DEVBENCH_SERVICE` | Django: the project (`acme_shop` from `acme_shop.settings`); Flask: the app's import name; else `app`; **`<that>-celery` in a Celery worker** | Groups this app's issues. Set it and it wins everywhere. |
+| `DEVBENCH_RELEASE` | the first found of: a `REVISION` file in the app root (Django's `BASE_DIR`, else the working directory), `HEROKU_SLUG_COMMIT`, `KAMAL_VERSION`, `GITHUB_SHA`, `GIT_SHA`, `SOURCE_VERSION`, `RENDER_GIT_COMMIT`; else empty | Which deploy an occurrence came from. |
+| `DEVBENCH_ENABLED` | on | `false` turns everything off: no hooks, no headers, nothing sent. |
+
+Or from code, before the first report:
+
+```python
+import devbench
+devbench.configure(dsn=secrets["devbench_dsn"], service="billing-api")
+```
+
+A DSN that does not parse logs one `[devbench]` warning (on the `devbench`
+logger) and reports nothing; it never raises into the app. Neither key is
+ever printed.
+
+## What is captured automatically
+
+| What | How | `context` |
+|---|---|---|
+| A Django view or middleware error answered with a 500 | `got_request_exception` | `request` |
+| A Flask view error answered with a 500 | `got_request_exception` | `request` |
+| An exception escaping a FastAPI/Starlette app (still answered 500 by Starlette, and your exception handlers still run) | the ASGI middleware reports, then re-raises the same object | `request` |
+| A failed Celery task (the last attempt; `self.retry()` is not a failure) | `task_failure` | `job` |
+
+Each report carries the class (`module.QualName`; builtins plainly, e.g.
+`KeyError`), the message (≤ 2,000 characters), where it surfaced (the view,
+endpoint or task: `shop.views.checkout`, `acme.charge`), up to 50 stack
+frames (innermost first, paths relative to the app root), the trace, and
+the user.
+
+- **Once per exception.** An error that passes several hooks is reported
+  once.
+- **Status codes are not failures.** Django's `Http404`, `PermissionDenied`,
+  `BadRequest`, `SuspiciousOperation`; werkzeug and Starlette
+  `HTTPException`s; Celery's `Retry`, `Ignore`, `Reject`; and anything that
+  is not an `Exception` (`SystemExit`, `KeyboardInterrupt`,
+  `asyncio.CancelledError`) are never reported. Add your own by name:
+
+  ```python
+  devbench.ignore_exceptions().append("myapp.errors.NotAuthorized")
+  ```
+
+- **Never in the way.** No hook raises into the app; a failure while
+  reporting is dropped, and the application's own exception always comes
+  out unchanged.
+
+## What is sent, and when
+
+- Each report is **fingerprinted and counted in the process** (class,
+  templated message and in-app frames; the same algorithm as every other
+  Dev Bench SDK). Repeats cost a counter increment.
+- **Once a minute** a background thread sends the counts (fingerprint, how
+  many, first/last seen, up to 20 affected users each) in one small request.
+  Nothing is sent for a quiet minute (except a small poll while the process
+  holds log lines, below), and what is left is sent when the process exits
+  (waiting at most 2 seconds; a Celery prefork child flushes at shutdown).
+- **Detail only on request.** When Dev Bench sees a fingerprint for the
+  first time it asks for evidence, and the SDK uploads the stack and one
+  example message, **templated and scrubbed first** (emails, numbers, quoted
+  values, tokens, card numbers, credentials and two-word names are removed).
+  Who was affected never goes into evidence.
+- **Never harms the app.** No network I/O on a request thread; 5-second
+  timeouts on the background thread, one retry, then the data is dropped;
+  memory is bounded (512 distinct problems per minute, the rest only
+  counted). Safe under forking servers (gunicorn, uWSGI, Celery prefork):
+  each process reports on its own.
+
+## Server log lines
+
+Triage reads the server's log lines for the user action that failed. The
+SDK keeps them itself, no sidecar:
+
+- **What:** every record that reaches the root logger's handlers while a
+  request or task carries a trace (`x-adt-trace` from the browser sensor; a
+  Celery task inherits the trace of the request that enqueued it). It sees
+  exactly what your logging configuration already lets through: it never
+  turns on a level you have off, writes nothing anywhere, and leaves your
+  handlers unchanged. A logger with `propagate = False` is not seen. An
+  exception's traceback is held one line each. Untraced records are not
+  kept.
+- **Bounded:** per process, the newest 10,000 lines or 4 MiB, nothing older
+  than 15 minutes, 4 KiB per line. A logging call never waits on I/O and
+  never raises because of this.
+- **Sent only when asked:** when Dev Bench asks for a trace, the flush
+  thread sends that trace's lines from this process (the newest ≤ 200 lines
+  / 64 KiB), **redacted first** with the same strict rules as evidence, plus
+  any redaction rules Dev Bench has learned for your app.
+- **Several processes:** each gunicorn worker and Celery process keeps and
+  answers for its own lines (a task's lines are in the worker, under the
+  trace of the request that enqueued it); Dev Bench assembles them.
+
+A plain WSGI/ASGI app without one of the integrations: `devbench.capture_logs()`.
+
+## Who was affected
+
+Set it once per request, after your authentication has run (a middleware
+after Django's `AuthenticationMiddleware`, a FastAPI dependency, a Flask
+`before_request`):
+
+```python
+devbench.set_user(email=request.user.email, account=request.user.account_id)
+```
+
+- `email` is trimmed and lowercased; `account` is your own tenant/customer
+  id, sent as a string. Both optional, each truncated to 255 characters.
+- It is sent in its own field with the counts, never inside a message or
+  evidence.
+- It ends with the request (a Celery task: with the task), so the next
+  request on the same thread never inherits it.
+
+## Reporting what you caught
+
+An exception you caught but want seen, like Sentry's `capture_exception`:
+
+```python
+except requests.RequestException as e:
+    devbench.capture_exception(e, symbol="billing.sync")
+    retry_later()
+```
+
+A failure you handled and turned into a normal response, the case this
+product exists for:
+
+```python
+except IntegrityError as e:
+    devbench.report_handled(e, symbol="customers.views.update", reason="uniqueness")
+    return JsonResponse({"ok": True})   # <- the user is about to be told this worked
+```
+
+`report_handled` also marks the response with `x-adt-handled: <count>` (and
+lists it in `Access-Control-Expose-Headers`, appending to what is there).
+The browser already knows whether the user was shown an error; this is the
+one fact it cannot know on its own. The header carries a count and nothing
+else, and it is added even when reporting is down.
+
+## Trace propagation
+
+The correlation id the browser sent (`x-adt-trace`) is `devbench.current_trace()`
+for the duration of the request. Forward it on outbound calls to other
+instrumented services:
+
+```python
+requests.post(url, json=body, headers=devbench.trace_headers())
+```
+
+## Not in this release
+
+- No sidecar transport: without a DSN nothing is sent.
+- `devbench.track` (custom events) and the chat widget's signed identity
+  are in the Ruby and Go SDKs; they come to Python later.

devbench-0.1.0/README.md

@@ -0,0 +1,240 @@
+# Dev Bench for Python
+
+Errors, who they hit, and the server log lines of the request that failed,
+from Django, FastAPI, Flask and Celery to Dev Bench. Zero runtime
+dependencies (the standard library only); Python 3.9+.
+
+## Install
+
+```sh
+pip install devbench
+```
+
+Set **one** value in the app's environment, the DSN `adt dsn create`
+printed for this environment:
+
+```sh
+DEVBENCH_DSN=https://<public>:<secret>@adt-ingest.onrender.com
+```
+
+Then add one line where your framework wants it.
+
+### Django
+
+In `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    "devbench.django",
+    # ...
+]
+```
+
+That is the whole install: at startup it puts its middleware first in
+`MIDDLEWARE` (not again if you list `devbench.django.middleware.DevbenchMiddleware`
+yourself), reports what Django answers with a 500, keeps log lines, and,
+when Celery is loaded, installs the Celery hooks. WSGI and ASGI. Django 4.2+.
+
+### FastAPI (and Starlette)
+
+```python
+from fastapi import FastAPI
+from devbench.fastapi import DevbenchMiddleware
+
+app = FastAPI()
+app.add_middleware(DevbenchMiddleware)
+```
+
+Async and sync endpoints alike. Any other ASGI app: `devbench.asgi.DevbenchMiddleware`.
+
+### Flask
+
+```python
+from flask import Flask
+from devbench.flask import Devbench
+
+app = Flask(__name__)
+Devbench(app)          # or: Devbench().init_app(app)
+```
+
+Any other WSGI app: `application = devbench.wsgi.DevbenchMiddleware(application)`.
+
+### Celery
+
+Under Django there is nothing to add. Otherwise, where your Celery app is
+created:
+
+```python
+import devbench.celery
+devbench.celery.install()
+```
+
+### Check it
+
+```sh
+python -m devbench test             # Django: python manage.py devbench_test
+# Dev Bench: checking the DSN against https://adt-ingest.onrender.com (service "acme_shop")
+#   HTTP 200: accepted - tenant "acme", environment "production". Nothing was recorded; real errors will appear as issues.
+```
+
+It prints the HTTP result, or says plainly what is wrong (`DEVBENCH_DSN is
+not set`, `HTTP 401: the key in DEVBENCH_DSN was rejected`, `could not reach
+…`) and exits non-zero. It records nothing.
+
+## Configuration
+
+All optional except the DSN.
+
+| Variable | Default | |
+|---|---|---|
+| `DEVBENCH_DSN` | — (falls back to `ADT_DSN`) | `https://<public>:<secret>@<host>[:port]` from `adt dsn create`. The server authenticates with the secret. Plain `http://` is accepted only for localhost. Unset: nothing is sent (there is no sidecar mode). |
+| `DEVBENCH_SERVICE` | Django: the project (`acme_shop` from `acme_shop.settings`); Flask: the app's import name; else `app`; **`<that>-celery` in a Celery worker** | Groups this app's issues. Set it and it wins everywhere. |
+| `DEVBENCH_RELEASE` | the first found of: a `REVISION` file in the app root (Django's `BASE_DIR`, else the working directory), `HEROKU_SLUG_COMMIT`, `KAMAL_VERSION`, `GITHUB_SHA`, `GIT_SHA`, `SOURCE_VERSION`, `RENDER_GIT_COMMIT`; else empty | Which deploy an occurrence came from. |
+| `DEVBENCH_ENABLED` | on | `false` turns everything off: no hooks, no headers, nothing sent. |
+
+Or from code, before the first report:
+
+```python
+import devbench
+devbench.configure(dsn=secrets["devbench_dsn"], service="billing-api")
+```
+
+A DSN that does not parse logs one `[devbench]` warning (on the `devbench`
+logger) and reports nothing; it never raises into the app. Neither key is
+ever printed.
+
+## What is captured automatically
+
+| What | How | `context` |
+|---|---|---|
+| A Django view or middleware error answered with a 500 | `got_request_exception` | `request` |
+| A Flask view error answered with a 500 | `got_request_exception` | `request` |
+| An exception escaping a FastAPI/Starlette app (still answered 500 by Starlette, and your exception handlers still run) | the ASGI middleware reports, then re-raises the same object | `request` |
+| A failed Celery task (the last attempt; `self.retry()` is not a failure) | `task_failure` | `job` |
+
+Each report carries the class (`module.QualName`; builtins plainly, e.g.
+`KeyError`), the message (≤ 2,000 characters), where it surfaced (the view,
+endpoint or task: `shop.views.checkout`, `acme.charge`), up to 50 stack
+frames (innermost first, paths relative to the app root), the trace, and
+the user.
+
+- **Once per exception.** An error that passes several hooks is reported
+  once.
+- **Status codes are not failures.** Django's `Http404`, `PermissionDenied`,
+  `BadRequest`, `SuspiciousOperation`; werkzeug and Starlette
+  `HTTPException`s; Celery's `Retry`, `Ignore`, `Reject`; and anything that
+  is not an `Exception` (`SystemExit`, `KeyboardInterrupt`,
+  `asyncio.CancelledError`) are never reported. Add your own by name:
+
+  ```python
+  devbench.ignore_exceptions().append("myapp.errors.NotAuthorized")
+  ```
+
+- **Never in the way.** No hook raises into the app; a failure while
+  reporting is dropped, and the application's own exception always comes
+  out unchanged.
+
+## What is sent, and when
+
+- Each report is **fingerprinted and counted in the process** (class,
+  templated message and in-app frames; the same algorithm as every other
+  Dev Bench SDK). Repeats cost a counter increment.
+- **Once a minute** a background thread sends the counts (fingerprint, how
+  many, first/last seen, up to 20 affected users each) in one small request.
+  Nothing is sent for a quiet minute (except a small poll while the process
+  holds log lines, below), and what is left is sent when the process exits
+  (waiting at most 2 seconds; a Celery prefork child flushes at shutdown).
+- **Detail only on request.** When Dev Bench sees a fingerprint for the
+  first time it asks for evidence, and the SDK uploads the stack and one
+  example message, **templated and scrubbed first** (emails, numbers, quoted
+  values, tokens, card numbers, credentials and two-word names are removed).
+  Who was affected never goes into evidence.
+- **Never harms the app.** No network I/O on a request thread; 5-second
+  timeouts on the background thread, one retry, then the data is dropped;
+  memory is bounded (512 distinct problems per minute, the rest only
+  counted). Safe under forking servers (gunicorn, uWSGI, Celery prefork):
+  each process reports on its own.
+
+## Server log lines
+
+Triage reads the server's log lines for the user action that failed. The
+SDK keeps them itself, no sidecar:
+
+- **What:** every record that reaches the root logger's handlers while a
+  request or task carries a trace (`x-adt-trace` from the browser sensor; a
+  Celery task inherits the trace of the request that enqueued it). It sees
+  exactly what your logging configuration already lets through: it never
+  turns on a level you have off, writes nothing anywhere, and leaves your
+  handlers unchanged. A logger with `propagate = False` is not seen. An
+  exception's traceback is held one line each. Untraced records are not
+  kept.
+- **Bounded:** per process, the newest 10,000 lines or 4 MiB, nothing older
+  than 15 minutes, 4 KiB per line. A logging call never waits on I/O and
+  never raises because of this.
+- **Sent only when asked:** when Dev Bench asks for a trace, the flush
+  thread sends that trace's lines from this process (the newest ≤ 200 lines
+  / 64 KiB), **redacted first** with the same strict rules as evidence, plus
+  any redaction rules Dev Bench has learned for your app.
+- **Several processes:** each gunicorn worker and Celery process keeps and
+  answers for its own lines (a task's lines are in the worker, under the
+  trace of the request that enqueued it); Dev Bench assembles them.
+
+A plain WSGI/ASGI app without one of the integrations: `devbench.capture_logs()`.
+
+## Who was affected
+
+Set it once per request, after your authentication has run (a middleware
+after Django's `AuthenticationMiddleware`, a FastAPI dependency, a Flask
+`before_request`):
+
+```python
+devbench.set_user(email=request.user.email, account=request.user.account_id)
+```
+
+- `email` is trimmed and lowercased; `account` is your own tenant/customer
+  id, sent as a string. Both optional, each truncated to 255 characters.
+- It is sent in its own field with the counts, never inside a message or
+  evidence.
+- It ends with the request (a Celery task: with the task), so the next
+  request on the same thread never inherits it.
+
+## Reporting what you caught
+
+An exception you caught but want seen, like Sentry's `capture_exception`:
+
+```python
+except requests.RequestException as e:
+    devbench.capture_exception(e, symbol="billing.sync")
+    retry_later()
+```
+
+A failure you handled and turned into a normal response, the case this
+product exists for:
+
+```python
+except IntegrityError as e:
+    devbench.report_handled(e, symbol="customers.views.update", reason="uniqueness")
+    return JsonResponse({"ok": True})   # <- the user is about to be told this worked
+```
+
+`report_handled` also marks the response with `x-adt-handled: <count>` (and
+lists it in `Access-Control-Expose-Headers`, appending to what is there).
+The browser already knows whether the user was shown an error; this is the
+one fact it cannot know on its own. The header carries a count and nothing
+else, and it is added even when reporting is down.
+
+## Trace propagation
+
+The correlation id the browser sent (`x-adt-trace`) is `devbench.current_trace()`
+for the duration of the request. Forward it on outbound calls to other
+instrumented services:
+
+```python
+requests.post(url, json=body, headers=devbench.trace_headers())
+```
+
+## Not in this release
+
+- No sidecar transport: without a DSN nothing is sent.
+- `devbench.track` (custom events) and the chat widget's signed identity
+  are in the Ruby and Go SDKs; they come to Python later.

devbench-0.1.0/devbench/__init__.py

@@ -0,0 +1,121 @@
+"""Dev Bench server SDK for Python.
+
+    pip install devbench
+    DEVBENCH_DSN=https://<public>:<secret>@<ingest host>   (from `adt dsn create`)
+
+then one line where your framework wants it (README): Django
+(``"devbench.django"`` in INSTALLED_APPS), FastAPI/Starlette
+(``app.add_middleware(DevbenchMiddleware)``), Flask (``Devbench(app)``),
+Celery (``devbench.celery.install()``; automatic under Django).
+
+What it does:
+
+* accepts and forwards the correlation id     (the middlewares, trace_headers)
+* reports unhandled exceptions                (the middlewares, Celery hooks,
+                                               capture_exception)
+* reports handled failures                    (report_handled)
+* records who was affected                    (set_user)
+* keeps recent log lines per trace            (capture_logs; a logging handler)
+
+Nothing here raises into the application.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from . import _core, context, reporter
+from .config import DSN, Configuration, InvalidDSN
+from .identity import set_user
+from .trace import HEADER as TRACE_HEADER
+from .trace import Trace
+from .version import PROTOCOL_VERSION, VERSION
+
+__version__ = VERSION
+
+__all__ = [
+    "PROTOCOL_VERSION", "VERSION", "DSN", "Configuration", "InvalidDSN", "Trace", "TRACE_HEADER",
+    "configure", "enabled", "set_user", "capture_exception", "report_handled", "ignore_exceptions",
+    "trace_headers", "current_trace", "capture_logs", "flush", "test",
+]
+
+
+def configure(dsn: Optional[str] = None, service: Optional[str] = None, release: Optional[str] = None,
+              enabled: Optional[bool] = None, flush_interval: Optional[float] = None) -> None:
+    """Sets any of the environment's values from code (only those given)::
+
+        devbench.configure(dsn=secrets["devbench_dsn"], service="billing-api")
+
+    Takes effect from the next report. Never raises."""
+    _core.configure(dsn=dsn, service=service, release=release, enabled=enabled, flush_interval=flush_interval)
+
+
+def enabled() -> bool:
+    """False when DEVBENCH_ENABLED=false (or configure(enabled=False))."""
+    return _core.enabled()
+
+
+def capture_exception(error: Optional[BaseException] = None, symbol: Optional[str] = None) -> None:
+    """Reports an exception the application caught and wants seen, as
+    Sentry's capture_exception does (the one being handled when ``error`` is
+    omitted). Returns None and never raises::
+
+        except requests.RequestException as e:
+            devbench.capture_exception(e, symbol="billing.sync")
+    """
+    if error is None:
+        import sys
+
+        error = sys.exc_info()[1]
+    reporter.capture(error, "explicit", True, symbol)
+
+
+def report_handled(error: Any, symbol: str, reason: Optional[str] = None) -> None:
+    """Records that a failure was handled (caught and not re-raised) here.
+    Does not change behaviour. Repeats at the same site are counted::
+
+        except IntegrityError as e:
+            devbench.report_handled(e, symbol="customers.views.update", reason="uniqueness")
+    """
+    reporter.report_handled(error, symbol, reason)
+
+
+def ignore_exceptions() -> list:
+    """Class names (``module.QualName``) never reported; append your own."""
+    return reporter.ignore_exceptions()
+
+
+def current_trace() -> Optional[Trace]:
+    """The x-adt-trace of the request or job being handled, or None."""
+    return context.current_trace()
+
+
+def trace_headers() -> Dict[str, str]:
+    """Headers to add to an outbound HTTP call to another instrumented
+    service: the active trace with its hop incremented, or {}::
+
+        requests.post(url, json=body, headers={**headers, **devbench.trace_headers()})
+    """
+    trace = context.current_trace()
+    if trace is None:
+        return {}
+    forwarded = trace.next_hop()
+    return {TRACE_HEADER: str(forwarded)} if forwarded is not None else {}
+
+
+def capture_logs() -> bool:
+    """Keeps recent log lines per trace for triage (direct mode). The
+    integrations call this; a plain WSGI/ASGI app may call it itself."""
+    return _core.capture_logs()
+
+
+def flush(timeout: float = 5.0) -> bool:
+    """Sends whatever has been counted now, waiting at most ``timeout``
+    seconds. Returns True when nothing is left unsent."""
+    return _core.flush(timeout)
+
+
+def test(out: Any = None) -> bool:
+    """Checks DEVBENCH_DSN against ingest and prints the result; the same as
+    ``python -m devbench test``."""
+    return _core.self_test(out)

devbench-0.1.0/devbench/__main__.py

@@ -0,0 +1,24 @@
+"""``python -m devbench test``: checks DEVBENCH_DSN against Dev Bench and
+prints the HTTP result, without waiting for a flush. Exits non-zero when the
+DSN is missing, malformed, unreachable or rejected."""
+
+from __future__ import annotations
+
+import sys
+from typing import List, Optional
+
+from . import _core
+
+USAGE = "usage: python -m devbench test\n"
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if args != ["test"]:
+        sys.stderr.write(USAGE)
+        return 2
+    return 0 if _core.self_test(sys.stdout) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())