| 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 |
Reference
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.