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/c/plan.py
ADDED
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
"""Capture plans. One plan per image, addresses are unrelocated low_pc.
|
|
2
|
+
|
|
3
|
+
SysV x86-64 return class, simplified
|
|
4
|
+
------------------------------------
|
|
5
|
+
void (no type): RET_VOID, nreg 0, size 0.
|
|
6
|
+
|
|
7
|
+
Base float, double, and a 16-byte float (__float128, and long double,
|
|
8
|
+
which this pass does not put in x87): RET_SSE, nreg 1, or nreg 2 when
|
|
9
|
+
the size is greater than 8 and at most 16. Larger than 16 is RET_MEM.
|
|
10
|
+
|
|
11
|
+
Integers, enums, and pointers: RET_INT, nreg 1, or nreg 2 for a value
|
|
12
|
+
wider than 8 and at most 16 (__int128). Wider than 16 is RET_MEM.
|
|
13
|
+
|
|
14
|
+
Struct, union, class, and array: split into 8-byte eightbytes.
|
|
15
|
+
|
|
16
|
+
* An eightbyte is INTEGER if it holds any integer, pointer, or enum,
|
|
17
|
+
SSE if it holds only float or double.
|
|
18
|
+
* MEMORY if a member crosses an eightbyte boundary, the aggregate is
|
|
19
|
+
larger than 16 bytes, it needs more than two eightbytes, a field is
|
|
20
|
+
unaligned for its type, or it has a flexible array member.
|
|
21
|
+
* Merging two classes in one eightbyte: MEMORY if either is MEMORY,
|
|
22
|
+
else INTEGER if either is INTEGER, else SSE.
|
|
23
|
+
* More than two INTEGER or two SSE registers is MEMORY.
|
|
24
|
+
|
|
25
|
+
A mix of INTEGER and SSE eightbytes does not fit one plan class. INTEGER
|
|
26
|
+
wins for the label (RET_INT) and the eightbyte map is stored on the type
|
|
27
|
+
so the decoder can pull each eightbyte from rax/rdx or xmm0/xmm1. The V
|
|
28
|
+
record always carries all four registers.
|
|
29
|
+
|
|
30
|
+
RET_MEM records the real byte size up to 4096. The runtime caps the copy
|
|
31
|
+
at 256. RET_INT and RET_SSE store ret_size 0 and ret_nreg 1 or 2.
|
|
32
|
+
"""
|
|
33
|
+
from __future__ import annotations
|
|
34
|
+
|
|
35
|
+
from sensorium.c.format import (
|
|
36
|
+
FLAG_CSTR, NO_SLOT, RET_INT, RET_MEM, RET_SSE, RET_VOID, FuncPlan,
|
|
37
|
+
ParamPlan, write_plan,
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
_CAP = 4096
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def write_image_plan(elf_path, out_path) -> None:
|
|
44
|
+
"""Write ``out_path`` for ``elf_path`` via ``format.write_plan``."""
|
|
45
|
+
from sensorium.c.dwarf import DwarfImage
|
|
46
|
+
|
|
47
|
+
image = DwarfImage(elf_path)
|
|
48
|
+
funcs = []
|
|
49
|
+
for addr, fn in image.funcs.items():
|
|
50
|
+
params = []
|
|
51
|
+
for p in fn.params:
|
|
52
|
+
if p.off is None:
|
|
53
|
+
params.append(ParamPlan(NO_SLOT, 0, 0))
|
|
54
|
+
continue
|
|
55
|
+
size = p.typ.size if p.typ is not None else 0
|
|
56
|
+
if size < 0:
|
|
57
|
+
size = 0
|
|
58
|
+
if size > 256:
|
|
59
|
+
size = 256
|
|
60
|
+
flags = FLAG_CSTR if p.typ is not None and p.typ.is_cstr else 0
|
|
61
|
+
params.append(ParamPlan(int(p.off), int(size), int(flags)))
|
|
62
|
+
funcs.append(FuncPlan(int(addr), int(fn.ret_class), int(fn.ret_nreg),
|
|
63
|
+
int(fn.ret_size), tuple(params)))
|
|
64
|
+
write_plan(out_path, funcs)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def classify_return(typ):
|
|
68
|
+
"""(ret_class, ret_nreg, ret_size) for a resolved type."""
|
|
69
|
+
if typ is None or typ.kind == "void":
|
|
70
|
+
return RET_VOID, 0, 0
|
|
71
|
+
if typ.kind == "float":
|
|
72
|
+
return _scalar(RET_SSE, typ.size)
|
|
73
|
+
if typ.kind in ("int", "bool", "ptr", "enum"):
|
|
74
|
+
return _scalar(RET_INT, typ.size)
|
|
75
|
+
if typ.kind in ("struct", "union", "array"):
|
|
76
|
+
return _aggregate(typ)
|
|
77
|
+
return _scalar(RET_INT, typ.size)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _scalar(cls, size):
|
|
81
|
+
size = size or 0
|
|
82
|
+
if size <= 0:
|
|
83
|
+
return cls, 0, 0
|
|
84
|
+
if size <= 8:
|
|
85
|
+
return cls, 1, 0
|
|
86
|
+
if size <= 16:
|
|
87
|
+
return cls, 2, 0
|
|
88
|
+
return RET_MEM, 0, min(size, _CAP)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _mem(typ):
|
|
92
|
+
return RET_MEM, 0, min(max(typ.size or 0, 0), _CAP)
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def _aggregate(typ):
|
|
96
|
+
if _flex(typ, set()) or (typ.size or 0) > 16:
|
|
97
|
+
return _mem(typ)
|
|
98
|
+
if not _aligned(typ, 0, set()):
|
|
99
|
+
return _mem(typ)
|
|
100
|
+
leaves = []
|
|
101
|
+
if not _leaves(typ, 0, leaves, set()):
|
|
102
|
+
return _mem(typ)
|
|
103
|
+
size = typ.size or 0
|
|
104
|
+
if size <= 0:
|
|
105
|
+
return RET_INT, 0, 0
|
|
106
|
+
n = (size + 7) // 8
|
|
107
|
+
if n > 2:
|
|
108
|
+
return _mem(typ)
|
|
109
|
+
classes = ["NO"] * n
|
|
110
|
+
for off, width, cls in leaves:
|
|
111
|
+
if width <= 0:
|
|
112
|
+
continue
|
|
113
|
+
start = off // 8
|
|
114
|
+
end = (off + width - 1) // 8
|
|
115
|
+
if start != end or not 0 <= start < n:
|
|
116
|
+
return _mem(typ)
|
|
117
|
+
classes[start] = _merge(classes[start], cls)
|
|
118
|
+
if "MEM" in classes:
|
|
119
|
+
return _mem(typ)
|
|
120
|
+
ints = sum(c == "INT" for c in classes)
|
|
121
|
+
sses = sum(c == "SSE" for c in classes)
|
|
122
|
+
if ints > 2 or sses > 2:
|
|
123
|
+
return _mem(typ)
|
|
124
|
+
used = tuple(c for c in classes if c in ("INT", "SSE"))
|
|
125
|
+
if not used:
|
|
126
|
+
return RET_INT, 0, 0
|
|
127
|
+
if ints and sses:
|
|
128
|
+
# Both register files. INTEGER wins the plan class; the map tells
|
|
129
|
+
# the decoder which file each eightbyte came from.
|
|
130
|
+
typ.eights = used
|
|
131
|
+
return RET_INT, len(used), 0
|
|
132
|
+
if ints:
|
|
133
|
+
return RET_INT, ints, 0
|
|
134
|
+
return RET_SSE, sses, 0
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def _merge(a, b):
|
|
138
|
+
if a == "NO" or a is None:
|
|
139
|
+
return b
|
|
140
|
+
if b == "NO" or b is None:
|
|
141
|
+
return a
|
|
142
|
+
if a == "MEM" or b == "MEM":
|
|
143
|
+
return "MEM"
|
|
144
|
+
if a == "INT" or b == "INT":
|
|
145
|
+
return "INT"
|
|
146
|
+
return "SSE"
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def _cross(off, size):
|
|
150
|
+
if size <= 0:
|
|
151
|
+
return False
|
|
152
|
+
return off // 8 != (off + size - 1) // 8
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _leaves(typ, base, out, stack):
|
|
156
|
+
if typ is None:
|
|
157
|
+
return False
|
|
158
|
+
mark = id(typ)
|
|
159
|
+
if mark in stack:
|
|
160
|
+
return False
|
|
161
|
+
if typ.kind in ("struct", "union"):
|
|
162
|
+
stack.add(mark)
|
|
163
|
+
try:
|
|
164
|
+
for m in typ.members or ():
|
|
165
|
+
if m.bit_size:
|
|
166
|
+
if m.bit_pos is None or _bit_cross(m.bit_pos, m.bit_size):
|
|
167
|
+
return False
|
|
168
|
+
out.append((m.bit_pos // 8, 1, "INT"))
|
|
169
|
+
continue
|
|
170
|
+
if not _leaves(m.typ, base + m.offset, out, stack):
|
|
171
|
+
return False
|
|
172
|
+
return True
|
|
173
|
+
finally:
|
|
174
|
+
stack.discard(mark)
|
|
175
|
+
if typ.kind == "array":
|
|
176
|
+
if typ.count is None or typ.elem is None:
|
|
177
|
+
return False
|
|
178
|
+
stack.add(mark)
|
|
179
|
+
try:
|
|
180
|
+
es = typ.elem.size or 0
|
|
181
|
+
for i in range(typ.count):
|
|
182
|
+
if not _leaves(typ.elem, base + i * es, out, stack):
|
|
183
|
+
return False
|
|
184
|
+
return True
|
|
185
|
+
finally:
|
|
186
|
+
stack.discard(mark)
|
|
187
|
+
if typ.kind == "float":
|
|
188
|
+
if _cross(base, typ.size):
|
|
189
|
+
return False
|
|
190
|
+
out.append((base, typ.size, "SSE"))
|
|
191
|
+
return True
|
|
192
|
+
if _cross(base, typ.size or 1):
|
|
193
|
+
return False
|
|
194
|
+
out.append((base, typ.size or 1, "INT"))
|
|
195
|
+
return True
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
def _bit_cross(bit_pos, bit_size):
|
|
199
|
+
if bit_size <= 0:
|
|
200
|
+
return False
|
|
201
|
+
return bit_pos // 64 != (bit_pos + bit_size - 1) // 64
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def _flex(typ, stack):
|
|
205
|
+
if typ is None:
|
|
206
|
+
return False
|
|
207
|
+
mark = id(typ)
|
|
208
|
+
if mark in stack:
|
|
209
|
+
return False
|
|
210
|
+
if typ.kind == "array":
|
|
211
|
+
return typ.count is None
|
|
212
|
+
if typ.kind in ("struct", "union"):
|
|
213
|
+
stack.add(mark)
|
|
214
|
+
try:
|
|
215
|
+
return any(_flex(m.typ, stack) for m in (typ.members or ()))
|
|
216
|
+
finally:
|
|
217
|
+
stack.discard(mark)
|
|
218
|
+
return False
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def _nat(size):
|
|
222
|
+
if size >= 16:
|
|
223
|
+
return 16
|
|
224
|
+
if size >= 8:
|
|
225
|
+
return 8
|
|
226
|
+
if size >= 4:
|
|
227
|
+
return 4
|
|
228
|
+
if size >= 2:
|
|
229
|
+
return 2
|
|
230
|
+
return 1
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
def _align(typ):
|
|
234
|
+
if typ is None:
|
|
235
|
+
return 1
|
|
236
|
+
if typ.kind == "ptr":
|
|
237
|
+
return 8
|
|
238
|
+
if typ.kind in ("int", "bool", "float", "enum"):
|
|
239
|
+
return _nat(typ.size or 1)
|
|
240
|
+
if typ.kind == "array":
|
|
241
|
+
return _align(typ.elem)
|
|
242
|
+
if typ.kind in ("struct", "union"):
|
|
243
|
+
als = [_align(m.typ) for m in (typ.members or ()) if not m.bit_size]
|
|
244
|
+
return max(als) if als else 1
|
|
245
|
+
return 1
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
def _aligned(typ, base, stack):
|
|
249
|
+
if typ is None:
|
|
250
|
+
return True
|
|
251
|
+
mark = id(typ)
|
|
252
|
+
if mark in stack:
|
|
253
|
+
return True
|
|
254
|
+
if typ.kind == "struct":
|
|
255
|
+
stack.add(mark)
|
|
256
|
+
try:
|
|
257
|
+
for m in typ.members or ():
|
|
258
|
+
if m.bit_size:
|
|
259
|
+
continue
|
|
260
|
+
if (base + m.offset) % _align(m.typ) != 0:
|
|
261
|
+
return False
|
|
262
|
+
if not _aligned(m.typ, base + m.offset, stack):
|
|
263
|
+
return False
|
|
264
|
+
return True
|
|
265
|
+
finally:
|
|
266
|
+
stack.discard(mark)
|
|
267
|
+
if typ.kind == "union":
|
|
268
|
+
stack.add(mark)
|
|
269
|
+
try:
|
|
270
|
+
return all(
|
|
271
|
+
_aligned(m.typ, base + m.offset, stack)
|
|
272
|
+
for m in (typ.members or ()) if not m.bit_size)
|
|
273
|
+
finally:
|
|
274
|
+
stack.discard(mark)
|
|
275
|
+
if typ.kind == "array" and typ.elem is not None:
|
|
276
|
+
return _aligned(typ.elem, base, stack)
|
|
277
|
+
return True
|
sensorium/cli.py
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
"""sensorium command-line interface.
|
|
2
|
+
|
|
3
|
+
Every `main()` return is appended to the invocation log (see
|
|
4
|
+
`sensorium.invocations`) after dispatch, including the version guard
|
|
5
|
+
below and the three exception classes caught around `args.func(args)`.
|
|
6
|
+
The one shape this never sees is any argparse exit: a parse failure and
|
|
7
|
+
`--help`/`--version` alike raise `SystemExit` straight out of
|
|
8
|
+
`argparse.parse_args`, before dispatch, so both escape `main()` without
|
|
9
|
+
a record -- do not wrap it.
|
|
10
|
+
"""
|
|
11
|
+
import argparse
|
|
12
|
+
import sys
|
|
13
|
+
|
|
14
|
+
from sensorium import invocations, paths
|
|
15
|
+
from sensorium.mcp import cmd as mcp_cmd
|
|
16
|
+
from sensorium.query import (diff_cmd, exceptions_cmd, failures_cmd, flow_cmd,
|
|
17
|
+
fmt, frame_cmd, grep_cmd, info_cmd, redact_cmd,
|
|
18
|
+
refocus_cmd, runs_cmd, tree_cmd, watch_cmd)
|
|
19
|
+
from sensorium.store import db
|
|
20
|
+
from sensorium.store.gc import add_parsers as add_gc_parsers
|
|
21
|
+
from sensorium.c import cli as c_cli
|
|
22
|
+
from sensorium.ts import cli as ts_cli
|
|
23
|
+
|
|
24
|
+
_QUERY_MODULES = [runs_cmd, info_cmd, tree_cmd, frame_cmd, grep_cmd,
|
|
25
|
+
exceptions_cmd, failures_cmd, flow_cmd, watch_cmd, diff_cmd,
|
|
26
|
+
refocus_cmd, redact_cmd]
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _add_run_parser(sub):
|
|
30
|
+
p = sub.add_parser(
|
|
31
|
+
"run", help="record one execution",
|
|
32
|
+
description="Runs the command under the recorder from `cwd` and "
|
|
33
|
+
"writes one trace; only code under `cwd` is recorded; "
|
|
34
|
+
"the command is a .py file, a `-m` module or a console "
|
|
35
|
+
"script, never `python` itself.",
|
|
36
|
+
epilog="exit: the target's own status")
|
|
37
|
+
p.add_argument("--focus", action="append", default=[],
|
|
38
|
+
help="pkg.module or pkg.module:qualname; repeatable")
|
|
39
|
+
p.add_argument("--include", action="append", default=[],
|
|
40
|
+
help="glob matched against each file's path relative "
|
|
41
|
+
"to the working directory; when given, only the "
|
|
42
|
+
"files it matches are recorded; repeatable")
|
|
43
|
+
p.add_argument("--exclude", action="append", default=[],
|
|
44
|
+
help="glob matched against each file's path relative "
|
|
45
|
+
"to the working directory; a file it matches is "
|
|
46
|
+
"never recorded; repeatable")
|
|
47
|
+
p.add_argument("--window", default=None,
|
|
48
|
+
help="limit --focus line capture to what runs inside this "
|
|
49
|
+
"function's activations; MODULE:QUALNAME scopes to one "
|
|
50
|
+
"function, a bare QUALNAME matches that name in any "
|
|
51
|
+
"module")
|
|
52
|
+
p.add_argument("--max-events", default=None,
|
|
53
|
+
help="stop storing events after this many (0 is unlimited)")
|
|
54
|
+
p.add_argument("--max-bytes", default=None,
|
|
55
|
+
help="stop storing events after the trace reaches this "
|
|
56
|
+
"size, for example 8M (0 is unlimited)")
|
|
57
|
+
p.add_argument("--max-calls", default=None,
|
|
58
|
+
help="store at most this many calls of each function; "
|
|
59
|
+
"later calls are counted and marked elided "
|
|
60
|
+
"(0 is unlimited)")
|
|
61
|
+
p.add_argument("--no-cap", action="store_true",
|
|
62
|
+
help="record without an event, size, or per-function cap")
|
|
63
|
+
p.add_argument("--no-children", action="store_true",
|
|
64
|
+
help="do not record Python child processes (subprocess, "
|
|
65
|
+
"multiprocessing, pytest-xdist) into this run; "
|
|
66
|
+
"SENSORIUM_NO_CHILDREN=1 does the same")
|
|
67
|
+
p.add_argument("--run-id", default=None, help=argparse.SUPPRESS)
|
|
68
|
+
p.add_argument("--refocus-of", default=None, help=argparse.SUPPRESS)
|
|
69
|
+
p.add_argument("target", nargs=argparse.REMAINDER)
|
|
70
|
+
p.set_defaults(func=_run)
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def _run(args) -> int:
|
|
74
|
+
from sensorium.record import boot
|
|
75
|
+
target = list(args.target)
|
|
76
|
+
if target and target[0] == "--":
|
|
77
|
+
target = target[1:]
|
|
78
|
+
if not target:
|
|
79
|
+
print("usage: sensorium run [options] -- <command> [args...]",
|
|
80
|
+
file=sys.stderr)
|
|
81
|
+
return 2
|
|
82
|
+
from sensorium.limits import LimitsError, resolve
|
|
83
|
+
try:
|
|
84
|
+
limits = resolve(max_events=args.max_events, max_bytes=args.max_bytes,
|
|
85
|
+
max_calls=args.max_calls, no_cap=args.no_cap)
|
|
86
|
+
except LimitsError as e:
|
|
87
|
+
print(f"error: {e}", file=sys.stderr)
|
|
88
|
+
return 2
|
|
89
|
+
try:
|
|
90
|
+
from sensorium.record.children import children_enabled
|
|
91
|
+
run_id, exit_status = boot.run_target(
|
|
92
|
+
target, focus=args.focus, include=args.include,
|
|
93
|
+
exclude=args.exclude, window=args.window,
|
|
94
|
+
run_id=args.run_id, refocus_of=args.refocus_of, limits=limits,
|
|
95
|
+
record_children=False if args.no_children else children_enabled())
|
|
96
|
+
except boot.TargetError as e:
|
|
97
|
+
print(f"error: {e}", file=sys.stderr)
|
|
98
|
+
return 2
|
|
99
|
+
print(f"run: {run_id}")
|
|
100
|
+
print(f"trace: {paths.traces_dir() / (run_id + '.db')}")
|
|
101
|
+
return exit_status
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def main(argv=None) -> int:
|
|
105
|
+
# The argv the invocation log records: what this call received, never
|
|
106
|
+
# the environment or the working directory.
|
|
107
|
+
recorded_argv = list(argv) if argv is not None else list(sys.argv[1:])
|
|
108
|
+
if sys.version_info < (3, 12):
|
|
109
|
+
print("sensorium requires Python 3.12+ (sys.monitoring); running "
|
|
110
|
+
f"under {sys.version.split()[0]}", file=sys.stderr)
|
|
111
|
+
invocations.record(recorded_argv, 2, None)
|
|
112
|
+
return 2
|
|
113
|
+
parser = argparse.ArgumentParser(
|
|
114
|
+
prog="sensorium",
|
|
115
|
+
description="Record a program's execution; query what actually "
|
|
116
|
+
"happened. `sensorium run` records Python, `cargo "
|
|
117
|
+
"sensorium` records Rust, `sensorium ts run` records "
|
|
118
|
+
"TypeScript and `sensorium c run` records C; every "
|
|
119
|
+
"query below reads any of the four traces.")
|
|
120
|
+
sub = parser.add_subparsers(dest="cmd", required=True)
|
|
121
|
+
_add_run_parser(sub)
|
|
122
|
+
ts_cli.add_parser(sub)
|
|
123
|
+
c_cli.add_parser(sub)
|
|
124
|
+
mcp_cmd.add_parser(sub)
|
|
125
|
+
add_gc_parsers(sub)
|
|
126
|
+
for mod in _QUERY_MODULES:
|
|
127
|
+
mod.add_parser(sub)
|
|
128
|
+
args = parser.parse_args(argv)
|
|
129
|
+
error = None
|
|
130
|
+
try:
|
|
131
|
+
exit_status = args.func(args)
|
|
132
|
+
except (paths.TraceLookupError, fmt.RefError, db.TraceFormatError) as e:
|
|
133
|
+
# "the reference you gave does not name anything", or "this trace is
|
|
134
|
+
# from a newer sensorium" -- user-facing conditions every query command
|
|
135
|
+
# can hit, and never a reason to hand back a traceback.
|
|
136
|
+
print(f"error: {e}", file=sys.stderr)
|
|
137
|
+
exit_status = 2
|
|
138
|
+
error = type(e).__name__
|
|
139
|
+
invocations.record(recorded_argv, exit_status, error)
|
|
140
|
+
return exit_status
|
sensorium/driver.py
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
"""Which `cargo-sensorium` this box will use, resolved in ONE place.
|
|
2
|
+
|
|
3
|
+
The rule is two lines long and was written out three times: in
|
|
4
|
+
`query/refocus_rust.py` (what a `refocus` re-runs with), in
|
|
5
|
+
`corpus/run_corpus.py` (what a corpus case records with), and in
|
|
6
|
+
`tests/test_focus_refusal.py` (what its skip is decided on). They agreed,
|
|
7
|
+
and a parametrised test held them to it -- but agreement kept by a test is
|
|
8
|
+
agreement that has to be re-established after every edit, and the three
|
|
9
|
+
answers have to be the SAME answer or a corpus case records with one binary
|
|
10
|
+
and its `refocus` question re-runs with another.
|
|
11
|
+
|
|
12
|
+
It lives under `src/sensorium/` because that is the only one of the three
|
|
13
|
+
trees all three can reach. `corpus/` is a development tree beside the
|
|
14
|
+
package and is not in the wheel (`pyproject.toml` packages `src/sensorium`
|
|
15
|
+
only), so a query command importing it would work from a checkout and fail
|
|
16
|
+
from an install; `tests/` is no better. The dependency runs the other way
|
|
17
|
+
here -- the corpus and the suite already require `sensorium` to be
|
|
18
|
+
importable, since the corpus records by running `python -m sensorium`.
|
|
19
|
+
"""
|
|
20
|
+
import os
|
|
21
|
+
import shutil
|
|
22
|
+
|
|
23
|
+
#: The variable that names the driver, and the only one. CI's `rust` job
|
|
24
|
+
#: builds a binary and sets it; so does a developer with a release build on
|
|
25
|
+
#: a second disk. Written down here so a reader looking for "how do I point
|
|
26
|
+
#: this at my build" finds one name and not three copies of it.
|
|
27
|
+
ENV_VAR = "SENSORIUM_CARGO_SENSORIUM"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def cargo_sensorium() -> str | None:
|
|
31
|
+
"""The `cargo-sensorium` binary to use, or None when there is none.
|
|
32
|
+
|
|
33
|
+
`SENSORIUM_CARGO_SENSORIUM` first, then PATH. An EMPTY variable is not a
|
|
34
|
+
driver -- `or` and not a presence test, so `SENSORIUM_CARGO_SENSORIUM=`
|
|
35
|
+
falls through to PATH rather than resolving to `""` and failing later at
|
|
36
|
+
exec time with a message about an empty command.
|
|
37
|
+
|
|
38
|
+
None is not an error. It is the ordinary state of the Python CI matrix,
|
|
39
|
+
which has no Rust toolchain: the corpus reports the cases it cannot
|
|
40
|
+
record as skipped BY NAME, and `refocus` refuses a Rust re-run with a
|
|
41
|
+
sentence that says what is missing. Both of those readings need to be
|
|
42
|
+
told "no driver" rather than handed a path that does not exist.
|
|
43
|
+
|
|
44
|
+
`shutil.which` is called through the module (never `from shutil import
|
|
45
|
+
which`) so a test can patch it where every caller sees the patch.
|
|
46
|
+
"""
|
|
47
|
+
return os.environ.get(ENV_VAR) or shutil.which("cargo-sensorium")
|
sensorium/exit.py
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""The query CLI's exit status is the caller's next action, not a health code.
|
|
2
|
+
|
|
3
|
+
0 the question was answered affirmatively: the trace says yes.
|
|
4
|
+
1 the question was answered negatively: the trace says no, or none.
|
|
5
|
+
2 the call is wrong: edit the command and ask again.
|
|
6
|
+
3 the trace cannot settle it: change the recording and re-record.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
ANSWERED = 0
|
|
10
|
+
"""The trace answered affirmatively -- what was asked for is in the output."""
|
|
11
|
+
|
|
12
|
+
NEGATIVE = 1
|
|
13
|
+
"""The trace answered negatively -- no match, no frame, no exception, none."""
|
|
14
|
+
|
|
15
|
+
BAD_CALL = 2
|
|
16
|
+
"""The call is wrong -- a bad flag, a bad ref, an unreadable trace."""
|
|
17
|
+
|
|
18
|
+
UNSETTLED = 3
|
|
19
|
+
"""The trace cannot settle the question -- record again with what it lacks."""
|
|
20
|
+
|
|
21
|
+
#: Each status as the sentence a caller is told, for a surface
|
|
22
|
+
#: that hands back a status instead of printing this module's
|
|
23
|
+
#: docstring: an MCP client shows the four words, never the
|
|
24
|
+
#: convention. Keyed by the constants, so a status that moved
|
|
25
|
+
#: takes its sentence with it.
|
|
26
|
+
MEANING = {
|
|
27
|
+
ANSWERED: "the trace answered affirmatively",
|
|
28
|
+
NEGATIVE: "the trace answered negatively -- no match, no frame, "
|
|
29
|
+
"no exception, none",
|
|
30
|
+
BAD_CALL: "the call is wrong -- fix the arguments and ask again",
|
|
31
|
+
UNSETTLED: "the trace cannot settle it -- change the recording "
|
|
32
|
+
"and re-record",
|
|
33
|
+
}
|
sensorium/invocations.py
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
"""The invocation log: one JSON line per `cli.main` return.
|
|
2
|
+
|
|
3
|
+
`cli.main` calls `record` once per invocation, after dispatch, with the
|
|
4
|
+
argv it was given and the exit status (and, for the three exception
|
|
5
|
+
classes it catches, the exception's class name) it is about to return.
|
|
6
|
+
The log exists to answer "was sensorium called, and how did it end" --
|
|
7
|
+
the census a future on-demand flag would otherwise be arguing from thin
|
|
8
|
+
air (finding §4) -- not to reconstruct the process, so a line carries
|
|
9
|
+
exactly `utc`, `argv`, `exit`, `error`: never the environment, never the
|
|
10
|
+
working directory.
|
|
11
|
+
|
|
12
|
+
Default on. Opt out for one process by setting `SENSORIUM_NO_INVOCATION_LOG`
|
|
13
|
+
to any non-empty value other than `"0"` -- so `=1`, `=true`, `=yes` all
|
|
14
|
+
disable it, `=0` does not (logging stays on), and unset or empty is the
|
|
15
|
+
default (also on).
|
|
16
|
+
|
|
17
|
+
The log lives at `paths.trace_root() / "invocations.jsonl"`, a *sibling*
|
|
18
|
+
of `traces/` -- `runs` and `find_trace` only glob `traces/*.db`, so this
|
|
19
|
+
file is invisible to every trace lookup, by construction rather than by
|
|
20
|
+
filtering.
|
|
21
|
+
|
|
22
|
+
`record` never raises: a location it cannot write to (its directory
|
|
23
|
+
missing and uncreatable, e.g. a regular file sitting where a directory
|
|
24
|
+
belongs) prints one line to stderr and returns, exactly like a dropped
|
|
25
|
+
log line from any other best-effort logger -- a command's exit status is
|
|
26
|
+
never the invocation log's business.
|
|
27
|
+
"""
|
|
28
|
+
import json
|
|
29
|
+
import os
|
|
30
|
+
import sys
|
|
31
|
+
from datetime import datetime, timezone
|
|
32
|
+
from pathlib import Path
|
|
33
|
+
|
|
34
|
+
from sensorium import paths
|
|
35
|
+
|
|
36
|
+
_DISABLE_VAR = "SENSORIUM_NO_INVOCATION_LOG"
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def path() -> Path:
|
|
40
|
+
return paths.trace_root() / "invocations.jsonl"
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _utc_now() -> str:
|
|
44
|
+
return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f") + "Z"
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _log_disabled() -> bool:
|
|
48
|
+
"""Any non-empty value other than `"0"` disables the log; `"0"` and
|
|
49
|
+
unset/empty both mean "keep logging" -- see the module docstring."""
|
|
50
|
+
value = os.environ.get(_DISABLE_VAR)
|
|
51
|
+
return bool(value) and value != "0"
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def record(argv: list[str], exit_status: int, error: str | None) -> None:
|
|
55
|
+
"""Append one JSON line to `path()`. Never raises."""
|
|
56
|
+
if _log_disabled():
|
|
57
|
+
return
|
|
58
|
+
line = {"utc": _utc_now(), "argv": list(argv), "exit": exit_status,
|
|
59
|
+
"error": error}
|
|
60
|
+
try:
|
|
61
|
+
p = path()
|
|
62
|
+
# 0700, like `paths.traces_dir` and `redact.Key.load_or_create`:
|
|
63
|
+
# this is the third hand that can create the store root, and the
|
|
64
|
+
# root is where `redaction.key` and this log live. An EXISTING
|
|
65
|
+
# directory keeps its own mode -- `exist_ok=True` ignores this one,
|
|
66
|
+
# which is the intent, and the parents created on the way get the
|
|
67
|
+
# default, exactly as `paths.traces_dir` documents.
|
|
68
|
+
p.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
|
|
69
|
+
# 0600 on creation, not afterwards: the log names every sensorium
|
|
70
|
+
# invocation and its argv, and `p.open("a")` would create it
|
|
71
|
+
# 0666-under-the-umask. The mode is ignored when the file is already
|
|
72
|
+
# there, which is the intent -- an existing log keeps whatever the
|
|
73
|
+
# user gave it.
|
|
74
|
+
fd = os.open(p, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
|
|
75
|
+
with os.fdopen(fd, "a", encoding="utf-8") as f:
|
|
76
|
+
f.write(json.dumps(line) + "\n")
|
|
77
|
+
except (OSError, RuntimeError) as e:
|
|
78
|
+
# OSError: the usual "can't write there" (missing/uncreatable
|
|
79
|
+
# directory, a file sitting where one belongs). RuntimeError:
|
|
80
|
+
# `path()` -> `paths.trace_root()` -> `Path.home()` raises this,
|
|
81
|
+
# not OSError, when no home directory can be determined and
|
|
82
|
+
# SENSORIUM_DIR is unset -- same best-effort drop, same one line.
|
|
83
|
+
print(f"sensorium: invocation log unwritable: {e}", file=sys.stderr)
|