Docs

trace.json

Goals live in code, next to the events that feed them. Review them in a pull request, check them with trace check, apply them with trace push, ideally from CI on every merge.

An example

{
  "site": "shop-example-com",
  "events": { "purchase": "Payment succeeded" },
  "kpis": {
    "checkout_conversion": {
      "name": "Checkout conversion",
      "conversion": { "from": { "pageview": "/checkout" }, "to": { "event": "purchase" } },
      "goal": "increase", "target": "55%"
    }
  },
  "funnels": {
    "buying": { "steps": [{ "pageview": "/cart" }, { "pageview": "/checkout" }, { "event": "purchase" }] }
  },
  "areas": { "checkout": { "name": "Checkout", "match": [{ "pageview": "/checkout*" }] } },
  "audience": { "marketing": ["/", "/pricing"], "engaged": [{ "event": "purchase" }] }
}

The keys

Key	What it holds
`site`	The Trace website this repository is. Your agent uses it to work on the right one, and `trace push` refuses to apply the file to another.
`events`	The custom events your code sends, each with a description. Trace warns when one stops arriving.
`kpis`	Your goals. A `conversion` (from → to) or a `session_rate`, a direction (`increase` or `decrease`) and an optional `target`.
`funnels`	Ordered steps. Trace shows where people drop out, and names the biggest drop once someone finishes.
`areas`	Parts of your product, optionally with `features` inside, each matched by pages or events. Trace shows which are used and which hurt.
`audience`	Which pages are marketing (for bounce) and which actions make someone engaged.

Matchers

Steps, goals and areas match events the same way: { "pageview": "/checkout*" }, { "event": "purchase" }, { "click": "button#pay" }, { "rage_click": "…" }, { "error": "*" }. A trailing * matches the rest of a path.

Check and apply

trace check
trace push trace.json --server https://app.tracetells.com --token $TRACE_TOKEN

Create the token under Account in the dashboard. Goals are matched by key, so renaming one keeps its history. Your coding agent can do the same with check_config and push_config.