Debug Log no Salesforce: decifrando Category, Level e Events

Debug Log no Salesforce: decifrando o Category, o Level e os Events

E aí, dev! Seja bem-vindo(a).

Se você já abriu um Debug Log e pensou "o que é esse monte de texto?", relaxa. Todo mundo já passou por isso. Esse guia foi feito pra ser aquele papo que você queria ter tido com alguém mais experiente no seu primeiro mês de Salesforce, mas que ninguém sentou pra te explicar. A ideia é simples: a gente vai destrinchar as três peças que controlam o Debug Log (Category, Level e Events), com calma, com prints de tela real, e sem enrolação.

Se você já manja do assunto, fica também. Sempre tem aquele detalhe que escapou.

Ah, e uma dica rápida antes de começar: se a sua org está em outro idioma, muda pra inglês. Já vi muito iniciante procurando uma opção que simplesmente não acha porque o nome na tela está traduzido e ele não consegue fazer a ponte com o tutorial em inglês. Setup > Language & Time Zone > Language, troca, e depois volta se quiser.

Bora?

Glossário: leitura obrigatória antes de seguir

Não pula essa parte. Todo termo abaixo aparece no artigo, e se um ficar solto, o resto não cola. Mesmo que você já saiba o que é SOQL ou o que faz um trigger, passa o olho. Às vezes a ficha só cai na segunda vez que alguém explica.

Org - o ambiente Salesforce da sua empresa. Pensa num apartamento: seus móveis (dados), seus moradores (usuários), sua fiação (código). "Na minha org" = "no Salesforce da minha empresa". Você pode ter várias: produção (onde o negócio roda de verdade), sandbox (onde você quebra tudo sem culpa), scratch org (um apê temporário que some depois de uns dias), dev org (um grátis que a Salesforce te dá pra estudar).

Transação - tudo que rola entre o clique do usuário e a resposta do Salesforce. O usuário clica em "Salvar" e nesse instante o Salesforce pode rodar um trigger, disparar dois flows, avaliar três validation rules, executar cinco queries e chamar uma API externa. Tudo isso junto, empilhado, é uma transação. Tipo uma fila de dominós: o clique derruba o primeiro, e o Salesforce só responde quando o último cai (ou quando um deles tomba pro lado errado e tudo para). O Debug Log registra a fila inteira, dominó por dominó.

Apex - a linguagem de programação do Salesforce. Sintaxe parecida com Java. É nela que você escreve classes, triggers, testes e lógica de negócio que o declarativo sozinho não resolve.

Trigger - código Apex que roda sozinho quando algo acontece com um registro: criou, atualizou, deletou, restaurou da lixeira. Você não chama trigger na mão. Ele é tipo sensor de presença de corredor: você passou, a luz acendeu. Não pediu. Não apertou nada. Mas o sensor estava ali, e pronto.

SOQL (Salesforce Object Query Language) - a linguagem que você usa pra buscar registros no banco de dados do Salesforce. Se você já escreveu SQL na vida, vai reconhecer quase tudo. A diferença é que SOQL tem umas regras extras (tipo não poder fazer SELECT *) que no começo irritam, mas existem por causa dos governor limits. Exemplo: SELECT Name FROM Account WHERE Industry = 'Energy'.

SOSL (Salesforce Object Search Language) - primo menos famoso do SOQL. Enquanto o SOQL busca registros de um objeto com condições específicas, o SOSL faz busca de texto livre em vários objetos ao mesmo tempo. Tipo um Ctrl+F no banco inteiro. Menos comum no dia a dia, mas aparece nos logs.

DML (Data Manipulation Language) - operações que escrevem no banco de dados. SOQL pergunta, DML executa: insert (criar), update (alterar), delete (apagar), upsert (criar ou alterar, o Salesforce decide), undelete (tirar da lixeira). Cada DML que você executa consome um pedaço da cota da transação.

Governor Limits - o Salesforce divide servidor com muita gente (multi-tenant, tem uma entrada sobre isso aqui embaixo). Pra ninguém monopolizar os recursos, existem limites rígidos por transação: 100 queries SOQL, 150 operações DML, 10 segundos de CPU, 6 MB de heap. Passou do limite? A transação morre com System.LimitException, sem negociação, sem "vai, só mais uma queryzinha". É disjuntor: disparou, cortou.

Flow - automação visual montada no Flow Builder, sem código. Arrastar caixinha, ligar setinha, configurar condição. Pode rodar quando um registro é salvo (Record-Triggered), quando o usuário clica num botão de tela (Screen Flow), em horário agendado (Scheduled), entre outros. Nos logs, Flows aparecem sob a categoria Workflow. Sim, o nome confunde. Não, não tem como mudar.

Validation Rule - regra declarativa que barra a gravação de um registro quando uma condição é verdadeira. Exemplo clássico: impedir desconto acima de 30%. Se a regra bloqueia, no log aparece VALIDATION_FAIL dizendo exatamente qual regra barrou e por quê. Pensa no segurança da porta do banco de dados: ele olha o registro, confere os critérios, e decide se entra ou volta.

Callout - chamada HTTP que o Salesforce faz pra um sistema externo (REST, SOAP, o que for). O que foi enviado e o que voltou ficam registrados nos logs, no canal Callouts.

System.debug() - o console.log() do Salesforce. O print(). É o comando Apex que deixa um recadinho no Debug Log. Tem um porém que pega todo mundo de surpresa: ele só aparece se a categoria Apex Code estiver configurada em DEBUG ou acima. Se estiver abaixo, seu System.debug() está lá no código, executando normalmente, mas a gravação simplesmente não pega aquele canal. Você gritou, a sala estava com o microfone desligado.

Trace Flag - o botão de "gravar" do Debug Log. Sem ele ligado, nenhum log é gerado. O Trace Flag diz pro Salesforce três coisas: quem monitorar (usuário, processo automático), como monitorar (qual Debug Level usar) e por quanto tempo (data de início e expiração). Se você está olhando pra tela de Debug Logs e ela está vazia, a primeira pergunta é: "tem Trace Flag ativo?". Em 90% dos casos, não tem.

Debug Level - template de configuração que define quanto de cada área do sistema você quer registrar. Funciona como um equalizador de som: você sobe o grave (Database) no talo, deixa o agudo (Visualforce) no mudo, e ajusta o meio (Apex Code) pro que faz sentido naquele momento. O bom é que depois de montado, ele é reutilizável. Salva uma vez, usa em quantos Trace Flags quiser.

Truncation (truncamento) - todo Debug Log tem um limite de 20 MB de texto puro. Parece bastante até você ligar tudo em FINEST e ver 20 MB sumir em meio segundo. Quando estoura o teto, o Salesforce pega uma tesoura e corta pedaços do meio do log pra preservar o começo e o final. O problema é que a causa raiz do bug muitas vezes mora justo no meio. Você fica com a cena do crime e o desfecho, mas perde o momento exato em que tudo deu errado.

Multi-tenant - a arquitetura onde várias empresas dividem os mesmos servidores físicos. Cada empresa tem sua org separada, com seus dados e seu código, mas CPU, memória e banco de dados são compartilhados. Se uma org resolve rodar 47 batch jobs ao mesmo tempo sem otimizar nada, o impacto respinga nas vizinhas. É por isso que governor limits existem: proteger o prédio inteiro de um único morador bagunceiro.

Glossário lido? Então a gente fala a mesma língua agora. Bora pro artigo.

Seu código quebrou. Ou pior: não quebrou de vez, só está fazendo alguma coisa esquisita que ninguém consegue explicar. Você abre o Debug Log pra investigar e... duas coisas podem acontecer.

Ou ele vem completamente vazio, e você fica olhando pra tela sem entender por que nada foi registrado. Ou ele vem gigante — milhares de linhas, 15 MB de texto — e o erro que você procura está enterrado em algum lugar no meio daquilo tudo.

Os dois problemas têm a mesma raiz: ninguém te explicou direito como configurar o que entra e o que fica de fora do log. E é isso que a gente vai resolver aqui, com calma, usando uma analogia que vai grudar na sua cabeça.

O analogão: uma central de rádio num set de filmagem

Imagina um set de filmagem grande. Tem gente em vários departamentos diferentes — câmera, som, figurino, elétrica — e cada departamento se comunica pelo próprio canal de walkie-talkie. Na central de rádio, o diretor de produção tem um painel na frente dele com um botão pra cada canal.

Esse painel tem três coisas que você, como diretor de produção, controla:

Qual canal você quer monitorar — câmera, som, figurino? Isso é o Category.
O volume de cada canal — quer ouvir só quando alguém grita "socorro", ou quer ouvir cada respiração? Isso é o Level.
O que realmente sai da caixinha de som quando alguém fala naquele canal, naquele volume — isso são os Events.

No Salesforce, é exatamente essa mesma lógica. O Debug Log é o painel de rádio, e cada transação que roda no sistema é como um dia inteiro de filmagem cheio de gente falando em canais diferentes ao mesmo tempo. Se você não escolher os canais certos e o volume certo, ou não escuta nada relevante, ou fica surdo de tanto ruído.

Vamos abrir os três botões desse painel, um de cada vez.

Category: os canais de rádio

Cada Category representa uma área diferente do motor do Salesforce — um "departamento" que fala a própria língua e faz o próprio tipo de trabalho. Você liga ou desliga o canal de cada um separadamente.

Essa é a lista real, na mesma ordem em que ela aparece na tela de configuração:

Database — o canal de quem mexe no banco de dados. Toda consulta (SOQL, SOSL) e toda escrita (insert, update, delete, upsert) passa por aqui. Se o seu bug é sobre "por que essa query não trouxe o registro que eu esperava", é nesse canal que a resposta está.

Workflow — o canal da automação sem código. Apesar do nome parecer coisa antiga, esse canal cobre bem mais do que as antigas Workflow Rules: ele também registra Flows, Process Builder e Approval Processes. Se uma automação declarativa fez (ou deixou de fazer) alguma coisa, é aqui que você vai procurar.

Validation — o canal do "não, essa gravação não vai passar". Registra qual validation rule foi avaliada, e se ela bloqueou ou liberou o registro.

Callouts — o canal de quem fala com o mundo lá fora. Toda chamada HTTP pra uma API externa aparece aqui: o que foi enviado, e o que voltou.

Apex Code — o canal principal do seu próprio código. Classes, triggers, blocos de Apex anônimo. Se a lógica que você escreveu quebrou, é praticamente certo que a resposta está neste canal.

Apex Profiling — o canal que não conta o que aconteceu, conta quanto custou. Tempo de CPU, tamanho de heap, quantas queries e DMLs você já gastou. É o canal que te avisa quando você está perto de estourar um governor limit.

Visualforce — o canal das páginas Visualforce antigas. Se o seu projeto é 100% Lightning/LWC, você praticamente nunca vai precisar ligar esse canal.

System — o canal das operações internas da própria plataforma. Cuidado com esse nome — ele engana bastante gente (a gente chega nesse ponto daqui a pouco, vale a leitura).

Wave — o canal do CRM Analytics (antigo Tableau CRM). Queries e processamento analítico daquele mundo.

Nba — o canal do Next Best Action, as recomendações inteligentes da plataforma.

Access — um canal mais novo e menos conhecido, ligado a verificações de acesso/segurança. Você raramente vai precisar dele no dia a dia, mas ele existe e aparece na tela de configuração.

No seu dia a dia como Salesforce dev, os canais que você mais vai abrir são Apex Code, Database e System. O resto você liga só quando a investigação realmente pedir.

Aqui está a tela de configuração de verdade, pra você ver os canais e os eventos de cada um lado a lado:

Tela real de configuração de Debug Level, mostrando cada categoria (Database, Workflow, Validation, Callouts, Apex Code, Apex Profiling, Visualforce, System, Wave, Nba, Access), o nível escolhido para cada uma e a lista de eventos que cada categoria pode gerar

Repara em uma coisa nessa tela: a coluna Events, à direita, já entrega um baita spoiler do que vem na próxima seção.

Level: o volume de cada canal

Beleza, você escolheu os canais que quer monitorar. Agora vem a segunda pergunta: quanto de cada canal você quer realmente ouvir?

É o volume do walkie-talkie. Do "mudo total" até "eu escuto até o som da respiração entre uma palavra e outra". A escada de volume, do mais baixo pro mais alto, é essa:

NONE → ERROR → WARN → INFO → DEBUG → FINE → FINER → FINEST

E o detalhe mais importante de todos: cada degrau inclui tudo que o degrau anterior já registrava, mais coisa nova. É uma escada cumulativa, não uma escolha exclusiva.

NONE — canal mudo. Nada é registrado ali.
ERROR — só o grito de socorro. Exceções não tratadas, falhas fatais. Se ninguém gritou, o canal fica em silêncio.
WARN — grito de socorro + avisos. Coisa que não quebrou a execução, mas que o sistema achou estranha.
INFO — os avisos + uma visão geral do fluxo (entradas e saídas dos métodos principais).
DEBUG — é aqui que os seus System.debug() aparecem. Se o canal estiver configurado abaixo de DEBUG, os seus prints simplesmente não existem no log — não é bug, é o volume que está baixo demais pra pegar a sua fala.
FINE — tudo do DEBUG + detalhes que o próprio sistema gera sozinho, como as queries SOQL já com as bind variables resolvidas, e a contagem de linhas de cada DML.
FINER — mais granular ainda: linhas de execução individuais, alocação de heap. O log começa a inchar de tamanho aqui.
FINEST — tudo, literalmente tudo. Cada linha executada, cada valor de variável, stack trace completo. É o volume no talo — e o log cresce rapidíssimo.

Agora o pulo do gato que quase ninguém conta: nem todo canal tem o controle de volume completo. Cada categoria expõe um conjunto diferente de opções no dropdown. Não é um bug da UI, é o Salesforce te dizendo "esse canal não produz eventos nesse nível, então nem adianta selecionar".

Olha o mapa real, tirado direto da tela de configuração:

Category	Níveis disponíveis no dropdown
Database	None, Warn, Info, Fine, Finest
Workflow	None, Error, Warn, Info, Fine, Finer
Validation	None, Info
Callouts	None, Error, Info, Finer, Finest
Apex Code	None, Error, Warn, Info, Debug, Fine, Finer, Finest
Apex Profiling	None, Info, Fine, Finest
Visualforce	None, Info, Fine, Finer
System	None, Info, Debug, Fine
Wave	None, Error, Info, Fine, Finer, Finest
Nba	None, Error, Info, Fine
Access	None, Info, Fine, Finer

Repara em algumas coisas nessa tabela:

Apex Code é o único canal que tem a escada completa de 8 níveis. Faz sentido, é o canal mais rico em eventos e o único onde os seus System.debug() aparecem (que dependem do nível DEBUG pra ficarem visíveis).

Validation é o extremo oposto: só None e Info. Ou você está escutando, ou não está. Sem meio-termo.

E tem um detalhe que resolve aquela confusão clássica: só Apex Code e System expõem o nível Debug no dropdown. Se você quer ver seus System.debug(), o canal que precisa estar em DEBUG é Apex Code, não System.

Na prática, os saltos que mais importam no dia a dia são:

De DEBUG pra FINE: é onde as queries e os DMLs passam a aparecer com detalhe real.
De FINER pra FINEST: é onde o log incha de tamanho — use com moderação e só quando for realmente necessário.

Events: o que realmente sai na caixinha de som

Você escolheu o canal (Category) e o volume (Level). Mas o que efetivamente aparece escrito, linha por linha, dentro do arquivo do log?

São os Events. Cada combinação de canal + volume libera um conjunto específico de eventos — e são eles que carregam a informação de verdade. Se o canal é quem fala e o volume é o quão alto, o evento é a frase exata que sai da caixa de som, com hora marcada.

Alguns dos eventos mais úteis no dia a dia, por canal:

Category	Eventos que valem a pena conhecer	O que eles te contam
Database	`SOQL_EXECUTE_BEGIN` / `SOQL_EXECUTE_END`	Quando uma query começou e terminou — e quantas linhas ela trouxe
Database	`DML_BEGIN` / `DML_END`	Início e fim de um insert/update/delete
Apex Code	`CODE_UNIT_STARTED` / `CODE_UNIT_FINISHED`	Quando um bloco de código (trigger, classe, flow) começou e terminou — dá pra montar o mapa de "quem chamou quem"
Apex Code	`USER_DEBUG`	É onde os seus `System.debug()` aparecem de fato
Apex Code	`EXCEPTION_THROWN`	Uma exceção foi lançada — e onde, exatamente
Apex Profiling	`LIMIT_USAGE` / `CUMULATIVE_LIMIT_USAGE`	Quanto dos governor limits você já consumiu naquele ponto da execução
Workflow	`WF_RULE_EVAL_BEGIN` / `WF_RULE_EVAL_END`	Avaliação de uma workflow rule ou flow
Validation	`VALIDATION_RULE`, `VALIDATION_PASS`, `VALIDATION_FAIL`	Qual regra rodou, e se ela barrou o registro
Callouts	`CALLOUT_REQUEST` / `CALLOUT_RESPONSE`	O que foi enviado pra API externa, e o que voltou

Você não precisa decorar essa lista inteira — e olhando de novo pra tela real lá em cima, dá pra ver que a lista completa de eventos por categoria é bem mais longa do que isso (o Workflow sozinho tem uma quantidade generosa deles). O que importa é entender o princípio: toda linha do seu Debug Log começa com um timestamp e um desses nomes de evento. É isso que te diz o quê, quando, e em que ordem algo aconteceu.

Onde configurar tudo isso, na prática

Beleza, a teoria está aí. Agora vamos abrir a org juntos e montar essa coisa de verdade.

Abre o Setup, vai em Environments > Logs > Debug Logs (ou digita "debug" no Quick Find, que é mais rápido). Você vai cair nessa tela aqui:

Tela de Debug Logs no Setup, mostrando a lista de User Trace Flags com colunas Action, Name, Log Type, Requested By, Start Date, Expiration Date e Debug Level Name, e o botão New

Essa é a central de comando. Na parte de cima ficam os Trace Flags (quem está sendo monitorado agora), e mais embaixo ficam os logs que já foram gerados. Se a lista de cima estiver vazia, é porque ninguém está sendo monitorado. Normal, é o estado padrão.

Pra começar a gravar, clica no botão New na seção User Trace Flags. Vai abrir esse formulário:

Formulário New Trace Flag com campos Traced Entity Type, Traced Entity Name, Start Date, Expiration Date, Debug Level e botão New Debug Level

Parece simples, mas cada campo aqui importa. Vamos por eles.

O primeiro é o Traced Entity Type, uma lista suspensa com cinco opções:

Dropdown de Traced Entity Type mostrando as opções Automated Process, Platform Integration, User, Apex Class e Apex Trigger

User é o que você vai usar 90% das vezes. Seleciona o usuário pelo nome na lupa, e quando essa pessoa executar qualquer transação durante a janela de tempo, o log é gerado.

Automated Process é pra quando o bug acontece de madrugada, sem ninguém logado. Batch jobs, platform events, certos tipos de flow que rodam em background, tudo isso roda sob um usuário interno chamado Automated Process. Se você colocar o Trace Flag no seu próprio usuário tentando pegar um erro de batch, vai ficar olhando pra tela em branco a noite inteira.

Platform Integration é mais raro. Callbacks assíncronos de sistemas externos, Connected Apps, esse tipo de coisa.

Agora, Apex Class e Apex Trigger: aqui mora uma armadilha que pega muita gente. Selecionar uma classe ou trigger no Trace Flag não gera log. Nenhum. Zero. O que ele faz é funcionar como um override de resolução: se já existe um Trace Flag ativo pra um User, e a execução desse User entra naquela classe, o nível de detalhe sobe temporariamente só dentro daquele trecho de código. Quando a execução sai da classe, o nível volta pro que era antes. Mas se não tem nenhum User sendo monitorado em primeiro lugar, o flag de Apex Class é completamente invisível pro sistema. Ele não liga a câmera, ele só muda o zoom de uma câmera que já estava ligada.

Seguindo no formulário: Traced Entity Name é onde você busca pela lupa o usuário, classe ou trigger que acabou de escolher. Start Date e Expiration Date definem a janela. Aqui a regra de ouro: 15 a 30 minutos, não mais. Janela longa em usuário de alto volume gera centenas de logs enormes e pode fazer o Salesforce bloquear a geração de novos Trace Flags pra org inteira.

E o último campo é o Debug Level. Se você já tem um template salvo, busca pela lupa. Se é sua primeira vez (ou quer criar um específico pra essa investigação), clica em New Debug Level e vai abrir essa tela aqui:

Tela de criação de New Debug Level mostrando todas as 11 categorias (Database, Workflow, Validation, Callouts, Apex Code, Apex Profiling, Visualforce, System, Wave, Nba, Access) com seus respectivos dropdowns de nível e a lista completa de eventos por categoria

Reconhece? São exatamente as categorias e os níveis que a gente acabou de discutir. Aqui é onde o painel de rádio toma forma. Você dá um nome pro template (tipo Apex_Debug_Padrao ou Flow_Investigation, só letras, números e underscores), ajusta cada dropdown, salva, e pronto. Esse Debug Level fica guardado e pode ser reaproveitado em qualquer Trace Flag futuro sem precisar reconfigurar nada.

Com o Trace Flag salvo e ativo, vai lá e reproduz o erro. Navega direto pro registro, clica no botão, salva o campo. Sem passeio pela org, sem abrir dashboard, sem checar Chatter. Cada página que você carrega gera ruído no log. Quanto mais limpa a interação, mais fácil de ler o resultado.

Reproduziu? Volta pra tela de Debug Logs, desativa ou deleta o Trace Flag (pra não ficar gerando lixo), e na lista de logs gerados lá embaixo, você vai encontrar o log fresquinho. Pode clicar em View pra olhar direto no navegador, mas a recomendação real é: faz download do arquivo .log e abre no VS Code. O visualizador nativo do Salesforce trunca strings longas só pra caber na tela (sem te avisar), e o navegador trava com arquivos grandes. No VS Code você tem Ctrl+F, syntax highlighting, e consegue navegar sem surpresas.

O fluxo completo, de ponta a ponta:

Setup > Debug Logs > New Trace Flag > escolhe quem + por quanto tempo + qual Debug Level > reproduz o erro > desativa o flag > baixa o .log

Via API, o Trace Flag vive no objeto TraceFlag e o template de configuração no objeto DebugLevel, com campos ApexCode, ApexProfiling, Callout, Database, System, Validation, Visualforce, Workflow, Wave, Nba.

Uma configuração que funciona bem no dia a dia

Para depurar Apex — que é a grande maioria do trabalho de um dev nessa plataforma — essa combinação costuma dar conta do recado:

Categoria	Nível
Apex Code	FINEST
Database	FINEST
System	DEBUG
Apex Profiling	INFO
Todo o resto	NONE

Repara que o segredo aqui não é ligar tudo no talo — é ligar fundo só onde importa, e desligar completamente o que não tem relação com o que você está investigando. Cada canal ligado gera linhas no log, e um Debug Log só pode ter até 20 MB. Se você deixar tudo em FINEST, esse teto estoura rapidinho, e o Salesforce corta o conteúdo mais antigo pra preservar o final da transação — e adivinha onde normalmente mora a causa raiz de um bug? Muitas vezes, bem lá no começo. Justamente a parte que corre risco de ser cortada.

Por isso, mesmo com essa configuração relativamente "pesada" em só dois canais, vale manter a janela do Trace Flag curta — 15 a 30 minutos — e reproduzir o erro logo em seguida, sem deixar o flag ligado o dia inteiro.

Resumindo os três botões do painel

Category = o canal de rádio. Qual área do sistema você quer escutar.
Level = o volume daquele canal. Quanto detalhe você quer receber dali — lembrando que a escada é cumulativa, e nem todo canal tem a escada completa disponível.
Events = a fala que realmente chega até você, com timestamp e nome, contando exatamente o que aconteceu.

Um Debug Log bem configurado te mostra o problema em menos de um minuto. Um Debug Log mal configurado te faz perder a tarde inteira rolando um arquivo de texto gigante, ou olhando pra uma tela em branco. A diferença entre os dois não é sorte — é saber girar esses três botões com intenção.