Echo: Oz Telemetry Receiver

Echo is a small FastAPI + MongoDB service that works with telemetry in Oz API. It has two jobs:

1. Ingest – accept batches of session-lifecycle (telemetry) events from the mobile SDK (mSDK) and Web SDK (WebSDK), de-duplicate and store them.

2. Query – let an authorized caller retrieve a session's stored events back out, for debugging or analysis.

Echo sits alongside the main Oz API, reachable through the same ingress/reverse proxy, at /api/event_sessions. It doesn’t affect analyses or any other processes.

Where the data comes from

Each SDK session buffers a structured trace of events happened on client-side. This buffer is not sent to Echo directly or in real time.

On the Web SDK, the flow is:

Browser (SDK)  →  SDK's own backend (buffered, ~every 3s)
                        │
                        ▼  background cron, batched + sampled
                   POST /api/event_sessions  →  Echo  →  MongoDB

Mobile SDK sessions follow the same shape (event batch → POST /api/event_sessions), with mobile-specific event names.

This means that:

• Delivery is batched, not real-time. The SDK's own backend waits for a session to go idle (defaults: ~60 minutes after session open, ~10 minutes after last activity) before shipping it to Echo. Thus, a session appears in Echo with a delay.

• Delivery can be sampled. A configurable sampling ratio (per-tenant, defaults to sending everything) can be set to only forward a fraction of sessions, for cost/volume control.

• Delivery is best-effort. If the send to Echo fails, it's logged and dropped – there's no retry queue. Echo isn't an authoritative audit trail of every session, it should be treated as a debugging and analytics aid, .

Main API methods

Main methods that Echo uses are:

• POST /api/event_sessions – SDKs call this to submit a batch of events.

• GET /api/event_sessions – query stored sessions (access-restricted to an explicit allowlist of accounts).

• GET /healthz, GET /livez, GET /version – health/version checks, no auth required.

If Echo is installed as an API subcomponent, its endpoints are not exposed publicly. The only exception is Docker, where they can be accessed with an echo prefix: GET /echo/version.

Endpoint list

Method & path	Auth	Purpose
GET /version	none	Echo + MongoDB version info
GET /livez	none	Liveness probe
GET /healthz	none	Readiness probe (checks Mongo connectivity)
POST /api/authorize/auth	body: {"credentials": {"email", "password"}}	Login, checked against users.toml
POST /api/authorize/refresh	body: {"expire_token"}	Exchange a refresh token for a new token pair
POST /api/event_sessions	X-Forensic-Access-Token header, Authorization: Bearer, or a JWS-signed body	Ingest a batch of session events (called by the SDKs, not normally by clients directly)
GET /api/event_sessions	same as above, and the caller must be in the service.toml allow-list	Query stored sessions. Use filters if needed: session_id, time_created.min/max, time_updated.min/max, device_family, device_platform, sdk_version, bundle_id, sorting, offset/cursor, limit, include_count

Every deployment also serves interactive documentation directly from the running service: /docs (Swagger UI), /redoc, and the raw schema at /openapi.json. Use these to explore the exact request/response shapes rather than relying solely on this table.

Authentication

By default, Echo uses API access token and sends telemetry to the API address. For this, it requires:

• Echo installed as subcomponent and available via {{api_host}}/api/event_sessions.

• The non-service JWT token used .

• Public key from API JWT key pair set in Echo.

Here is how to set Echo as a telemetry receiver in SDK. We recommend creating a separate user in Echo and configure SDK for Echo separately.

Mobile SDKs require login and password. In the users.toml file of Echo, set:

users.toml

"your_email" = "your_strong_password"

Web SDK needs service_token, not JWT. Add to the static_tokens.toml Echo file:

static_tokens.toml

"your_email" = "your-token-one,your-token-two"

Obtaining telemetry

To read telemetry, you need to add the corresponding user to the service.toml Echo file.

Example:

emails = "your_email,your_another_email,api-uuid"

Use cases

1. Create a telemetry reader user with the login [e-mail] and password 123:

users.toml

"[e-mail]" = "123"

service.toml

emails = "[e-mail]"

1. Create a telemetry reader user with the login [e-mail] and token token:

static_tokens.toml

"[e-mail]" = "token"

service.toml

emails = "[e-mail]"

1. Create a telemetry reader API user with UUID = 1111aaaa-11aa-11aa-11aa-111111aaaaaa:

service.toml

emails = "1111aaaa-11aa-11aa-11aa-111111aaaaaa"

The public Oz API JWT key must be configured in Echo.

Configuration

This reference applies to all install paths. What differs between paths is now what setting means but how it reaches Echo. This may be a raw environment variable in Docker/Compose or a Helm value that becomes a ConfigMap/Secret entry. Each install guide notes path-specific details; this document is the shared source of truth for meaning and defaults.

Environment variables

Both variables are functionally required.

Variable	Default	Description
MONGODB_URL	mongodb://localhost:27017/	MongoDB connection string
MONGODB_DB_NAME	dbname	Database name for the sessions collection

TOML file formats

users.toml – login accounts (email → password):

"your_email" = "your_strong_password"

static_tokens.toml – pre-shared bearer tokens (email → comma-separated tokens):

"your_email" = "your-token-one,your-token-two"

service.toml – allowlist for GET /api/event_sessions (comma-separated emails or uuids):

emails = "your_email,your_another_email,uuid"

Query parameter notes

• cursor (opaque string, returned as next_cursor in responses) is the recommended way to page through large result sets – it's more efficient than offset and mutually exclusive with it.

• include_count defaults to true; set it to false if you don't need the total count and want a faster response.

• device_family matches by substring/pattern, not exact match; device_platform, sdk_version, and bundle_id match exactly.

Optional: conversion-funnel log export

Echo can optionally maintain a short-lived buffer (in Redis) of in-progress sessions and, once a session goes idle, emit one structured JSON log line summarizing its funnel result – intended for a log-shipping pipeline into your own analytics system, as an alternative to querying Echo's API directly.

This is off by default and not wired up by either Helm chart – turning it on requires reachable Redis plus these settings (via envs on the Helm paths, or plain environment variables on the Docker paths):

Variable	Default	Purpose
LOG_CONVERSION_ENABLED	false	Master switch
REDIS_URL	redis://localhost:6379	Redis connection string
LOG_CONVERSION_SESSION_MINUTE_TTL	30	Minutes a session is buffered before being flushed/logged

If you want this feature, you'll need to provide your own Redis instance reachable from Echo – none of the install paths provision one for this purpose.

Installation

We recommend using Echo in our cloud: in this case, you don’t host anything, and the installation efforts are minimal. All you need is credentials and Echo endpoint, both will be provided by Oz representative. Then, depending on SDK you use, set up echo connection.

Web SDK: by default, we send telemetry to the API URL, but if this URL is a direct path, add these parameters to the Web Adapter configuration file:

"tm_url":"your_echo_endpoint/api/",
"tm_token":"<TOKEN>"

Mobile SDK: follow the instructions.

• Android

• iOS

• Flutter

If you are going to install Echo within your infrastructure, please choose the installation option:

• Standalone Docker

• Echo within API via Docker Compose

• Standalone oz-echo Helm chart

• oz-echo as a part of api-decomposed (oz-k8s)