#Logger

O NocoBase oferece um sistema de logs de alta performance baseado no pino. Em qualquer lugar onde você tiver acesso ao context, você pode obter uma instância do logger através de ctx.logger para registrar logs importantes durante a execução de um plugin ou do sistema.

#Uso Básico

// Registra erros fatais (ex: falha na inicialização)
ctx.logger.fatal('Falha na inicialização do aplicativo', { error });

// Registra erros gerais (ex: erros em requisições de API)
ctx.logger.error('Falha ao carregar dados', { status, message });

// Registra avisos (ex: riscos de performance ou operações inesperadas do usuário)
ctx.logger.warn('O formulário atual contém alterações não salvas');

// Registra informações gerais de execução (ex: componente carregado)
ctx.logger.info('Componente de perfil do usuário carregado');

// Registra informações de depuração (ex: mudanças de estado)
ctx.logger.debug('Estado atual do usuário', { user });

// Registra informações detalhadas de rastreamento (ex: fluxo de renderização)
ctx.logger.trace('Componente renderizado', { component: 'UserProfile' });

Esses métodos correspondem a diferentes níveis de log (do mais alto para o mais baixo):

#Formato do Log

Cada saída de log está no formato JSON estruturado, contendo os seguintes campos por padrão:

Saída de exemplo:

{
  "level": 30,
  "time": 1730540153064,
  "pid": 12765,
  "hostname": "nocobase.local",
  "msg": "HelloModel rendered",
  "a": "a"
}

#Vinculação de Contexto

ctx.logger injeta automaticamente informações de contexto, como o plugin atual, módulo ou origem da requisição, permitindo que os logs rastreiem a fonte com mais precisão.

plugin.context.logger.info('Plugin inicializado');
model.context.logger.error('Falha na validação do modelo', { model: 'User' });

Saída de exemplo (com contexto):

{
  "level": 30,
  "msg": "Plugin initialized",
  "plugin": "plugin-audit-trail"
}

#Logger Personalizado

Você pode criar instâncias de logger personalizadas em plugins, herdando ou estendendo as configurações padrão:

const logger = ctx.logger.child({ module: 'MyPlugin' });
logger.info('Submódulo iniciado');

Loggers filhos herdam a configuração do logger principal e anexam automaticamente o contexto.

#Hierarquia de Níveis de Log

Os níveis de log do Pino seguem uma definição numérica do mais alto para o mais baixo, onde números menores indicam menor prioridade. Abaixo está a tabela completa da hierarquia de níveis de log:

O Pino só exibirá logs maiores ou iguais à configuração de level atual. Por exemplo, quando o nível de log for info, os logs de debug e trace serão ignorados.

#Boas Práticas no Desenvolvimento de Plugins

1. Use o Logger de Contexto Use ctx.logger em contextos de plugin, modelo ou aplicativo para que as informações de origem sejam automaticamente incluídas.

2. Diferencie os Níveis de Log

   • Use error para registrar exceções de negócio
   • Use info para registrar mudanças de status
   • Use debug para registrar informações de depuração de desenvolvimento

3. Evite Logs Excessivos Especialmente nos níveis debug e trace, é recomendado ativá-los apenas em ambientes de desenvolvimento.

4. Use Dados Estruturados Passe parâmetros de objeto em vez de concatenar strings, o que ajuda na análise e filtragem de logs.

Ao seguir essas práticas, os desenvolvedores podem rastrear a execução de plugins com mais eficiência, solucionar problemas e manter um sistema de logs estruturado e extensível.