> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirador.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Patterns for getting the most out of the Mirador SDKs, automations, and REST API

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

<AccordionGroup>
  <Accordion title="Create one client and reuse it" icon="plug">
    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](/api-reference/client#usage-patterns).
  </Accordion>

  <Accordion title="Name traces and events for the activity feed" icon="tag">
    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.
  </Accordion>

  <Accordion title="Use attributes for values, tags for buckets" icon="filter">
    **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](/concepts/attributes-and-tags).
  </Accordion>

  <Accordion title="Always close traces" icon="circle-check">
    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](/advanced/lifecycle-callbacks).
  </Accordion>

  <Accordion title="Record severity so automations can target it" icon="triangle-exclamation">
    Emit `error`/`warn` events when things go wrong. A trace's highest severity
    is both a filter field in the [REST API](/api/endpoints#filtering) and a
    natural automation trigger — instrument it deliberately.
  </Accordion>

  <Accordion title="Sample high-volume paths" icon="chart-simple">
    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](/api-reference/client#sampling).
  </Accordion>

  <Accordion title="Don't block the user on tracing" icon="bolt">
    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](/advanced/retry-logic).
  </Accordion>
</AccordionGroup>

## Automations

<AccordionGroup>
  <Accordion title="Start specific, then broaden" icon="bullseye">
    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](/automations/rules#best-practices).
  </Accordion>

  <Accordion title="Simulate before saving" icon="flask">
    Always run a rule simulation against existing traces before going live — it
    shows exactly which traces would have matched and why.
  </Accordion>

  <Accordion title="Name rules after what they detect" icon="signature">
    "Failed Bridge Transfers" or "High-Value Swaps (> \$10k)" make the activity
    feed and any downstream tickets self-explanatory.
  </Accordion>

  <Accordion title="Layer integrations for critical rules" icon="layer-group">
    Link both Slack and email (and/or a webhook) to high-priority rules so a
    missed channel doesn't mean a missed alert.
  </Accordion>

  <Accordion title="Harden your webhook consumers" icon="shield-halved">
    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](/api/trace-export#3-harden-the-consumer).
  </Accordion>
</AccordionGroup>

## Programmatic & agent access

<AccordionGroup>
  <Accordion title="Use server keys + the REST API to read data" icon="server">
    To pull traces into other systems — tickets, dashboards, warehouses — use
    the [REST API](/api/overview) 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](/api/authentication).
  </Accordion>

  <Accordion title="Point AI agents at llms.txt" icon="robot">
    Give an agent the contents of
    [`https://api.mirador.org/llms.txt`](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.
  </Accordion>

  <Accordion title="Count with pagination.total, don't scroll" icon="hashtag">
    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](/api/endpoints#traces).
  </Accordion>

  <Accordion title="Export the full trace from two calls" icon="file-export">
    A complete trace export is `GET /v1/traces/{id}` (summary) merged with
    `GET /v1/traces/{id}/events` (timeline). See
    [Exporting traces](/api/trace-export).
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={3}>
  <Card title="Automations" icon="bolt" href="/automations/overview">
    Rules, integrations, and activity
  </Card>

  <Card title="REST API" icon="server" href="/api/overview">
    Read traces from a backend or agent
  </Card>

  <Card title="Exporting traces" icon="file-export" href="/api/trace-export">
    The webhook → ticket recipe
  </Card>
</CardGroup>