TrackingCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: tracking
description: >-
  Server-side analytics tracking with pluggable providers. Use when adding
  analytics events, registering custom tracking providers, or configuring
  built-in providers (PostHog, Mixpanel, Amplitude, Webhook).
scope: dev
metadata:
  internal: true
---

# Tracking

## Rule

The tracking system provides a single server-side `track()` call that fans out
to all registered providers, plus the browser-side `trackEvent()` counterpart.
Built-in providers auto-register from env vars - set the var and tracking
starts. Custom providers can be registered for any analytics backend. Both
surfaces are best-effort and never block request handling.

## How It Works

1. At server startup, `registerBuiltinProviders()` checks env vars and registers any configured providers.
2. Application code calls `track(eventName, properties, source)` from actions, plugins, or server routes.
3. The registry fans out the event to every registered provider. Errors are caught and logged -- a failing provider never crashes the caller.
4. Built-in providers batch HTTP calls (flush every 10 seconds or 50 events, whichever comes first).

## API

### `track(name, properties?, source?)`

Fire an analytics event. `source` is either a `{ userId, anonymousId, sessionId }`
meta object or an action's `ctx` passed straight through.

```ts
import { track } from "@agent-native/core/tracking";

// From an action — pass ctx; userId comes from ctx.userEmail.
run: async ({ name }, ctx) => {
  track("meal.logged", { mealName: name, calories: 350 }, ctx);
};

// From a plugin or route with no ctx.
track(
  "meal.logged",
  { mealName: "Salad", calories: 350 },
  { userId: "[email protected]" },
);
```

The caller's browser session comes from the ambient request context
(`RequestContext.browserSessionId`, set from the `X-Agent-Native-Session-Id`
header), so it resolves the same whether the UI called the action or the agent
did. Pass `sessionId` in the meta object to override it — routes that run
outside a request context, such as `/_agent-native/track`, do exactly that.
Providers map it to their own session field: `$session_id` for PostHog (which
joins the event to session replay), `session_id` as a property for Mixpanel and
Amplitude, a top-level `sessionId` for webhooks and Agent-Native Analytics. It
is absent for callers with no browser — cron, CLI, MCP, A2A.

### `identify(userId, traits?)`

Identify a user with traits. Forwarded to providers that support it.

```ts
import { identify } from "@agent-native/core/tracking";

identify("[email protected]", { plan: "pro", company: "ExampleCo" });
```

### `registerTrackingProvider(provider)`

Register a custom provider.

```ts
import { registerTrackingProvider } from "@agent-native/core/tracking";

registerTrackingProvider({
  name: "my-analytics",
  track(event) {
    // Send event to your backend
  },
  identify(userId, traits) {
    // Optional
  },
  flush() {
    // Optional -- called on graceful shutdown
  },
});
```

### `flushTracking()`

Flush all providers (call before process exit).

## Built-in Providers

Set the env var and the provider auto-registers at startup. No SDK dependencies -- all providers use raw HTTP.

| Provider               | Env vars                                                                                                                                           |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| PostHog                | `POSTHOG_API_KEY` (required), `POSTHOG_HOST` (optional, defaults to `https://us.i.posthog.com`), `POSTHOG_ERROR_TRACKING=false` (optional opt-out) |
| Mixpanel               | `MIXPANEL_TOKEN`                                                                                                                                   |
| Amplitude              | `AMPLITUDE_API_KEY`                                                                                                                                |
| Agent-Native Analytics | `AGENT_NATIVE_ANALYTICS_PUBLIC_KEY` (server), `AGENT_NATIVE_ANALYTICS_ENDPOINT` (optional, defaults to `https://analytics.agent-native.com/track`) |
| Webhook                | `TRACKING_WEBHOOK_URL` (required), `TRACKING_WEBHOOK_AUTH` (optional, sent as `Authorization` header)                                              |

Multiple providers can be active simultaneously. All receive every event.

Browser-side `trackEvent()` also forwards to Agent-Native Analytics when `VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY` is present. Use `VITE_AGENT_NATIVE_ANALYTICS_ENDPOINT` to override the default browser endpoint. The built-in Agent-Native Analytics sender is quiet on localhost/local dev by default; set `AGENT_NATIVE_ANALYTICS_ALLOW_LOCALHOST=true` only for an intentional local ingestion test.

An app served from a hosted beta host (`beta.*.agent-native.com`) reports to beta Analytics: `resolveLaneEndpoint` moves an endpoint on a production lane host to its beta lane for browser events, auth-page events, replay uploads, and server events. A new sender that reads the analytics endpoint must pass it through `resolveLaneEndpoint` too, or beta traffic splits. Beta and production Analytics share one database, so an ingest change runs on beta traffic first, and checking it on beta proves the merged code rather than production's. An endpoint on any other host is left as configured.

## Error Capture

Exceptions fan out through `server/capture-error.ts` to every registered
backend - Sentry, PostHog, and the tracking providers - from one
`captureError()` call. Backends are additive: configuring a second one does not
displace the first, and no backend is required for the others to work.

When first-party Agent-Native Analytics is configured, browser
`configureTracking()` captures uncaught errors, unhandled rejections, and
manual `captureException()` calls as `$exception`

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Tracking](https://modelsatlas.com/skills/builderio/tracking/badge.svg)](https://modelsatlas.com/skills/builderio/tracking/)

Not your listing, or something out of date? Claim or update your listing.