Glossary

The term this site uses for each concept, with the synonyms it does not use.

One term per concept, its definition in one line, and the synonyms this site bans for it. A field, enum value, flag, environment variable, record kind, or tool name keeps the spelling the code gives it, in code font, even where that spelling is a word the prose avoids. The page that owns a concept carries the longer account; the terms below run in reading order, not alphabetically.

Term	Definition	Banned synonyms
Vexlo	Captures how code actually ran in production, per-request execution graphs at function level with real inputs, outputs, and errors, served to humans (UI) and AI agents (MCP server).	the platform, the tool, observability platform
execution graph	A per-request record of actual execution: every step a function that ran, every edge a real invocation. The concept and the wire format.	request graph, call graph, execution trace
trace	The execution graph for one request in one service; trace_id is 32 lowercase hex characters, SDK-assigned.	request (as a name for it), graph (bare), session, transaction
step	A node in a trace: one marked function at one position in the call tree, identified by its path, carrying one or more attempts.	node, span, function call, frame
attempt	One execution of a step; a retried step has several, indexed from 0. A completed attempt is a step-attempt record with status, timing, and slots; an attempt reported while it was still running is a step-open record, and reads as in_flight with no duration_us and no slots.	retry (as the unit), invocation, call
attempt grouping	The SDK’s decision whether a call continues the previous child’s path as a new attempt, taken against the parent’s last completed child on five conditions; retries=True waives the same-error and same-input conditions. attempt_grouping is the server’s derived label single, declared, observed_retry.	retry detection, retry collapsing
mark (verb), marker	Decorate a function with @vexlo.trace or @vexlo.step; the decorator is a marker, and those two are the only markers. init(), tag(), flush(), diagnostics(), carrier(), and attach() are the SDK’s six other public calls, never called markers.	watch, instrument (a function), trace (verb), wrap, annotate
instrumented process	A process or host running the SDK with init() called. Never said of a function.	watched service, traced process
SDK	The package that runs inside a process, marks functions, captures values, and writes records to the spool directory. Python is the only one.	library, client library, agent
init()	The one call per process that configures the SDK; service is required; raises ConfigurationError on bad configuration.	setup, configure Vexlo (as a name)
service	The name set at init(), 1 to 128 printable ASCII characters; the leading key of the function index and what an ingest pin names.	app, application, component, deployment
instance id	instance_id: an opaque per-process id minted at init(), on every trace-open; two under one trace_id set instance_mismatch. Distinct from the writer id that names spool files.	process id, pid, replica id, writer id
team	The isolation boundary, derived from the credential: an ingest token binds one team, a read token one or more; ^[a-z0-9-]{1,64}$; ?team= narrows, never widens.	tenant, org, workspace, project, namespace
environment	An optional per-deployment label the relay daemon declares (-environment, sent as X-Vexlo-Environment), 1 to 64 printable ASCII characters, no comma; a filter with no isolation weight.	env (prose), stage, cluster
tag	A key/value pair on a trace’s trace-open record, from init(tag_keys=[...]) or vexlo.tag(); at most 32 per trace, key 64, value 256 characters; relates traces across services and never implies a call.	attribute, label, annotation, metadata, correlation id
entry point	A function-index property: a function observed opening a trace (is_entry_point). A null caller in observed_callers means entry point or orphan (a step whose parent never arrived), so it alone never proves one.	root (bare), handler, endpoint
root step	The step at path: "" in one trace; its function is root_function.	root node, top-level step, entry point
root_status	ok or error: the outcome of the root step’s last attempt; absent until that attempt’s completion record arrives, so a root present with an in_flight attempt leaves it absent.	trace status, request status, outcome
completeness	running, complete, partial, abandoned: whether every record of the trace arrived; derived at read time.	trace status, status (trace level), state
status	Attempt-level ok or error, plus in_flight for an attempt whose entry record arrived and whose completion record did not; in_flight is derived at read time and never on the wire. error_class accompanies error. Never used for a trace or for the health route.	result, outcome, success flag
slot	One captured value position on an attempt: input, output, error, or logs.	field, channel, argument, return value
handle	What a slot carries in place of bytes: state plus, when bytes were held, bytes_count, truncated, encoding, preview.	pointer, reference, stub, placeholder
handle state	Seven wire states (stored, pending, redacted, too_large, not_captured, sampled_out, dropped) and two read-time states (expired, missing).	value status, slot status, capture state
preview	The first 64 Unicode code points of a slot’s value, computed at capture time; display only.	snippet, excerpt, sample
value	The captured bytes of one slot (encoding json, text, or base64), fetched through /v1/traces/{id}/values or GET /v1/functions/examples?include=values. Also the value record kind and response field; qualify which.	payload, blob, data, body, content
path	A step’s identity: per-level ordinals from the root; lowercase hex on the wire ("" for the root), an opaque base32 string on the read API; never encodes the attempt. Rebuild trees from parent_path and depth, never by decoding it.	step id, node id, position, span id
record	One wire item of the five kinds: trace-open, step-open, step-attempt, value, trace-close. Never a trace or a step.	event, message, entry
coverage block	The coverage object on every trace-detail response: records_lost, records_shed, truncated and instance_mismatch always, plus service_loss_24h only while GET /v1/coverage lists that service. A list summary carries the four as flat scalars and no service_loss_24h.	coverage (bare), loss report, data quality
service coverage	GET /v1/coverage and vexlo_check_coverage: per service, traces_24h, marked_functions_seen, loss counters, last_seen_at. Names what is marked, never what is not.	coverage (bare), instrumentation coverage, code coverage
records_lost, records_shed	Records the SDK could not deliver (counted by the SDK on trace-close); records ingest rejected with trace_shed (counted by the server).	dropped records, lost data, throttled
truncated	Three fields: a handle cut at 16 KiB, a log message cut at 4 KiB, a trace that hit the 10,000-step cap. Always name which.	clipped, cut off, capped
redaction	Replacing a dict value whose key matches a redaction rule with {"$redacted":true} in place, at any depth including a top-level argument name; the slot stays stored. Keys from init(redact_keys=[...]), 12 by default.	masking, scrubbing, filtering, sanitising
adapter	The SDK’s fallback that turns a dataclass, namedtuple, or model_dump() object into a dict, marked captured_via: "adapter"; on by default.	serializer, plugin, converter
capture policy	The four fields a heartbeat resolves per (team, service): enabled, value_sample_rate, max_value_bytes, capture_logs; written by the daemon to <spool_dir>/policy/<service>.json; the SDK clamps downward only.	sampling config, remote config, policy (bare)
value sampling	Deciding once per trace on trace_id whether an ok trace’s values are kept; shape is always recorded; errors keep values.	trace sampling, head sampling, sample rate (bare)
heartbeat	POST /v1/heartbeat, sent by the relay daemon per (service, instance_id); always answered with the resolved capture policy.	ping, keepalive, health check
spool directory	The on-disk meeting point of SDK and daemon on one host (VEXLO_SPOOL_DIR, -spool-dir, default ~/.vexlo): spool/<hour>/<writer-id>.jsonl, cursor/, writers/, policy/.	local queue, buffer, spool (bare), data directory
server storage directory	The server’s storage location, holding vexlo.db and values/; ~/.vexlo/data by default. vexlo token names it with -data-dir (VEXLO_DATA_DIR); serve and check name the two parts with -db-path and -value-store-dir and fall back to the same default.	data dir, storage location, server directory, database directory
outbox	The SDK’s in-process memory queue (10,000 records / 16 MiB) drained by the vexlo-writer thread; overflow drops whole traces, except an entry record, which is dropped alone and leaves its trace’s structure intact.	queue (bare), buffer (bare)
relay daemon	vexlo relay run: one per host, tails the spool directory, batches, gzips, POSTs to the server, sends heartbeats, writes the policy file. “relay daemon” first, then “daemon”.	relay (bare), agent, forwarder, shipper, sidecar
server	vexlo serve: ingests records, owns storage, serves the /v1 API and the UI. “the Vexlo server” first, then “the server”.	collector, backend, ingest server
API token	vxlo_<role>_<token_id>_<secret>, shown once at vexlo token create, stored hashed; role ingest or read. “API token” first, then “token”.	API key, bearer (bare), credential, access token
pin	An optional restriction on an ingest token: -service and -environment; violations are 422 service_scope_mismatch / environment_scope_mismatch.	restriction, allowlist, scope (bare)
team-set	The teams a read token can see (team_ids on /v1/whoami).	team scope, visibility
no-auth mode	vexlo serve -no-auth: no tokens, loopback forced, rate limiting off, everything scoped to -team (default default); auth_mode: "none".	dev mode, insecure mode, anonymous mode
header-trust mode	Read-API auth where a reverse proxy injects X-Vexlo-Team and X-Vexlo-Trust-Secret; consulted only when Authorization is absent.	proxy auth, SSO mode, trusted headers
rate limit	Per-token buckets: reads 20 req/s burst 40; ingest 4,000 records/s burst 8,000 and 4 MiB/s burst 8 MiB; 429 rate_limited, Retry-After capped at 60 s.	throttle, quota, shedding
shedding	Ingest’s per-trace admission control under pressure: rejected per record with trace_shed, counted in records_shed.	throttling, rate limiting, dropping
shape	Steps, attempts, timing, status, and handles with previews, without value bytes; what GET /v1/traces/{id} returns; the middle rung of the ladder.	skeleton, metadata, outline
retention	Shape by day count (default 7 days), values against a byte budget (vexlo check reports the effective value retention), function index 90 days.	TTL (prose), expiry, garbage collection
expired, missing	Read-time handle states: the byte budget reclaimed stored bytes; an expected value record never arrived.	evicted, gone, lost, not found
the /v1 API	The HTTP read and ingest surface, 15 routes, the only way anything reads execution data. “the /v1 API” first, then “the API”. “endpoint” is used only for a route of the host application, never for a Vexlo route (say “route”).	REST API, backend API, endpoint (for a route)
cursor	?cursor= / next_cursor, opaque pagination on every list route. The relay daemon’s durable spool offset is always “spool cursor”.	page token, offset, checkpoint (for the spool cursor)
capabilities	GET /v1/capabilities: the unauthenticated route reporting server_version, api_version, features, auth_mode, limits; the MCP server reads its bounds from limits.	feature flags, server info, discovery
function index	Server-kept observed caller/callee pairs per (team, service, name), 90 days; a function that ran always has a row.	call graph, dependency graph
observed callers, observed callees	The function index’s two lists; always “observed”, never “the callers”.	callers, callees, dependents, dependencies
related traces	Same-team traces sharing a tag with the anchor within a window; relation: "shares_tag". A shared tag value relates them and proves neither a call nor one request.	linked traces, child traces, distributed trace
UI	The web interface embedded in the server binary, a read-token client of the API.	web app, dashboard, frontend, console
MCP server	vexlo-mcp: a stdio process an AI agent’s host launches, holding one read token and exposing eleven tools. Always with “MCP”.	MCP (bare), plugin, connector, integration
tool	One of the eleven MCP tools, vexlo_<verb>_<object>, camelCase arguments, responses are the API’s JSON.	function (collides with the index), command, action
find/shape/values ladder	The three rungs the tools sit on: find (seven tools, no captured value), shape (two), values (two).	cost ladder, drill-down levels
progressive disclosure	A trace readable at increasing depth, with values fetched only where the reader is looking.	lazy loading, levels of detail
token-cost ladder	The measured table of bytes and tokens per tool call.	cost ladder (bare), pricing, budget
scope note	scope_note: the string a tool attaches when a requested team is outside the token’s team-set.	warning, hint, notice
OpenTelemetry correlation	With correlate_otel=True (default), the active span’s trace id becomes the otel_trace_id tag, 32 lowercase hex characters; a pure read.	OTel integration, span linking, context propagation
never-raise boundary	The two markers and tag() catch and count their own faults and run the function as if unmarked, re-raising them only under strict; the host’s exception is re-raised bare. init() sits outside it and raises ConfigurationError; flush() never raises.	fail-safe, error swallowing
context	The ambient trace and step in contextvars; carried across threads with vexlo.carrier() / vexlo.attach().	trace context, propagation (as a name), thread-local
log entry	One element of the logs slot: level, logged_at_us, logger_name, message (4 KiB), truncated; 100 entries and 16 KiB per attempt.	log line, log record