sensorium-trace 0.18.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sensorium/__init__.py +0 -0
- sensorium/__main__.py +4 -0
- sensorium/_c/rt/sensorium_c_rt.c +1446 -0
- sensorium/_typescript/package-lock.json +68 -0
- sensorium/_typescript/package.json +39 -0
- sensorium/_typescript/src/bindings.mjs +792 -0
- sensorium/_typescript/src/cap.mjs +227 -0
- sensorium/_typescript/src/capabilities.mjs +40 -0
- sensorium/_typescript/src/dbg.mjs +348 -0
- sensorium/_typescript/src/escape.mjs +351 -0
- sensorium/_typescript/src/focus.mjs +135 -0
- sensorium/_typescript/src/hook.mjs +127 -0
- sensorium/_typescript/src/index.mjs +1 -0
- sensorium/_typescript/src/naming.mjs +63 -0
- sensorium/_typescript/src/positions.mjs +37 -0
- sensorium/_typescript/src/probe.mjs +246 -0
- sensorium/_typescript/src/qualname.mjs +236 -0
- sensorium/_typescript/src/redact.mjs +711 -0
- sensorium/_typescript/src/register.mjs +15 -0
- sensorium/_typescript/src/resolve.mjs +260 -0
- sensorium/_typescript/src/rt.mjs +798 -0
- sensorium/_typescript/src/setup.mjs +11 -0
- sensorium/_typescript/src/tally.mjs +164 -0
- sensorium/_typescript/src/tasks.mjs +175 -0
- sensorium/_typescript/src/transform.mjs +800 -0
- sensorium/_typescript/src/vite.mjs +99 -0
- sensorium/c/__init__.py +8 -0
- sensorium/c/cc.py +612 -0
- sensorium/c/cli.py +60 -0
- sensorium/c/convert.py +669 -0
- sensorium/c/decode.py +300 -0
- sensorium/c/driver.py +365 -0
- sensorium/c/dwarf.py +706 -0
- sensorium/c/format.py +271 -0
- sensorium/c/pkg.py +187 -0
- sensorium/c/plan.py +277 -0
- sensorium/cli.py +140 -0
- sensorium/driver.py +47 -0
- sensorium/exit.py +33 -0
- sensorium/invocations.py +83 -0
- sensorium/limits.py +253 -0
- sensorium/mcp/__init__.py +0 -0
- sensorium/mcp/audit.py +162 -0
- sensorium/mcp/child.py +240 -0
- sensorium/mcp/cmd.py +101 -0
- sensorium/mcp/jsonrpc.py +172 -0
- sensorium/mcp/result.py +187 -0
- sensorium/mcp/schema.py +390 -0
- sensorium/mcp/server.py +493 -0
- sensorium/mcp/tools.py +299 -0
- sensorium/paths.py +80 -0
- sensorium/query/__init__.py +0 -0
- sensorium/query/caps.py +150 -0
- sensorium/query/dbg_dialects.py +64 -0
- sensorium/query/diff_cmd.py +748 -0
- sensorium/query/diff_notes.py +117 -0
- sensorium/query/exceptions_c.py +263 -0
- sensorium/query/exceptions_cmd.py +788 -0
- sensorium/query/exceptions_group.py +571 -0
- sensorium/query/exceptions_invocation.py +487 -0
- sensorium/query/exceptions_rust.py +683 -0
- sensorium/query/exceptions_typescript.py +688 -0
- sensorium/query/expr.py +606 -0
- sensorium/query/failures_cmd.py +306 -0
- sensorium/query/flow_cmd.py +778 -0
- sensorium/query/flow_report.py +128 -0
- sensorium/query/flow_values.py +195 -0
- sensorium/query/fmt.py +280 -0
- sensorium/query/frame_cmd.py +237 -0
- sensorium/query/grep_cmd.py +156 -0
- sensorium/query/help.py +18 -0
- sensorium/query/info_cmd.py +527 -0
- sensorium/query/info_rust.py +214 -0
- sensorium/query/info_typescript.py +261 -0
- sensorium/query/js_inspect.py +394 -0
- sensorium/query/moves.py +254 -0
- sensorium/query/redact_cmd.py +304 -0
- sensorium/query/refocus_cmd.py +661 -0
- sensorium/query/refocus_env.py +493 -0
- sensorium/query/refocus_facts.py +269 -0
- sensorium/query/refocus_licence.py +187 -0
- sensorium/query/refocus_report.py +327 -0
- sensorium/query/refocus_rust.py +537 -0
- sensorium/query/refocus_threads.py +197 -0
- sensorium/query/refocus_typescript.py +756 -0
- sensorium/query/refocus_world.py +666 -0
- sensorium/query/runs_cmd.py +213 -0
- sensorium/query/rust_debug.py +176 -0
- sensorium/query/sites.py +171 -0
- sensorium/query/tree_cmd.py +511 -0
- sensorium/query/tree_threads.py +168 -0
- sensorium/query/vocab.py +723 -0
- sensorium/query/watch_cmd.py +657 -0
- sensorium/record/__init__.py +0 -0
- sensorium/record/boot.py +797 -0
- sensorium/record/boot_io.py +141 -0
- sensorium/record/budget.py +135 -0
- sensorium/record/capture.py +433 -0
- sensorium/record/children.py +755 -0
- sensorium/record/children_merge.py +179 -0
- sensorium/record/elide.py +55 -0
- sensorium/record/fingerprint.py +26 -0
- sensorium/record/thread_starts.py +261 -0
- sensorium/record/tracer.py +798 -0
- sensorium/record/tracer_exc.py +199 -0
- sensorium/record/tracer_frames.py +618 -0
- sensorium/redact.py +304 -0
- sensorium/redact_content.py +156 -0
- sensorium/redact_key.py +317 -0
- sensorium/redact_store.py +502 -0
- sensorium/redact_values.py +433 -0
- sensorium/store/__init__.py +0 -0
- sensorium/store/db.py +284 -0
- sensorium/store/gc.py +360 -0
- sensorium/store/payloads.py +69 -0
- sensorium/store/reader.py +438 -0
- sensorium/store/writer.py +283 -0
- sensorium/ts/__init__.py +10 -0
- sensorium/ts/build.py +783 -0
- sensorium/ts/cli.py +130 -0
- sensorium/ts/driver.py +472 -0
- sensorium/ts/focus.py +146 -0
- sensorium/ts/harness.py +314 -0
- sensorium/ts/ingest.py +380 -0
- sensorium/ts/invocation.py +252 -0
- sensorium/ts/pkg.py +167 -0
- sensorium/ts/redaction.py +64 -0
- sensorium/ts/spool.py +168 -0
- sensorium/ts/truncation.py +81 -0
- sensorium/ts/wrapper.py +255 -0
- sensorium_trace-0.18.2.dist-info/METADATA +245 -0
- sensorium_trace-0.18.2.dist-info/RECORD +135 -0
- sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
- sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
- sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
sensorium/ts/pkg.py
ADDED
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
"""Where the Node library is, and whether this box can run it.
|
|
2
|
+
|
|
3
|
+
Two questions the driver has to settle BEFORE it mints an invocation or
|
|
4
|
+
spawns anything, because both of them have answers a recording cannot
|
|
5
|
+
recover from: a Node older than the one the recorder was measured on, and a
|
|
6
|
+
package that has never been installed. Each is a refusal with a sentence
|
|
7
|
+
naming the fix, and neither leaves a spool directory behind.
|
|
8
|
+
|
|
9
|
+
The package's location is one rule in one place (`locate`). `SENSORIUM_TS_PKG`
|
|
10
|
+
names it when the library lives somewhere else -- a test pointing at an empty
|
|
11
|
+
directory, a checkout beside a wheel -- and otherwise it is the `typescript/`
|
|
12
|
+
directory beside `src/` when this module was imported from a checkout, or the
|
|
13
|
+
`sensorium/_typescript` tree a wheel ships next to the package. The same
|
|
14
|
+
variable is exported to the harness, so what the driver checked and what the
|
|
15
|
+
loader hook resolves are the same directory by construction.
|
|
16
|
+
"""
|
|
17
|
+
import os
|
|
18
|
+
import re
|
|
19
|
+
import subprocess
|
|
20
|
+
from pathlib import Path
|
|
21
|
+
|
|
22
|
+
import sensorium
|
|
23
|
+
|
|
24
|
+
#: The variable that names the package, and the only one. Read here and
|
|
25
|
+
#: exported to the harness by the driver.
|
|
26
|
+
ENV_VAR = "SENSORIUM_TS_PKG"
|
|
27
|
+
|
|
28
|
+
#: The Node the recorder was measured on (D2). Below it nothing was
|
|
29
|
+
#: measured, so nothing is claimed: the driver refuses rather than record a
|
|
30
|
+
#: run whose async semantics it has never seen.
|
|
31
|
+
NODE_FLOOR = 24
|
|
32
|
+
|
|
33
|
+
#: The one file whose presence says the package has been installed. The
|
|
34
|
+
#: transform bare-imports `magic-string`, so its absence is not a missing
|
|
35
|
+
#: nicety -- it is an `ERR_MODULE_NOT_FOUND` thrown deep inside a Vite
|
|
36
|
+
#: transform, minutes later, about a module the consumer never mentioned.
|
|
37
|
+
INSTALLED = Path("node_modules") / "magic-string"
|
|
38
|
+
|
|
39
|
+
#: The one module resolved from the CONSUMER's tree rather than this
|
|
40
|
+
#: package's. The transform positions itself against the AST the consumer's
|
|
41
|
+
#: own build produces, so it parses with the compiler that build trusts.
|
|
42
|
+
CONSUMER_DEP = "typescript"
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class PackageError(Exception):
|
|
46
|
+
"""The Node side cannot be used, and the sentence says what to do."""
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def locate() -> Path:
|
|
50
|
+
"""The `sensorium-ts` package directory.
|
|
51
|
+
|
|
52
|
+
An EMPTY variable is not a location -- `or` and not a presence test, so
|
|
53
|
+
`SENSORIUM_TS_PKG=` falls through rather than resolving to the process's
|
|
54
|
+
working directory.
|
|
55
|
+
|
|
56
|
+
A checkout (and an editable install of one) keeps the Node package at
|
|
57
|
+
`typescript/` beside `src/`. A non-editable install has no such
|
|
58
|
+
directory: `parents[2]` of an installed `sensorium/__init__.py` is the
|
|
59
|
+
virtualenv, not the repository. The wheel carries the Node sources at
|
|
60
|
+
`sensorium/_typescript`, which is the location a `git+https` install
|
|
61
|
+
can actually see. `node_modules` is not part of that tree; `check`
|
|
62
|
+
still refuses until `npm ci --prefix` that directory.
|
|
63
|
+
"""
|
|
64
|
+
env = os.environ.get(ENV_VAR)
|
|
65
|
+
if env:
|
|
66
|
+
return Path(env)
|
|
67
|
+
here = Path(sensorium.__file__).resolve()
|
|
68
|
+
checkout = here.parents[2] / "typescript"
|
|
69
|
+
if (checkout / "package.json").is_file():
|
|
70
|
+
return checkout
|
|
71
|
+
installed = here.parent / "_typescript"
|
|
72
|
+
if (installed / "package.json").is_file():
|
|
73
|
+
return installed
|
|
74
|
+
raise PackageError(
|
|
75
|
+
"cannot find the recorder's Node package. A checkout keeps it at "
|
|
76
|
+
"typescript/ beside src/. A wheel install ships it inside the "
|
|
77
|
+
"sensorium package, at sensorium/_typescript. Set "
|
|
78
|
+
f"{ENV_VAR} to the directory that contains package.json.")
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def check(pkg: Path) -> None:
|
|
82
|
+
"""Refuse a package whose dependencies were never installed."""
|
|
83
|
+
if not (pkg / INSTALLED).is_dir():
|
|
84
|
+
raise PackageError(
|
|
85
|
+
f"the recorder's Node package at {pkg} has no {INSTALLED}: "
|
|
86
|
+
f"install it with `npm ci --prefix {pkg}`")
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def check_root(root: Path) -> None:
|
|
90
|
+
"""Refuse a project whose own TypeScript the transform cannot resolve.
|
|
91
|
+
|
|
92
|
+
The transform parses with the CONSUMER's compiler and never with this
|
|
93
|
+
package's: the loader hook and the Vite plugin both `require` it from
|
|
94
|
+
the ROOT, because the AST a recorder positions itself against has to be
|
|
95
|
+
the one the consumer's own build produces. Absent, that surfaced as an
|
|
96
|
+
`ERR_MODULE_NOT_FOUND` thrown inside a transform, minutes into a run,
|
|
97
|
+
about a module the consumer never mentioned -- the same failure shape
|
|
98
|
+
`check` above exists to stop for `magic-string`.
|
|
99
|
+
|
|
100
|
+
Resolved the way NODE resolves it from `<root>/package.json`:
|
|
101
|
+
`<root>/node_modules`, then each parent's. A workspace package whose
|
|
102
|
+
dependency is hoisted to the repository root has no `node_modules` of
|
|
103
|
+
its own and runs fine, and refusing it for a directory Node was never
|
|
104
|
+
going to look in would be a refusal about this check, not about the run.
|
|
105
|
+
"""
|
|
106
|
+
root = Path(root)
|
|
107
|
+
for directory in (root, *root.parents):
|
|
108
|
+
if (directory / "node_modules" / CONSUMER_DEP
|
|
109
|
+
/ "package.json").is_file():
|
|
110
|
+
return
|
|
111
|
+
raise PackageError(
|
|
112
|
+
f"{root} has no {CONSUMER_DEP} in node_modules: the transform "
|
|
113
|
+
f"parses with the consumer's own compiler, and there is none here "
|
|
114
|
+
f"to parse with -- install it with `npm install --save-dev "
|
|
115
|
+
f"{CONSUMER_DEP}`")
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def version(pkg: Path) -> str:
|
|
119
|
+
"""The package's own version, for the `recorder` a spool without one
|
|
120
|
+
falls back to (R5).
|
|
121
|
+
|
|
122
|
+
Read as text rather than as JSON, and never an error: this is a
|
|
123
|
+
FALLBACK, used only for a spool whose BOOT record did not name its own
|
|
124
|
+
writer, and a manifest this cannot read is not a reason to refuse a
|
|
125
|
+
recording that would otherwise happen.
|
|
126
|
+
"""
|
|
127
|
+
try:
|
|
128
|
+
text = (pkg / "package.json").read_text(encoding="utf-8")
|
|
129
|
+
except OSError:
|
|
130
|
+
return "unknown"
|
|
131
|
+
m = re.search(r'"version"\s*:\s*"([^"]*)"', text)
|
|
132
|
+
return m.group(1) if m else "unknown"
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def node_version(node: str = "node") -> tuple[str, tuple[int, ...]]:
|
|
136
|
+
"""What `node --version` says, as it said it and as numbers.
|
|
137
|
+
|
|
138
|
+
The reported string is carried into the trace verbatim (`meta.node` is
|
|
139
|
+
what the container itself reports; this is what the DRIVER saw), so it
|
|
140
|
+
is returned beside the parse rather than replaced by it.
|
|
141
|
+
"""
|
|
142
|
+
try:
|
|
143
|
+
out = subprocess.run([node, "--version"], capture_output=True,
|
|
144
|
+
text=True)
|
|
145
|
+
except OSError:
|
|
146
|
+
raise PackageError(
|
|
147
|
+
f"cannot run `{node} --version`: this recorder drives node, and "
|
|
148
|
+
f"Node {NODE_FLOOR} or newer is the version it was measured on"
|
|
149
|
+
) from None
|
|
150
|
+
reported = out.stdout.strip()
|
|
151
|
+
parts = tuple(int(n) for n in re.findall(r"\d+", reported)[:3])
|
|
152
|
+
if out.returncode != 0 or not parts:
|
|
153
|
+
raise PackageError(
|
|
154
|
+
f"`{node} --version` answered nothing this recorder can read "
|
|
155
|
+
f"({reported!r}): it needs Node {NODE_FLOOR} or newer")
|
|
156
|
+
return reported, parts
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def check_node(node: str = "node") -> str:
|
|
160
|
+
"""The Node version string, or a refusal naming the floor."""
|
|
161
|
+
reported, parts = node_version(node)
|
|
162
|
+
if parts[0] < NODE_FLOOR:
|
|
163
|
+
raise PackageError(
|
|
164
|
+
f"node {reported} is below this recorder's floor of "
|
|
165
|
+
f"{NODE_FLOOR}: Node {NODE_FLOOR} is the version its async "
|
|
166
|
+
"model was measured on, and nothing older was")
|
|
167
|
+
return reported
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
"""Which hand applied rule v1 to a TypeScript spool, and whether it runs.
|
|
2
|
+
|
|
3
|
+
Two decisions, both read off the BOOT record and both taken ONCE per spool,
|
|
4
|
+
because every value site in `build.py` needs the same answer:
|
|
5
|
+
|
|
6
|
+
* **`rule_runs`** -- whether rule v1 applies to this spool's captures at all
|
|
7
|
+
(B26). A recording made with the rule off is converted as it was written.
|
|
8
|
+
* **`ran_the_value_rule`** -- whether the RECORDER already applied the NAME
|
|
9
|
+
half, which decides both what `build.py` has left to do and the `by` word
|
|
10
|
+
the trace carries (B2).
|
|
11
|
+
|
|
12
|
+
Its own module for the reason `cargo-sensorium`'s `convert/redaction.rs` is
|
|
13
|
+
one: the converter's mapping is long enough already, and this is the part of
|
|
14
|
+
it that has to be read against the design's §5.4 rather than against the
|
|
15
|
+
wire.
|
|
16
|
+
"""
|
|
17
|
+
import re
|
|
18
|
+
|
|
19
|
+
#: The `sensorium-ts` the value half of rule v1 shipped in (B2). A BOOT
|
|
20
|
+
#: below it says `mode: "on"` about its ENVIRONMENT and nothing else, so the
|
|
21
|
+
#: converter runs the name rule over its captures itself.
|
|
22
|
+
VALUES_FROM = (0, 6, 0)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def ran_the_value_rule(boot: dict) -> bool:
|
|
26
|
+
"""Whether the RECORDER applied rule v1 to its own captures (B2).
|
|
27
|
+
|
|
28
|
+
Two facts together: the BOOT says `mode: "on"`, and it was written by a
|
|
29
|
+
recorder that HAD the value rules. 0.5.0 says `mode: "on"` about its
|
|
30
|
+
environment while its captures are plaintext, and a converter that
|
|
31
|
+
trusted the word alone would pass those through as recorded.
|
|
32
|
+
"""
|
|
33
|
+
recorded = boot.get("redaction")
|
|
34
|
+
return (isinstance(recorded, dict) and recorded.get("mode") == "on"
|
|
35
|
+
and version_tuple(boot.get("version")) >= VALUES_FROM)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def rule_runs(boot: dict) -> bool:
|
|
39
|
+
"""Whether rule v1 runs over this spool's captures at all (B26).
|
|
40
|
+
|
|
41
|
+
True for a spool written before the rule existed -- it is exactly the
|
|
42
|
+
spool whose captures nobody has judged -- and for one whose BOOT says
|
|
43
|
+
`mode: "on"`. False for `mode: "off"`, for a mode this converter does
|
|
44
|
+
not know, and for a `redaction` that is not an object: the same set
|
|
45
|
+
`_redaction` passes through untouched, because a converter that added a
|
|
46
|
+
judgement to a header it could not read would be reporting one nobody
|
|
47
|
+
made.
|
|
48
|
+
"""
|
|
49
|
+
recorded = boot.get("redaction")
|
|
50
|
+
if not recorded:
|
|
51
|
+
return True
|
|
52
|
+
return isinstance(recorded, dict) and recorded.get("mode") == "on"
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def version_tuple(reported) -> tuple[int, ...]:
|
|
56
|
+
"""`"0.6.0"` -> `(0, 6, 0)`, and `()` for anything unreadable.
|
|
57
|
+
|
|
58
|
+
The empty tuple sorts BELOW every real version, so a spool that names no
|
|
59
|
+
writer is treated as older than the rule -- the safe direction, where
|
|
60
|
+
the converter applies it rather than assuming somebody else did.
|
|
61
|
+
"""
|
|
62
|
+
if not isinstance(reported, str):
|
|
63
|
+
return ()
|
|
64
|
+
return tuple(int(n) for n in re.findall(r"\d+", reported)[:3])
|
sensorium/ts/spool.py
ADDED
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
"""The wire: one JSONL spool, streamed back into records.
|
|
2
|
+
|
|
3
|
+
One file per container -- `<pid>-<threadId>.jsonl` -- one JSON object per
|
|
4
|
+
line, in the order the runtime observed the events. This module does the
|
|
5
|
+
reading and the two refusals that belong to it, and nothing else: what a
|
|
6
|
+
record MEANS is `ingest`'s.
|
|
7
|
+
|
|
8
|
+
The file is WALKED, never materialised (A3). BOOT is read eagerly, from
|
|
9
|
+
line 1, because nothing downstream can start without it; every later record
|
|
10
|
+
is yielded as the file is read, so the converter holds one record at a time
|
|
11
|
+
and not a list of two million. `exit` and `torn_tail` are therefore facts
|
|
12
|
+
only once the walk is DONE -- which is where the builder reads them, after
|
|
13
|
+
its loop.
|
|
14
|
+
|
|
15
|
+
Three properties of the file this module turns into facts:
|
|
16
|
+
|
|
17
|
+
* **The first record is BOOT**, because a spool that does not say what
|
|
18
|
+
wrote it, under what environment, at what wall clock, is not a recording
|
|
19
|
+
anybody can date or place. A spool with no BOOT is refused by name, and
|
|
20
|
+
so is one whose BOOT is not on line 1: a reader that streams has already
|
|
21
|
+
handed records to its caller by the time a later BOOT turns up.
|
|
22
|
+
* **There is exactly one BOOT** (R16). Two runtime instances writing one
|
|
23
|
+
spool means two module graphs resolved the runtime by two specifiers,
|
|
24
|
+
and every frame id, task id and file id in the file is then two
|
|
25
|
+
independent counters interleaved. Nothing downstream can untangle that,
|
|
26
|
+
so the spool is refused rather than converted into a plausible lie. The
|
|
27
|
+
second BOOT is met mid-walk, which aborts a build already under way --
|
|
28
|
+
`ingest.convert` unlinks the temporary file it had reserved, and the
|
|
29
|
+
refusal comes back from the worker as a value, exactly as before.
|
|
30
|
+
* **The last line may be torn.** A container killed by SIGKILL loses
|
|
31
|
+
whatever `appendFileSync` had not finished writing. A final line with no
|
|
32
|
+
newline after it is that tail, and it is dropped -- the trace is then
|
|
33
|
+
`incomplete`, which is the honest artifact. A malformed line ANYWHERE
|
|
34
|
+
ELSE is a refusal: that is a corrupt file, not a killed process.
|
|
35
|
+
"""
|
|
36
|
+
import json
|
|
37
|
+
from collections.abc import Iterator
|
|
38
|
+
from dataclasses import dataclass, field
|
|
39
|
+
from pathlib import Path
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class SpoolError(Exception):
|
|
43
|
+
"""A spool cannot be read as one container's recording. Always names
|
|
44
|
+
the file: `ingest` prints it beside the spool it refused, and the other
|
|
45
|
+
spools of the same invocation are converted anyway."""
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass
|
|
49
|
+
class Spool:
|
|
50
|
+
"""One container's records, in the order they were written."""
|
|
51
|
+
|
|
52
|
+
path: Path
|
|
53
|
+
boot: dict
|
|
54
|
+
#: Every record after BOOT, in wire order, YIELDED as the file is
|
|
55
|
+
#: walked. BOOT is not among them: it is the header, and every caller
|
|
56
|
+
#: wants it by name. Consumable once, like any iterator -- a second
|
|
57
|
+
#: reader of one spool calls `read` again.
|
|
58
|
+
records: Iterator[dict] = field(default_factory=lambda: iter(()))
|
|
59
|
+
#: The EXIT record, or None. Its presence is what `incomplete` is read
|
|
60
|
+
#: from (R13) -- an EXIT with a `signal` still finalizes the trace,
|
|
61
|
+
#: because the container lived long enough to say how it ended. Known
|
|
62
|
+
#: once `records` is exhausted, which is where the builder reads it.
|
|
63
|
+
exit: dict | None = None
|
|
64
|
+
#: Whether the file's last line was cut mid-write. Known once
|
|
65
|
+
#: `records` is exhausted.
|
|
66
|
+
torn_tail: bool = False
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def read(path) -> Spool:
|
|
70
|
+
"""`path` opened and its BOOT read, or `SpoolError` naming it.
|
|
71
|
+
|
|
72
|
+
What comes back is a `Spool` whose `records` walks the rest of the file
|
|
73
|
+
as it is iterated; the handle it holds is closed when the walk ends, by
|
|
74
|
+
exhaustion or by refusal.
|
|
75
|
+
"""
|
|
76
|
+
path = Path(path)
|
|
77
|
+
try:
|
|
78
|
+
fh = open(path, "rb")
|
|
79
|
+
except OSError as e:
|
|
80
|
+
raise SpoolError(f"{path} cannot be read as a spool: {e}") from None
|
|
81
|
+
try:
|
|
82
|
+
boot = _boot(path, fh)
|
|
83
|
+
except BaseException:
|
|
84
|
+
# Every refusal above the walk closes the handle here: the generator
|
|
85
|
+
# that would otherwise have closed it is never created.
|
|
86
|
+
fh.close()
|
|
87
|
+
raise
|
|
88
|
+
sp = Spool(path=path, boot=boot)
|
|
89
|
+
sp.records = _stream(sp, fh)
|
|
90
|
+
return sp
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _boot(path: Path, fh) -> dict:
|
|
94
|
+
"""Line 1, which is BOOT or the end of this spool's reading."""
|
|
95
|
+
first = fh.readline()
|
|
96
|
+
if not first.endswith(b"\n") or not first.strip():
|
|
97
|
+
# No first line at all, nothing but a torn one, or a blank one: in
|
|
98
|
+
# none of those cases does the file open with a BOOT record.
|
|
99
|
+
raise SpoolError(f"no BOOT record in {path}: the spool does not say "
|
|
100
|
+
"what wrote it")
|
|
101
|
+
boot = _parse(path, 1, _decode(path, 1, first))
|
|
102
|
+
if boot.get("e") != "BOOT":
|
|
103
|
+
raise SpoolError(f"no BOOT record in {path}: line 1 is a "
|
|
104
|
+
f"{boot['e']} record, and the spool does not say "
|
|
105
|
+
"what wrote it")
|
|
106
|
+
caps = boot.get("capabilities")
|
|
107
|
+
if caps is not None and not isinstance(caps, dict):
|
|
108
|
+
# Present but not a map is not a declaration `build._meta` can merge
|
|
109
|
+
# over the constant -- refused here, where BOOT is read, rather than
|
|
110
|
+
# a worker crashing deep inside the merge.
|
|
111
|
+
raise SpoolError(f"{path}: BOOT carries a capabilities value that "
|
|
112
|
+
"is not a map")
|
|
113
|
+
return boot
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def _stream(sp: Spool, fh) -> Iterator[dict]:
|
|
117
|
+
"""Every record after BOOT, yielded as `fh` is walked.
|
|
118
|
+
|
|
119
|
+
`sp` is filled in as the walk goes: `torn_tail` when the last line has
|
|
120
|
+
no newline after it, `exit` when the EXIT record goes past. Both are
|
|
121
|
+
read by the builder AFTER its loop, which is the first point at which
|
|
122
|
+
either is known. The handle is closed on every way out of here --
|
|
123
|
+
exhaustion, torn tail, refusal, or a caller that stops early.
|
|
124
|
+
"""
|
|
125
|
+
lineno = 1
|
|
126
|
+
with fh:
|
|
127
|
+
for raw in fh:
|
|
128
|
+
lineno += 1
|
|
129
|
+
if not raw.endswith(b"\n"):
|
|
130
|
+
sp.torn_tail = True # the tail a SIGKILL cut; dropped
|
|
131
|
+
return
|
|
132
|
+
line = _decode(sp.path, lineno, raw)
|
|
133
|
+
if not line.strip():
|
|
134
|
+
continue
|
|
135
|
+
rec = _parse(sp.path, lineno, line)
|
|
136
|
+
if rec.get("e") == "BOOT":
|
|
137
|
+
raise SpoolError(f"two BOOT records in {sp.path}: two runtime "
|
|
138
|
+
"instances wrote one spool")
|
|
139
|
+
if rec.get("e") == "EXIT":
|
|
140
|
+
sp.exit = rec
|
|
141
|
+
yield rec
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _decode(path: Path, lineno: int, raw: bytes) -> str:
|
|
145
|
+
"""One line's bytes as text, or a refusal naming the line.
|
|
146
|
+
|
|
147
|
+
The file is read as bytes so the walk never holds more than a line of
|
|
148
|
+
it; a line that is not UTF-8 is then named where it is, which is more
|
|
149
|
+
than the whole-file decode this replaced could say.
|
|
150
|
+
"""
|
|
151
|
+
try:
|
|
152
|
+
return raw.decode("utf-8")
|
|
153
|
+
except UnicodeDecodeError as e:
|
|
154
|
+
raise SpoolError(f"{path} line {lineno} is not UTF-8: {e} -- a spool "
|
|
155
|
+
"this recorder wrote is UTF-8 throughout") from None
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def _parse(path: Path, lineno: int, line: str) -> dict:
|
|
159
|
+
try:
|
|
160
|
+
rec = json.loads(line)
|
|
161
|
+
except json.JSONDecodeError as e:
|
|
162
|
+
raise SpoolError(f"{path} line {lineno} is not readable JSON: {e} -- "
|
|
163
|
+
"a spool this recorder wrote is one object per "
|
|
164
|
+
"line") from None
|
|
165
|
+
if not isinstance(rec, dict) or not isinstance(rec.get("e"), str):
|
|
166
|
+
raise SpoolError(f"{path} line {lineno} is not a record: every line "
|
|
167
|
+
"carries an `e` naming its kind")
|
|
168
|
+
return rec
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
"""Trace-cap meta from one ELISION spool record.
|
|
2
|
+
|
|
3
|
+
Written only when calls were dropped. No record, or a record whose elided
|
|
4
|
+
count is zero, leaves the trace without truncation meta, so a spool from
|
|
5
|
+
before caps still converts. The wire stays v1: `file` and `c` are the same
|
|
6
|
+
ids a CALL carries, and this module resolves them through the FILE header
|
|
7
|
+
the same way a CALL becomes a code object.
|
|
8
|
+
"""
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from sensorium.ts.spool import SpoolError
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def truncation_meta(rec: dict | None, files: dict, spool_path: str) -> dict:
|
|
15
|
+
"""Optional meta. ``{}`` when nothing was dropped.
|
|
16
|
+
|
|
17
|
+
``files`` maps a wire file id to its FILE record. A name this record
|
|
18
|
+
cannot resolve is a spool this converter cannot read.
|
|
19
|
+
"""
|
|
20
|
+
if not rec:
|
|
21
|
+
return {}
|
|
22
|
+
try:
|
|
23
|
+
dropped = rec["callsElided"]
|
|
24
|
+
except KeyError as e:
|
|
25
|
+
raise _bad(spool_path, e) from None
|
|
26
|
+
if not isinstance(dropped, int) or isinstance(dropped, bool) or dropped <= 0:
|
|
27
|
+
return {}
|
|
28
|
+
rows = []
|
|
29
|
+
for row in rec.get("elisions") or []:
|
|
30
|
+
rows.append(_row(row, files, spool_path))
|
|
31
|
+
try:
|
|
32
|
+
limits = {
|
|
33
|
+
"max_events": rec["maxEvents"],
|
|
34
|
+
"max_bytes": rec["maxBytes"],
|
|
35
|
+
"max_calls": rec["maxCalls"],
|
|
36
|
+
"hit": list(rec["hit"]),
|
|
37
|
+
"events_recorded": rec["eventsRecorded"],
|
|
38
|
+
"calls_elided": dropped,
|
|
39
|
+
}
|
|
40
|
+
except (KeyError, TypeError) as e:
|
|
41
|
+
raise _bad(spool_path, e) from None
|
|
42
|
+
failures = rec.get("failuresKept") or 0
|
|
43
|
+
if failures:
|
|
44
|
+
limits["failures_kept"] = failures
|
|
45
|
+
return {
|
|
46
|
+
"trace_truncated": True,
|
|
47
|
+
"trace_limits": limits,
|
|
48
|
+
"elisions": rows,
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _row(row: dict, files: dict, spool_path: str) -> dict:
|
|
53
|
+
try:
|
|
54
|
+
file_id = row["file"]
|
|
55
|
+
index = row["c"]
|
|
56
|
+
except KeyError as e:
|
|
57
|
+
raise _bad(spool_path, e) from None
|
|
58
|
+
header = files.get(file_id)
|
|
59
|
+
if header is None:
|
|
60
|
+
raise SpoolError(
|
|
61
|
+
f"{spool_path}: an ELISION names file {file_id}, which no "
|
|
62
|
+
"FILE record declared")
|
|
63
|
+
codes = header["codes"]
|
|
64
|
+
if not isinstance(index, int) or isinstance(index, bool) or not 0 <= index < len(codes):
|
|
65
|
+
raise SpoolError(
|
|
66
|
+
f"{spool_path}: an ELISION names site {index} of "
|
|
67
|
+
f"{header['rel']}, which declared {len(codes)}")
|
|
68
|
+
qualname, line, _kind = codes[index]
|
|
69
|
+
return {
|
|
70
|
+
"file": header["abs"],
|
|
71
|
+
"qualname": qualname,
|
|
72
|
+
"firstlineno": line,
|
|
73
|
+
"elided": row["elided"],
|
|
74
|
+
"kept": row["kept"],
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def _bad(spool_path: str, err: BaseException) -> SpoolError:
|
|
79
|
+
return SpoolError(
|
|
80
|
+
f"{spool_path}: an ELISION record is not the shape wire 1 "
|
|
81
|
+
f"declares ({type(err).__name__}: {err})")
|