Melhores práticas de erros e logs
Equilibre observabilidade com disciplina de CU: códigos de erro estáveis para clientes, logs controlados para engenheiros, eventos estruturados para indexadores.
Como usar esta lista
- Publique IDL/errors.json em todo release.
- Simule principais caminhos de falha no CI.
- Controle logs verbosos com features.
A - Erros
- Retorne
ProgramError- nunca faça panic em input controlado pelo usuário. Códigos de falha limpos. - Mantenha códigos de erro customizados estáveis; apenas append de novas variantes. Compatibilidade com clientes.
- Publique tabelas de erro legíveis por máquina com versão do programa. Precisão de decode.
- Mapeie erros de CPI deliberadamente quando UX precisa de mensagens por programa. Responsabilidade clara.
- Teste unitariamente todo branch de erro. Cobertura de modos de falha.
B - Logs
- Controle
msg!com features em builds de release. Controle de CU. - Nunca logue segredos, seeds ou dados privados do usuário. Chain pública.
- Use tokens de log prefixados para grep (
MYAPP:step). Eficiência de ops. - Evite logs dentro de loops e cadeias CPI. Multiplicação de CU.
- Prefira eventos para observabilidade destinada a indexadores. Pipelines estruturados.
C - Operações
- Simule antes do envio em dApps; mostre erros decodificados. UX + economia de suporte.
- Arquive IDL + error JSON por hash de deploy. Viagem no tempo de incidentes.
- Adicione testes LiteSVM assertando códigos de erro específicos. Segurança de regressão.
- Documente playbook de debug para equipe de suporte. Resolução mais rápida.
- Remova logs de debug temporários antes da tag mainnet. Custo e ruído.
FAQs
Erros vs eventos?
Erros falham; eventos observam principalmente caminhos de sucesso.
Anchor é suficiente?
Ainda controle logs e publique IDL.
Logs Pinocchio?
Mesmos custos de syscall.
i18n?
Mapeie códigos off-chain.
Monitoramento?
Indexe eventos, não logs spam brutos.
Orçamento CU?
Logs afetam landing em ix apertada.
Programa imutável?
Tabela de erros congelada - planeje códigos.
Surfpool?
Padrão de debug.
Kit 7.0.0?
Padrão de decode no cliente.
Segurança?
Erros podem vazar dicas - texto genérico ao usuário.
Compliance?
Sem PII nos logs.
CI?
Falhe em novos caminhos de panic.
Relacionados
- Noções básicas de tratamento de erros - Intro
- Logging com msg! - Logs conscientes de CU
- Error Code & require! - Stack Anchor
Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.