traceact 0.6.0__tar.gz → 0.6.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.6.0
+Version: 0.6.2
 Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
 Author: Mohammed Shehu
 License-Expression: MIT
@@ -41,7 +41,7 @@ Dynamic: license-file
 
 X-ray vision for Python code.
 
-TraceAct is a lightweight Python package for action-level tracing. It records the full story of what happens when a function runs — every step taken, resource touched, event recorded, and failure encountered — so you or your agent can understand what actually happened.
+TraceAct is a lightweight Python package for action-level tracing. It records the full story of what happens when a function runs — every step taken, resource touched, event recorded, and failure encountered — so you or your agent can understand what happened.
 
 ## Install
 
@@ -154,7 +154,7 @@ Checks Python version, that `~/.traceact` is writable, whether a viewer is alrea
 
 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.
+Wherever TraceAct might skip, drop, or truncate data, there is a signal for it. Events truncated by a budget limit set the `budget_hit` flag. Records dropped by `AsyncSink` under backpressure increment `AsyncSink.dropped`. A failure inside a sampled-out trace is recorded anyway (with `always_trace_errors`, on by default) and marked `sampled_out` so you know its detail was not captured. The one deliberate silence is a sampled-out *success* — that's what sampling is for — and it's opt-in through `sample_rate`.
 
 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.
 

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

@@ -6,7 +6,7 @@
 
 X-ray vision for Python code.
 
-TraceAct is a lightweight Python package for action-level tracing. It records the full story of what happens when a function runs — every step taken, resource touched, event recorded, and failure encountered — so you or your agent can understand what actually happened.
+TraceAct is a lightweight Python package for action-level tracing. It records the full story of what happens when a function runs — every step taken, resource touched, event recorded, and failure encountered — so you or your agent can understand what happened.
 
 ## Install
 
@@ -119,7 +119,7 @@ Checks Python version, that `~/.traceact` is writable, whether a viewer is alrea
 
 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.
+Wherever TraceAct might skip, drop, or truncate data, there is a signal for it. Events truncated by a budget limit set the `budget_hit` flag. Records dropped by `AsyncSink` under backpressure increment `AsyncSink.dropped`. A failure inside a sampled-out trace is recorded anyway (with `always_trace_errors`, on by default) and marked `sampled_out` so you know its detail was not captured. The one deliberate silence is a sampled-out *success* — that's what sampling is for — and it's opt-in through `sample_rate`.
 
 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.
 

{traceact-0.6.0 → traceact-0.6.2}/USAGE.md

@@ -403,7 +403,9 @@ def export_report():
 
 **Sampling and nested traces:**
 
-When `sample_rate < 1.0` and a trace is sampled out, a skip sentinel is pushed onto the ContextVar. All nested `@traced_action` calls inside that function also produce nothing. A child trace can't appear in the sink without its parent.
+When `sample_rate < 1.0` and a trace is sampled out, a skip sentinel is pushed onto the ContextVar. All nested `@traced_action` calls inside that function are suppressed with it — a successful child trace can't appear in the sink without its parent.
+
+One exception, on by default: with `always_trace_errors=True`, a failure inside a sampled-out trace still produces a record. Nothing was recording while the action ran, so the record carries the action's identity, true timing, and the error, but empty steps/events/inputs — marked `sampled_out: true` to explain the reduced detail. Each suppressed frame the exception passes through records its own failure, the same shape as an unsampled run. Set `always_trace_errors=False` to make suppression absolute.
 
 ---
 
@@ -665,13 +667,13 @@ JsonlSink("data/traces/traces.jsonl")
 JsonlSink("/absolute/path/to/traces.jsonl")
 ```
 
-**Rotation (`max_bytes`):** by default the file grows without limit. Pass `max_bytes` to cap the active file's size — once the next write would exceed it, the current file is renamed to `<path>.<UTC timestamp>` and a fresh file starts at `path`:
+**Rotation (`max_bytes`):** by default the file grows without limit. Pass `max_bytes` to cap the active file's size — once the next write would exceed it, the current file is renamed to `<stem>.<UTC timestamp><extension>` (e.g. `traces.20260726T120000000000Z.jsonl` — the extension stays last so rotated segments keep matching the `*.jsonl` pattern folder sources read) and a fresh file starts at `path`:
 
 ```python
 JsonlSink("data/traces/traces.jsonl", max_bytes=50_000_000)  # cap ~50 MB per file
 ```
 
-Rotation renames rather than deletes, so history isn't lost — it's just no longer at `path`. Point the viewer at the containing **folder** rather than the single file to see the active file plus every rotated segment merged together: `traceact view data/traces/`. TraceAct doesn't currently delete old rotated segments on a schedule; clean them up yourself (e.g. a cron job or a retention script) if disk usage matters.
+Rotation renames rather than deletes, so history isn't lost — it's just no longer at `path`. Point the viewer at the containing **folder** rather than the single file to see the active file plus every rotated segment merged together: `traceact view data/traces/`. TraceAct doesn't currently delete old rotated segments on a schedule; clean them up yourself (e.g. a cron job or a retention script) to keep disk usage down.
 
 ### ConsoleSink
 
@@ -1197,6 +1199,7 @@ The full JSON object written to the JSONL sink:
   "actor": "user",
   "status": "completed",
   "budget_hit": false,
+  "sampled_out": false,
   "started_at": "2026-07-20T08:30:00.000Z",
   "ended_at": "2026-07-20T08:30:00.015Z",
   "duration_ms": 15.2,
@@ -1250,6 +1253,8 @@ The full JSON object written to the JSONL sink:
 
 **`budget_hit`** is a separate boolean field, not a status. A trace can be `"completed"` with `budget_hit: true`, meaning the function ran to completion but TraceAct stopped recording events partway through.
 
+**`sampled_out`** is `true` only on a failure record promoted from a sampled-out trace (`always_trace_errors`, on by default — see [Sampling and nested traces](#parent-and-child-traces)). Such a record has `status: "failed"` and the error, but empty `steps`/`events`/`inputs`, because nothing was recording while the action ran. It is `false` on every normally recorded trace.
+
 ---
 
 ## Viewing traces
@@ -1385,7 +1390,7 @@ The trace log's search box and the row-limit setting both operate on the live-ta
 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.
+- 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. Because `source` and `limit` are reserved for the endpoint itself, trace fields with those two names can't be filtered over HTTP — use `TraceLog.filter()` directly for that.
 - `__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:
@@ -1523,7 +1528,7 @@ they answer separate questions:
 | `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
+Keeping them separate is deliberate: 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.
 

{traceact-0.6.0 → traceact-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traceact"
-version = "0.6.0"
+version = "0.6.2"
 description = "X-ray vision for your code. Lightweight action-level tracing for Python."
 readme = "README.md"
 requires-python = ">=3.9"

{traceact-0.6.0 → traceact-0.6.2}/tests/test_async_sink.py

@@ -203,6 +203,43 @@ class TestFaultTolerance:
             sink.close()
 
 
+# ---------------------------------------------------------------------------
+# Closed-sink contract
+# ---------------------------------------------------------------------------
+
+class TestWriteAfterClose:
+    def test_write_after_close_is_counted_dropped_not_enqueued(self):
+        inner = CaptureSink()
+        sink = AsyncSink([inner])
+        sink.write({"trace_id": "trc_1", "action": "a"})
+        sink.close()
+
+        sink.write({"trace_id": "trc_late", "action": "b"})
+        sink.write({"trace_id": "trc_later", "action": "c"})
+
+        assert sink.dropped == 2
+        assert [r["trace_id"] for r in inner.records] == ["trc_1"]
+
+    def test_write_after_close_does_not_restart_worker(self):
+        sink = AsyncSink([CaptureSink()])
+        sink.write({"trace_id": "trc_1", "action": "a"})
+        sink.close()
+        sink.write({"trace_id": "trc_late", "action": "b"})
+        assert sink._started is False
+
+    def test_close_before_any_write_still_closes(self):
+        sink = AsyncSink([CaptureSink()])
+        sink.close()
+        sink.write({"trace_id": "trc_1", "action": "a"})
+        assert sink.dropped == 1
+
+    def test_close_twice_is_safe(self):
+        sink = AsyncSink([CaptureSink()])
+        sink.write({"trace_id": "trc_1", "action": "a"})
+        sink.close()
+        sink.close()  # must not raise
+
+
 # ---------------------------------------------------------------------------
 # Exported from public API
 # ---------------------------------------------------------------------------

{traceact-0.6.0 → traceact-0.6.2}/tests/test_otlp_sink.py

@@ -140,6 +140,18 @@ class TestOtlpAttr:
 # ---------------------------------------------------------------------------
 
 class TestToOtlpSpan:
+    def test_sampled_out_true_emitted_as_attribute(self):
+        span = _to_otlp_span(_trace(sampled_out=True))
+        keys = {a["key"] for a in span["attributes"]}
+        assert "traceact.sampled_out" in keys
+
+    def test_sampled_out_false_emits_no_attribute(self):
+        # Emitted only when true, like budget_hit — a false flag on every
+        # span would be attribute noise in the collector.
+        span = _to_otlp_span(_trace(sampled_out=False))
+        keys = {a["key"] for a in span["attributes"]}
+        assert "traceact.sampled_out" not in keys
+
     def test_trace_id_field(self):
         span = _to_otlp_span(_trace())
         assert span["traceId"] == _trace_id_hex("trc_order_create")

{traceact-0.6.0 → traceact-0.6.2}/tests/test_propagation.py

@@ -514,6 +514,36 @@ class TestTraceActMiddleware(_SinkTestCase):
             self.assertEqual(rec["upstream_trace_id"], "trc_stream")
             self.assertEqual(rec["correlation_id"], "corr_s")
 
+    def test_len_preserved_for_list_bodies(self):
+        # PEP 3333 servers may special-case a body of len() == 1 (single
+        # write with Content-Length instead of chunked encoding). The
+        # streaming-safe wrapper must not hide __len__ when the body has it.
+        def app_with_list_body(environ, start_response):
+            start_response("200 OK", [])
+            return [b"whole body"]
+
+        app = TraceActMiddleware(app_with_list_body)
+        body = app(self._environ(trace_id="trc_len"), lambda s, h: None)
+        assert len(body) == 1
+        list(body)
+        body.close()
+
+    def test_no_len_on_generator_bodies(self):
+        # A generator body has no __len__; the wrapper must not grow one,
+        # since len() raising from inside would break servers that only
+        # check hasattr before calling it.
+        def streaming_app(environ, start_response):
+            start_response("200 OK", [])
+            def generate():
+                yield b"chunk"
+            return generate()
+
+        app = TraceActMiddleware(streaming_app)
+        body = app(self._environ(trace_id="trc_nolen"), lambda s, h: None)
+        assert not hasattr(body, "__len__")
+        list(body)
+        body.close()
+
     def test_flask_end_to_end(self):
         """Real Flask app behind the middleware, driven by its test client."""
         from flask import Flask

traceact-0.6.2/tests/test_sinks.py

@@ -0,0 +1,165 @@
+# test_sinks.py — JsonlSink writes, size-based rotation, and the shared
+# buffered-mode record buffer.
+
+import json
+import os
+import threading
+
+from traceact import JsonlSink, TraceLog
+
+from conftest import read_traces
+
+
+def test_jsonl_sink_appends_one_line_per_record(tmp_path):
+    path = tmp_path / "traces.jsonl"
+    sink = JsonlSink(str(path))
+
+    sink.write({"trace_id": "trc_1", "action": "a", "started_at": "t1"})
+    sink.write({"trace_id": "trc_2", "action": "a", "started_at": "t2"})
+
+    records = read_traces(path)
+    assert [r["trace_id"] for r in records] == ["trc_1", "trc_2"]
+
+
+def test_jsonl_sink_creates_parent_directories(tmp_path):
+    path = tmp_path / "nested" / "dir" / "traces.jsonl"
+    JsonlSink(str(path))  # should not raise
+
+    assert path.parent.is_dir()
+
+
+def test_max_bytes_rotates_active_file_by_renaming(tmp_path):
+    path = tmp_path / "traces.jsonl"
+    sink = JsonlSink(str(path), max_bytes=500)
+
+    for i in range(20):
+        sink.write({
+            "trace_id": f"trc_{i}", "action": "a", "started_at": f"t{i}",
+            "padding": "x" * 20,
+        })
+
+    siblings = sorted(os.listdir(tmp_path))
+    rotated = [f for f in siblings if f != "traces.jsonl"]
+
+    # More than one file exists — rotation happened at least once.
+    assert len(rotated) > 0
+    # The active file never exceeds the cap.
+    assert os.path.getsize(path) <= 500
+    # Every rotated segment is itself under the cap too (each is a snapshot
+    # of what was the active file at the moment it got rotated away).
+    for name in rotated:
+        assert os.path.getsize(tmp_path / name) <= 500
+
+    # No record was lost: total lines across all files == number written.
+    total_lines = 0
+    for name in siblings:
+        with open(tmp_path / name, encoding="utf-8") as f:
+            total_lines += sum(1 for line in f if line.strip())
+    assert total_lines == 20
+
+
+def test_no_max_bytes_never_rotates(tmp_path):
+    path = tmp_path / "traces.jsonl"
+    sink = JsonlSink(str(path))  # max_bytes=None (default)
+
+    for i in range(50):
+        sink.write({
+            "trace_id": f"trc_{i}", "action": "a", "started_at": f"t{i}",
+            "padding": "x" * 50,
+        })
+
+    assert sorted(os.listdir(tmp_path)) == ["traces.jsonl"]
+    assert len(read_traces(path)) == 50
+
+
+def test_rotated_segments_keep_jsonl_extension(tmp_path):
+    # The rotation timestamp goes before the extension, not after it. A name
+    # ending in anything other than .jsonl would be invisible to the *.jsonl
+    # folder-source pattern the viewer and TraceLog read.
+    path = tmp_path / "traces.jsonl"
+    sink = JsonlSink(str(path), max_bytes=300)
+
+    for i in range(10):
+        sink.write({
+            "trace_id": f"trc_{i}", "action": "a", "started_at": f"t{i}",
+            "padding": "x" * 20,
+        })
+
+    rotated = [f for f in os.listdir(tmp_path) if f != "traces.jsonl"]
+    assert len(rotated) > 0
+    for name in rotated:
+        assert name.endswith(".jsonl")
+        assert name.startswith("traces.")
+
+
+def test_folder_source_reads_active_plus_rotated_segments(tmp_path):
+    # End to end: every record written through a rotating sink is readable
+    # back through a folder source, active file and rotated segments together.
+    path = tmp_path / "traces.jsonl"
+    sink = JsonlSink(str(path), max_bytes=300)
+
+    for i in range(15):
+        sink.write({
+            "trace_id": f"trc_{i}", "action": "a",
+            "started_at": f"2026-07-26T00:{i:02d}:00Z",
+            "padding": "x" * 20,
+        })
+
+    assert len(os.listdir(tmp_path)) > 1  # rotation happened
+    assert TraceLog(str(tmp_path)).count() == 15
+
+
+def test_folder_source_reads_legacy_rotated_names(tmp_path):
+    # Segments rotated by versions that appended the timestamp AFTER the
+    # extension (traces.jsonl.<ts>) must stay reachable too.
+    legacy = tmp_path / "traces.jsonl.20260726T120000000000Z"
+    with open(legacy, "w", encoding="utf-8") as f:
+        f.write(json.dumps({"trace_id": "trc_old", "action": "a",
+                            "started_at": "2026-07-26T00:00:00Z"}) + "\n")
+    active = tmp_path / "traces.jsonl"
+    with open(active, "w", encoding="utf-8") as f:
+        f.write(json.dumps({"trace_id": "trc_new", "action": "a",
+                            "started_at": "2026-07-26T01:00:00Z"}) + "\n")
+
+    log = TraceLog(str(tmp_path))
+    assert log.count() == 2
+
+    from traceact.viewer.reader import SourceReader
+    assert len(SourceReader(str(tmp_path)).snapshot(10)) == 2
+
+
+def test_buffer_records_appended_during_flush_are_not_lost():
+    # flush_buffer snapshots and clears atomically; concurrent buffer_record
+    # calls during repeated flushes must never lose a record between the
+    # iterate and the clear.
+    from traceact.sinks import buffer_record, flush_buffer, _buffer
+
+    written = []
+
+    class Capture:
+        def write(self, record):
+            written.append(record)
+
+    total = 2000
+    stop = threading.Event()
+
+    def producer():
+        for i in range(total):
+            buffer_record({"n": i})
+
+    def flusher():
+        while not stop.is_set():
+            flush_buffer([Capture()])
+
+    p = threading.Thread(target=producer)
+    f = threading.Thread(target=flusher)
+    f.start()
+    p.start()
+    p.join()
+    stop.set()
+    f.join()
+    flush_buffer([Capture()])  # drain whatever the last cycle left behind
+
+    leftover = len(_buffer)
+    assert len(written) + leftover == total
+    assert leftover == 0