Tracking API

The tracking API is available via the yavio singleton, which you import from @yavio/sdk.

Accessing the context

Inside tool handlers

Import the yavio singleton and call its methods from within any tool handler wrapped by withYavio():

import { withYavio, yavio } from "@yavio/sdk";

// Using registerTool (recommended, MCP SDK v1.26+)
instrumented.registerTool("search", {
  description: "Search for items",
  inputSchema: { query: { type: "string" } },
}, async ({ query }) => {
  yavio.identify("user_123");
  yavio.track("search_executed", { query });

  return { content: [{ type: "text", text: "Results..." }] };
});

// Using tool (deprecated but still supported)
instrumented.tool("search", { query: { type: "string" } }, async ({ query }) => {
  yavio.identify("user_123");
  yavio.track("search_executed", { query });

  return { content: [{ type: "text", text: "Results..." }] };
});

Outside tool handlers

The yavio singleton also works in any code that runs within the same async context as a tool handler (e.g., helper functions called from a tool handler):

import { yavio } from "@yavio/sdk";

function processResults(results: Result[]) {
  yavio.track("results_processed", { count: results.length });
}

The yavio singleton relies on AsyncLocalStorage. It only works within the async context of a tool handler invocation. Calls outside that context are silently ignored.

.identify()

Ties the current session to a known user ID. Call this as early as possible in your tool handler.

yavio.identify(userId: string, traits?: Record<string, unknown>): void

Parameters

Parameter	Type	Description
`userId`	`string`	Unique user identifier. Immutable per session — subsequent calls with a different ID are ignored.
`traits`	`Record<string, unknown>`	Optional user properties (e.g., `plan`, `company`). Additive across calls.

Behavior

The userId is set once per session. If you call .identify() again with a different ID, the second call is ignored and a YAVIO-1302 warning is logged.
Traits are merged additively — calling .identify("u1", { plan: "pro" }) then .identify("u1", { company: "Acme" }) results in both traits being attached.
All subsequent events in the session include the user_id and traits.

yavio.identify("user_42", {
  plan: "enterprise",
  company: "Acme Corp",
});

See User Identification for a deeper look at identity rules and session semantics.

.step()

Records a named step in a multi-step workflow. Steps are auto-numbered within a trace for funnel analysis.

yavio.step(name: string, meta?: Record<string, unknown>): void

Parameters

Parameter	Type	Description
`name`	`string`	Step name (e.g., `"search"`, `"filter"`, `"select"`)
`meta`	`Record<string, unknown>`	Optional metadata attached to the step event

Example

instrumented.tool("wizard", { step: { type: "string" } }, async ({ step }) => {
  yavio.step(step, { page: 1 });

  // ... handle the step

  return { content: [{ type: "text", text: "Step complete" }] };
});

Steps generate events with event_type: "step" and an auto-incrementing step_sequence within the trace. This enables funnel visualization in the dashboard.

.track()

Records a custom event with arbitrary properties.

yavio.track(event: string, properties?: Record<string, unknown>): void

Parameters

Parameter	Type	Description
`event`	`string`	Event name (e.g., `"feature_used"`, `"export_requested"`)
`properties`	`Record<string, unknown>`	Optional event properties

Example

yavio.track("document_generated", {
  format: "pdf",
  pages: 12,
});

Custom events use event_type: "track" with the event name in the event_name field.

.conversion()

Records a conversion event with monetary value. Used for revenue attribution and ROI analysis.

yavio.conversion(
  name: string,
  data: {
    value: number;
    currency: string;
    meta?: Record<string, unknown>;
  }
): void

Parameters

Parameter	Type	Description
`name`	`string`	Conversion name (e.g., `"purchase"`, `"upgrade"`, `"signup"`)
`data.value`	`number`	Monetary value of the conversion
`data.currency`	`string`	ISO 4217 currency code (e.g., `"USD"`, `"EUR"`)
`data.meta`	`Record<string, unknown>`	Optional metadata

Example

yavio.conversion("subscription_upgrade", {
  value: 99,
  currency: "USD",
  meta: { plan: "enterprise", annual: true },
});

Conversions generate events with event_type: "conversion", conversion_value, and conversion_currency fields.

On this page