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/store/db.py
ADDED
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
"""Trace file creation, opening, and run-metadata access."""
|
|
2
|
+
import importlib.metadata
|
|
3
|
+
import json
|
|
4
|
+
import os
|
|
5
|
+
import sqlite3
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
|
|
8
|
+
from sensorium import paths
|
|
9
|
+
|
|
10
|
+
TRACE_FORMAT = 4
|
|
11
|
+
|
|
12
|
+
# The languages this sensorium has a vocabulary column for
|
|
13
|
+
# (`query/vocab._TABLES`). A trace naming any other is refused at open,
|
|
14
|
+
# ONCE, rather than narrated in another language's words by every renderer
|
|
15
|
+
# in turn: until S5 an unknown `lang` fell back to the Python column, which
|
|
16
|
+
# told a reader of such a trace about `asyncio tasks` and `python ?`. The
|
|
17
|
+
# order is the order the columns were written, and it is the order the
|
|
18
|
+
# refusal lists them in.
|
|
19
|
+
KNOWN_LANGS = ("python", "rust", "typescript", "c")
|
|
20
|
+
|
|
21
|
+
# Keys a finalized format-4 trace MUST carry (spec §5.1). Every reader
|
|
22
|
+
# defaults these when absent; on a trace that claims `incomplete = False`
|
|
23
|
+
# that default would print as a measured zero, so absence is refused here,
|
|
24
|
+
# once, instead of guarded at every `.get(key, 0)`.
|
|
25
|
+
REQUIRED_META = ("run_id", "argv", "cwd", "env_hash", "start_ts", "end_ts",
|
|
26
|
+
"exit_status", "main_thread_ident", "fingerprint_basis",
|
|
27
|
+
"truncated_count", "source_hashes",
|
|
28
|
+
"recorder", "lang", "capabilities")
|
|
29
|
+
# Witness keys, required only when the recorder declares the capability
|
|
30
|
+
# that produces them. A capability declared False means "not witnessed",
|
|
31
|
+
# which every reader prints as such -- never as zero, never as "predates".
|
|
32
|
+
WITNESS_KEYS = {"threads": ("threads_started", "live_threads"),
|
|
33
|
+
"children": ("children", "spawn_syscalls", "audit_errors"),
|
|
34
|
+
"stdin": ("stdin_consumed",)}
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class TraceFormatError(Exception):
|
|
38
|
+
"""A trace this sensorium must not read: written by a NEWER sensorium,
|
|
39
|
+
or a format-4 trace that claims to be finalized without the keys the
|
|
40
|
+
format requires.
|
|
41
|
+
|
|
42
|
+
`trace_format` is stamped at creation; a higher value means the file's
|
|
43
|
+
layout may differ from what these queries assume. A trace with no
|
|
44
|
+
`trace_format` at all predates the key and is read as format 1. Format
|
|
45
|
+
2 (async attribution) added events.task_id, the tasks table and
|
|
46
|
+
CALL-payload keys. Format 3 (inspectable coroutines) added frames.kind,
|
|
47
|
+
the YIELD/RESUME event kinds, and task_fingerprints. Format 4 (the
|
|
48
|
+
trace-format contract, docs/TRACE-FORMAT.md) adds no column: it makes
|
|
49
|
+
`recorder`, `lang` and `capabilities` required meta, and requires the
|
|
50
|
+
finalize keys above on any trace that says `incomplete = False`, so a
|
|
51
|
+
second recorder can never render an absent record as a zero.
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
SCHEMA = """
|
|
55
|
+
CREATE TABLE meta (
|
|
56
|
+
key TEXT PRIMARY KEY,
|
|
57
|
+
value TEXT NOT NULL
|
|
58
|
+
);
|
|
59
|
+
CREATE TABLE code_objects (
|
|
60
|
+
id INTEGER PRIMARY KEY,
|
|
61
|
+
file TEXT NOT NULL,
|
|
62
|
+
qualname TEXT NOT NULL,
|
|
63
|
+
firstlineno INTEGER NOT NULL
|
|
64
|
+
);
|
|
65
|
+
CREATE TABLE frames (
|
|
66
|
+
id INTEGER PRIMARY KEY,
|
|
67
|
+
parent_id INTEGER,
|
|
68
|
+
code_id INTEGER NOT NULL,
|
|
69
|
+
call_event_id INTEGER NOT NULL,
|
|
70
|
+
return_event_id INTEGER,
|
|
71
|
+
depth INTEGER NOT NULL,
|
|
72
|
+
thread_id INTEGER NOT NULL,
|
|
73
|
+
closed_by TEXT,
|
|
74
|
+
unwind_exc TEXT,
|
|
75
|
+
kind TEXT
|
|
76
|
+
);
|
|
77
|
+
CREATE TABLE events (
|
|
78
|
+
id INTEGER PRIMARY KEY,
|
|
79
|
+
ts_ns INTEGER NOT NULL,
|
|
80
|
+
thread_id INTEGER NOT NULL,
|
|
81
|
+
kind TEXT NOT NULL,
|
|
82
|
+
frame_id INTEGER,
|
|
83
|
+
code_id INTEGER,
|
|
84
|
+
line INTEGER,
|
|
85
|
+
payload TEXT,
|
|
86
|
+
task_id INTEGER
|
|
87
|
+
);
|
|
88
|
+
CREATE TABLE output (
|
|
89
|
+
id INTEGER PRIMARY KEY,
|
|
90
|
+
after_event_id INTEGER NOT NULL,
|
|
91
|
+
stream TEXT NOT NULL,
|
|
92
|
+
data TEXT NOT NULL
|
|
93
|
+
);
|
|
94
|
+
CREATE TABLE tasks (
|
|
95
|
+
id INTEGER PRIMARY KEY,
|
|
96
|
+
name TEXT,
|
|
97
|
+
thread_id INTEGER NOT NULL
|
|
98
|
+
);
|
|
99
|
+
CREATE TABLE fingerprints (
|
|
100
|
+
thread_id INTEGER PRIMARY KEY,
|
|
101
|
+
hash TEXT NOT NULL,
|
|
102
|
+
n_events INTEGER NOT NULL
|
|
103
|
+
);
|
|
104
|
+
CREATE TABLE task_fingerprints (
|
|
105
|
+
task_id INTEGER PRIMARY KEY,
|
|
106
|
+
name TEXT,
|
|
107
|
+
hash TEXT NOT NULL,
|
|
108
|
+
n_events INTEGER NOT NULL
|
|
109
|
+
);
|
|
110
|
+
CREATE INDEX idx_events_code ON events(code_id);
|
|
111
|
+
CREATE INDEX idx_events_frame ON events(frame_id);
|
|
112
|
+
CREATE INDEX idx_events_kind ON events(kind);
|
|
113
|
+
CREATE INDEX idx_frames_code ON frames(code_id);
|
|
114
|
+
"""
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def _create_parent(parent: Path) -> None:
|
|
118
|
+
"""The directory a trace is about to be written into, 0700 (R35).
|
|
119
|
+
|
|
120
|
+
This was `parent.mkdir(parents=True, exist_ok=True)` -- the last
|
|
121
|
+
default-mode creator left inside the store after E16 part A. It is
|
|
122
|
+
normally preceded by `paths.traces_dir()`, so the hole was latent (E16
|
|
123
|
+
read `traces/` at 0700), but a caller reaching here first would have
|
|
124
|
+
made the directory holding every trace on the box world-listable.
|
|
125
|
+
|
|
126
|
+
Routed through `paths.traces_dir()` when the parent IS the store's own
|
|
127
|
+
`traces/`, so that directory has ONE owner and one rule. Otherwise the
|
|
128
|
+
same two-level idiom that function documents: `mkdir(parents=True,
|
|
129
|
+
mode=...)` applies the mode to the directory it NAMES and gives every
|
|
130
|
+
parent it creates the default, so the level above is created explicitly
|
|
131
|
+
too. An existing directory is never chmod'ed.
|
|
132
|
+
|
|
133
|
+
The comparison is against `trace_root() / "traces"` and not against
|
|
134
|
+
`traces_dir()`, because the latter CREATES what it names: asking it
|
|
135
|
+
where the store is would mint a `~/.sensorium` for a caller writing a
|
|
136
|
+
trace somewhere else entirely. `RuntimeError` is `Path.home()`'s answer
|
|
137
|
+
when there is no home and `SENSORIUM_DIR` is unset -- then this is not
|
|
138
|
+
the store's `traces/` by definition.
|
|
139
|
+
"""
|
|
140
|
+
try:
|
|
141
|
+
is_the_store = parent == paths.trace_root() / "traces"
|
|
142
|
+
except RuntimeError:
|
|
143
|
+
is_the_store = False
|
|
144
|
+
if is_the_store:
|
|
145
|
+
paths.traces_dir()
|
|
146
|
+
return
|
|
147
|
+
parent.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
|
|
148
|
+
parent.mkdir(exist_ok=True, mode=0o700)
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def create_trace(path: Path) -> sqlite3.Connection:
|
|
152
|
+
path = Path(path)
|
|
153
|
+
_create_parent(path.parent)
|
|
154
|
+
# The trace exists at 0600 from its first instant. sqlite would create
|
|
155
|
+
# it 0666-under-the-umask -- 0644 on most boxes -- and a trace holds the
|
|
156
|
+
# whole recorded environment, so the window between "file appears" and
|
|
157
|
+
# "we chmod it" is the window the spec closes (design §5.5).
|
|
158
|
+
#
|
|
159
|
+
# No `O_EXCL`: `ts/ingest.py` reserves a run id by creating the file
|
|
160
|
+
# itself, `O_EXCL`, and hands TraceWriter the zero-byte result, which
|
|
161
|
+
# sqlite opens as a new database exactly as it would its own. The guard
|
|
162
|
+
# against an explicit `--run-id` colliding with a real trace stays where
|
|
163
|
+
# it was, in `boot.run_target`'s `trace_path.exists()` refusal.
|
|
164
|
+
#
|
|
165
|
+
# `fchmod` behind the open because `O_CREAT`'s mode applies only when
|
|
166
|
+
# the open CREATES the file: on ingest's reserved file it is ignored,
|
|
167
|
+
# and that file was made 0600 by its own creator -- fchmod is what makes
|
|
168
|
+
# this function's promise hold whichever of the two paths arrived.
|
|
169
|
+
fd = os.open(path, os.O_WRONLY | os.O_CREAT, 0o600)
|
|
170
|
+
try:
|
|
171
|
+
os.fchmod(fd, 0o600)
|
|
172
|
+
finally:
|
|
173
|
+
os.close(fd)
|
|
174
|
+
# The tracer flushes on whichever thread fills the batch, so the write
|
|
175
|
+
# connection outlives its creating thread. TraceWriter serialises every
|
|
176
|
+
# access under its own lock, which is the invariant check_same_thread
|
|
177
|
+
# approximates. (open_trace stays checked: the read path is single-threaded.)
|
|
178
|
+
conn = sqlite3.connect(path, check_same_thread=False)
|
|
179
|
+
conn.execute("PRAGMA journal_mode=WAL")
|
|
180
|
+
conn.executescript(SCHEMA)
|
|
181
|
+
set_meta(conn, "trace_format", TRACE_FORMAT)
|
|
182
|
+
conn.commit()
|
|
183
|
+
return conn
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def missing_required(conn: sqlite3.Connection) -> list[str]:
|
|
187
|
+
"""Required keys absent from a trace that claims to be finalized, in
|
|
188
|
+
a stable order; [] when nothing is missing or the claim is not made.
|
|
189
|
+
|
|
190
|
+
A `capabilities` that is present but not a dict counts as absent. This
|
|
191
|
+
is a validation boundary for a recorder nobody here wrote: a list, a
|
|
192
|
+
string or a null is not a declaration this reader can act on, and
|
|
193
|
+
reporting it by name is the whole point of the mechanism. Reading it
|
|
194
|
+
anyway would raise AttributeError out of `open_trace`, which the CLI
|
|
195
|
+
does not catch, or -- for null -- pass silently and be rendered
|
|
196
|
+
downstream as the full Python capability set.
|
|
197
|
+
"""
|
|
198
|
+
if get_meta(conn, "incomplete") is not False:
|
|
199
|
+
return []
|
|
200
|
+
present = {k for (k,) in conn.execute("SELECT key FROM meta")}
|
|
201
|
+
missing = [k for k in REQUIRED_META if k not in present]
|
|
202
|
+
caps = get_meta(conn, "capabilities")
|
|
203
|
+
if not isinstance(caps, dict):
|
|
204
|
+
if "capabilities" not in missing:
|
|
205
|
+
missing.append("capabilities")
|
|
206
|
+
caps = {}
|
|
207
|
+
for cap, keys in WITNESS_KEYS.items():
|
|
208
|
+
if caps.get(cap):
|
|
209
|
+
missing += [k for k in keys if k not in present]
|
|
210
|
+
return missing
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def open_trace(path: Path) -> sqlite3.Connection:
|
|
214
|
+
path = Path(path)
|
|
215
|
+
if not path.exists():
|
|
216
|
+
raise FileNotFoundError(f"no trace at {path}")
|
|
217
|
+
conn = sqlite3.connect(path)
|
|
218
|
+
fmt = get_meta(conn, "trace_format")
|
|
219
|
+
if fmt is not None and fmt > TRACE_FORMAT:
|
|
220
|
+
conn.close()
|
|
221
|
+
raise TraceFormatError(
|
|
222
|
+
f"{path} is trace format {fmt}, newer than this sensorium reads "
|
|
223
|
+
f"(up to {TRACE_FORMAT}); upgrade sensorium to open it")
|
|
224
|
+
if fmt is not None and fmt >= 4:
|
|
225
|
+
missing = missing_required(conn)
|
|
226
|
+
if missing:
|
|
227
|
+
who = _recorder_name(conn)
|
|
228
|
+
conn.close()
|
|
229
|
+
raise TraceFormatError(
|
|
230
|
+
f"{path} claims to be finalized (incomplete = false) but "
|
|
231
|
+
f"lacks required meta {', '.join(missing)} -- written by "
|
|
232
|
+
f"{who}; format 4 refuses rather than read those as zero")
|
|
233
|
+
# A `lang` no reader has words for, refused HERE and nowhere else: one
|
|
234
|
+
# choke point every command goes through, so `info`, `tree`, `grep` and
|
|
235
|
+
# `diff` cannot answer it differently -- and so no renderer has to
|
|
236
|
+
# remember the check. An ABSENT `lang` is not unknown: it predates the
|
|
237
|
+
# key and is the Python recorder's, which is what `Trace.lang` reads it
|
|
238
|
+
# as. `cli.main` turns this into `error: ...` at exit 2.
|
|
239
|
+
lang = get_meta(conn, "lang")
|
|
240
|
+
if lang is not None and lang not in KNOWN_LANGS:
|
|
241
|
+
who = _recorder_name(conn)
|
|
242
|
+
conn.close()
|
|
243
|
+
raise TraceFormatError(
|
|
244
|
+
f"{path} was written by {who} for lang {lang!r}, which this "
|
|
245
|
+
f"sensorium ({_version()}) has no vocabulary for "
|
|
246
|
+
f"({', '.join(KNOWN_LANGS)}); upgrade sensorium to read it")
|
|
247
|
+
return conn
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def _recorder_name(conn: sqlite3.Connection) -> str:
|
|
251
|
+
"""Who wrote this trace, for a refusal to name. `meta["recorder"]` when
|
|
252
|
+
it is a name, and the words for its absence otherwise -- absent, null
|
|
253
|
+
or not a string are one case to a reader: nobody said."""
|
|
254
|
+
who = get_meta(conn, "recorder")
|
|
255
|
+
if not isinstance(who, str) or not who:
|
|
256
|
+
return "an unnamed recorder"
|
|
257
|
+
return who
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def _version() -> str:
|
|
261
|
+
"""This sensorium's own version, for the sentence that says an upgrade
|
|
262
|
+
is what would read the file. `?` from a source tree that was never
|
|
263
|
+
installed: a refusal must not fail while explaining itself."""
|
|
264
|
+
try:
|
|
265
|
+
return importlib.metadata.version("sensorium-trace")
|
|
266
|
+
except importlib.metadata.PackageNotFoundError:
|
|
267
|
+
return "?"
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
def set_meta(conn: sqlite3.Connection, key: str, value) -> None:
|
|
271
|
+
conn.execute(
|
|
272
|
+
"INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)",
|
|
273
|
+
(key, json.dumps(value, separators=(",", ":"))),
|
|
274
|
+
)
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
def get_meta(conn: sqlite3.Connection, key: str, default=None):
|
|
278
|
+
row = conn.execute("SELECT value FROM meta WHERE key = ?", (key,)).fetchone()
|
|
279
|
+
return default if row is None else json.loads(row[0])
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
def all_meta(conn: sqlite3.Connection) -> dict:
|
|
283
|
+
return {k: json.loads(v)
|
|
284
|
+
for k, v in conn.execute("SELECT key, value FROM meta")}
|
sensorium/store/gc.py
ADDED
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
"""Delete traces the store no longer needs to keep.
|
|
2
|
+
|
|
3
|
+
``gc`` removes a trace when it is older than the age limit, past the keep
|
|
4
|
+
count, or what has to go to bring the store under its size budget. A pinned
|
|
5
|
+
run and the most recent run are never deleted, even when that leaves the
|
|
6
|
+
store over the count or the budget. ``--dry-run`` prints the same set and
|
|
7
|
+
deletes nothing.
|
|
8
|
+
|
|
9
|
+
Pins live in ``$SENSORIUM_DIR/pins.json`` (``{"runs": [...]}``, mode 0600),
|
|
10
|
+
outside any trace file. Automatic cleanup after a recording calls
|
|
11
|
+
``maybe_auto``, which is a no-op unless a retention rule is set in the
|
|
12
|
+
environment or the config file, and which never changes the recorded
|
|
13
|
+
program's exit status.
|
|
14
|
+
"""
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import json
|
|
18
|
+
import os
|
|
19
|
+
import sqlite3
|
|
20
|
+
import time
|
|
21
|
+
from dataclasses import dataclass
|
|
22
|
+
from pathlib import Path
|
|
23
|
+
|
|
24
|
+
from sensorium.limits import LimitsError, store_policy
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class GcError(ValueError):
|
|
28
|
+
"""A retention rule or a pins file that cannot be acted on."""
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@dataclass(frozen=True)
|
|
32
|
+
class Item:
|
|
33
|
+
path: Path
|
|
34
|
+
run_id: str
|
|
35
|
+
mtime: float
|
|
36
|
+
size: int
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
@dataclass(frozen=True)
|
|
40
|
+
class Plan:
|
|
41
|
+
victims: tuple[Item, ...]
|
|
42
|
+
kept: tuple[Item, ...]
|
|
43
|
+
protected: frozenset[str]
|
|
44
|
+
total_before: int
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def format_bytes(n: int) -> str:
|
|
48
|
+
n = int(n)
|
|
49
|
+
for unit, step in (("GiB", 1024 ** 3), ("MiB", 1024 ** 2), ("KiB", 1024)):
|
|
50
|
+
if abs(n) >= step:
|
|
51
|
+
return f"{n / step:.1f} {unit}"
|
|
52
|
+
return f"{n} B"
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _root(environ: dict | None = None) -> Path:
|
|
56
|
+
env = os.environ if environ is None else environ
|
|
57
|
+
raw = env.get("SENSORIUM_DIR")
|
|
58
|
+
return Path(raw) if raw else Path.home() / ".sensorium"
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _pins_path(root: Path) -> Path:
|
|
62
|
+
return root / "pins.json"
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def load_pins(root: Path | None = None) -> list[str]:
|
|
66
|
+
"""Run ids ``gc`` must not delete. A missing file is an empty list.
|
|
67
|
+
|
|
68
|
+
A file that exists and is not ``{"runs": [...]}`` is an error: treating
|
|
69
|
+
it as empty would delete a run the user had pinned.
|
|
70
|
+
"""
|
|
71
|
+
path = _pins_path(root or _root())
|
|
72
|
+
if not path.is_file():
|
|
73
|
+
return []
|
|
74
|
+
try:
|
|
75
|
+
data = json.loads(path.read_text(encoding="utf-8"))
|
|
76
|
+
except (OSError, json.JSONDecodeError) as e:
|
|
77
|
+
raise GcError(f"cannot read {path}: {e}") from e
|
|
78
|
+
if not isinstance(data, dict) or not isinstance(data.get("runs"), list):
|
|
79
|
+
raise GcError(f"{path} must be a JSON object with a runs list")
|
|
80
|
+
runs = []
|
|
81
|
+
for item in data["runs"]:
|
|
82
|
+
if not isinstance(item, str) or not item or item != Path(item).name:
|
|
83
|
+
raise GcError(f"{path} has a run id that is not a single name")
|
|
84
|
+
runs.append(item)
|
|
85
|
+
return runs
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def save_pins(runs: list[str], root: Path | None = None) -> Path:
|
|
89
|
+
root = root or _root()
|
|
90
|
+
root.mkdir(parents=True, exist_ok=True, mode=0o700)
|
|
91
|
+
path = _pins_path(root)
|
|
92
|
+
payload = json.dumps({"runs": runs}, indent=2) + "\n"
|
|
93
|
+
tmp = path.with_suffix(".json.tmp")
|
|
94
|
+
fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
|
|
95
|
+
try:
|
|
96
|
+
os.write(fd, payload.encode("utf-8"))
|
|
97
|
+
os.fsync(fd)
|
|
98
|
+
finally:
|
|
99
|
+
os.close(fd)
|
|
100
|
+
os.replace(tmp, path)
|
|
101
|
+
os.chmod(path, 0o600)
|
|
102
|
+
return path
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def _trace_size(path: Path) -> int:
|
|
106
|
+
total = path.stat().st_size
|
|
107
|
+
for ext in ("-wal", "-shm"):
|
|
108
|
+
side = Path(str(path) + ext)
|
|
109
|
+
if side.is_file():
|
|
110
|
+
total += side.stat().st_size
|
|
111
|
+
return total
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def list_traces(root: Path | None = None) -> list[Item]:
|
|
115
|
+
"""``*.db`` files already in the store. Does not create the directory."""
|
|
116
|
+
directory = (root or _root()) / "traces"
|
|
117
|
+
if not directory.is_dir():
|
|
118
|
+
return []
|
|
119
|
+
base = directory.resolve()
|
|
120
|
+
found = []
|
|
121
|
+
for path in directory.glob("*.db"):
|
|
122
|
+
try:
|
|
123
|
+
resolved = path.resolve()
|
|
124
|
+
except OSError:
|
|
125
|
+
continue
|
|
126
|
+
if resolved.parent != base:
|
|
127
|
+
continue
|
|
128
|
+
try:
|
|
129
|
+
stat = path.stat()
|
|
130
|
+
except OSError:
|
|
131
|
+
continue
|
|
132
|
+
found.append(Item(path, path.stem, stat.st_mtime, _trace_size(path)))
|
|
133
|
+
return found
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def plan(policy, *, root: Path | None = None,
|
|
137
|
+
now: float | None = None) -> Plan:
|
|
138
|
+
"""Which traces ``policy`` would delete. Reads pins; deletes nothing."""
|
|
139
|
+
root = root or _root()
|
|
140
|
+
items = list_traces(root)
|
|
141
|
+
pins = set(load_pins(root))
|
|
142
|
+
if not items:
|
|
143
|
+
return Plan((), (), frozenset(pins), 0)
|
|
144
|
+
newest_first = sorted(items, key=lambda item: (item.mtime, item.run_id),
|
|
145
|
+
reverse=True)
|
|
146
|
+
protected = set(pins)
|
|
147
|
+
protected.add(newest_first[0].run_id)
|
|
148
|
+
victims: dict[str, Item] = {}
|
|
149
|
+
moment = time.time() if now is None else now
|
|
150
|
+
if policy.older_than is not None:
|
|
151
|
+
cutoff = moment - policy.older_than
|
|
152
|
+
for item in newest_first:
|
|
153
|
+
if item.run_id not in protected and item.mtime < cutoff:
|
|
154
|
+
victims[item.run_id] = item
|
|
155
|
+
if policy.keep is not None:
|
|
156
|
+
kept = 0
|
|
157
|
+
for item in newest_first:
|
|
158
|
+
if item.run_id in victims:
|
|
159
|
+
continue
|
|
160
|
+
if kept < policy.keep:
|
|
161
|
+
kept += 1
|
|
162
|
+
continue
|
|
163
|
+
if item.run_id not in protected:
|
|
164
|
+
victims[item.run_id] = item
|
|
165
|
+
remaining = [item for item in newest_first if item.run_id not in victims]
|
|
166
|
+
if policy.max_bytes is not None:
|
|
167
|
+
total = sum(item.size for item in remaining)
|
|
168
|
+
for item in reversed(remaining):
|
|
169
|
+
if total <= policy.max_bytes:
|
|
170
|
+
break
|
|
171
|
+
if item.run_id in protected:
|
|
172
|
+
continue
|
|
173
|
+
victims[item.run_id] = item
|
|
174
|
+
total -= item.size
|
|
175
|
+
victim_list = tuple(item for item in reversed(newest_first)
|
|
176
|
+
if item.run_id in victims)
|
|
177
|
+
kept_list = tuple(item for item in newest_first
|
|
178
|
+
if item.run_id not in victims)
|
|
179
|
+
return Plan(victim_list, kept_list, frozenset(protected),
|
|
180
|
+
sum(item.size for item in items))
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def _unlink(path: Path) -> None:
|
|
184
|
+
path.unlink(missing_ok=True)
|
|
185
|
+
for ext in ("-wal", "-shm"):
|
|
186
|
+
Path(str(path) + ext).unlink(missing_ok=True)
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
def vacuum(path: Path) -> None:
|
|
190
|
+
"""Checkpoint and rebuild one remaining trace so deleted pages are gone."""
|
|
191
|
+
conn = sqlite3.connect(path)
|
|
192
|
+
try:
|
|
193
|
+
conn.isolation_level = None
|
|
194
|
+
conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
|
|
195
|
+
conn.execute("VACUUM")
|
|
196
|
+
finally:
|
|
197
|
+
conn.close()
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def apply(chosen: Plan, *, dry_run: bool = False) -> tuple[int, int, list[str]]:
|
|
201
|
+
"""Delete ``chosen.victims``. Returns ``(count, bytes, vacuum notes)``.
|
|
202
|
+
|
|
203
|
+
Dry-run deletes nothing and does not vacuum. Vacuum runs only after a
|
|
204
|
+
real deletion, and only on the traces that remain.
|
|
205
|
+
"""
|
|
206
|
+
if dry_run or not chosen.victims:
|
|
207
|
+
return 0, 0, []
|
|
208
|
+
freed = 0
|
|
209
|
+
for item in chosen.victims:
|
|
210
|
+
freed += item.size
|
|
211
|
+
_unlink(item.path)
|
|
212
|
+
notes = []
|
|
213
|
+
for item in chosen.kept:
|
|
214
|
+
try:
|
|
215
|
+
vacuum(item.path)
|
|
216
|
+
except sqlite3.Error as e:
|
|
217
|
+
notes.append(f"{item.run_id}: {e}")
|
|
218
|
+
return len(chosen.victims), freed, notes
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def render(chosen: Plan, *, dry_run: bool, deleted: int, freed: int,
|
|
222
|
+
notes: list[str]) -> str:
|
|
223
|
+
if not chosen.victims:
|
|
224
|
+
return "nothing to delete"
|
|
225
|
+
lines = []
|
|
226
|
+
verb = "would delete" if dry_run else "deleted"
|
|
227
|
+
shown = chosen.victims if dry_run else chosen.victims
|
|
228
|
+
for item in shown:
|
|
229
|
+
lines.append(f"{verb} {item.run_id} ({format_bytes(item.size)})")
|
|
230
|
+
if dry_run:
|
|
231
|
+
total = sum(item.size for item in chosen.victims)
|
|
232
|
+
lines.append(
|
|
233
|
+
f"dry-run: {len(chosen.victims)} traces, {format_bytes(total)}")
|
|
234
|
+
else:
|
|
235
|
+
lines.append(f"deleted {deleted} traces, freed {format_bytes(freed)}")
|
|
236
|
+
return "\n".join(lines)
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
def maybe_auto(environ: dict | None = None) -> str | None:
|
|
240
|
+
"""Apply the configured retention rule. ``None`` when there is no rule
|
|
241
|
+
or nothing to delete. A failure here is the caller's to report."""
|
|
242
|
+
policy = store_policy(environ=environ)
|
|
243
|
+
if policy.is_empty():
|
|
244
|
+
return None
|
|
245
|
+
chosen = plan(policy, root=_root(environ))
|
|
246
|
+
if not chosen.victims:
|
|
247
|
+
return None
|
|
248
|
+
deleted, freed, _notes = apply(chosen)
|
|
249
|
+
if not deleted:
|
|
250
|
+
return None
|
|
251
|
+
return (f"sensorium: gc deleted {deleted} traces, "
|
|
252
|
+
f"freed {format_bytes(freed)}")
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def _policy_from_args(args):
|
|
256
|
+
from sensorium.limits import parse_duration
|
|
257
|
+
older = None if args.older_than is None else parse_duration(args.older_than)
|
|
258
|
+
return store_policy(max_bytes=args.max_bytes, keep=args.keep,
|
|
259
|
+
older_than=older)
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
def gc_main(args) -> int:
|
|
263
|
+
try:
|
|
264
|
+
policy = _policy_from_args(args)
|
|
265
|
+
except (LimitsError, GcError) as e:
|
|
266
|
+
print(f"error: {e}", file=_err())
|
|
267
|
+
return 2
|
|
268
|
+
if policy.is_empty():
|
|
269
|
+
print("error: gc needs --older-than, --keep, or --max-bytes "
|
|
270
|
+
"(or the same rule in the environment or the config file)",
|
|
271
|
+
file=_err())
|
|
272
|
+
return 2
|
|
273
|
+
try:
|
|
274
|
+
chosen = plan(policy)
|
|
275
|
+
except GcError as e:
|
|
276
|
+
print(f"error: {e}", file=_err())
|
|
277
|
+
return 2
|
|
278
|
+
deleted, freed, notes = apply(chosen, dry_run=args.dry_run)
|
|
279
|
+
print(render(chosen, dry_run=args.dry_run, deleted=deleted, freed=freed,
|
|
280
|
+
notes=notes))
|
|
281
|
+
for note in notes:
|
|
282
|
+
print(f"sensorium: vacuum failed: {note}", file=_err())
|
|
283
|
+
return 0
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
def pin_main(args) -> int:
|
|
287
|
+
from sensorium import paths
|
|
288
|
+
try:
|
|
289
|
+
path = paths.find_trace(args.run)
|
|
290
|
+
runs = load_pins()
|
|
291
|
+
except (paths.TraceLookupError, GcError) as e:
|
|
292
|
+
print(f"error: {e}", file=_err())
|
|
293
|
+
return 2
|
|
294
|
+
run_id = path.stem
|
|
295
|
+
if run_id not in runs:
|
|
296
|
+
runs.append(run_id)
|
|
297
|
+
save_pins(runs)
|
|
298
|
+
print(f"pinned: {run_id}")
|
|
299
|
+
return 0
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
def unpin_main(args) -> int:
|
|
303
|
+
from sensorium import paths
|
|
304
|
+
try:
|
|
305
|
+
runs = load_pins()
|
|
306
|
+
except GcError as e:
|
|
307
|
+
print(f"error: {e}", file=_err())
|
|
308
|
+
return 2
|
|
309
|
+
target = args.run
|
|
310
|
+
try:
|
|
311
|
+
target = paths.find_trace(args.run).stem
|
|
312
|
+
except paths.TraceLookupError:
|
|
313
|
+
target = args.run
|
|
314
|
+
if target not in runs:
|
|
315
|
+
print(f"error: {args.run!r} is not pinned", file=_err())
|
|
316
|
+
return 2
|
|
317
|
+
save_pins([run for run in runs if run != target])
|
|
318
|
+
print(f"unpinned: {target}")
|
|
319
|
+
return 0
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
def _err():
|
|
323
|
+
import sys
|
|
324
|
+
return sys.stderr
|
|
325
|
+
|
|
326
|
+
|
|
327
|
+
def add_parsers(sub) -> None:
|
|
328
|
+
gc = sub.add_parser(
|
|
329
|
+
"gc", help="delete traces the store no longer needs",
|
|
330
|
+
description="Removes traces by age, by how many to keep, or by a "
|
|
331
|
+
"total size. A pinned trace and the most recent trace "
|
|
332
|
+
"are kept even when that exceeds the rule. With no rule "
|
|
333
|
+
"on the command, in the environment, or in the config "
|
|
334
|
+
"file, nothing is deleted.",
|
|
335
|
+
epilog="exit: 0 done, 2 fix the call")
|
|
336
|
+
gc.add_argument("--dry-run", action="store_true",
|
|
337
|
+
help="print the traces that would be deleted and delete nothing")
|
|
338
|
+
gc.add_argument("--older-than", default=None,
|
|
339
|
+
help="delete traces older than this duration (30d, 12h, 2w, 45m)")
|
|
340
|
+
gc.add_argument("--keep", default=None,
|
|
341
|
+
help="how many of the newest traces to keep; must be >= 1")
|
|
342
|
+
gc.add_argument("--max-bytes", default=None,
|
|
343
|
+
help="delete the oldest traces until the store is under this size")
|
|
344
|
+
gc.set_defaults(func=gc_main)
|
|
345
|
+
|
|
346
|
+
pin = sub.add_parser(
|
|
347
|
+
"pin", help="keep one trace from gc",
|
|
348
|
+
description="Records the run id in the store's pins file. gc never "
|
|
349
|
+
"deletes a pinned trace.",
|
|
350
|
+
epilog="exit: 0 pinned, 2 fix the call")
|
|
351
|
+
pin.add_argument("run", help="a run id, a unique prefix, or last")
|
|
352
|
+
pin.set_defaults(func=pin_main)
|
|
353
|
+
|
|
354
|
+
unpin = sub.add_parser(
|
|
355
|
+
"unpin", help="drop a trace from the pins file",
|
|
356
|
+
description="Removes the run id from the store's pins file. The "
|
|
357
|
+
"trace itself is left where it is.",
|
|
358
|
+
epilog="exit: 0 unpinned, 2 fix the call")
|
|
359
|
+
unpin.add_argument("run", help="a run id, a unique prefix, or last")
|
|
360
|
+
unpin.set_defaults(func=unpin_main)
|