Skip to content
Blopblop docs

First steps

This page walks you from an empty store to a queried trace in under five minutes. For installation, see Getting started → Installation.

Start the collector

Section titled “Start the collector”
Terminal window
$ npx @blopai/cli monitor start --detach

The collector starts as an identity-verified background daemon and prints its endpoints and data path. Omit --detach to keep it in the foreground:

blop monitor listening on http://127.0.0.1:27686
  OTLP:  POST http://127.0.0.1:27686/v1/traces  POST http://127.0.0.1:27686/v1/logs
  Query: GET  http://127.0.0.1:27686/api/health  ...
  DB:    ~/.local/state/blop/monitor/telemetry.sqlite

Bare blop is an alias for blop monitor start during the monitoring-first transition. The server binds to 127.0.0.1 by default; override with --host/--port or BLOP_MONITOR_HOST/BLOP_MONITOR_PORT.

Use blop monitor status to inspect the managed daemon and blop monitor stop to stop it safely.

Send it telemetry

Section titled “Send it telemetry”

In a second terminal, run any OpenTelemetry-instrumented workload with the exporter pointed at the collector:

Terminal window
$ OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:27686 pnpm test

Standard OTLP/HTTP traces and logs, JSON or protobuf, from any language. No Blop SDK, no code changes.

Check health

Section titled “Check health”
Terminal window
$ blop status

Reports collector reachability, database path, retention window, service count, latest telemetry timestamp, and versions — cheap and deterministic.

Ask for evidence

Section titled “Ask for evidence”
Terminal window
$ blop services                                  # which services emitted
$ blop traces --service checkout --limit 10      # bounded trace list
$ blop trace 4f6c9c... --include logs            # one trace + correlated logs
$ blop spans --status error attr.http.route=/pay # direct span search
$ blop logs --severity ERROR --since 15m         # bounded log slice
$ blop trace-stats service error_rate --json     # compact aggregate

Default windows are useful and bounded: a 15-minute CLI lookback, 20 traces, and 100 spans or logs. Hard caps are 100 traces, 500 spans or logs, and a 24-hour lookback. Filters use named flags or explicit attr.KEY=VALUE tokens.

Audit the window

Section titled “Audit the window”
Terminal window
$ blop audit --service checkout --since 15m --json
$ blop audit --fail-on regression --json; echo "exit: $?"

blop audit performs deterministic analysis over stored telemetry; it never calls an LLM. Findings cover error traces and their root spans, new error signatures versus a baseline window, slow traces and spans, log bursts, incomplete traces, and services that stopped emitting. Every finding carries a stable code, a severity, a concise summary, observed evidence with trace/span/log identifiers, and a follow-up blop command.

With --fail-on error|regression, the exit code gates CI and agent loops: 0 means nothing at or above the threshold, 1 means the audit failed.

The loop, end to end

Section titled “The loop, end to end”
  1. blop status --json — confirm the collector.
  2. Reproduce the target behavior with OTLP configured.
  3. Query the smallest relevant window.
  4. Inspect one trace or correlated log set.
  5. Make the code change.
  6. Reproduce again.
  7. blop audit --fail-on regression --json before declaring success.

Next steps

Section titled “Next steps”
CLI reference
Environment variables
Monitor HTTP API
Features
Observe, investigate, verify
Troubleshooting