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

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.