traceact 0.4.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.4.0
+Version: 0.6.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
@@ -123,7 +128,7 @@ Double-click `launch.command` in the repo root to open TraceAct from Finder with
 
 The source modal (click the source name in the header) lets you:
 
-- **Choose file / Choose folder** — opens a native macOS picker; returns the real filesystem path for live tailing
+- **Choose file / Choose folder** — opens a native macOS picker; returns the filesystem path for live tailing
 - **Drag and drop** a `.jsonl` file — saved as a static snapshot in `~/.traceact/imports/`
 - **Type a path** — collapsible fallback for pasting an absolute path
 

{traceact-0.4.0 → traceact-0.6.0}/README.md

@@ -93,7 +93,7 @@ Double-click `launch.command` in the repo root to open TraceAct from Finder with
 
 The source modal (click the source name in the header) lets you:
 
-- **Choose file / Choose folder** — opens a native macOS picker; returns the real filesystem path for live tailing
+- **Choose file / Choose folder** — opens a native macOS picker; returns the filesystem path for live tailing
 - **Drag and drop** a `.jsonl` file — saved as a static snapshot in `~/.traceact/imports/`
 - **Type a path** — collapsible fallback for pasting an absolute path
 

{traceact-0.4.0 → traceact-0.6.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)
 
 ---
 
@@ -622,7 +626,7 @@ configure(config=TraceConfig(redaction_presets=["filesystem_paths", "env_vars"])
 
 An unknown preset name raises `ValueError` immediately at `TraceConfig(...)` construction, not later at trace time.
 
-Also settable per-decorator, same as any other `TraceConfig` field — but note that a decorator-level `redaction_presets` **replaces** the package-level list rather than adding to it, exactly like `capture_inputs` does:
+Also settable per-decorator, same as any other `TraceConfig` field — but note that a decorator-level `redaction_presets` **replaces** the package-level list rather than adding to it, the same way `capture_inputs` does:
 
 ```python
 @traced_action(action="report.export", kind="app",
@@ -631,7 +635,7 @@ def export_report(...):
     ...
 ```
 
-**These are field-name patterns, not content scanning.** A value is redacted because of what its *key* is called, not what it contains. `trace.input({"path": "/Users/mo/secret"})` is redacted by the `filesystem_paths` preset; `trace.input({"location": "/Users/mo/secret"})` is not, because `"location"` doesn't match any active pattern. This mirrors the baseline mechanism exactly (same substring, case-insensitive matching) — it's simple and has no false-positive risk from scanning arbitrary string content, at the cost of missing secrets stored under an unexpected field name.
+**These are field-name patterns, not content scanning.** A value is redacted because of what its *key* is called, not what it contains. `trace.input({"path": "/Users/mo/secret"})` is redacted by the `filesystem_paths` preset; `trace.input({"location": "/Users/mo/secret"})` is not, because `"location"` doesn't match any active pattern. This mirrors the baseline mechanism (same substring, case-insensitive matching) — it's simple and has no false-positive risk from scanning arbitrary string content, at the cost of missing secrets stored under an unexpected field name.
 
 **Nested redaction example:**
 
@@ -701,7 +705,7 @@ configure(sinks=[
 ])
 ```
 
-**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.
+**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, `JsonlSink` alone rarely needs the extra wrapping.
 
 **Backpressure — and why drops are always observable:**
 
@@ -979,6 +983,32 @@ 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.
 
+`last()`/`first()` are memory-bounded: they hold at most `n` matching records per file at once rather than collecting every match before truncating. A broad filter (or no filter at all) over a large source costs memory proportional to `n`, not to how much of the source matches.
+
+### query() — bounded result plus two completeness flags
+
+```python
+result = log.filter(status="failed").query(500)
+result["traces"]         # up to 500 matches, newest-first
+result["scan_capped"]    # True if max_lines_scanned stopped the scan early
+result["limit_reached"]  # True if more than 500 traces matched
+```
+
+Two separate reasons a result might not be every match that exists:
+
+- `scan_capped` — the scan itself gave up early, per `max_lines_scanned`.
+- `limit_reached` — the scan finished (or found enough to stop), but `n` (or more) results matched — there may be more beyond what's returned. This is true of `last(n)` too; `last()` just has nowhere to report it, since it returns a plain list. Note that `len(result["traces"]) == n` alone can't tell you this — a bounded scan returns at most `n` regardless of whether `n` or a hundred thousand traces matched, so `limit_reached` is tracked from a count taken during the scan, not inferred from the result's length afterward.
+
+Use `query()` instead of `last()` when the caller needs to distinguish those two situations — this is what the viewer's `/api/query` endpoint uses under the hood (see [Server-side search](#server-side-search-apiquery) above). `last()`/`first()` keep returning a plain list; `query()` is a separate method rather than a change to their return shape, so nothing about them breaks for existing callers.
+
+### max_lines_scanned — bounding scan time
+
+```python
+log = TraceLog("data/traces.jsonl", max_lines_scanned=200_000)
+```
+
+Caps how many lines a scan reads (matched or not) before giving up and returning whatever was found, setting `scan_capped=True` on the next `query()` call. Defaults to `None` — unbounded, the same behaviour as before this existed. Set it when reading a source you don't control the size of, or when a single call needs a predictable worst-case cost (an HTTP handler, for instance — see below).
+
 ### Using TraceLog in tests
 
 ```python
@@ -1301,7 +1331,7 @@ Pass `--new` to bypass this and force a second instance — useful when you want
 
 The "Add source" modal supports three ways to load a source:
 
-- **Choose file / Choose folder buttons** — opens a native macOS file or folder picker. The picker runs on the server side via AppleScript (`osascript`), so it returns the real filesystem path and the viewer can tail it live. (Falls back to a `tkinter` dialog on non-macOS platforms.)
+- **Choose file / Choose folder buttons** — opens a native macOS file or folder picker. The picker runs on the server side via AppleScript (`osascript`), so it returns the filesystem path and the viewer can tail it live. (Falls back to a `tkinter` dialog on non-macOS platforms.)
 - **Drag and drop** — drop a `.jsonl` file onto the drop zone. The browser reads the file contents and posts them to the server, which saves a copy to `~/.traceact/imports/` and adds it as a source. Because the server holds a copy (not the original), this is a **static snapshot** — new writes to the original file won't appear. The viewer labels imported sources accordingly.
 - **Type a path** — a collapsible text input for pasting or typing an absolute path. This gives live tailing just like the command-line argument.
 
@@ -1315,11 +1345,11 @@ The "Add source" modal supports three ways to load a source:
 4. Installs or upgrades `traceact` inside that venv.
 5. Runs `traceact view`, waits for the server to be ready, then opens the browser.
 
-The Terminal window stays open so Ctrl+C stops the viewer cleanly. To pass a source file at launch from a script: `open launch.command path/to/traces.jsonl`.
+The Terminal window stays open so Ctrl+C stops the viewer. To pass a source file at launch from a script: `open launch.command path/to/traces.jsonl`.
 
 ### What the viewer shows
 
-- **Trace log** — a live, newest-first table of traces (time, action, status, duration, and touch/error/budget counts). A search box filters by action, kind, status, correlation ID, or touched target. The row count is capped (25 / 50 / 100 / 250, default 100) and paired with live tailing, so the newest traces are always in view.
+- **Trace log** — a live, newest-first table of traces (time, action, status, duration, and touch/error/budget counts). A search box filters by action, kind, status, correlation ID, or touched target, against the currently tailed rows. The row count is capped (25 / 50 / 100 / 250, default 100) and paired with live tailing, so the newest traces are always in view. A pre-filtered view opened via `TraceLog.view()` instead searches the full source on disk — see [Server-side search](#server-side-search-apiquery) below.
 - **Trace inspector** — selecting a trace shows its own ID, its parent and root trace IDs (when it is a child trace), correlation ID (when present, shown in full), kind, duration, and touch/error counts. "Copy JSON" copies the full record.
 - **Trace map** — a visual of one trace: the action as origin, its events and resources as connected nodes, with per-node status and a red marker on failures. Plays as a sequential step-through replay, with a speed slider (1×–10×, live, persisted) and pause/play.
 - **Settings** — accent colour, display density, default trace view, row count, default replay speed, and a **Run diagnostics** button — all persisted to `localStorage` except diagnostics, which runs fresh each time.
@@ -1341,11 +1371,29 @@ These endpoints are available while a viewer is running. Apps and scripts can ca
 | `GET` | `/api/pick?type=file\|folder` | — | `{"path":"...","cancelled":bool}` |
 | `POST` | `/api/import` | `{"name":"file.jsonl","content":"..."}` | `{"name":"...","path":"...","imported":true}` |
 | `GET` | `/api/stream?source=NAME&limit=N` | — | SSE stream: `snapshot` then `append` events |
+| `GET` | `/api/query?source=NAME&field[__op]=value&limit=N` | — | `{"traces":[...],"scan_capped":bool,"limit_reached":bool,"count":N}` |
 
 `/api/doctor`'s `status` is `"pass"`, `"fail"`, or `"info"`; `hint` is present only on `"fail"` checks. `ok` is `true` only if every `"pass"`/`"fail"` check passed — `"info"` checks (traceact's version, whether a viewer is running) never affect it.
 
 The SSE stream delivers one `snapshot` message (the last N traces as a JSON array) then `append` messages for each newly-written trace. A `": keepalive"` comment is sent every 0.5 s when nothing new arrives, to keep the connection alive through proxies.
 
+### Server-side search (`/api/query`)
+
+The trace log's search box and the row-limit setting both operate on the live-tailed buffer — whatever the last N traces happen to be. That's fine for the search box (a quick, instant, client-side filter over what's currently in view), but a `TraceLog.view()` pre-filter is a precise, deliberately-specified query — it needs to find its match regardless of whether that match is still inside the tail window. `/api/query` answers filters against the whole source on disk, via `TraceLog`, and the viewer routes pre-filters through it automatically. You don't need to call it directly for that to happen.
+
+```
+GET /api/query?source=traces&status=failed&action__contains=order&limit=200
+```
+
+- Every query param except `source` and `limit` is a filter field, in the same `field` / `field__contains` / `field__startswith` / `field__endswith` form as `TraceLog.filter()`. Multiple params are ANDed, same as chaining `.filter()` calls.
+- `__re` is not accepted here — it's rejected with `400`. `TraceLog.filter(field__re=...)` only makes sense when the pattern comes from trusted code; over HTTP it's arbitrary caller-supplied input, and a catastrophic-backtracking pattern could hang the request. Use `__re` directly against `TraceLog` in Python instead.
+- **`limit` is hard-capped at 1000 server-side.** Requesting `limit=5000` against a source with 3000 matches returns only the newest 1000 — but not silently: `count` in the response is the count *returned*, not the count that matched, and `limit_reached` (below) tells you whether more may exist.
+- The response carries two separate completeness flags, both `false` when the result is everything that matched:
+  - **`scan_capped`** — `true` if the scan hit its internal line-read ceiling before finishing reading the source.
+  - **`limit_reached`** — `true` if more traces matched than `limit` allowed back (including when a too-large requested `limit` was clamped to 1000). `count == limit` is not itself a safe signal that nothing more exists — a bounded scan always returns at most `limit` regardless of whether `limit` or a hundred thousand traces matched, so this comes from a count taken during the scan, not from inspecting the returned list's length afterward.
+
+  Either flag `true` means the same thing to a caller: this may not be every match. The viewer shows "results may be incomplete" next to the pre-filter badges when either is set, rather than presenting a partial result as if it were exhaustive.
+
 ### Notes
 
 - The viewer is a **local, single-node development tool**. It reads files on the machine it runs on. Exposing one machine's traces to another over the network (`traceact serve`) is planned for a later version.
@@ -1464,6 +1512,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 +1683,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.6.0}/pyproject.toml

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