Configuration

The SDK resolves configuration from multiple sources with a clear precedence order. The first source that provides a value wins.

Precedence chain

Code options → Environment variables → .yaviorc.json → Defaults → No-op

1. Code options — passed directly to withYavio(server, { apiKey, endpoint, capture, shutdownTimeoutMs, flushTimeoutMs, waitUntilTimeoutMs, sessionKey }) or createYavio({ … }); sessionKey exists only here (a function)
2. Environment variables — YAVIO_API_KEY, YAVIO_ENDPOINT, YAVIO_SERVER_ONLY, YAVIO_INTENT, YAVIO_SHUTDOWN_TIMEOUT_MS, YAVIO_FLUSH_TIMEOUT_MS and YAVIO_WAIT_UNTIL_TIMEOUT_MS
3. Config file — .yaviorc.json found by walking up from process.cwd()
4. Defaults — built-in defaults for endpoint, capture, shutdownTimeoutMs, flushTimeoutMs and waitUntilTimeoutMs
5. No-op — if no API key is found from any source, the SDK is disabled

Environment variables

YAVIO_API_KEY=yav_abc123...
# Optional — omit to use the hosted endpoint. Point it at your own ingest when
# self-hosting, or at http://localhost:3001/v1/events when running the stack locally.
YAVIO_ENDPOINT=https://ingest.yavio.ai/v1/events

Config file

The SDK walks up the directory tree from process.cwd() looking for a .yaviorc.json file. This is useful for local development and monorepo setups.

{
  "apiKey": "yav_abc123...",
  "endpoint": "http://localhost:3001/v1/events",
  "shutdownTimeoutMs": 5000,
  "flushTimeoutMs": 1000,
  "waitUntilTimeoutMs": 10000
}

Place it in your project root or any parent directory. The nearest file wins.

Defaults

Capture options

The capture object controls which data is collected on every tool_call event.

withYavio(server, {
  capture: {
    inputValues: false,  // no input_keys, input_types, input_values, no client metadata
    outputValues: false, // no output_content, no error_message from isError results
    geo: "country",      // country_code, but only { country } in input_values (false: no location at all)
  },
});

geo takes two more values between "everything" and "nothing":

• "region": country_code and region (the state or province, as the platform names it — on ChatGPT an English name such as North Rhine-Westphalia, not an ISO 3166-2 code) are set, and openai/userLocation in the captured _meta is replaced by { country, region }. Use it for a breakdown by state or province without city or coordinates.
• "country": country_code is set, and openai/userLocation is replaced by { country }. Use it when a privacy review asks for country-level analytics only.

In both, city, timezone, coordinates and any field the platform adds to the location object later are not stored; without a valid country the object is removed, and a region only counts next to a valid country. The region is normalised the way ingest does it: typographic apostrophes and dashes folded, at most 64 characters, no digits or @ (a name that fails is dropped). In city-states the region is the city — ChatGPT reports Berlin as State of Berlin, and likewise Hamburg, Bremen, Vienna or Washington, D.C. — so say so if your privacy policy promises "no city". true sets region too and keeps _meta whole.

With any geo other than true ("region", "country", false), the rest of the captured _meta keeps exactly openai/locale, openai/userAgent, openai/subject and openai/session. Everything else is dropped — ChatGPT's top-level timezone and timezone_offset_minutes, the conversation and request ids (sessionId, windowId, callId, itemId, openai/request_id), openai/organization, the client capabilities, and any key the platform adds later, since nothing guarantees a new location field gets a recognisable name. The names of dropped keys (never their values) are stored in input_values._metaDroppedKeys, so you can see when a new one appears; a name with a run of 8 or more hex digits is only counted, in _metaDroppedUnnamed. The allow-listed request headers in _requestInfo are not affected. Before 0.4.1, "country" and false kept the top-level timezone. geo has no per-tool override. The React widget's widget_render event stores the browser's time zone regardless of capture.geo.

Under every geo, true included, the trace context never stays in the captured _meta (SDK 0.5.5 and later): baggage (free-form context such as user or tenant ids that the client's tracing sends along), tracestate, .NET's Correlation-Context and Datadog's _dd_trace_context, in any letter case, are dropped and only their key names are stored in _metaDroppedKeys, under geo: true too; Jaeger's uberctx-… and OpenTracing's ot-baggage-… keys, one baggage member each, are dropped and only counted in _metaDroppedUnnamed. A valid traceparent is stored once, as the tool call's metadata.traceparent, also when it arrives as an HTTP header or inside Datadog's _dd_trace_context, and for tools without arguments. Before 0.5.5, geo: true kept all of these verbatim.

Every capture flag fails closed, in capture and in a per-tool tools override alike: inputValues, outputValues, rejectedInputValues, tokens, retries and the per-tool intent accept exactly true and false, geo accepts true, false, "country" and "region". Any other value (for example the string "false" in .yaviorc.json, which is truthy) turns that capture off and logs YAVIO-1006 once per flag and process.

Client metadata (locale, country_code, region, end_user_agent, subject_id, and metadata.traceparent) is captured under inputValues for every tool, including tools that take no arguments.

rejectedInputValues exists because a successful call only ever stores values the tool's schema accepted, while a rejected call would store whatever the model sent. With an enum field such as plan: z.enum(["basic", "premium"]), the model may send "premium, my wife is pregnant"; the schema rejects it, and with the flag on that sentence is stored. Leave it off if your privacy policy says only fixed values are collected. It has no effect while inputValues is off.

tokens and retries are accepted but reserved — they have no effect today.

Per-tool overrides

tools overrides the capture flags for individual tools, keyed by tool name. A key that is omitted inherits the global value.

withYavio(server, {
  capture: { inputValues: true, outputValues: true },
  tools: {
    "book-contract": { inputValues: false, outputValues: false, intent: false },
  },
});

{
  "apiKey": "yav_abc123...",
  "tools": { "book-contract": { "inputValues": false, "outputValues": false } }
}

Use this for a tool whose input must never reach analytics — an IBAN, a message body, a birth date. The tool stays on the wrapped server, so it still produces tool_call events with latency and status, and yavio.conversion() and friends still work from inside its handler. Registering the tool on the unwrapped server instead loses all of that under withYavio(): no tool_call event, and tracking calls from the handler are dropped (see Tracking API). Under createYavio().wrap() it does not even keep the input out: wrap() instruments every tool on the server, so the override is the only way.

rejectedInputValues can be set per tool as well, in both directions.

intent: false additionally keeps the tool out of intent capture: the context parameter is neither advertised nor captured for it, and a context a client still sends from a cached schema is stripped before validation.

Tool names are not validated — tools register after withYavio() runs — so an override for a name that never registers is simply unused. There is no environment-variable form.

Session key

sessionKey tells the SDK which conversation a call belongs to when the call carries no session key the SDK knows — over HTTP every such call would otherwise be a session of its own (since SDK 0.5.5, on any host; 0.5.4 put all key-less callers of a server that reuses one stateless transport into one), which the dashboard does not count (session_source: "per_request"). Code option only, on createYavio() and withYavio():

const analytics = createYavio({
  serverOnly: true,
  sessionKey: ({ headers }) => headers["x-conversation-id"],
});

The SDK takes a call's session from the first key it finds: Mcp-Session-Id, ChatGPT's _meta["openai/session"], VS Code's _meta["vscode.conversationId"], the Codex CLI's _meta.threadId (only from codex-mcp-client), then sessionKey; without any, a session of its own for the call over HTTP (per_request) and the connection's own session on stdio (connection). sessionKey(request) gets { headers, meta, authInfo, extra } — the HTTP headers (names lower-cased, {} off HTTP), the request _meta, what your auth middleware set as req.auth, and the MCP SDK's handler context — the same on MCP SDK v1 and v2. It runs synchronously before the handler, at most once per call. Return a string of at most 1 024 characters, or undefined / "" for none; a throw, a promise, a non-string or a longer string counts as none, with one YAVIO-1102 warning per process, and never affects the call. A value that is not a function logs YAVIO-1006 once and is ignored. The SDK stores ses_ + an HMAC of the value keyed with the API key, never the value.

Each session a process sees takes an entry in its session store (1 000, least recently used out) and in the connection-event marks (10 000); with more concurrent conversations than that an idle one ages out and starts over. A call without a key on an HTTP request takes no entry in the session store. See Setup for the order of the keys and what per_request means.

Example configurations

Production (Yavio Cloud)

// Code — just the API key, everything else uses defaults
withYavio(server, {
  apiKey: process.env.YAVIO_API_KEY,
});

Local development

{
  "apiKey": "yav_dev_key",
  "endpoint": "http://localhost:3001/v1/events"
}

// No options needed — config file is auto-discovered
withYavio(server);

Disabled (CI / testing)

// No API key anywhere → no-op mode, zero overhead
withYavio(server);