Logs Customizados

Registre mensagens próprias nos logs oficiais de execução com bm.bmLog() e acompanhe-as na Trilha de Auditoria, separadas dos logs gerais do sistema.

O que são logs customizados

Durante a execução, o browserMate grava automaticamente os logs gerais: início e fim de cada etapa, erros e desvios de rota. Os logs customizados são as mensagens que você registra dentro das etapas de Regra Customizada com bm.bmLog().

Use-os para registrar o que só o seu código sabe: quantos itens foram processados, qual documento está sendo tratado, por que uma ramificação foi tomada.

Como gravar

bm.bmLog('Iniciando processamento do lote');
bm.bmLog('Item atual: ' + bm.get('{item_atual}'));
bm.bmLog('[OK] 42 registros gravados na planilha');

bm.bmLog('Iniciando processamento do lote')
bm.bmLog(f'Item atual: {bm.get("{item_atual}")}')
bm.bmLog('[FALHA] documento sem CNPJ, pulado')

Em scripts inline, o objeto bm já está disponível. Em projetos ZIP, importe o módulo no entry point (const bm = require('./browsermate') ou import browsermate as bm).

Convenção de ícones {application_*}

Toda mensagem de log da plataforma carrega um token de classificação no formato {application_*}. É ele que define o ícone e a severidade exibidos na coluna Tipo da Trilha de Auditoria. Os logs do sistema já vêm classificados; nos seus logs customizados, inicie a mensagem com o token para classificá-la:

// Node.js
bm.bmLog('{application_info} Processando lote de 42 itens');
bm.bmLog('{application_warn} Documento sem CNPJ, pulado');
bm.bmLog('{application_error} Falha ao consultar a API do ERP');
bm.bmLog('{application_success} Lote gravado com sucesso');

# Python
bm.bmLog('{application_info} Iniciando conciliação')
bm.bmLog('{application_rule} Regra de desconto aplicada')

O painel Scripts de Sessão da etapa de Regra Customizada tem um snippet pronto, o Marcadores de log (referência), que cola essa mesma lista como comentário direto no editor, para consulta sem sair da etapa.

O resultado do done()

Além das mensagens de log, o primeiro parâmetro de bm.done(result, updates) também aparece no log da execução. Use-o como um resumo do que o script fez:

bm.done('Processados 42 de 45 itens (3 pulados por CNPJ inválido)', {
  '{processados}': '42',
  '{pulados}':     '3'
});

Onde visualizar

Todo bm.bmLog() vira uma mensagem na Trilha de Auditoria. Não fica preso ao console de Debug, é o mesmo destino oficial dos logs de produção:

1. No Menu, acesse Meus Insights e abra a aba Trilha de Auditoria.
2. Selecione o período e o processo desejado.
3. No painel Logs e Mensagens, use o filtro Customizados para ver apenas as mensagens gravadas com bm.bmLog(), ou Gerais para os logs do sistema, ou Todos.
4. Filtre também por severidade, instância, usuário ou texto da mensagem.

Veja a referência completa da tela em Trilha de Auditoria.

Boas práticas

• Prefixos padronizados. Use [OK], [FALHA], [AVISO] no início das mensagens, o que facilita buscar na Trilha de Auditoria.
• Logue identificadores, não conteúdo. Registre o número do documento ou o ID do registro, não o conteúdo completo, porque logs extensos dificultam a leitura.
• Nunca logue segredos. Senhas, tokens e API Keys não devem aparecer em bm.bmLog(). Para preencher um campo com credencial sem que ela apareça em log, use o Cofre de Senhas, com o Objeto de Tela em Valor do Cofre (veja Mapeamento de Dados).
• Dado pessoal também. Valor de uma variável marcada como Dado sensível é escondido nestas mensagens quando já foi registrado antes do script rodar, mas o que o seu próprio código cria não é marcado sozinho. Registre identificadores, não o dado em si.
• Logue decisões. Ao ramificar dentro do código (if/else), registre qual caminho foi tomado e por quê, o que economiza tempo de investigação depois.
• Uma mensagem por evento. Evite concatenar dezenas de linhas numa única chamada; várias chamadas curtas dão granularidade de timestamp.