Echo: receptor de telemetria da Oz

Echo é um pequeno serviço FastAPI + MongoDB que trabalha com telemetria no Oz API. Ele tem duas funções:

1. Ingestão – aceitar lotes de eventos de ciclo de vida da sessão (telemetria) do Mobile SDK (mSDK) e do Web SDK (WebSDK), desduplicá-los e armazená-los.

2. Consulta – permitir que um chamador autorizado recupere os eventos armazenados de uma sessão, para depuração ou análise.

Echo fica ao lado da API principal Oz, acessível pelo mesmo ingress/reverse proxy, em /api/event_sessions. Isso não afeta análises nem quaisquer outros processos.

De onde vêm os dados

Cada sessão do SDK armazena em buffer um traço estruturado dos eventos ocorridos no lado do cliente. Esse buffer é não enviado ao Echo diretamente ou em tempo real.

No Web SDK, o fluxo é:

Navegador (SDK)  →  backend próprio do SDK (com buffer, ~a cada 3s)
                        │
                        ▼  cron em segundo plano, em lotes + amostrado
                   POST /api/event_sessions  →  Echo  →  MongoDB

As sessões do Mobile SDK seguem a mesma estrutura (lote de eventos → POST /api/event_sessions), com nomes de eventos específicos para mobile.

Isso significa que:

• A entrega é em lotes, não em tempo real. O backend próprio do SDK espera a sessão ficar ociosa (padrões: ~60 minutos após a abertura da sessão, ~10 minutos após a última atividade) antes de enviá-la ao Echo. Assim, uma sessão aparece no Echo com atraso.

• A entrega pode ser amostrada. Uma proporção de amostragem configurável (por tenant, com padrão de enviar tudo) pode ser definida para encaminhar apenas uma fração das sessões, para controle de custo/volume.

• A entrega é em melhor esforço. Se o envio ao Echo falhar, ele é registrado e descartado – não há fila de retry. O Echo não é uma trilha de auditoria autoritativa de todas as sessões; ele deve ser tratado como um recurso de apoio para depuração e análises, .

Principais métodos da API

Os principais métodos que o Echo usa são:

• POST /api/event_sessions – os SDKs chamam isso para enviar um lote de eventos.

• GET /api/event_sessions – consultar sessões armazenadas (acesso restrito a uma allowlist explícita de contas).

• GET /healthz, GET /livez, GET /version – verificações de saúde/versão, sem autenticação necessária.

Se o Echo for instalado como um subcomponente da API, seus endpoints não são expostos publicamente. A única exceção é Docker, onde eles podem ser acessados com um prefixo echo: GET /echo/version.

Lista de endpoints

Método e caminho	Autenticação	Objetivo
GET /version	nenhuma	Informações de versão de Echo + MongoDB
GET /livez	nenhuma	Verificação de Liveness
GET /healthz	nenhuma	Verificação de readiness (confere a conectividade com Mongo)
POST /api/authorize/auth	corpo: {"credentials": {"email", "password"}}	Login, validado contra users.toml
POST /api/authorize/refresh	corpo: {"expire_token"}	Trocar um refresh token por um novo par de tokens
POST /api/event_sessions	X-Forensic-Access-Token cabeçalho, Authorization: Bearer, ou um corpo assinado com JWS	Ingerir um lote de eventos de sessão (chamado pelos SDKs, normalmente não pelos clientes diretamente)
GET /api/event_sessions	mesmo que acima, e o chamador deve estar na service.toml allowlist	Consultar sessões armazenadas. Use filtros, se necessário: session_id, time_created.min/max, time_updated.min/max, device_family, device_platform, sdk_version, bundle_id, sorting, offset/cursor, limit, include_count

Toda implantação também serve documentação interativa diretamente do serviço em execução: /docs (Swagger UI), /redoc, e o esquema bruto em /openapi.json. Use isso para explorar os formatos exatos de request/response em vez de depender somente desta tabela.

Autenticação

Por padrão, o Echo usa um token de acesso à API e envia telemetria para o endereço da API. Para isso, ele requer:

• Echo instalado como subcomponente e disponível via {{api_host}}/api/event_sessions.

• O token JWT que não é de serviço usado .

• Chave pública do par de chaves JWT da API configurada no Echo.

Veja como definir o Echo como receptor de telemetria no SDK. Recomendamos criar um usuário separado no Echo e configurar o SDK para o Echo separadamente.

Os Mobile SDKs exigem login e senha. No users.toml arquivo do Echo, defina:

users.toml

"your_email" = "your_strong_password"

O Web SDK precisa de service_token, não de JWT. Adicione ao static_tokens.toml arquivo do Echo:

static_tokens.toml

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

Obtenção de telemetria

Para ler a telemetria, é necessário adicionar o usuário correspondente ao arquivo service.toml do Echo.

Exemplo:

emails = "your_email,your_another_email,api-uuid"

Casos de uso

1. Criar um usuário leitor de telemetria com o login [e-mail] e a senha 123:

users.toml

"[e-mail]" = "123"

service.toml

emails = "[e-mail]"

1. Criar um usuário leitor de telemetria com o login [e-mail] e o token token:

static_tokens.toml

"[e-mail]" = "token"

service.toml

emails = "[e-mail]"

1. Criar um usuário de API leitor de telemetria com UUID = 1111aaaa-11aa-11aa-11aa-111111aaaaaa:

service.toml

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

A chave JWT pública da Oz API deve ser configurada no Echo.

Configuração

Esta referência se aplica a todos os caminhos de instalação. O que muda entre os caminhos não é o significado da configuração, mas como ela chega ao Echo. Isso pode ser uma variável de ambiente bruta em Docker/Compose ou um valor de Helm que se torna uma entrada de ConfigMap/Secret. Cada guia de instalação registra detalhes específicos do caminho; este documento é a fonte única de verdade para significado e padrões. como ele chega ao Echo. Isso pode ser uma variável de ambiente bruta em Docker/Compose ou um valor de Helm que se torna uma entrada de ConfigMap/Secret. Cada guia de instalação registra detalhes específicos do caminho; este documento é a fonte única de verdade para significado e padrões.

Variáveis de ambiente

Ambas as variáveis são funcionalmente obrigatórias.

Variável	Padrão	Descrição
MONGODB_URL	mongodb://localhost:27017/	String de conexão do MongoDB
MONGODB_DB_NAME	dbname	Nome do banco de dados para as sessions collection

Formatos de arquivo TOML

users.toml – contas de login (email → senha):

"your_email" = "your_strong_password"

static_tokens.toml – tokens bearer pré-compartilhados (email → tokens separados por vírgula):

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

service.toml – allowlist para GET /api/event_sessions (emails ou UUIDs separados por vírgula):

emails = "your_email,your_another_email,uuid"

Observações sobre parâmetros de consulta

• cursor (string opaca, retornada como next_cursor nas respostas) é a forma recomendada de paginar grandes conjuntos de resultados – é mais eficiente do que offset e mutuamente exclusiva com ela.

• include_count padrão: true; defina-o como false se você não precisar da contagem total e quiser uma resposta mais rápida.

• device_family corresponde por substring/padrão, não por correspondência exata; device_platform, sdk_version e bundle_id corresponde exatamente.

Opcional: exportação de logs do funil de conversão

O Echo pode, opcionalmente, manter um buffer de curta duração (no Redis) de sessões em andamento e, quando uma sessão ficar ociosa, emitir uma linha de log JSON estruturada resumindo o resultado do funil dela – destinada a um pipeline de envio de logs para seu próprio sistema de analytics, como alternativa a consultar a API do Echo diretamente.

Isso vem desativado por padrão e não está conectado por nenhum dos charts Helm – ativá-lo requer Redis acessível mais estas configurações (via envs nos caminhos Helm, ou variáveis de ambiente simples nos caminhos Docker):

Variável	Padrão	Objetivo
LOG_CONVERSION_ENABLED	false	Chave mestra
REDIS_URL	redis://localhost:6379	String de conexão do Redis
LOG_CONVERSION_SESSION_MINUTE_TTL	30	Minutos que uma sessão permanece em buffer antes de ser esvaziada/registrada

Se quiser este recurso, será necessário fornecer sua própria instância Redis acessível pelo Echo – nenhum dos caminhos de instalação provisiona uma para essa finalidade.

Instalação

Recomendamos usar o Echo em nossa nuvem: nesse caso, nada precisa ser hospedado, e o esforço de instalação é mínimo. Tudo o que é necessário são credenciais e o endpoint do Echo, ambos serão fornecidos pelo representante da Oz. Depois, dependendo do SDK que você usar, configure a conexão com o Echo.

Web SDK: por padrão, enviamos telemetria para a URL da API, mas, se essa URL for um caminho direto, adicione estes parâmetros ao arquivo de configuração do Web Adapter:

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

Mobile SDK: siga as instruções.

• Android

• iOS

• Flutter

Se for instalar o Echo em sua infraestrutura, escolha a opção de instalação:

• Docker autônomo

• Echo dentro da API via Docker Compose

• Autônomo oz-echo Helm chart

• oz-echo como parte de api-decomposed (oz-k8s)