Observe the SDK

observe lets your code, a test or a tracing library watch what the SDK decides and does. It is read-only: an observer can't veto or change a call.

It covers each network, permission and access decision, each AI, MCP, files, pay and share call, and spans for fetches, driver calls and actions. One that throws or stalls never changes a request. Reach for it to feed a metrics tool, to assert in tests, or to debug a refused call.

# Observers are code, not configuration. Debug output is an environment variable:
#   MAINSDK_DEBUG=observe                         print every event, with detail fields (dev only)
#   MAINSDK_DEBUG=mainsdk:access.*,mainsdk:network.*   only matching channels
schema: 1

import { observe } from "mainsdk";

const stop = observe("mainsdk:network.*", (e) => {
  console.log(e.channel, e.data.host, e.data.decision);
});

observe:
  driver: builtin

Quick start

import { observe } from "mainsdk";

const stop = observe("mainsdk:network.*", (e) => {
  console.log(e.channel, e.data.host, e.data.decision);
});
// later: stop()

The pattern is an exact channel name or one ending in *. A name that matches no channel throws MAIN-OBS-0005 and names the closest one. The full list is on the channels reference.

Configuration

There is no main.yaml section: observers are code, registered at start. These calls and settings shape them.

• observe(pattern, fn, opts?) subscribes and returns stop. opts.max bounds the queue (default 1,000).
• app.observe(pattern, fn, opts?) is the same for one app.
• observe.channels() lists every channel with its version, kind, publisher and JSON Schema.
• observe.schema(name) returns the JSON Schema 2020-12 of one payload.
• observe.flush() waits until every queue is drained. observe.stats() reports delivered and dropped counts.
• observe.otel(api?) bridges spans to an OpenTelemetry API you pass in, using only the allowed attributes.
• registerChannel(def) and removeChannel(name, version) add or remove a channel entry. A changed shape ships as @2 beside @1.
• detailScope(opts, fn) turns debug detail on for fn for up to 60 minutes. In development MAINSDK_DEBUG=observe, or a list of channel patterns, prints matching events with their detail fields. In production MAINSDK_DEBUG is ignored and MAIN-LOG-0003 is logged once.
• tracedDriver(driver, { publisher, interface, ops }) wraps a driver's async operations in driver.call spans.

What you get

Every event has the same envelope: channel, schema, kind, phase, id, time, app, tenant, user, traceId, spanId, parentSpanId, caller, data and detail. The payload is redacted with the log rules, URL query values are removed, and the object is frozen. An observer does not receive events its own calls caused.

Observers run off the request path. When a queue is full the oldest event is dropped and MAIN-OBS-0002 is logged at most once a minute. A throw is caught and logged as MAIN-OBS-0001. Synchronous work over 10 ms is reported as MAIN-OBS-0003.

Errors and checks

The MAIN-OBS-0001 to 0005 codes above are runtime codes: a throwing observer, a full queue, slow synchronous work, a payload that breaks its schema and an unknown channel. See check codes.

Swapping drivers

observe has no drivers. It is part of the core, and the same calls work whatever drivers the app uses. tracedDriver wraps a driver's calls in driver.call spans, and observe.otel() bridges spans to OpenTelemetry.

Testing

createTestApp() gives app.events(pattern?), which returns the recorded events at once, and app.events.clear(). A payload with a field its schema doesn't list throws MAIN-OBS-0004.

In development

With no setup, events from the dev server are written to .mainsdk/events/channels.jsonl, and mainsdk logs --channel "mainsdk:network.*" reads them.

Next

• Channels reference
• Logging
• Test your app
• Watch what your app decides