traceact 0.2.1__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.2.1
+Version: 0.4.0
 Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
 Author: Mohammed Shehu
 License-Expression: MIT
@@ -127,6 +127,14 @@ The source modal (click the source name in the header) lets you:
 - **Drag and drop** a `.jsonl` file — saved as a static snapshot in `~/.traceact/imports/`
 - **Type a path** — collapsible fallback for pasting an absolute path
 
+### Health checks
+
+```bash
+traceact doctor [SOURCE]
+```
+
+Checks Python version, that `~/.traceact` is writable, whether a viewer is already running, and (if `SOURCE` is given) that the file or folder parses as valid trace data. Useful for ruling out setup problems before debugging your own code. The same checks are also available from the viewer itself — Settings > **Run diagnostics**. See [USAGE.md](USAGE.md#viewing-traces) for full output and exit-code details.
+
 ## Concepts
 
 | Concept | Meaning |
@@ -135,7 +143,15 @@ The source modal (click the source name in the header) lets you:
 | `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
 
@@ -174,6 +190,13 @@ document.getElementById("btn-viewer").addEventListener("click", async () => {
 
 Python 3.9+. No runtime dependencies.
 
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
 ## Full reference
 
 See [USAGE.md](USAGE.md) for complete API documentation: all decorator and context manager parameters, helper methods (`trace.db`, `trace.http`, `trace.file`, `trace.model`), input capture, parent/child traces, sinks, budget configuration, the trace record schema, test isolation, and the full viewer server API.

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

@@ -97,6 +97,14 @@ The source modal (click the source name in the header) lets you:
 - **Drag and drop** a `.jsonl` file — saved as a static snapshot in `~/.traceact/imports/`
 - **Type a path** — collapsible fallback for pasting an absolute path
 
+### Health checks
+
+```bash
+traceact doctor [SOURCE]
+```
+
+Checks Python version, that `~/.traceact` is writable, whether a viewer is already running, and (if `SOURCE` is given) that the file or folder parses as valid trace data. Useful for ruling out setup problems before debugging your own code. The same checks are also available from the viewer itself — Settings > **Run diagnostics**. See [USAGE.md](USAGE.md#viewing-traces) for full output and exit-code details.
+
 ## Concepts
 
 | Concept | Meaning |
@@ -105,7 +113,15 @@ The source modal (click the source name in the header) lets you:
 | `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
 
@@ -144,6 +160,13 @@ document.getElementById("btn-viewer").addEventListener("click", async () => {
 
 Python 3.9+. No runtime dependencies.
 
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
 ## Full reference
 
 See [USAGE.md](USAGE.md) for complete API documentation: all decorator and context manager parameters, helper methods (`trace.db`, `trace.http`, `trace.file`, `trace.model`), input capture, parent/child traces, sinks, budget configuration, the trace record schema, test isolation, and the full viewer server API.