Skip to main content
Check the application, local queue, relay, server and reader separately. The SDK writes locally; the relay forwards those records. A local flush does not confirm server delivery, and a successful HTTP connection does not establish that the application recorded anything.

​
Establish a delivery-health baseline

Set the application’s queue path, the server URL and a read token, then inspect delivery:
For the relay’s default health address, check:
Use your configured -health-addr instead when it differs. The relay also exposes /metrics on that listener. These local endpoints are separate from authenticated /v1/health. A zero backlog can mean records were sent or terminally dropped. Compare sent and dropped counters, then find a known execution on the server. Server loss information depends on what reached the server; compare it with the local queue.

​
No recording appears

  1. Confirm init() ran before the marked entry point. A @vexlo.step outside a trace does not start a recording. Inspect vexlo.diagnostics() in the application process, including steps_outside_trace and internal-error counters.
  2. Check local enabled configuration and service policy. Confirm the SDK and relay use the same queue directory.
  3. Run relay status against that directory. If no writer appears, confirm the SDK selected that directory and the entry point executed. Inspect a backlog for delivery failures. Check relay logs and the destination/token settings.
  4. Check server access with whoami, then reader team, environment, service and time filters. A correctly recorded trace outside your token’s scope looks absent.

​
The server was unreachable

Network errors, 429, and HTTP 500, 502, 503 and 504 are retryable. Restore the server or correct the destination while the records remain queued. Queue pressure can evict unsent records during an outage. See local queue retention.

​
The server rejected records

Other response statuses are terminal, including invalid or wrong-role credentials. The relay counts the rejected records as daemon_terminal_reject and advances past them. Correcting the credential prevents later rejections; it does not automatically send the rejected records again. A wrong-role relay credential produced this queue status:
The first writer sent seven records. The second had seven terminal drops and zero backlog. After replacing the credential, those dropped records remained counted and were not retried. The raw files still occupied queue space; their presence did not make the records pending. Do not reset delivery cursors or edit queue files to attempt recovery. Correct the destination or credential, verify delivery of a new identified execution, and preserve diagnostic files for investigating the loss.

​
Authentication or transport fails

The API returned this response after a credential was revoked:
Follow Authentication for issuance, replacement and transport configuration. Token commands must open the same database the server uses.

​
Calls or values are missing

Review Capture controls before changing what leaves the process. For missing bytes, Retention distinguishes capture decisions, delivery loss and server expiry. Increasing a budget cannot reconstruct bytes already unavailable.

​
Capture resumes after a policy outage

The Python SDK falls back to init() configuration when its policy file is unusable or older than 300 seconds. A remote restriction is therefore temporary while policy delivery is unavailable. Put required restrictions in local configuration, then use policy only to lower that ceiling. See policy freshness.

​
A recording remains open or incomplete

Read completeness separately from the root call’s status. An in_flight attempt has an entry record without a completion record; a lost completion leaves the same evidence as a still-running function. Follow every step page, collecting distinct paths until next_cursor is null. Compare that count with the newest step_count and restart the walk if they differ. A walk while records are still arriving does not establish exhaustive coverage. Slowest-first order puts calls without a completed duration last, beyond the first page when the trace is large. See HTTP traces and values for exact fields and pagination semantics.

​
Capacity check or relay health fails

A nonzero vexlo check indicates invalid configuration, including a value budget greater than the total capacity of its volume. serve applies the same capacity validation. Reduce the budget or select a larger volume before using -allow-overcommit. Values expiring before call records are reported without failing the check. With a backlog, relay health is degraded until the first accepted send, or after five minutes without an accepted send. Queue usage above 80% of its budget also degrades health. Inspect relay status and relay logs to distinguish destination failure, terminal drops and pressure eviction.

​
An agent cannot connect or read data

The MCP server requires VEXLO_API_URL and a read-role VEXLO_TOKEN. Set VEXLO_API_URL to the same server base URL used for VEXLO_ENDPOINT, without /v1. It checks the server’s capabilities and API version, then the credential’s identity and role. A successful connection with no results still requires checking service, team, environment and instrumentation. Use Connect an agent for the supported host setup and MCP tools for exact filters and errors.