Telemetry

Fire-and-forget collector for first-party telemetry (ABCP-114). One request carries one identity envelope and 1..N events.

The one validated field is service. It must be present and one of: odk, amasian. A body that is not a JSON object, or whose service is missing or outside the allow-list, returns 400 with a detail message and produces no row. This is deliberate: an unknown service would land rows under the wrong service, which is worse than an unknown event type, so it fails at integration time instead of silently. The check is case-sensitive — ODK and odkr are rejected.

Every accepted request returns 202 with an empty body, including for bodies the server cannot use. Apart from service, the server never validates the payload shape; validation and quarantine happen in the warehouse (quarantine_telemetry).

What lands where: each event becomes one Kafka message on telemetry-{event_type} → raw_telemetry_{event_type}. An event_type outside the allow-list (visit, heartbeat, view; env TELEMETRY_EVENT_TYPES) goes to telemetry-unknown. Non-object items inside events, or a scalar events value, become _malformed rows. No row is produced for a rejected service, a server-side produce failure (Kafka unavailable, mid-batch error; still 202 and counted in the server's _stats log). Clients should not expect a retry signal.

Enrichment (server-side): raw client ip (from X-Forwarded-For, stored as-is like PEv2), geo fields (continent country region city metro time_zone), isp, autonomous_system_number, is_ias_blocked, is_office_ip. No hashed IP on this route.

Event types (v1, see the schemas): visit — apps/CTV, on app open (context.trigger=launch) and on foreground-resume after ≥ 30 min in background (resume). The 30-minute suppression is overridden in two cases, which always emit: the first foreground of a new UTC day — a session straddling midnight would otherwise drop the device out of DAU — and any deeplink entry, whose attribution is otherwise lost for good. Deeplink entries may also carry context.entry_source / deeplink_url / referrer / target_id — all optional, so send what the platform exposes. Clients strip credential-bearing parameters, including any nested url=, before sending deeplink_url. context.since_last_ms reports the elapsed time itself, so the threshold can be re-cut downstream. heartbeat — no context. Every ~15 min on every platform, but gated differently: apps and CTV beat while the app is foregrounded, whether or not anything is playing — suppress on screensaver or display-off where the platform exposes it — and web beats only while a video is playing, starting on play and stopping when nothing is playing. A web playback shorter than the interval therefore emits no heartbeat at all, which is fine: the view events either side of it are already close enough together to keep that session whole. The beat exists for the long watch. view — web, target_type=page, target_id=path, on every page load including SPA route changes; context.referrer / context.utm. Web sends no visit: web sessionization runs off view, and the playback-gated heartbeat is what keeps a long watch — which emits no view for its whole duration — from reading as an ended session.

Envelope identity and consent: osdid/islat use the same keys as PEv2. gpp (mobile, web) and us_privacy (CTV) are stored raw; the collector never gates on them. They are applied downstream on the restricted osdid paths (targeting, DMP, advertiser hand-off) only; analytics never read osdid.

event_id is client-generated and required: it is the idempotency key for retries and batch replays.