Event Schema

Every event sent by an SDK Garden client library is a JSON object POSTed to the ingest endpoint as part of a batch. This page documents the exact shape of each event type.

Wire format

Each HTTP POST to /track contains a JSON body with this structure:

{
  "api_key": "sgk_live_abc123",
  "events": [
    { /* event object */ },
    { /* event object */ }
  ]
}

Event object

All events share these top-level fields:

Field	Type	Description
`event`	`string`	Event type name. See event types below.
`sdk`	`object`	Identifies the SDK being observed.
`sdk.name`	`string`	The `sdkName` / `sdk_name` passed to `init()`.
`sdk.version`	`string`	The `sdkVersion` / `sdk_version` passed to `init()`.
`session_id`	`string`	UUID4 generated once per client instance. Groups events from the same SDK session.
`timestamp`	`number`	Unix timestamp in milliseconds at the moment the event was enqueued.
`properties`	`object`	Event-specific payload. See each event type below.
`meta`	`object`	Runtime context collected at enqueue time. See Meta fields.

Event types

`sdk_initialized`

Emitted automatically by SdkGarden.init() / SdkGarden(...).start() immediately after the client is configured.

The environment fields are runtime-specific — each client sends only what is meaningful for its runtime. A server-side client (Python, Java, C#, etc.) will never include browser fields like screen dimensions or viewport size. The example below shows a browser JavaScript payload; see the per-runtime tables beneath it for what each runtime actually sends.

{
  "event": "sdk_initialized",
  "sdk": { "name": "acme-payments", "version": "2.1.0" },
  "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": 1716163200000,
  "properties": {
    "environment": {
      "runtime": "browser",
      "screen_width": 1920,
      "screen_height": 1080,
      "viewport_width": 1440,
      "viewport_height": 900,
      "color_depth": 24,
      "pixel_ratio": 2,
      "timezone": "America/New_York",
      "language": "en-US"
    }
  },
  "meta": {
    "url": "https://example.com/dashboard",
    "referrer": "https://example.com/"
  }
}

Properties — JavaScript (browser):

Field	Type	Description
`environment.runtime`	`"browser"`	Always `"browser"` in browser environments.
`environment.screen_width`	`number`	`screen.width` in pixels.
`environment.screen_height`	`number`	`screen.height` in pixels.
`environment.viewport_width`	`number`	`window.innerWidth` in pixels.
`environment.viewport_height`	`number`	`window.innerHeight` in pixels.
`environment.color_depth`	`number`	`screen.colorDepth`.
`environment.pixel_ratio`	`number`	`window.devicePixelRatio`.
`environment.timezone`	`string`	IANA timezone from `Intl.DateTimeFormat`.
`environment.language`	`string`	`navigator.language`.

Properties — JavaScript (Node.js):

Field	Type	Description
`environment.runtime`	`"node"`	Always `"node"` in Node.js.

Properties — Python:

Field	Type	Description
`environment.runtime`	`"cpython"`	Always `"cpython"`.
`environment.python_version`	`string`	Python version string, e.g. `"3.11.4"`.

`method_called`

Emitted at the start of every call to a wrapped method, before the function runs.

{
  "event": "method_called",
  "sdk": { "name": "acme-payments", "version": "2.1.0" },
  "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": 1716163201234,
  "properties": {
    "method": "processPayment",
    "args_count": 2
  },
  "meta": {}
}

Field	Type	Description
`properties.method`	`string`	The `methodName` passed to `trackMethod` / `track_method`.
`properties.args_count`	`number`	Number of positional arguments the function was called with.

`method_success`

Emitted when a wrapped method returns successfully. For async functions (JavaScript), emitted when the returned promise resolves.

{
  "event": "method_success",
  "sdk": { "name": "acme-payments", "version": "2.1.0" },
  "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": 1716163201456,
  "properties": {
    "method": "processPayment",
    "duration_ms": 222,
    "is_async": false,
    "args_count": 2
  },
  "meta": {}
}

Field	Type	Description
`properties.method`	`string`	The method name.
`properties.duration_ms`	`number`	Wall-clock time from call start to return, in milliseconds.
`properties.is_async`	`boolean`	`true` if the function returned a Promise. JavaScript only.
`properties.args_count`	`number`	Number of positional arguments. JavaScript only.

`sdk_error`

Emitted when a wrapped method throws (or its promise rejects), or when trackError / track_error is called directly.

{
  "event": "sdk_error",
  "sdk": { "name": "acme-payments", "version": "2.1.0" },
  "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": 1716163202789,
  "properties": {
    "error_message": "Connection refused to postgres://db.internal:5432",
    "error_type": "ConnectionError",
    "method": "connectToDatabase",
    "duration_ms": 2003
  },
  "meta": {}
}

Field	Type	Description
`properties.error_message`	`string`	`error.message` (JS) or `str(error)` (Python), with email addresses replaced by `[REDACTED]`.
`properties.error_type`	`string`	`error.name` (JS) or `type(error).__name__` (Python).
`properties.method`	`string`	Present when the error came from a wrapped method. The method name.
`properties.duration_ms`	`number`	Present when the error came from a wrapped method. Time until the exception.
`properties.is_async`	`boolean`	Present in JavaScript when the error came from a wrapped async function.
(any key)	`any`	Additional fields from the `context` argument passed to `trackError` / `track_error`.

PII scrubbing: Before enqueueing, both clients replace any string matching /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/ with [REDACTED] in error_message. No other scrubbing is applied — avoid putting PII in error messages.

Custom events

Any string passed as the first argument to SdkGarden.track() / sg.track() becomes a custom event. The properties payload is whatever you pass as the second argument.

{
  "event": "feature_used",
  "sdk": { "name": "acme-payments", "version": "2.1.0" },
  "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": 1716163203000,
  "properties": {
    "feature": "streaming",
    "model": "gpt-4"
  },
  "meta": {}
}

Properties can be any JSON-serializable key/value pairs. Nested objects are supported.

Meta fields

The meta object is populated by the client at enqueue time with runtime context. In browser environments it includes URL and referrer. In Node.js and Python it is typically empty ({}).

Field	Source	Description
`meta.url`	Browser only	`window.location.href` at the time the event was enqueued.
`meta.referrer`	Browser only	`document.referrer`.

Wire format​

Event object​

Event types​

sdk_initialized​

method_called​

method_success​

sdk_error​

Custom events​

Meta fields​