traceact 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.4.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

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

@@ -17,6 +17,9 @@ traceact/
                     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
@@ -59,6 +62,7 @@ tests/            — pytest suite (pip install -e ".[dev]" && pytest)
 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)
 
 ---
 
@@ -1464,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
@@ -1476,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.4.0 → traceact-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traceact"
-version = "0.4.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]