SDK instrumentation
Create one client and reuse it
Create one client and reuse it
A
Client holds the connection and configuration. Create it once at startup
and import it everywhere — don’t construct a new client per request or per
trace. See Client.Name traces and events for the activity feed
Name traces and events for the activity feed
Use stable, human-readable names (
SwapExecution, swap_confirmed) rather
than IDs or free-form strings. Good names make traces, rule activity, and
exported tickets scannable at a glance.Always close traces
Always close traces
A trace that’s never closed stays
running and can’t reach a terminal
state. In the browser, set autoClose: true (or close on the relevant
lifecycle event); on the server, await trace.close(reason) when the flow
ends. See Lifecycle Callbacks.Record severity so automations can target it
Record severity so automations can target it
Emit
error/warn events when things go wrong. A trace’s highest severity
is both a filter field in the REST API and a
natural automation trigger — instrument it deliberately.Sample high-volume paths
Sample high-volume paths
For very hot code paths, set a
sampleRate (or a custom sampler) so you
keep representative coverage without flooding ingest. Keep critical flows
(payments, bridges) at full rate. See Client → Sampling.Don't block the user on tracing
Don't block the user on tracing
The SDK flushes asynchronously and retries with backoff. Don’t
await
tracing calls on the critical user path, and rely on the built-in retry
behaviour rather than rolling your own. See Retry Logic.Automations
Start specific, then broaden
Start specific, then broaden
Begin with narrow conditions targeting a known issue, confirm the rule
behaves, then widen it. A too-broad rule generates noisy alerts; a too-narrow
one misses events. See Rules → Best Practices.
Simulate before saving
Simulate before saving
Always run a rule simulation against existing traces before going live — it
shows exactly which traces would have matched and why.
Name rules after what they detect
Name rules after what they detect
“Failed Bridge Transfers” or “High-Value Swaps (> $10k)” make the activity
feed and any downstream tickets self-explanatory.
Layer integrations for critical rules
Layer integrations for critical rules
Link both Slack and email (and/or a webhook) to high-priority rules so a
missed channel doesn’t mean a missed alert.
Harden your webhook consumers
Harden your webhook consumers
Verify a shared-secret header on every delivery, acknowledge with
2xx
quickly and do heavy work async, and dedupe on the delivery’s event_id so
retried deliveries don’t create duplicates. See
Exporting traces → Harden the consumer.Programmatic & agent access
Use server keys + the REST API to read data
Use server keys + the REST API to read data
To pull traces into other systems — tickets, dashboards, warehouses — use
the REST API with a
mir_srv_* server key. It’s read-only
and project-scoped. Keep server keys in a secrets manager, one per
integration, and rotate them. See Authentication.Point AI agents at llms.txt
Point AI agents at llms.txt
Give an agent the contents of
https://api.mirador.org/llms.txt plus a
server key — it documents the auth scheme, filter grammar, pagination, and
every response shape in one file, enough to query Mirador with no other
context.Count with pagination.total, don't scroll
Count with pagination.total, don't scroll
To answer “how many match X?”, call
GET /v1/traces with per_page=10 and
read pagination.total — an exact count in a single request. See
Endpoints.Export the full trace from two calls
Export the full trace from two calls
A complete trace export is
GET /v1/traces/{id} (summary) merged with
GET /v1/traces/{id}/events (timeline). See
Exporting traces.Next Steps
Automations
Rules, integrations, and activity
REST API
Read traces from a backend or agent
Exporting traces
The webhook → ticket recipe