Sign in Open an account
SPOT TAPE
FRNT-200K2.180+1.42%
MID-128K0.4204−0.81%
OW-70B0.0840+3.11%
OW-8B0.0191+0.44%
VIS-1M1.6400−2.19%
RSN-XL6.9000+0.93%
EMB-S0.01100.00%
14:02:07 UTC
Documentation v1 · UPDATED 21 AUG 2026
Search the docs⌘K
Get an API key
On this page
Reconciliation with PostHog Event Taxonomy brief Common properties SDK onboarding funnel events
sdk.initialized sdk.first_api_call sdk.first_order_placed sdk.first_order_settled
API call pattern event
api_call
Opt-in and disclosure PostHog configuration Distinct_id strategy Contracts summary

SDK Telemetry Event Schema

This is the shared contract every SDK telemetry implementation follows. The Rust, Python, and TypeScript SDKs all capture the same event names with the same properties so cross-SDK funnel analysis in PostHog works without drift. Implementers should be able to produce a valid PostHog capture payload for any event below by reading only this page.

The published, sidebar-linked version of this contract lives at SDK telemetry event schema. The opt-in default and distinct_id strategy quoted below come from the telemetry decision record and the opt-in ADR (docs/decisions/sdk-telemetry-opt-in.md).

Reconciliation with PostHog Event Taxonomy brief

The four sdk.* funnel event names and property allow-lists are authoritative in docs/analytics/events.md and the binding contract at SDK telemetry (schema_version 2). This page restates that contract; do not invent parallel milestone names.

Common properties

Every sdk.* funnel event carries these identity fields in addition to its event-specific allow-listed properties. SDK capture bypasses the Rust capture() allow-list, so SDK authors own conformance.

PropertyTypeRequiredDescription
distinct_idstringrequiredStable per-developer id. See Distinct_id strategy.
trace_idstringrequiredFresh UUID generated per emission.
timestampstring (ISO-8601 / RFC 3339 UTC)requiredWhen the event occurred.

SDK onboarding funnel events

Each of the four events fires once per install. Property allow-lists match docs/analytics/events.md.

sdk.initialized

PropertyTypeRequiredDescription
languagestringrequiredrust | typescript | python
versionstringrequiredSDK package version
environmentstringrequiredprod | dev
user_idstringrequiredCarries distinct_id

sdk.first_api_call

PropertyTypeRequiredDescription
latency_msintegerrequiredRequest round-trip in ms
endpointstringrequiredPath only, query stripped
response_statusintegerrequiredHTTP status code

sdk.first_order_placed

PropertyTypeRequiredDescription
successbooleanrequiredWhether placement succeeded
model_tierstringrequiredRequested model / tier
order_sizeintegerrequiredRequested token quantity

sdk.first_order_settled

PropertyTypeRequiredDescription
end_to_end_latency_msintegerrequiredPlacement → settlement in ms
settlement_statusstringrequired"success" or "failed"

API call pattern event

api_call

Fires on every SDK HTTP call (after opt-in), success or failure. This event powers SDK API coverage and health/usage analysis.

PropertyTypeRequiredDescription
endpointstringrequiredPath template, not the concrete URL. Path params are replaced with placeholders, e.g. /v1/sellers/{id}/asks. Never carries user data or query values.
methodstringrequiredHTTP method, e.g. POST, GET, DELETE.
response_time_msintegerrequiredWall-clock time from request send to response received, in milliseconds.
successbooleanrequiredtrue when status_code is 2xx, else false.
status_codeintegerrequiredHTTP status code returned, e.g. 200, 408, 502.

The canonical endpoint path templates (aligned to the gateway API the SDKs already call) are:

TemplateMethods
/v1/chat/completionsPOST
/v1/sellers/registerPOST
/v1/sellers/{id}/asksPOST
/v1/sellers/{id}/asks/{ask_id}DELETE
/v1/sellers/{id}/capacityPOST
/v1/sellers/{id}/tradesGET

Opt-in and disclosure

Quoted verbatim from the telemetry decision record and the opt-in ADR (docs/decisions/sdk-telemetry-opt-in.md):

  • Default: opt-in by default — telemetry is off unless the developer explicitly enables it.
  • Constructor/config flag: telemetry_enabled (Rust field telemetry_enabled, Python kwarg telemetry_enabled, TypeScript field telemetryEnabled). Default value: false.
  • Environment variable: TOKEN_GATEWAY_TELEMETRY (1/true enable, 0/false disable). The env var wins when both it and the flag are set.
  • Disclosure surface: a telemetry section in each SDK README plus a single first-run log line emitted when telemetry initialises.

Reusable disclosure copy (SDK READMEs paste this with minimal variation):

This SDK can send anonymous usage telemetry (onboarding milestones and API call patterns) to help improve the AI Token Gateway. Telemetry is off by default. To enable it, set telemetry_enabled: true when constructing the client, or set the TOKEN_GATEWAY_TELEMETRY=1 environment variable. No API keys, request bodies, or response bodies are ever collected. See the SDK telemetry event schema for the full list of events and properties.

PostHog configuration

(This section fulfils the parent task's in-scope item 4 — the shared PostHog project API key and host configuration convention.)

All three SDKs read the PostHog project API key and host from the same environment variables and expose the same client-config field, so telemetry configuration is identical across languages. The canonical names below are namespaced under TOKEN_GATEWAY_ to avoid colliding with a developer's own PostHog environment variables in their application.

SettingCanonical env varDefault
PostHog project API keyTOKEN_GATEWAY_POSTHOG_API_KEYnone — telemetry stays off if unset even when telemetry_enabled is true
PostHog host endpointTOKEN_GATEWAY_POSTHOG_HOSThttps://app.posthog.com

Per-SDK client-config field for the PostHog project API key (each following its language's naming convention):

SDKConfig fieldCase convention
Rustposthog_api_keysnake_case struct field
Pythonposthog_api_keysnake_case kwarg
TypeScriptposthogApiKeycamelCase interface field

Rules every SDK honours:

  • The project API key must be configurable via the env var or the config field — it must never be hardcoded into SDK source.
  • When a config field is provided it takes precedence over the env var; when neither is set and telemetry_enabled is true, the SDK logs the first-run disclosure but sends no events (it has no destination key).
  • The host defaults to https://app.posthog.com and is overridable via TOKEN_GATEWAY_POSTHOG_HOST.

Distinct_id strategy

Quoted verbatim from the telemetry decision record:

  • Generation: a random UUIDv4 generated the first time telemetry initialises. Never derived from the API key or any secret.
  • Persistence: written to <config_dir>/token-gateway/telemetry-id, where <config_dir> is the OS user config directory. Overridable via TOKEN_GATEWAY_TELEMETRY_DISTINCT_ID, which takes precedence over the file.
  • Fallback: if the config directory is unreadable or unwritable, generate a per-process ephemeral UUIDv4 and continue without failing the SDK call.

Contracts summary

Grep-checkable identifiers all three SDKs must use verbatim:

  • Event names: package_install_detected, api_key_generated, first_authenticated_request, first_successful_api_call, first_order_placement, api_call.
  • Common properties: distinct_id, sdk_language, sdk_version, install_timestamp.
  • api_call properties: endpoint, method, response_time_ms, success, status_code.
  • Opt-in flag / env var: telemetry_enabled / TOKEN_GATEWAY_TELEMETRY.
  • PostHog config env vars: TOKEN_GATEWAY_POSTHOG_API_KEY, TOKEN_GATEWAY_POSTHOG_HOST.
  • Distinct_id override: TOKEN_GATEWAY_TELEMETRY_DISTINCT_ID.