traceact 0.3.0__tar.gz → 0.5.0__tar.gz

{traceact-0.3.0/traceact.egg-info → traceact-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.3.0
+Version: 0.5.0
 Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
 Author: Mohammed Shehu
 License-Expression: MIT
@@ -26,6 +26,11 @@ License-File: LICENSE
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-randomly>=3.15; extra == "dev"
+Requires-Dist: flask>=3.0; extra == "dev"
+Requires-Dist: starlette>=0.36; extra == "dev"
+Requires-Dist: django>=4.2; extra == "dev"
+Requires-Dist: requests>=2.31; extra == "dev"
 Dynamic: license-file
 
 # TraceAct
@@ -143,7 +148,15 @@ Checks Python version, that `~/.traceact` is writable, whether a viewer is alrea
 | `Step` | A human-readable timeline marker within a trace |
 | `Event` | A structured operation: db, http, file, model, job, etc. |
 | `Touch` | A resource involved in the trace (auto-derived from events) |
-| `Sink` | Where completed traces are written (`JsonlSink`, `ConsoleSink`) |
+| `Sink` | Where completed traces are written (`JsonlSink`, `ConsoleSink`, `AsyncSink`) |
+
+### Design principle: observable by choice, never forced blind
+
+TraceAct exists to give you X-ray vision for your code. That means nothing TraceAct does itself should take that vision away.
+
+Wherever TraceAct might skip, drop, or truncate data — a trace sampled out by `sample_rate`, events truncated by a budget limit, records dropped by `AsyncSink` under backpressure — there is always an observable signal. The `budget_hit` flag marks truncated traces. The `AsyncSink.dropped` counter counts every dropped record. Sampling decisions are made before a trace object is created, so nothing is half-recorded.
+
+The design choice is always: **silent by default, observable by choice**. You decide whether to log, alert on, or ignore those signals. TraceAct never makes that decision for you.
 
 ## Wiring into a web app
 

{traceact-0.3.0 → traceact-0.5.0}/README.md

@@ -113,7 +113,15 @@ Checks Python version, that `~/.traceact` is writable, whether a viewer is alrea
 | `Step` | A human-readable timeline marker within a trace |
 | `Event` | A structured operation: db, http, file, model, job, etc. |
 | `Touch` | A resource involved in the trace (auto-derived from events) |
-| `Sink` | Where completed traces are written (`JsonlSink`, `ConsoleSink`) |
+| `Sink` | Where completed traces are written (`JsonlSink`, `ConsoleSink`, `AsyncSink`) |
+
+### Design principle: observable by choice, never forced blind
+
+TraceAct exists to give you X-ray vision for your code. That means nothing TraceAct does itself should take that vision away.
+
+Wherever TraceAct might skip, drop, or truncate data — a trace sampled out by `sample_rate`, events truncated by a budget limit, records dropped by `AsyncSink` under backpressure — there is always an observable signal. The `budget_hit` flag marks truncated traces. The `AsyncSink.dropped` counter counts every dropped record. Sampling decisions are made before a trace object is created, so nothing is half-recorded.
+
+The design choice is always: **silent by default, observable by choice**. You decide whether to log, alert on, or ignore those signals. TraceAct never makes that decision for you.
 
 ## Wiring into a web app
 

{traceact-0.3.0 → traceact-0.5.0}/USAGE.md

@@ -14,9 +14,12 @@ traceact/
   context.py      — ContextVar for active trace, SKIP sentinel
   redaction.py    — SENSITIVE_PATTERNS baseline + REDACTION_PRESETS registry
   sinks.py        — JsonlSink (thread-safe, rotation via max_bytes), ConsoleSink,
-                    AsyncSink (not yet public)
+                    AsyncSink (background-thread wrapper; public as of v0.4)
   helpers.py      — TraceHelpersMixin (trace.db, trace.http, trace.file, trace.model)
   ids.py          — ID generation (trc_, evt_, stp_, corr_ prefixes)
+  propagation.py  — extract_trace_id, inject_headers, propagate context manager,
+                    _INCOMING_TRACE_ID ContextVar for cross-service correlation
+  middleware.py   — TraceActMiddleware (WSGI), TraceActASGIMiddleware (ASGI)
 
   viewer/
     cli.py        — `traceact view` / `traceact show` / `traceact doctor` CLI entry point
@@ -52,12 +55,14 @@ tests/            — pytest suite (pip install -e ".[dev]" && pytest)
 13. [Background jobs and correlation IDs](#background-jobs-and-correlation-ids)
 14. [Input capture](#input-capture)
 15. [Sinks](#sinks)
-16. [Budget configuration](#budget-configuration)
-17. [TraceConfig fields](#traceconfig-fields)
-18. [Test isolation](#test-isolation)
-19. [Trace record schema](#trace-record-schema)
-20. [Viewing traces](#viewing-traces)
-21. [Integrating the viewer into your app](#integrating-the-viewer-into-your-app)
+16. [TraceLog](#tracelog)
+17. [Budget configuration](#budget-configuration)
+18. [TraceConfig fields](#traceconfig-fields)
+19. [Test isolation](#test-isolation)
+20. [Trace record schema](#trace-record-schema)
+21. [Viewing traces](#viewing-traces)
+22. [Integrating the viewer into your app](#integrating-the-viewer-into-your-app)
+23. [Distributed propagation](#distributed-propagation)
 
 ---
 
@@ -688,12 +693,341 @@ configure(sinks=[
 ])
 ```
 
+### AsyncSink
+
+Wraps any other sink(s) and performs all writes on a background thread, keeping I/O completely off the application's hot path. The traced function drops the record into an in-memory queue and returns immediately; a single worker thread drains the queue at its own pace.
+
+```python
+from traceact import AsyncSink, JsonlSink
+
+configure(sinks=[
+    AsyncSink([JsonlSink("data/traces/traces.jsonl")])
+])
+```
+
+**When to use it:** any time the inner sink is slow or remote — an HTTP collector, a database, or a high-latency filesystem. For local files on fast hardware, the overhead of `JsonlSink` alone is rarely worth wrapping.
+
+**Backpressure — and why drops are always observable:**
+
+If your application produces traces faster than the worker can write them, the queue fills up. TraceAct will never crash or block your app to protect a trace record — but it will never drop records *silently* either. Every record dropped under a backpressure policy is counted in `AsyncSink.dropped`. Check it, log it, or expose it in a health endpoint:
+
+```python
+sink = AsyncSink([JsonlSink("traces.jsonl")])
+configure(sinks=[sink])
+
+# later, in a health check or periodic log:
+if sink.dropped > 0:
+    logger.warning("AsyncSink dropped %d trace records (queue full)", sink.dropped)
+```
+
+The whole point of TraceAct is X-ray vision for your code. A silent drop is blindness. The `dropped` counter means you can *choose* to ignore dropped records — but the choice is yours, not the library's.
+
+Three policies for when the queue is full:
+
+| Policy | Behaviour | Use when |
+|---|---|---|
+| `"drop_newest"` (default) | Discard the incoming record; count it | Older in-flight records are more diagnostically useful |
+| `"drop_oldest"` | Evict the oldest queued record to make room | Recent traces matter more than historical ones |
+| `"block"` | Stall the calling thread until there is space | Zero loss is required and brief latency is acceptable |
+
+```python
+AsyncSink([JsonlSink("traces.jsonl")], max_queue=50_000, on_full="drop_oldest")
+```
+
+**Graceful shutdown:** `AsyncSink` registers an `atexit` hook on first write. When the process exits normally, the worker flushes all buffered records before stopping — short-lived scripts don't need to call `close()` explicitly, but you can call it yourself at a known shutdown point to flush sooner.
+
+**Fork safety:** `os.fork()` doesn't copy background threads into child processes. `AsyncSink` registers a post-fork handler to reset the worker in the child so it starts fresh on the next write.
+
+**Wrapping multiple sinks:**
+
+```python
+AsyncSink([
+    JsonlSink("data/traces/traces.jsonl"),
+    ConsoleSink(pretty=False),
+])
+```
+
+Both inner sinks receive every record on the background thread. A failing inner sink is caught and skipped so one bad sink can't kill the worker or lose records destined for the others.
+
+### SqliteSink
+
+Writes finished traces to a local SQLite database using stdlib `sqlite3` — no extra dependencies. Common fields (`action`, `kind`, `status`, `started_at`, `correlation_id`, etc.) are stored as indexed scalar columns for fast filtering; the full trace record is also stored as JSON in a `record` column so no detail is ever lost. The schema is created automatically on first write.
+
+```python
+from traceact import SqliteSink, configure
+
+configure(sinks=[SqliteSink("data/traces.db")])
+```
+
+**Custom table name:**
+
+```python
+SqliteSink("data/traces.db", table="my_traces")
+```
+
+**Querying traces directly from the database:**
+
+```python
+import sqlite3, json
+
+conn = sqlite3.connect("data/traces.db")
+
+# All failures in the last hour:
+rows = conn.execute("""
+    SELECT action, duration_ms, record
+    FROM traces
+    WHERE status = 'failed'
+      AND started_at > datetime('now', '-1 hour')
+    ORDER BY started_at DESC
+""").fetchall()
+
+for action, ms, raw in rows:
+    record = json.loads(raw)
+    print(f"{action}  {ms}ms  errors={record.get('errors')}")
+```
+
+**Concurrent writes:** SQLite is opened in WAL mode so reads and writes can proceed concurrently. For high-concurrency workloads, wrap in `AsyncSink` so write latency stays off the application's hot path:
+
+```python
+from traceact import AsyncSink, SqliteSink, configure
+
+configure(sinks=[AsyncSink([SqliteSink("data/traces.db")])])
+```
+
+**Write errors** are printed to stderr and never propagated to the caller — a database hiccup doesn't interrupt the traced function.
+
+### HttpSink
+
+POSTs each finished trace as a JSON body to an HTTP or HTTPS endpoint. Uses stdlib `urllib` only — zero extra dependencies.
+
+```python
+from traceact import HttpSink, AsyncSink, configure
+
+configure(sinks=[
+    AsyncSink([HttpSink("https://collector.example.com/traces")])
+])
+```
+
+**Always wrap in `AsyncSink` for production use.** Each write makes a synchronous HTTP request; without `AsyncSink` that latency hits every traced function call on the return path.
+
+**Custom headers** (API keys, auth tokens):
+
+```python
+HttpSink(
+    "https://collector.example.com/traces",
+    headers={"Authorization": "Bearer <your-token>"},
+)
+```
+
+**Custom timeout** (default: 5 seconds):
+
+```python
+HttpSink("https://collector.example.com/traces", timeout=2.0)
+```
+
+**Observable failures:** network errors, timeouts, and non-2xx responses are counted in `HttpSink.failed` — never raised, never silently swallowed. Check it in a health endpoint or periodic log:
+
+```python
+sink = HttpSink("https://collector.example.com/traces")
+configure(sinks=[AsyncSink([sink])])
+
+# in a health check or periodic log:
+if sink.failed > 0:
+    logger.warning("HttpSink: %d trace deliveries failed", sink.failed)
+```
+
+### OtlpSink
+
+Exports finished traces to any OTLP-compatible collector — Jaeger, Grafana Tempo, Honeycomb, Datadog agent, the OpenTelemetry Collector, and others. Uses OTLP/HTTP+JSON over stdlib `urllib`. Zero extra dependencies; no `opentelemetry-sdk` required.
+
+```python
+from traceact import OtlpSink, AsyncSink, configure
+
+configure(sinks=[
+    AsyncSink([OtlpSink("http://localhost:4318")])
+])
+```
+
+Point `endpoint` at your collector's OTLP HTTP receiver base URL (the standard port is 4318). TraceAct appends `/v1/traces` automatically.
+
+**Always wrap in `AsyncSink` for production use** — each write makes a synchronous HTTP request.
+
+**SaaS collectors (Honeycomb, Datadog, etc.):**
+
+```python
+# Honeycomb
+OtlpSink(
+    "https://api.honeycomb.io",
+    headers={"x-honeycomb-team": "<your-api-key>"},
+)
+
+# Datadog (OTLP agent receiver, default port 4318)
+OtlpSink("http://localhost:4318")
+
+# Grafana Cloud
+OtlpSink(
+    "https://<your-instance>.grafana.net/otlp",
+    headers={"Authorization": "Basic <base64-encoded-credentials>"},
+)
+```
+
+**Service name and resource attributes:**
+
+```python
+OtlpSink(
+    "http://localhost:4318",
+    resource_attributes={
+        "service.name":    "orders-api",
+        "deployment.env":  "production",
+        "service.version": "2.1.0",
+    },
+)
+```
+
+These appear as resource-level attributes on every span exported by this sink. `service.name` defaults to `"traceact"` if you don't set it.
+
+**How TraceAct records map to OTel spans:**
+
+| TraceAct field | OTel span field |
+|---|---|
+| `action` | Span name |
+| `kind` (`db`, `http`, `cache`, `model`, `auth`, `payment`) | SpanKind CLIENT |
+| `kind` (`queue`, `email`, `export`) | SpanKind PRODUCER |
+| `kind` (`job`) | SpanKind CONSUMER |
+| Everything else | SpanKind INTERNAL |
+| `started_at` / `ended_at` | `startTimeUnixNano` / `endTimeUnixNano` |
+| `status = "completed"` | StatusCode OK |
+| `status = "failed"` | StatusCode ERROR |
+| `parent_trace_id` | `parentSpanId` |
+| `steps` | Span events (`name="step"`) |
+| `errors` | Span events (`name="exception"`) |
+| `inputs.*` | Span attributes `traceact.input.*` |
+| `outputs.*` | Span attributes `traceact.output.*` |
+| `touches` | Span attributes `traceact.touch.N.kind/target` |
+| `trace_id`, `correlation_id`, `actor`, etc. | Span attributes `traceact.*` |
+| Any unlisted scalar field | Span attribute `traceact.<field>` |
+
+TraceAct IDs (`trc_...`) are hashed with MD5 to produce the 128-bit trace ID and 64-bit span ID that OTel requires. The original TraceAct IDs are always preserved as `traceact.trace_id` (and `traceact.root_trace_id`, `traceact.correlation_id`) span attributes so you can cross-reference them.
+
+**Observable failures:** network errors, timeouts, and non-2xx responses from the collector are counted in `OtlpSink.failed`:
+
+```python
+sink = OtlpSink("http://localhost:4318")
+configure(sinks=[AsyncSink([sink])])
+
+if sink.failed > 0:
+    logger.warning("OtlpSink: %d trace deliveries failed", sink.failed)
+```
+
 ### Fallback
 
 If no sinks are configured when a trace finishes, TraceAct falls back to `ConsoleSink()` so traces aren't silently dropped.
 
 ---
 
+## TraceLog
+
+`TraceLog` is the programmatic query interface for TraceAct JSONL files. Use it when code — an AI agent, a test suite, or a background script — needs to read trace data without opening a browser.
+
+```python
+from traceact import TraceLog
+
+log = TraceLog("data/traces/traces.jsonl")   # file or folder
+```
+
+A folder source behaves the same as in the viewer: all `.jsonl` files inside it are merged on every read.
+
+### Filtering
+
+`filter()` returns a **new** `TraceLog` — the original is never mutated.
+
+```python
+failures  = log.filter(status="failed")
+db_traces = log.filter(kind="db")
+
+# AND logic: both conditions must hold
+recent_db_failures = log.filter(kind="db", status="failed")
+
+# Chained calls are equivalent
+same_thing = log.filter(kind="db").filter(status="failed")
+```
+
+**Supported operators:**
+
+| Syntax | Behaviour |
+|---|---|
+| `field=value` | Exact equality (case-sensitive) |
+| `field__contains=value` | Case-insensitive substring |
+| `field__startswith=value` | Case-insensitive prefix |
+| `field__endswith=value` | Case-insensitive suffix |
+| `field__re=pattern` | `re.search` — partial regex match |
+
+```python
+log.filter(action__contains="order")          # any action with "order"
+log.filter(action__startswith="payment")      # actions starting with "payment"
+log.filter(action__re=r"^order\.(create|update)$")
+log.filter(correlation_id="job_abc123")       # find one background job's traces
+```
+
+### Terminal methods
+
+```python
+log.filter(status="failed").all()       # List[dict], oldest-first
+log.filter(status="failed").last(10)    # 10 most recent
+log.filter(status="failed").first(10)   # 10 oldest
+log.filter(status="failed").count()     # int
+
+log.filter(status="failed").render_table()      # pretty-print to stdout
+log.filter(status="failed").render_table(n=25)  # cap rows shown
+```
+
+Each terminal call re-reads the JSONL file(s) — there is no caching, so you always get the current state of a live source.
+
+### Using TraceLog in tests
+
+```python
+import pytest
+from traceact import TraceLog, configure, reset_config, JsonlSink
+
+def test_checkout_records_payment_touch(tmp_path):
+    sink_path = tmp_path / "traces.jsonl"
+    configure(sinks=[JsonlSink(str(sink_path))])
+
+    # run the function under test
+    checkout(user_id="u_42", amount=99.00)
+
+    log = TraceLog(str(sink_path))
+    traces = log.filter(action="checkout").all()
+
+    assert len(traces) == 1
+    touch_kinds = [t["kind"] for t in traces[0].get("touches", [])]
+    assert "payment" in touch_kinds
+
+    reset_config()
+```
+
+### TraceLog.view() — shared lens
+
+`view()` opens the viewer pre-filtered to match the `TraceLog`'s current filters. The viewer shows each active filter as a dismissable badge above the trace list — a human can remove any badge to widen the view, and the search box still works on top.
+
+```python
+# Open the viewer showing only failed traces
+TraceLog("data/traces/traces.jsonl").filter(status="failed").view()
+
+# Open with multiple filters
+TraceLog("data/traces/traces.jsonl") \
+    .filter(kind="db", status="failed") \
+    .view()
+
+# Get the URL without opening a browser (useful in CI or a script)
+url = log.filter(status="failed").view(open_browser=False)
+print(f"Open the viewer at: {url}")
+```
+
+The viewer is launched (or an existing instance is reused) and pointed at the same source file or folder that the `TraceLog` reads from. The viewer's normal behaviour when opened without `view()` is completely unchanged.
+
+---
+
 ## Budget configuration
 
 `TraceBudget` controls how much TraceAct records. When a limit is reached, `budget_hit` is set to `True` on the trace and recording stops. The wrapped function continues running normally.
@@ -1134,6 +1468,165 @@ Because `launch_or_connect` starts the viewer on `127.0.0.1` by default, the ret
 
 ---
 
+## Distributed propagation
+
+When a traced action in Service A calls Service B, TraceAct links the two
+services' traces together with two separate HTTP headers — separate because
+they answer separate questions:
+
+| Header | Sets on the receiving trace | Answers |
+|---|---|---|
+| `traceact-trace-id` | `upstream_trace_id` | "which trace in another service triggered me?" (causal lineage) |
+| `traceact-correlation-id` | `correlation_id` | "which wider workflow do I belong to?" (business grouping, passed through untouched) |
+
+Keeping them separate matters: a trace can have an upstream parent in one
+service *and* belong to a correlation group that was assigned several hops
+earlier. Folding one into the other silently discards whichever one loses.
+
+### Outbound: stamp both headers
+
+`inject_headers()` reads the active trace and stamps its `trace_id` (always)
+and its `correlation_id` (if set) onto an outbound headers dict. It never
+mutates the dict you pass in.
+
+```python
+import requests
+from traceact import inject_headers
+
+with ActionTrace.start(action="order.submit", correlation_id="corr_wf_9f2a") as trace:
+    headers = inject_headers({"Content-Type": "application/json"})
+    requests.post("https://payments.internal/charge", json=payload, headers=headers)
+```
+
+Works the same with `httpx`, `urllib`, or any other HTTP client — `inject_headers`
+just returns a plain dict.
+
+### Inbound: extract the headers (manual)
+
+Use the `propagate` context manager when you want explicit control, or when
+your framework isn't covered by the automatic middleware. Pass the framework's
+header object **directly** — `request.headers` works as-is on Flask, Django,
+FastAPI, and Starlette, and so does a plain dict in any casing:
+
+```python
+from traceact import propagate, ActionTrace
+
+def handle_charge(request):
+    with propagate(request.headers):
+        with ActionTrace.start(action="charge.process") as trace:
+            # trace.upstream_trace_id == Service A's trace_id
+            # trace.correlation_id   == whatever correlation Service A had
+            ...
+```
+
+HTTP header names are case-insensitive and every framework reconstructs them
+differently (Flask/Werkzeug and Django hand back `Traceact-Trace-Id`,
+Title-Case; ASGI delivers raw lowercase bytes). `propagate()` and
+`extract_trace_id()`/`extract_correlation_id()` normalise all of that
+internally — pass the header object however your framework gives it to you,
+including `dict(request.headers)` if you already have that.
+
+### Inbound: automatic via middleware (Flask / Django)
+
+```python
+from traceact import TraceActMiddleware
+
+# Flask
+app.wsgi_app = TraceActMiddleware(app.wsgi_app)
+
+# Django (in wsgi.py)
+from django.core.wsgi import get_wsgi_application
+application = TraceActMiddleware(get_wsgi_application())
+```
+
+Reads both headers from the WSGI environ and applies them to every trace
+started during that request — including traces started while a streamed
+response body is generated (the context is held until the response is fully
+closed, not just until the view function returns). If neither header is
+present, the middleware is fully transparent.
+
+### Inbound: automatic via middleware (FastAPI / Starlette)
+
+```python
+from traceact import TraceActASGIMiddleware
+from fastapi import FastAPI
+
+app = FastAPI()
+app.add_middleware(TraceActASGIMiddleware)
+```
+
+Or wrap manually:
+
+```python
+app = TraceActASGIMiddleware(app)
+```
+
+### How the chain looks in the viewer and TraceLog
+
+Both services write their own trace records. Query by whichever link answers
+your question — `upstream_trace_id` for "what did this specific call trigger",
+`correlation_id` for "show me the whole workflow":
+
+```python
+from traceact import TraceLog
+
+log = TraceLog("traces.jsonl")
+log.filter(upstream_trace_id="trc_abc123").all()   # traces this call triggered
+log.filter(correlation_id="corr_wf_9f2a").all()    # the entire workflow
+log.filter(correlation_id="corr_wf_9f2a").view()   # same, in the browser viewer
+```
+
+The inspector's summary card shows both when present, each in full (not
+shortened) so they can be copied and searched against another service's logs.
+
+### `ai_prompts` redaction preset
+
+For AI pipelines where trace payloads must not store raw prompt text, model
+responses, or conversation history, enable the `ai_prompts` preset:
+
+```python
+configure(
+    config=TraceConfig(redaction_presets=["ai_prompts"]),
+)
+```
+
+Redacted fields include: `raw_prompt`, `prompt_content`, `system_prompt`,
+`raw_response`, `response_content`, `conversation`, `message_content`,
+`file_content`, `source_excerpt`, `context_window`, `completion`,
+`generation`, `output_text`. Safe fields like `model`, `latency_ms`,
+`prompt_id`, and token counts are unaffected.
+
+| What gets redacted | What stays |
+|---|---|
+| Raw prompts and responses | Model name, version |
+| System prompts | Token counts (as long as field name has no "token" substring) |
+| Conversation history | Latency, cost |
+| File and source excerpts | Trace IDs, correlation IDs |
+
+Combine with other presets:
+
+```python
+TraceConfig(redaction_presets=["ai_prompts", "api_keys"])
+```
+
+### Reference: headers
+
+| Header | Outbound (inject) | Inbound (extract) |
+|---|---|---|
+| `traceact-trace-id` | Active `ActionTrace.trace_id` | Sets `upstream_trace_id` |
+| `traceact-correlation-id` | Active `ActionTrace.correlation_id`, if set | Sets `correlation_id` |
+
+Accepted header collection types on the inbound side: any object with
+`.items()` (dict in any casing, Werkzeug/Django/Starlette header objects,
+`requests.CaseInsensitiveDict`), a list of `(name, value)` pairs, or raw ASGI
+`[(b"name", b"value")]` byte pairs. Matching is case-insensitive regardless of
+which form you pass.
+
+WSGI: the header arrives as `HTTP_TRACEACT_TRACE_ID` in the environ.
+ASGI: the header arrives as bytes in `scope["headers"]`.
+
+---
+
 ## Quick reference
 
 ```python
@@ -1146,5 +1639,9 @@ from traceact import (
     traced_action,  # decorator
     JsonlSink,      # write traces to a .jsonl file
     ConsoleSink,    # print traces to stdout
+    propagate,      # context manager for inbound propagation
+    inject_headers, # stamp outbound request headers
+    TraceActMiddleware,     # WSGI auto-propagation (Flask, Django)
+    TraceActASGIMiddleware, # ASGI auto-propagation (FastAPI, Starlette)
 )
 ```

{traceact-0.3.0 → traceact-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traceact"
-version = "0.3.0"
+version = "0.5.0"
 description = "X-ray vision for your code. Lightweight action-level tracing for Python."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -35,6 +35,22 @@ dependencies = []
 dev = [
     "pytest>=7.0",
     "pytest-asyncio>=0.21",
+    # Test-order randomisation. Activates automatically once installed — no
+    # flag needed. Kept on deliberately: an order-dependent failure means
+    # shared/global state is leaking between tests, which is a real bug.
+    # Never pin --randomly-seed in CI to "stabilise" a run; that hides exactly
+    # the failure mode this plugin exists to catch.
+    "pytest-randomly>=3.15",
+    # Real framework objects for propagation tests (extract_trace_id,
+    # TraceActMiddleware, TraceActASGIMiddleware). These are test-only —
+    # traceact itself has zero runtime dependencies. Testing against a
+    # hand-built dict instead of an actual Flask/Django/Starlette request
+    # object was exactly the gap that let a header-parsing bug through
+    # 43 green tests; these are here so that never happens again.
+    "flask>=3.0",
+    "starlette>=0.36",
+    "django>=4.2",
+    "requests>=2.31",
 ]
 
 [project.urls]