Streaming e TTFT

Acompanhe o text/event-stream do primeiro byte até o fim e saiba onde o TTFT é medido. Você separa a latência do upstream da latência do proxy e reage certo quando o primeiro frame não chega.

Pré-requisitos#

Para acompanhar o fluxo de ponta a ponta, você precisa de:

O que é TTFT#

TTFT (time to first token) é o tempo entre o recebimento do pedido no proxy e o primeiro frame SSE válido repassado ao cliente. É o número que descreve quanto tempo você espera até a resposta começar a aparecer.

O proxy guarda quatro medidas por request. Compare as colunas antes de atribuir a lentidão a uma chave:

Como o stream passa#

O caminho tem quatro tempos, nesta ordem. Cada um fecha uma porta: depois dele, muda o que ainda é possível fazer com a resposta.

1. 1 · Headers segurados

   Depois do dial, o handler não confirma 200. Ele segura o head e lê o primeiro frame SSE do upstream com readFirstFrame, sob o teto de FIRST_CHUNK_TIMEOUT_MS. Enquanto o head não sai, o failover para a próxima chave continua possível.

2. 2 · Primeiro frame

   Se o primeiro frame é dado válido, os bytes voltam para a frente da stream com unshift — replay byte-idêntico — e só então o proxy escreve o head SSE. Se o primeiro frame é erro, o corpo, até 64 KB, segue para o classificador e a chave seguinte é tentada em silêncio.

3. 3 · Corpo

   O coletor repassa só os bytes que o SseParser reconheceu como frame válido. Texto cru colado entre frames não chega ao cliente. É neste mesmo ponto que o TTFT é carimbado.

4. 4 · Fim

   Quando o stream termina, detectStreamErrors varre os eventos coletados e aplica a mesma política de erro do caminho HTTP. O cliente recebe o fechamento normal do stream.

O formato que atravessa o fio é o SSE canônico do Anthropic Messages. Cada frame carrega uma linha data: com um objeto JSON, e os frames são separados por uma linha em branco:

event: message_start
data: {"type":"message_start","message":{"id":"msg_01H8","type":"message","role":"assistant","model":"claude-sonnet-4-20250514","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":24,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Olá"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"!"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":12}}

event: message_stop
data: {"type":"message_stop"}

O sentinela [DONE] também conta como frame válido, e o parser o descarta em silêncio. Frame sem linha data: parseável não vale.

Antes do 200, o resultado da leitura do primeiro frame decide o caminho. Estes são os cinco desfechos possíveis:

Onde o proxy mede#

O TTFT é carimbado no transform do coletor, no mesmo if (validBytes) que repassa os bytes reconhecidos: é o instante em que o primeiro byte útil atravessa para o cliente. O carimbo nunca reseta — do segundo frame em diante, o valor já não é TTFT.

O ponto não é o primeiro byte cru. Entre o upstream e o cliente passam o parse do SSE, os transforms de provider e a fila do socket. Medir no start do upstream, ou no primeiro byte cru, daria um número menor do que o cliente sente, e você compararia esse número com a experiência do usuário acreditando que eram a mesma coisa.

Três consequências seguem desse ponto de medição:

Erro no meio do stream#

Depois que o 200 sai, o status HTTP está congelado. O proxy age sobre a chave e sobre o corpo que emite, mas não muda o que o cliente já recebeu.

Nesse ponto, o proxy faz o seguinte:

O frame que o cliente recebe é este:

event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"All configured providers are unavailable. Please try again shortly."}}

Erro que chega antes do primeiro frame válido é outro caso: o head ainda não saiu, então o proxy aplica a política na chave e faz failover em silêncio. Você recebe a mesma resposta que receberia se a primeira chave tivesse funcionado.

O que afeta a latência#

Cada fator abaixo age num ponto diferente do caminho. Use a terceira coluna para achar onde mexer: