pagodera/docs/PRISMA_QUERY_LOGS.md

📊 Prisma Query Logs - Explicação Completa

🔍 O que são os logs prisma:query?

Os logs prisma:query são queries SQL que o Prisma executa automaticamente no banco de dados PostgreSQL. Eles aparecem no console durante o desenvolvimento para ajudar você a:

1. Debugar - Ver exatamente quais queries estão sendo executadas
2. Otimizar - Identificar queries lentas ou desnecessárias
3. Entender - Compreender o que o Prisma está fazendo "por baixo dos panos"

---

⚙️ Configuração Atual

No arquivo lib/prisma/app.ts, o Prisma está configurado assim:

export const prisma = new PrismaClient({
  log:
    process.env.NODE_ENV === "development"
      ? ["query", "error", "warn"]  // ← Loga queries em desenvolvimento
      : ["error"],                  // ← Apenas erros em produção
});

Isso significa:

• ✅ Em desenvolvimento: Mostra todas as queries SQL
• ✅ Em produção: Apenas mostra erros (não mostra queries)

---

📝 Análise dos Logs do Seu Terminal

1. INSERT de Telemetria (Linhas 24-26, 58-59, 93-94)

INSERT INTO "public"."telemetry_events" 
  ("event_type","ad_id","user_id","session_id","metadata","timestamp") 
VALUES ($1,$2,$3,$4,$5,$6) 
RETURNING ...

O que é:

• Registra eventos de telemetria (cliques, visualizações, etc.)
• Executado quando o usuário interage com a página

Por que aparece:

• O sistema de telemetria está ativo e registrando eventos

---

2. SELECT de Listings (Linhas 35-36, 79-80)

SELECT COUNT(*) AS "_count$_all" 
FROM (SELECT "public"."listings"."listing_id" 
      FROM "public"."listings" 
      WHERE "public"."listings"."listing_status" = $1 
      OFFSET $2) AS "sub"

O que é:

• Conta quantos anúncios ativos existem
• Usado para paginação

E depois:

SELECT "public"."listings"."listing_id", 
       "public"."listings"."seller_id",
       "public"."listings"."item_id",
       -- ... todos os campos ...
FROM "public"."listings" 
WHERE "public"."listings"."listing_status" = $1 
ORDER BY "public"."listings"."created_at" DESC 
LIMIT $2 OFFSET $3

O que é:

• Busca os anúncios ativos com paginação
• Ordena por data de criação (mais recentes primeiro)
• Limita a 20 resultados por página

Por que aparece:

• A página do marketplace (/en/market) está carregando
• Está buscando anúncios para exibir

---

3. SELECT de Characters (Linhas 37, 81)

SELECT "public"."user_characters"."character_id", 
       "public"."user_characters"."user_id",
       "public"."user_characters"."character_name",
       "public"."user_characters"."server_name",
       "public"."user_characters"."is_main",
       "public"."user_characters"."verified",
       "public"."user_characters"."created_at" 
FROM "public"."user_characters" 
WHERE ("public"."user_characters"."user_id" = $1 
       AND "public"."user_characters"."server_name" = $2 
       AND "public"."user_characters"."is_main" = $3) 
LIMIT $4 OFFSET $5

O que é:

• Busca o personagem principal do vendedor
• Usado para exibir o nome do personagem nos cards de anúncio

Por que aparece:

• Para cada anúncio, busca o nome do personagem do vendedor
• Isso acontece porque implementamos a busca de seller_character_name

---

4. SELECT de Servers (Linha 66)

SELECT "public"."servers"."server_id", 
       "public"."servers"."server_name",
       -- ... outros campos ...
FROM "public"."servers" 
WHERE "public"."servers"."is_active" = $1 
ORDER BY "public"."servers"."server_name" ASC 
OFFSET $2

O que é:

• Busca todos os servidores ativos
• Usado para popular o filtro de servidores no marketplace

Por que aparece:

• O componente de filtros está carregando a lista de servidores

---

5. BEGIN / COMMIT (Linhas 23, 27, 57, 60, 92, 95)

BEGIN
-- ... queries ...
COMMIT

O que é:

• Transações do banco de dados
• Garante que múltiplas operações sejam executadas atomicamente
• Se uma falhar, todas são revertidas (ROLLBACK)

Por que aparece:

• Operações que precisam de atomicidade (ex: inserir múltiplos eventos de telemetria em batch)

---

🎯 Por que isso é útil?

✅ Benefícios:

1. Debugging:

   • Ver exatamente quais queries estão sendo executadas
   • Identificar queries N+1 (muitas queries desnecessárias)
   • Verificar se os índices estão sendo usados

2. Performance:

   • Identificar queries lentas
   • Ver quantas queries estão sendo executadas
   • Otimizar queries que são executadas repetidamente

3. Entendimento:

   • Aprender como o Prisma traduz suas operações para SQL
   • Ver como os relacionamentos são resolvidos

---

⚙️ Como Controlar os Logs

Opção 1: Desabilitar completamente (não recomendado em dev)

// lib/prisma/app.ts
export const prisma = new PrismaClient({
  log: ["error"], // Apenas erros
});

Opção 2: Apenas erros e warnings

export const prisma = new PrismaClient({
  log: ["error", "warn"],
});

Opção 3: Logs mais detalhados (com informações de tempo)

export const prisma = new PrismaClient({
  log: [
    { level: "query", emit: "event" },
    { level: "error", emit: "stdout" },
    { level: "warn", emit: "stdout" },
  ],
});

Opção 4: Manter como está (recomendado)

// Atual (já está assim)
export const prisma = new PrismaClient({
  log:
    process.env.NODE_ENV === "development"
      ? ["query", "error", "warn"]  // ← Bom para desenvolvimento
      : ["error"],                   // ← Otimizado para produção
});

✅ Recomendação: Manter como está! Os logs são úteis em desenvolvimento e não aparecem em produção.

---

🔍 Análise de Performance dos Seus Logs

Queries que aparecem frequentemente:

1. SELECT listings (2 queries):

   • Uma para contar total
   • Uma para buscar os itens
   • Status: ✅ Normal (paginação requer ambas)

2. SELECT user_characters (1 por anúncio):

   • Busca o personagem do vendedor
   • Status: ⚠️ Potencial otimização
   • Sugestão: Já está otimizado com Map para evitar queries duplicadas

3. INSERT telemetry_events (em batch):

   • Múltiplos eventos inseridos em uma transação
   • Status: ✅ Otimizado (usa transação)

---

📊 Níveis de Log do Prisma

O Prisma suporta diferentes níveis de log:

log: [
  "query",    // Todas as queries SQL
  "info",     // Informações gerais
  "warn",     // Avisos
  "error",    // Erros
]

Ou com eventos:

log: [
  { level: "query", emit: "event" },  // Evento customizado
  { level: "error", emit: "stdout" }, // Console padrão
]

---

🎯 Conclusão

Os logs prisma:query são:

• ✅ Normais - Esperados em desenvolvimento
• ✅ Úteis - Ajudam a debugar e otimizar
• ✅ Automáticos - Não afetam performance
• ✅ Desabilitados em produção - Não aparecem em produção

Você deve:

• ✅ Manter os logs em desenvolvimento
• ✅ Usar para identificar problemas de performance
• ✅ Ignorar se não estiver debuggando (são apenas informativos)

---

🔗 Referências

• Prisma Logging Documentation
• Prisma Query Performance