pyinsider 1.0.0__tar.gz

pyinsider-1.0.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# PyInsider output — traces can contain captured values, never commit them
+traces/
+*.tl
+!tests/data/*.tl
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Scratch
+_smoke.py
+tmp/

pyinsider-1.0.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to PyInsider are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-08-29
+
+Initial release.
+
+### Added
+
+- **Deterministic tracer** built on `sys.setprofile` / `threading.setprofile`,
+  recording the full call tree with nested-call and recursion handling.
+- **Typed trace model** (`ExecutionEvent`, `Trace`, `RunMetadata`) with
+  inclusive and self timings, per-thread stacks, and parent/child links.
+- **Bounded, safe value capture** that never retains references, never consumes
+  iterators, and guards every `repr()`.
+- **Exception exploration** that attributes propagating exceptions to the
+  recorded call path by walking the traceback.
+- **Versioned `.tl` trace format** — gzip-compressed JSON, schema-checked, no
+  pickle.
+- **Analysis functions**: `summarize`, `function_stats`, `hot_paths`, and
+  `compare` (recursion-aware inclusive time).
+- **CLI** (`pyinsider`) with `run`, `open`, `compare`, and `--version`;
+  preserves program exit codes and forwards arguments.
+- **Interactive local viewer** (stdlib HTTP server bound to `127.0.0.1`) with an
+  interactive timeline, virtualised call tree, source view, details panel,
+  exceptions view, hot paths, flame graph, and filtering.
+- **Public Python API**: `pyinsider.trace()` context manager and
+  `pyinsider.checkpoint()`.
+- Examples, tests, type checking, linting, and honest limitations documentation.
+
+[Unreleased]: https://github.com/Yashjindal11/pyinsider/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/Yashjindal11/pyinsider/releases/tag/v1.0.0

pyinsider-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PyInsider contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyinsider-1.0.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.5
+Name: pyinsider
+Version: 1.0.0
+Summary: See what your Python program actually did — execution tracing, timeline and call-tree exploration.
+Project-URL: Homepage, https://github.com/yashsutar/insider
+Project-URL: Repository, https://github.com/yashsutar/insider
+Project-URL: Issues, https://github.com/yashsutar/insider/issues
+Project-URL: Changelog, https://github.com/yashsutar/insider/blob/main/CHANGELOG.md
+Author: PyInsider contributors
+License: MIT License
+        
+        Copyright (c) 2026 PyInsider contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: call-graph,debugging,developer-tools,flame-graph,observability,performance,profiler,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PyInsider
+
+**See what your Python program actually did.**
+
+PyInsider records the real execution of a Python program — every function call,
+how long each took, how calls nested, what arguments went in, what came back,
+and the exact path that led to an exception — and lets you explore it afterward
+in an interactive local viewer.
+
+It is not a profiler that gives you aggregate numbers, and it is not a debugger
+that stops the world. It is an **execution recorder**: run once, then look at
+what happened.
+
+```console
+$ pyinsider run examples/nested_calls.py
+  recorded 22 calls · max depth 5 · 3.14 ms
+  trace written to traces/run-2026-08-29-001.tl
+
+$ pyinsider open traces/run-2026-08-29-001.tl
+  serving viewer at http://127.0.0.1:8721  (Ctrl-C to stop)
+```
+
+- **Deterministic, not sampled.** Every call is recorded via CPython's
+  `sys.setprofile` hook — no statistical guessing.
+- **No AI, no telemetry, no cloud.** Everything runs and stays on your machine.
+  The viewer binds only to `127.0.0.1`. Nothing is uploaded, ever.
+- **Local-first trace files.** A run produces a single versioned `.tl` file you
+  can save, diff, and share.
+- **Four clean layers.** The tracing and analysis engines have no dependency on
+  the UI, so you can use PyInsider entirely from Python if you prefer.
+
+---
+
+## Installation
+
+Requires **Python 3.10+**. PyInsider has **no runtime dependencies**.
+
+```console
+pip install pyinsider
+```
+
+Or from a clone, for development:
+
+```console
+git clone https://github.com/Yashjindal11/pyinsider.git
+cd pyinsider
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+Record a script and open the result:
+
+```console
+pyinsider run examples/simple.py
+pyinsider open traces/          # opens the most recent trace in your browser
+```
+
+Capture arguments and return values too:
+
+```console
+pyinsider run examples/complex_values.py --detail
+```
+
+Forward arguments to your program (everything after `--` goes to the script):
+
+```console
+pyinsider run app.py -- --verbose input.csv
+```
+
+Prefer to stay in the terminal? Skip the browser:
+
+```console
+pyinsider open traces/run-2026-08-29-001.tl --summary   # top-level summary
+pyinsider open traces/run-2026-08-29-001.tl --tree      # printed call tree
+```
+
+## Using it from Python
+
+The recorder is a plain context manager. The UI is optional.
+
+```python
+import pyinsider
+
+with pyinsider.trace() as run:
+    result = do_some_work()
+
+trace = run.result
+run.save("work.tl")
+
+# Analyse without any UI:
+for stat in pyinsider.hot_paths(trace):
+    print(stat.key, stat.inclusive_ms)
+```
+
+`pyinsider.checkpoint("loaded config")` drops a labelled marker into the active
+trace so you can find a moment on the timeline later.
+
+## The CLI
+
+```
+pyinsider run     <script.py | -m module> [--detail] [-o FILE] [-- args...]
+pyinsider open    <file.tl | dir> [--summary | --tree | --no-browser]
+pyinsider compare <before.tl> <after.tl>
+pyinsider --version
+```
+
+- `run` preserves your program's exit code and forwards its arguments, so it is
+  safe to drop in front of an existing command.
+- `open` accepts either a file or a directory (it picks the newest `.tl`).
+- `compare` diffs two runs and highlights functions that got slower, faster,
+  appeared, or disappeared.
+
+Colour output honours `NO_COLOR`, `TERM=dumb`, and non-TTY pipes.
+
+## Trace files (`.tl`)
+
+A `.tl` file is gzip-compressed JSON with an explicit schema version. It
+contains the full call tree, timings (nanoseconds relative to run start),
+captured values, exception information, and run metadata (Python version,
+platform, detail level). There is **no pickle** and no code in a trace file —
+it is safe to open and inspect by hand.
+
+Trace files are forward-compatible within a major schema version and are
+rejected if the major version is newer than the reader understands.
+
+## The viewer
+
+`pyinsider open` starts a tiny local web app (stdlib only, `127.0.0.1`) that
+shows:
+
+- an interactive, zoomable **timeline** of the run,
+- a virtualised **call tree** with inclusive/self timings,
+- a **source view** pointing at where each call was defined,
+- a **details** panel with arguments and return values,
+- an **exceptions** view with the call path that led to each failure,
+- **hot paths** and an aggregated **flame graph**,
+- filtering by module, name, duration, and project-vs-library code.
+
+## Architecture
+
+PyInsider is built in four layers, each depending only on the ones below it:
+
+```
+  cli / api / viewer        <- presentation (never imported by the engine)
+        |
+  trace model + analysis    <- Trace, function_stats, hot_paths, compare
+        |
+  trace events              <- typed, serialisable ExecutionEvent records
+        |
+  tracer / collector        <- sys.setprofile instrumentation
+```
+
+The tracer and analysis code never import the CLI or viewer, so the engine is
+usable as a library and the UI can be replaced without touching the core.
+
+## Limitations
+
+PyInsider is deliberately honest about what it can and cannot see. Highlights:
+
+- **Caught exceptions** are attributed by walking the exception's traceback, so
+  only exceptions that propagate are marked; an exception swallowed by a
+  `try/except` is not attributed to the function that raised it.
+- **C-level functions** (built-ins, C extensions) are not recorded as calls.
+- Timings include tracing overhead; treat them as *relative*, not absolute.
+- Async and multi-threaded code is recorded per-thread/per-task but concurrency
+  interleaving is simplified.
+- Subprocesses are invisible to the tracer.
+
+See [`docs/limitations.md`](docs/limitations.md) for the full, detailed list —
+it is required reading before you trust a number.
+
+## Development
+
+```console
+pip install -e ".[dev]"
+pytest                 # run the test suite
+ruff check pyinsider   # lint
+mypy pyinsider         # type-check
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow and project layout.
+
+## License
+
+[MIT](LICENSE). PyInsider is free and open source.

pyinsider-1.0.0/README.md

@@ -0,0 +1,186 @@
+# PyInsider
+
+**See what your Python program actually did.**
+
+PyInsider records the real execution of a Python program — every function call,
+how long each took, how calls nested, what arguments went in, what came back,
+and the exact path that led to an exception — and lets you explore it afterward
+in an interactive local viewer.
+
+It is not a profiler that gives you aggregate numbers, and it is not a debugger
+that stops the world. It is an **execution recorder**: run once, then look at
+what happened.
+
+```console
+$ pyinsider run examples/nested_calls.py
+  recorded 22 calls · max depth 5 · 3.14 ms
+  trace written to traces/run-2026-08-29-001.tl
+
+$ pyinsider open traces/run-2026-08-29-001.tl
+  serving viewer at http://127.0.0.1:8721  (Ctrl-C to stop)
+```
+
+- **Deterministic, not sampled.** Every call is recorded via CPython's
+  `sys.setprofile` hook — no statistical guessing.
+- **No AI, no telemetry, no cloud.** Everything runs and stays on your machine.
+  The viewer binds only to `127.0.0.1`. Nothing is uploaded, ever.
+- **Local-first trace files.** A run produces a single versioned `.tl` file you
+  can save, diff, and share.
+- **Four clean layers.** The tracing and analysis engines have no dependency on
+  the UI, so you can use PyInsider entirely from Python if you prefer.
+
+---
+
+## Installation
+
+Requires **Python 3.10+**. PyInsider has **no runtime dependencies**.
+
+```console
+pip install pyinsider
+```
+
+Or from a clone, for development:
+
+```console
+git clone https://github.com/Yashjindal11/pyinsider.git
+cd pyinsider
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+Record a script and open the result:
+
+```console
+pyinsider run examples/simple.py
+pyinsider open traces/          # opens the most recent trace in your browser
+```
+
+Capture arguments and return values too:
+
+```console
+pyinsider run examples/complex_values.py --detail
+```
+
+Forward arguments to your program (everything after `--` goes to the script):
+
+```console
+pyinsider run app.py -- --verbose input.csv
+```
+
+Prefer to stay in the terminal? Skip the browser:
+
+```console
+pyinsider open traces/run-2026-08-29-001.tl --summary   # top-level summary
+pyinsider open traces/run-2026-08-29-001.tl --tree      # printed call tree
+```
+
+## Using it from Python
+
+The recorder is a plain context manager. The UI is optional.
+
+```python
+import pyinsider
+
+with pyinsider.trace() as run:
+    result = do_some_work()
+
+trace = run.result
+run.save("work.tl")
+
+# Analyse without any UI:
+for stat in pyinsider.hot_paths(trace):
+    print(stat.key, stat.inclusive_ms)
+```
+
+`pyinsider.checkpoint("loaded config")` drops a labelled marker into the active
+trace so you can find a moment on the timeline later.
+
+## The CLI
+
+```
+pyinsider run     <script.py | -m module> [--detail] [-o FILE] [-- args...]
+pyinsider open    <file.tl | dir> [--summary | --tree | --no-browser]
+pyinsider compare <before.tl> <after.tl>
+pyinsider --version
+```
+
+- `run` preserves your program's exit code and forwards its arguments, so it is
+  safe to drop in front of an existing command.
+- `open` accepts either a file or a directory (it picks the newest `.tl`).
+- `compare` diffs two runs and highlights functions that got slower, faster,
+  appeared, or disappeared.
+
+Colour output honours `NO_COLOR`, `TERM=dumb`, and non-TTY pipes.
+
+## Trace files (`.tl`)
+
+A `.tl` file is gzip-compressed JSON with an explicit schema version. It
+contains the full call tree, timings (nanoseconds relative to run start),
+captured values, exception information, and run metadata (Python version,
+platform, detail level). There is **no pickle** and no code in a trace file —
+it is safe to open and inspect by hand.
+
+Trace files are forward-compatible within a major schema version and are
+rejected if the major version is newer than the reader understands.
+
+## The viewer
+
+`pyinsider open` starts a tiny local web app (stdlib only, `127.0.0.1`) that
+shows:
+
+- an interactive, zoomable **timeline** of the run,
+- a virtualised **call tree** with inclusive/self timings,
+- a **source view** pointing at where each call was defined,
+- a **details** panel with arguments and return values,
+- an **exceptions** view with the call path that led to each failure,
+- **hot paths** and an aggregated **flame graph**,
+- filtering by module, name, duration, and project-vs-library code.
+
+## Architecture
+
+PyInsider is built in four layers, each depending only on the ones below it:
+
+```
+  cli / api / viewer        <- presentation (never imported by the engine)
+        |
+  trace model + analysis    <- Trace, function_stats, hot_paths, compare
+        |
+  trace events              <- typed, serialisable ExecutionEvent records
+        |
+  tracer / collector        <- sys.setprofile instrumentation
+```
+
+The tracer and analysis code never import the CLI or viewer, so the engine is
+usable as a library and the UI can be replaced without touching the core.
+
+## Limitations
+
+PyInsider is deliberately honest about what it can and cannot see. Highlights:
+
+- **Caught exceptions** are attributed by walking the exception's traceback, so
+  only exceptions that propagate are marked; an exception swallowed by a
+  `try/except` is not attributed to the function that raised it.
+- **C-level functions** (built-ins, C extensions) are not recorded as calls.
+- Timings include tracing overhead; treat them as *relative*, not absolute.
+- Async and multi-threaded code is recorded per-thread/per-task but concurrency
+  interleaving is simplified.
+- Subprocesses are invisible to the tracer.
+
+See [`docs/limitations.md`](docs/limitations.md) for the full, detailed list —
+it is required reading before you trust a number.
+
+## Development
+
+```console
+pip install -e ".[dev]"
+pytest                 # run the test suite
+ruff check pyinsider   # lint
+mypy pyinsider         # type-check
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow and project layout.
+
+## License
+
+[MIT](LICENSE). PyInsider is free and open source.

pyinsider-1.0.0/docs/limitations.md

@@ -0,0 +1,181 @@
+# Limitations & honesty
+
+PyInsider records a great deal of what a Python program does, but it cannot see
+everything, and some of what it records is an approximation. This document
+states, plainly, where the boundaries are. Read it before you trust a number.
+
+The guiding principle: **it is better to record less and be correct than to
+guess and be wrong.** Where PyInsider cannot know something reliably, it does
+not pretend to.
+
+---
+
+## Instrumentation mechanism
+
+PyInsider records calls using CPython's `sys.setprofile` hook (and
+`threading.setprofile` for other threads). This has direct consequences.
+
+### C-level functions are not recorded as call events
+
+`sys.setprofile` reports `c_call` / `c_return` events for built-ins and C
+extension functions, but PyInsider does **not** record these as tree nodes. A
+call into `len()`, `numpy.dot()`, `json.loads()`, or any C function appears as
+time spent *inside its Python caller*, not as a separate node. This keeps the
+tree meaningful (you see your code) but means:
+
+- time spent in C is attributed to the nearest Python frame, and
+- you cannot expand a C function to see what it did (there is nothing to see —
+  the interpreter does not expose C-internal frames).
+
+### Only Python-level frames exist
+
+Generator, coroutine, and comprehension frames are Python frames and are
+recorded. Anything implemented in C (including much of the standard library's
+hot paths) is not.
+
+### Profile hooks are per-interpreter and can be displaced
+
+If your program (or another library) installs its own `sys.setprofile` handler
+while PyInsider is active, recording for the affected scope may stop or be
+disturbed. PyInsider restores the previous hook on exit but does not fight other
+tools for the slot.
+
+---
+
+## Timing
+
+### Timings include tracing overhead
+
+Every recorded call runs PyInsider's hook on entry and exit. That work is
+included in the elapsed time of the surrounding frames. As a result:
+
+- **Absolute durations are inflated** relative to an untraced run, especially
+  for programs that make many small, fast calls.
+- **Treat timings as relative,** not as ground truth. "Function A took twice as
+  long as function B in this trace" is trustworthy; "function A takes exactly
+  1.3 ms in production" is not.
+
+The overhead is roughly proportional to the number of calls, not to wall-clock
+time, so call-heavy code is affected most. Detail level `--detail` (value
+capture) adds further overhead.
+
+### Self time is inclusive-minus-children
+
+"Self time" is computed as a frame's inclusive time minus the inclusive time of
+its recorded children. Because C calls are not recorded as children, time spent
+in C is counted as *self* time of the calling Python frame. This is usually what
+you want, but it means self time is not "time spent on this exact line."
+
+### Line-level attribution
+
+PyInsider records where each function was *defined* (`co_firstlineno`) and the
+call structure, not a per-line execution profile. It does not claim to tell you
+which line inside a function was slow. If a source location is shown, it points
+at the function, not the hot statement.
+
+---
+
+## Exceptions
+
+### Only propagating exceptions are attributed
+
+`sys.setprofile` cannot reliably tell you, at return time, whether a frame is
+unwinding because of an exception — `sys.exc_info()` returns `None` during the
+normal return path of the profile hook (verified empirically on CPython 3.10–
+3.11). PyInsider therefore does **not** try to detect exceptions on every
+return.
+
+Instead, when an exception propagates out of a traced block, PyInsider walks the
+exception's authoritative traceback and matches each traceback frame back to a
+recorded call. This gives an accurate failing call path — but only for
+exceptions that actually escape.
+
+**Consequence:** an exception that is raised and then caught inside a
+`try/except` never reaches the traceback PyInsider inspects, so the function
+that raised it is **not** marked as failing. This is a deliberate correctness
+choice: PyInsider will not guess.
+
+### Frame matching and recursion
+
+When matching traceback frames to recorded events, PyInsider prefers a frame
+that is a child of the previously matched frame. This disambiguates recursion
+correctly in the common case, but pathological recursive/reentrant patterns
+could in principle be matched to the wrong recorded event.
+
+---
+
+## Concurrency
+
+### Threads
+
+Threads started while tracing is active are recorded via
+`threading.setprofile`, with a separate call stack per thread. Each event
+carries its thread id and name. However:
+
+- Threads that were **already running** before tracing started may not be
+  instrumented until they make their next call through the hook.
+- The timeline flattens concurrent activity onto a shared time axis; it shows
+  *when* things happened per thread, but does not model lock contention or true
+  parallel overlap semantics.
+
+### Async / coroutines
+
+Coroutine frames are recorded and tagged with a synthetic task id derived from
+the frame identity. This lets you see coroutine calls, but PyInsider does not
+reconstruct the full `await` scheduling graph of an event loop. Suspended-and-
+resumed coroutines are approximated, not perfectly serialized.
+
+---
+
+## Process boundaries
+
+### Subprocesses are invisible
+
+PyInsider traces the interpreter it runs in. Code executed in a **subprocess**
+(via `subprocess`, `multiprocessing` spawn, `os.exec*`, etc.) runs in a
+different interpreter and is not recorded. You would need to run PyInsider inside
+that child process separately.
+
+### `os._exit` and hard crashes
+
+If the program calls `os._exit()` or is terminated by a signal / segfault, the
+trace is not finalised and may be incomplete or unsaved. A normal `sys.exit()`
+(`SystemExit`) is handled cleanly and the exit code is preserved.
+
+---
+
+## Value capture
+
+When value capture is enabled (`--detail`), PyInsider captures a **bounded,
+best-effort representation** of arguments and return values:
+
+- It never retains references to your objects; it snapshots a string/shape
+  summary immediately.
+- It never consumes iterators or generators to inspect them.
+- Every `repr()` call is guarded; an object whose `__repr__` raises is recorded
+  as an error placeholder rather than crashing the trace.
+- Large containers and strings are truncated; deep/cyclic structures are cut off
+  with a recursion marker.
+
+Because capture is bounded and best-effort, a captured value is a **faithful
+summary, not a guaranteed round-trippable copy** of the original object.
+
+---
+
+## Bounds and dropping
+
+Recording is capped by `max_events` (see `TracerConfig`). If a run exceeds the
+cap, further events are dropped and the count of dropped events is recorded in
+the trace metadata. A trace that hit the cap is truncated, not corrupt — but it
+is not the whole story.
+
+---
+
+## Summary
+
+PyInsider is an honest recorder of Python-level execution. It is excellent for
+understanding *what your code did and in what order*, for finding *which of your
+functions dominated a run*, and for seeing *the call path to a failure*. It is
+**not** a substitute for a sampling profiler when you need low-overhead absolute
+timings, nor for a line profiler when you need per-statement cost, nor for a
+debugger when you need to inspect live state.