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.

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: "user@example.com" },
);

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.

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

identify("user@example.com", { plan: "pro", company: "ExampleCo" });

registerTrackingProvider(provider)

Register a custom provider.

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.

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 events through /track.
On the server, the core route plugin registers the tracking capture provider:
captureError() calls captureException(), and the Agent-Native provider sends
the same event when the server public key is configured. Analytics groups both
into owner-scoped error_issues and error_events, shown in Monitoring ->
Errors and exposed to authenticated agents through list-error-issues and
get-error-issue. This remains available even when external Sentry is
unavailable or rate-limited.

Emit through captureError() / captureException(). Never hand-roll a
track("$exception", …): each backend needs its own payload shape and the
providers build it.

• Provider-agnostic wiring must not live in a provider plugin. The Nitro
  error hook is in core-routes-plugin.ts, not sentry-plugin.ts, because
  that plugin returns early when no SENTRY_DSN is set — hooking route errors
  there meant an app on any other backend silently reported none.
• Every backend applies server/error-noise-filter.ts. It holds
  production-tuned drop rules (expected 4xx, access-control rejections, Lambda
  freeze/thaw socket hang up). A backend that skips it receives a firehose;
  the socket hang up rule alone is ~10k events/day.
• A backend can accept a malformed payload and still show a count. PostHog
  ingested the framework's camelCase $exception for a long time and rendered
  empty, ungroupable issues — which reads as coverage, not as breakage. When
  adding or changing a backend, check what an event looks like in its UI, not
  just that the request returned 200.
• Attribute the error. Without a user id, server exceptions land under
  anonymous and split one person in two against their browser events. Pass
  aiTraceId for anything inside an agent run so the issue and the LLM trace
  resolve to each other.

Symbolication is per-backend and not automatic: the framework uploads no source
maps to PostHog, so minified browser stacks stay minified there. Known gap, not
a bug to re-diagnose.

Browser keys and the SSR shell

Public keys (POSTHOG_PUBLIC_KEY, the Sentry client DSN, and the first-party
Analytics public key) ship inside the
CDN-cached SSR shell — publishable and identical for every visitor. Server keys
never do, and are never a fallback for a public one: POSTHOG_API_KEY may be a
private key and this value lands in public HTML.

Browser errors post directly to the backend rather than through
/_agent-native/track, because that route requires a resolved session and
relaying would drop every signed-out crash.

When adding a client config field, update both server/posthog-config.ts
and the mirrored worker emitter in deploy/build.ts — the worker bundles a
string copy and cannot import the module, so a one-sided edit drops the config
silently in deployed builds. posthog-config.spec.ts pins the two outputs
together.

MCP Server Events

The MCP server an app exposes reports its own usage. packages/core/src/mcp/analytics.ts
emits one event per protocol request, and the emission points sit in the shared
server builder (build-server.ts), so the HTTP mount and the stdio transport
report identically.

Event	Fires on
$mcp_initialize	the client/server handshake (HTTP mount only)
$mcp_tools_list	tools/list
$mcp_tool_call	tools/call, success or failure
$mcp_resources_list	resources/list
$mcp_resource_read	resources/read

Names come from PostHog's MCP analytics vocabulary
(https://posthog.com/docs/mcp-analytics/events) on purpose, so PostHog's MCP
dashboards read these events with no mapping layer — but they go through
track() like every other event, so Mixpanel, Amplitude, a webhook, and
Agent-Native Analytics receive the same ones.

Shared properties: $mcp_source (http / stdio), $mcp_server_name,
$mcp_server_version, $mcp_app_id, $mcp_client_name, $mcp_client_version,
$mcp_client_user_agent, $mcp_vendor_client, $mcp_protocol_version. Per
event: $mcp_tool_name, $mcp_tool_description, $mcp_tool_category
(read / write), $mcp_listed_tool_names, $mcp_duration_ms,
$mcp_is_error, $mcp_error_type, $mcp_error_message, $mcp_resource_name,
$mcp_resource_uri.

• A client's own name is only on the wire at initialize. The mount is
  stateless — one server per request — so no later event can recover it.
  $mcp_initialize carries the clientInfo from the handshake; every other
  event falls back to the 2026-era per-request _meta and the HTTP user agent,
  and $mcp_vendor_client buckets both spellings onto one row.
• A failed call is reported with its reason, not just isError. The
  tools/call handler renders "unknown tool", "forbidden scope", and a thrown
  action error as the same shape of error result, so each sets $mcp_error_type
  where it returns rather than having it guessed back out of the response text.
• Payloads stay out. $mcp_response is never emitted. $mcp_parameters is
  off by default and redacted when on — tool arguments carry user content.

Off switches: MCP_ANALYTICS=false (observability.mcpEvents) disables the
events; MCP_ANALYTICS_PARAMETERS=true (observability.mcpCaptureParameters)
opts into arguments. They sit in observability with the other capture
switches, not in analytics — they gate every provider, not the first-party
Agent-Native Analytics sender whose key lives there.

Default Baseline Events

Template roots call configureTracking() once during app startup. That installs default browser pageview tracking for hosted apps:

• Event: pageview
• Fires on initial load, history.pushState, history.replaceState, and popstate
• De-dupes repeated events for the same URL
• Includes url, path, hostname, referrer, title, navigation_type, app, and inferred template
• Includes LLM connection context on browser events when known: llm_connection (builder, anthropic, openai, etc.), llm_engine, llm_model, llm_connection_source, and llm_connection_configured
• Does not send first-party events from localhost/local dev

Visitor identity (anonymousId + sessionId)

Every browser-side trackEvent() POST to the Agent-Native Analytics /track endpoint includes:

• anonymousId — persistent per-browser visitor ID stored in localStorage under agent-native.anonymous_id. Generated once and reused across sessions. Use this for unique-visitor and returning-visitor metrics.
• sessionId — rotating per-visit ID stored in localStorage under agent-native.session_id, with a 30-minute idle timeout (matches GA4 / Mixpanel defaults). Use this for sessions-per-visitor, pages-per-session, and session-duration metrics.
• userId — only set when the calling code passes properties.userId. Anonymous traffic leaves this NULL by design; anonymousId is the fallback.

These fields land in the analytics_events.anonymous_id, analytics_events.session_id, and analytics_events.user_id columns in the analytics template. Storage access is wrapped in try/catch — private-browsing / blocked-storage clients silently degrade to NULL rather than crashing the page.

Referral / viral attribution (first-touch)

configureTracking() also captures an anonymous visitor's first-touch referral context once, on first page load, and persists it across the signup boundary so the server-side signup event records where the user came from. This powers virality metrics for every template (Clips share links, Plans public pages, etc.).

Share-link params (set by whatever generates the link; read client-side only):

• ref — referral source bucket, e.g. clip_share, plan_share
• via — the referrer's stable user id (the clip/plan owner)
• utm_source, utm_medium, utm_campaign, utm_content, utm_term

Client persistence (first-write-wins — an existing value is never overwritten):

• localStorage key an_attribution and first-party cookie an_ft (path=/; max-age=2592000; SameSite=Lax, not HttpOnly — non-sensitive, written by client JS).
• Both store the same URL-encoded compact JSON (empty fields omitted, each value capped at 120 chars): { ref, via, utm_source, utm_medium, utm_campaign, utm_content, utm_term, landing_path, landing_referrer, landed_at }. landing_referrer is the host only of document.referrer (scrubbed; same-origin referrers are dropped).
• getFirstTouchAttribution() (from @agent-native/core/client) returns the parsed object or null.

Signup event enrichment (server-side, from the an_ft cookie on the signup/OAuth-callback request, derived in packages/core/src/server/attribution.ts):

• referral_source — ref if present, else derived: /share/… → clip_share; a plan public path (/p/, /plan/, /share-plan/) → plan_share; a non-empty external referring host → external; otherwise direct.
• referrer_user (= via), referral_medium (= utm_medium), referral_campaign (= utm_campaign)
• utm_source, utm_medium, utm_campaign, utm_content, utm_term (raw passthrough)
• first_touch_path (= landing_path), landing_referrer

Attribution parsing is fully defensive and never blocks signup — a missing/malformed cookie falls back to referral_source: "direct".

Other framework-level baseline events:

• session status from useSession(), with signed_in
• action.response from the browser action transport, with action name,
  browser-perceived duration and TTFB, response status/outcome, response size
  when known, and parsed Server-Timing phases for framework readiness and
  database work. Its request_id joins the exact browser and server events.
  This separates server time from CDN/network/body overhead.
• http.response from Nitro request/response hooks, with normalized path,
  status, request duration, first-request-in-isolate cold marker, process age,
  framework readiness wait, deploy/runtime fingerprint, database
  connection/query counts and timings, retries, timeouts, and failures. It also
  emits Server-Timing for app, startup, db, db-connect, and
  db-slowest plus an X-Agent-Native-Request-Id correlation header where
  applicable. Query text and parameters are never captured.
  Database activity that begins during the first two minutes of process/plugin
  initialization is reported separately as startup_db_* on the first
  framework request that passes the readiness gate.
  Slow, cold-isolate, server failures, and 4xx action routes are always
  retained; fast successful requests default to 10% sampling. Override with
  AGENT_NATIVE_HTTP_TELEMETRY_SAMPLE_RATE on the server and
  VITE_AGENT_NATIVE_ACTION_TELEMETRY_SAMPLE_RATE in the browser.
• signup from Better Auth user creation, with auth_provider, auth_user_id, and first-touch referral attribution (referral_source, referrer_user, referral_medium, referral_campaign, utm_*, first_touch_path, landing_referrer — see "Referral / viral attribution" above)
• builder connect clicked and builder connect popup blocked from browser Connect Builder CTAs
• builder connect started, builder connect succeeded, builder connect failed, builder disconnect succeeded, and builder disconnect failed from the Builder connection routes, with LLM connection context when resolvable
• $ai_generation from instrumented agent loops, with PostHog AI Observability fields such as $ai_trace_id, $ai_session_id, $ai_model, $ai_provider, $ai_input_tokens, $ai_output_tokens, $ai_latency, $ai_total_cost_usd, and mirrored Agent-Native query fields such as run_id, thread_id, cost_cents_x100, duration_ms, tool_calls, and status. A bounded tools array contains names, start offsets, durations, statuses, and coarse error classes only; interrupted tools and failed runs remain visible, and delegated runs include protocol/task/parent-run/parent-turn correlation. Prompt, tool argument, result, and output content is excluded unless captureToolResults is opted in (see the observability skill), in which case each failed tool call also carries a error_message string truncated to 500 characters and already scrubbed of bearer tokens, API keys, and key/value secret patterns.

For new lifecycle events, call track() server-side when the server is the source of truth, and trackEvent() client-side only for browser interactions.

Lifecycle taxonomy

Lifecycle event names use lowercase snake_case; lifecycle properties use the
same convention. The shared dimensions are app_name, template_name,
user_id, user_email, workspace_id, session_id, output_id,
output_type, source, and referrer. App/template values are canonical ids
without the agent-native- prefix. Identity is also stored in the event's
top-level user/session columns for joins.

The canonical lifecycle events are app_entered, core_action_started,
core_action_completed, core_action_failed, output_viewed,
output_shared, cta_clicked, return_usage, and cross_app_used. The
framework also emits action_started, action_completed, and
action_failed for mutating defineAction() calls so UI, agent, MCP, A2A,
automation, and CLI activity share one action-level trail. Read-only actions
and high-frequency refresh, polling, navigation, and application-state actions
are excluded.

App entry is emitted once per app and browser session. Tracking is action-level
only: it does not install mouse, pointer, scroll, keypress, or DOM autocapture.
Existing legacy events remain available and emit their canonical lifecycle
counterpart where the meaning is unambiguous, so downstream dashboards can
migrate without losing historical names.

Event name migration

All new event names and properties use lowercase snake_case. The shared
track() and browser trackEvent() emitters preserve a legacy event exactly
and, for names in LEGACY_TRACKING_EVENT_NAME_ALIASES, emit a canonical alias
with legacy_event_name and canonical_event_name provenance properties. Use
the canonical alias for new dashboards and new call sites; do not normalize
historical warehouse rows or add new legacy names. Provider/framework names
such as $ai_*, $mcp_*, $exception, action.response, app.first_action,
and http.response are intentional exceptions.

Provider Interface

interface TrackingProvider {
  name: string;
  track(event: TrackingEvent): void | Promise<void>;
  identify?(
    userId: string,
    traits?: Record<string, unknown>,
  ): void | Promise<void>;
  flush?(): void | Promise<void>;
}

interface TrackingEvent {
  name: string;
  properties?: Record<string, unknown>;
  timestamp?: string;
  userId?: string;
}

Design Decisions

• globalThis singleton -- the registry uses a Symbol.for key on globalThis so multiple ESM graph instances (dev-mode Vite + Nitro, symlinks) share one provider set.
• Best-effort fan-out -- provider errors are caught and logged, never propagated. A broken analytics integration must not break app functionality.
• Batched HTTP -- built-in providers enqueue events and flush every 10 seconds or 50 events, minimizing outbound requests.
• NOT bridged to the event bus -- tracking and the event bus are separate concerns. The event bus is for triggering automations; tracking is for analytics. Do not subscribe to track() calls from the event bus or vice versa.

Key Files

File	Purpose
packages/core/src/tracking/registry.ts	track(), identify(), registerTrackingProvider(), flushTracking()
packages/core/src/tracking/providers.ts	Built-in providers (PostHog, Mixpanel, Amplitude, Agent-Native Analytics, Webhook) and registerBuiltinProviders()
packages/core/src/tracking/types.ts	TrackingEvent and TrackingProvider interfaces
packages/core/src/tracking/posthog-exception.ts	$exception_list builder + stack-frame parser (isomorphic: server and browser)
packages/core/src/tracking/redaction.ts	Shared bounding/redaction helpers used by every exception emitter
packages/core/src/server/error-noise-filter.ts	Provider-agnostic drop rules, applied by both Sentry beforeSend and the route error hook
packages/core/src/server/posthog-config.ts	Public browser PostHog config (mirrored in deploy/build.ts)

Related Skills

• secrets -- API keys for tracking providers can be registered as secrets
• server-plugins -- registerBuiltinProviders() is called by the core-routes plugin at startup
• actions -- call track() from action handlers to record user/agent activity