Observabilidade

Visao Geral

Toda requisicao que passa pelo gateway do Floopy e registrada automaticamente. Voce tem visibilidade completa do que aconteceu, quanto tempo levou, quanto custou e se o caching ou o firewall estiveram envolvidos. Todos os dados sao armazenados em um motor de analytics de alto desempenho projetado para consultas rapidas sobre grandes volumes de dados de log.

Nenhuma instrumentacao adicional ou SDK e necessario. O logging esta integrado ao gateway.

O Que e Registrado

Cada registro de requisicao inclui:

• Requisicao e resposta — o prompt completo e a completion (editavel se necessario).
• Latencia — tempo de resposta de ponta a ponta, detalhado por estagio.
• Uso de tokens — tokens de entrada e saida consumidos.
• Custo — custo calculado com base na precificacao do provedor.
• Status do cache — se a resposta foi servida do cache e qual nivel correspondeu.
• Eventos do firewall — pontuacoes de ameaca e se a requisicao foi sinalizada ou bloqueada.
• Modelo e provedor — qual modelo tratou a requisicao e atraves de qual provedor.
• Propriedades customizadas — qualquer metadado que sua aplicacao anexou a requisicao.

Paginas do Dashboard

Requests

A visualizacao principal de logs. Navegue por todas as requisicoes com filtros por intervalo de tempo, modelo, provedor, codigo de status, cache hit e mais. Clique em qualquer linha para abrir um painel de detalhes mostrando a requisicao e resposta completas, detalhamento de tokens, estagios de latencia e eventos associados.

Sessions

Requisicoes agrupadas por ID de sessao. Quando sua aplicacao envia um identificador de sessao com as requisicoes, o Floopy as agrupa em conversas para que voce possa acompanhar interacoes multi-turno do inicio ao fim.

Users

Analytics por usuario final. Se sua aplicacao envia um identificador de usuario, o Floopy rastreia uso, custo e volume de requisicoes por usuario. Util para identificar power users, detectar abuso e entender padroes de uso.

Properties

Segmente seu trafego por propriedades customizadas. Marque requisicoes com metadados como ambiente, nome do recurso ou tier do cliente, e depois filtre e agregue por essas dimensoes. Isso permite responder perguntas como “quanto custa o recurso de sumarizacao por dia?” ou “qual tier de cliente gera mais tokens?”

Tracing Distribuido

Cada requisicao gera um trace que mostra o ciclo de vida completo atraves do gateway:

1. Autenticacao — validacao da chave de API e busca da organizacao.
2. Verificacao de cache — buscas no exact, semantic e advanced cache com tempos.
3. Firewall — consulta ao cache de vereditos no Qdrant seguida de classificacao de seguranca por LLM (backend e model_ref registrados por chamada).
4. Roteamento — selecao do provedor e transformacao da requisicao.
5. Despacho ao provedor — a chamada ao provedor de IA upstream com tempo de resposta.

A visualizacao de trace exibe esses estagios como spans em uma timeline, para que voce possa ver exatamente onde o tempo e gasto e identificar gargalos.

Propriedades Customizadas e Rastreamento de Sessao

Anexe metadados as requisicoes usando headers para que voce possa filtrar, segmentar e analisar o trafego no dashboard.

Cada propriedade customizada e enviada como seu proprio header. Nao existe um header JSON combinado de propriedades — cada propriedade recebe um header individual floopy-property-<name>.

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
});

const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "floopy-user-id": "user-alice-001",
      "floopy-session-id": "sess-alice-a1b2c3",
      "floopy-session-name": "math-tutoring",
      "floopy-session-path": "/dashboard/math",
      "floopy-property-usertier": "premium",
      "floopy-property-usertype": "power-user",
      "floopy-property-industry": "education",
    },
  },
);

console.log(response.choices[0].message.content);

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.floopy.ai/v1",
    api_key=os.environ["FLOOPY_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "floopy-user-id": "user-alice-001",
        "floopy-session-id": "sess-alice-a1b2c3",
        "floopy-session-name": "math-tutoring",
        "floopy-session-path": "/dashboard/math",
        "floopy-property-usertier": "premium",
        "floopy-property-usertype": "power-user",
        "floopy-property-industry": "education",
    },
)

print(response.choices[0].message.content)

curl https://api.floopy.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "floopy-user-id: user-alice-001" \
  -H "floopy-session-id: sess-alice-a1b2c3" \
  -H "floopy-session-name: math-tutoring" \
  -H "floopy-session-path: /dashboard/math" \
  -H "floopy-property-usertier: premium" \
  -H "floopy-property-usertype: power-user" \
  -H "floopy-property-industry: education" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Confiabilidade: Fallback e Replay

O gateway nunca descarta dados de observabilidade quando o backend de analytics esta indisponivel. Logs, eventos do circuit breaker e spans de trace sao gravados por workers de batch dedicados, com um fallback em disco:

• Fallback em disco. Se o ClickHouse estiver inacessivel, cada worker grava os batches pendentes em um arquivo JSONL local de fallback (um por sink). Suas requisicoes continuam fluindo — observabilidade nunca fica no caminho critico.
• Rotacao com limite. Os arquivos de fallback sao limitados a 100 MiB e rotacionados em tres geracoes (.jsonl, .jsonl.1, .jsonl.2), entao uma interrupcao prolongada nao pode esgotar o disco. Geracoes mais antigas sao descartadas conforme a rotacao avanca.
• Replay automatico na recuperacao. Uma tarefa em background monitora a disponibilidade do ClickHouse. Quando a conectividade volta, o worker le os arquivos de fallback pendentes, reenvia em batches e apaga cada arquivo apenas apos a insercao ser confirmada.
• Replay seguro em concorrencia. Um arquivo de lock .replaying evita que multiplas instancias do gateway reinsiram as mesmas linhas durante o replay.

Isso se aplica a logs de requisicao, eventos de circuit breaker e spans distribuidos. Se voce roda uma implantacao multi-regiao e seu store de analytics sofre uma queda breve, voce vera os logs voltarem a chegar conforme o replay conclui — sem perder a janela inteira.

Retencao e Desempenho

Os logs sao retidos de acordo com a politica de retencao de dados do seu plano. Consultas sobre milhoes de registros retornam em segundos, para que voce possa buscar e filtrar sem esperar.

Para aplicacoes de alto volume, o Floopy agrega metricas (custo, uso de tokens, percentis de latencia) em rollups pre-computados que alimentam os graficos do dashboard sem escanear logs brutos.