How it works

Blop collects evidence on your machine first and adds a browser check only when a question needs one. The loop is observe, investigate, verify.

Text alternative: your app and coding agents send telemetry to the local collector, where you query and audit it, then reproduce and audit again after a change; a browser check produces a check run, kept apart in Blop Cloud when uploaded, and you rerun the check to verify.

Observe: send telemetry to the collector

blop up --detach
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:27811 pnpm test

Use the URL that blop up prints if it differs. The collector accepts standard OTLP/HTTP traces and logs, as JSON or protobuf. The workload must already be instrumented with an OpenTelemetry SDK; setting the endpoint alone emits nothing.

Two inputs cover two sides of the work:

• Hooks capture the coding agent itself: prompts, tool calls, tool errors and turn boundaries, read from the agent’s own lifecycle events. See Connect a coding agent.
• OpenTelemetry captures your application: its traces, spans and logs, including requests an agent caused.

Neither is inferred from the other.

Investigate: ask the smallest question first

blop traces --service checkout --status error --since 15m --json
blop trace <trace-id> --include logs --json
blop audit --service checkout --since 15m --json

Start from a compact summary and drill into one service, trace, span or log set. Results are bounded, so a query never dumps the whole store into an agent’s context. blop audit runs a fixed analysis over stored telemetry, looking for error traces, new error signatures, latency regressions and log bursts. The same data always gives the same findings, each with trace and span IDs. For a browser check, read its failing step, assertion and artifacts. See Investigate.

Verify: reproduce, then audit again

blop audit --service checkout --since 15m --fail-on regression --json

After a change, reproduce the behaviour and rerun the same queries or audit. --fail-on regression exits 1 when the audit finds a regression. If the claim is about a user-visible flow, rerun the browser check:

blop test tests/checkout.blop.ts --base-url http://localhost:3000

Run checks against local, preview or staging targets. A production target must be chosen deliberately; read Production checks first. A healthy collector or an installed hook is not proof that a flow succeeded.

Choose the evidence source

Question	Start with
Which service or span failed?	Local traces, spans and their logs
Did latency or errors regress after this change?	blop audit against a baseline
Can a user complete this exact flow?	A browser check
What did the browser check see and decide?	The check run’s steps, assertions and artifacts
Did an existing Vitest or JUnit suite fail?	Check runs uploaded to Blop Cloud by the test adapter

Where evidence is stored

	Local collector store	Blop Cloud
Holds	Traces, spans, logs, services, coding-agent sessions, runs (blop runs) and issues	Check runs, projects and organization memory
Lives	On your machine	In your team’s workspace
Input	OTLP/HTTP traces and logs, coding-agent hooks	Browser checks and test adapters
Read with	blop query and audit commands, the Inspector	Blop Cloud check run views

A run is not a trace: a run records one command that blop run started, and the traces it produced are stored beside it. Blop never copies the local store into Blop Cloud and never joins the two stores; an agent can still use both in one investigation.

The local store keeps telemetry for 720 hours (30 days), up to 1024 MB, deleting the oldest first. blop status shows its path, and BLOP_MONITOR_DB_PATH overrides it.

Safety in a coding loop

• The collector listens on 127.0.0.1 by default. Its query and ingestion routes have no authentication or TLS, so do not expose the port.
• Request bodies and result sizes are capped.
• The collector never runs application code, agent commands or browser actions.
• It keeps only what your app or agent sends as telemetry, never environment variables, source files or headers on its own.

JSON output contract

Every query takes --json. In JSON mode a command prints exactly one blop.cli/v1 document on stdout, on success and on failure, never prompts, and sends progress and notes to stderr:

{
  "schema_version": "blop.cli/v1",
  "command": "traces",
  "generated_at": "2026-11-03T09:46:53.891Z",
  "ok": true,
  "data": [],
  "page": { "limit": 20, "next_cursor": null },
  "warnings": [],
  "next": []
}

• ok is true exactly when the exit code is 0. The one exception is blop run: ok is true when the wrapped command started, and that command’s exit code is in data.exit_code.
• warnings holds {code, message} notes; next holds {command, when} steps.
• On failure, error carries a stable code to branch on, plus message and hint.
• Field names are snake_case and timestamps are ISO 8601 UTC.

blop run --json writes its document to stderr, because the wrapped command owns stdout. blop schema prints the JSON Schema.

Branch on the exit code (blop help exit-codes prints them all):

Code	Meaning
0	Success
1	The command reported a failure, such as a --fail-on threshold or a failed doctor check
2	Usage error; nothing was sent
3	Blop is not running; start it with blop up
4	The collector rejected the query
5	The collector did not answer in time
6	Could not verify (blop init, blop setup mcp)
78	Store unrecoverable or incompatible. Do not retry; run blop up --recover
127	blop run’s command or a launcher’s agent binary was not found
129, 130, 143	Stopped by SIGHUP, Ctrl-C or SIGTERM

blop run and the launchers (blop claude, blop codex, blop opencode) exit with the child’s own code.

See JSON output and exit codes for every field and code.