> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vexlo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 as reached by one call path from the root, 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 of the four names an attempt captures a value under: `input`, `output`, `error`, or `logs`; each carries a handle. | 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`. The SDK also writes a boolean `redacted` that ingest drops, so no read route carries it. | 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`). The Python SDK writes five of the seven: `stored`, `pending`, `sampled_out`, `too_large`, `not_captured`. | 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 keeps the state it would have had. Keys from `init(redact_keys=[...])`, 12 by default, each also matching its lower-, upper- and capitalized spelling. | 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, `tag()`, and `flush()` catch and count their own faults instead of raising, re-raising them only under `strict`; a marker whose own work faulted still runs the host's function as if unmarked, and the host's exception is re-raised bare. `init()` sits outside it and raises `ConfigurationError`, and a marker raises `UnsupportedCallable` at decoration over a binding descriptor or a non-callable, whose own call is already broken. | 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.