Skip to main content
This page collects the highest-leverage patterns for using Mirador well — instrumenting with the SDKs, building automations that fire on the right things, and reading data back programmatically. Each section links to the deeper reference.

​
SDK instrumentation

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.
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.
Attributes are key/value data you’ll filter or display (chain, amount, user_id). Tags are low-cardinality labels you group by (prod, bridge, swap). Keep tag values to a small, known set — they drive both the UI and automation filters. See Attributes & Tags.
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.
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.
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.
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

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.
Always run a rule simulation against existing traces before going live — it shows exactly which traces would have matched and why.
“Failed Bridge Transfers” or “High-Value Swaps (> $10k)” make the activity feed and any downstream tickets self-explanatory.
Link both Slack and email (and/or a webhook) to high-priority rules so a missed channel doesn’t mean a missed alert.
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

To pull traces, logs, and metrics into other systems — tickets, warehouses, incident bots — use the REST API with a mir_srv_* server key. Keys are project-scoped, and the same key can also manage dashboards and metric alerts, so constrain read-only integrations to GET. Keep server keys in a secrets manager, one per integration, and rotate them. See Authentication.
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.
To answer “how many traces match X?”, call GET /v1/traces with page_size=1 and read the top-level total — an exact count in a single request. For log counts, use GET /v1/logs/stats?interval=whole. See Traces and Logs.
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