all_logger

🇧🇷 Português | 🇺🇸 English

pub package CI license: MIT

Logging extensível em Dart puro, com níveis, filtros, printers e outputs combináveis. O pipeline separado mantém o logging testável sem acoplar o núcleo ao Flutter.

all_logger hero

Por que usar

Logs úteis precisam ser filtrados, formatados e enviados ao destino certo sem espalhar decisões de ambiente pelo código. all_logger separa essas etapas em um pipeline pequeno, permitindo trocar console por DevTools, memória ou um adapter próprio sem alterar as chamadas de log da aplicação.

  • Uma API consistente para Flutter, CLI, servidor e bibliotecas Dart.
  • Verbosidade controlada por ambiente e nível mínimo.
  • Formatação independente do destino.
  • Um evento pode seguir para vários outputs simultaneamente.
  • Erro e stack trace preservados no registro.
  • Testes determinísticos com captura em memória.
  • Dart puro e zero dependências de runtime.

Recursos

  • Níveis trace, debug, info, warning, error e fatal.
  • Release bloqueado por padrão, com ativação explícita quando necessária.
  • Filtros para desenvolvimento, produção, todos ou nenhum registro.
  • BrSimplePrinter e BrPrettyPrinter com ícones por padrão.
  • BrLogTheme para override de cores ANSI e ícones por nível.
  • Outputs para console, dart:developer, memória e múltiplos destinos.
  • Registros com mensagem, tag, horário, erro e stack trace.

Guia rápido da API

Necessidade API
Registrar eventos trace, debug, info, warning, error, fatal
Tudo fora de release e nenhum log em release BrDevelopmentFilter padrão
Ativar release conscientemente allowInRelease: true ou BrProductionFilter
Definir um nível mínimo fixo BrProductionFilter
Habilitar ou silenciar completamente BrAllFilter, BrNullFilter
Saída legível no terminal BrPrettyPrinter + BrPrintOutput
Linha simples para CI, arquivo ou DevTools BrSimplePrinter
Integrar com Flutter DevTools BrDeveloperOutput
Inspecionar logs em testes BrMemoryOutput
Enviar para vários destinos BrMultiOutput
Integrar arquivo, rede ou telemetria implemente BrLogOutput

Instalação

dependencies:
  all_logger: ^1.0.1

Exemplos de uso real

Configuração mínima

import 'package:all_logger/all_logger.dart';

final log = BrLogger(tag: 'Auth');
log.info('login concluído');
log.warning('sessão próxima do vencimento');
log.dispose();

Pipeline de produção com múltiplos destinos

final memory = BrMemoryOutput();
final log = BrLogger(
  tag: 'Checkout',
  filter: const BrProductionFilter(minLevel: BrLogLevel.warning),
  printer: const BrSimplePrinter(showTime: true),
  output: BrMultiOutput([
    const BrDeveloperOutput(),
    memory,
  ]),
);

log.info('pedido recebido'); // descartado pelo filtro
log.warning('gateway com latência elevada');

O filtro roda antes da formatação e do output, evitando trabalho para eventos descartados.

Erros com contexto de diagnóstico

try {
  await repository.confirmOrder(orderId);
} catch (error, stackTrace) {
  log.error(
    'falha ao confirmar pedido',
    error: error,
    stackTrace: stackTrace,
  );
}

A mensagem deve descrever a operação; o objeto de erro e o stack trace ficam em campos próprios do BrLogRecord.

Testes sem depender do console

final output = BrMemoryOutput(maxRecords: 20);
final log = BrLogger(
  tag: 'Auth',
  filter: const BrAllFilter(),
  printer: const BrSimplePrinter(showTime: false),
  output: output,
);

log.warning('sessão expirada');

expect(output.records.single.level, BrLogLevel.warning);
expect(output.records.single.message, 'sessão expirada');

maxRecords deve ser maior que zero. Limites iguais ou menores que zero são rejeitados no construtor com ArgumentError.

Adapters próprios

Implemente BrLogFilter para regras de seleção, BrLogPrinter para JSON ou outro formato e BrLogOutput para arquivo, observabilidade ou transporte. O núcleo permanece independente do fornecedor escolhido.

Cores e ícones

Ícones vêm ligados por padrão nos dois printers. Cores ANSI vêm ligadas no BrPrettyPrinter e podem ser sobrescritas por nível:

const terminalTheme = BrLogTheme(
  infoColor: BrAnsiColor.cyan,
  warningColor: '\x1B[38;5;208m',
  errorIcon: '⛔',
  fatalIcon: '☠',
);

final log = BrLogger(
  printer: const BrPrettyPrinter(
    theme: terminalTheme,
    useColors: true,
    showIcons: true,
  ),
  output: const BrPrintOutput(),
);

No Terminal do macOS, use BrPrintOutput com BrPrettyPrinter. O BrDeveloperOutput envia eventos para dart:developer; Xcode, DevTools ou a IDE decidem a apresentação e podem ignorar ANSI. Para esses destinos, prefira BrSimplePrinter: os ícones continuam visíveis mesmo sem cores.

Release desligado por padrão

BrLogger() usa BrDevelopmentFilter, que aceita todos os níveis fora de product/release e bloqueia todos em release. Para liberar conscientemente:

final log = BrLogger(
  filter: const BrDevelopmentFilter(
    allowInRelease: true,
    minLevelProduction: BrLogLevel.error,
  ),
);

Escolher BrProductionFilter ou BrAllFilter também é uma ativação explícita. O filtro roda antes do printer e do output. Como Dart avalia argumentos antes da chamada, não construa mensagens sensíveis ou caras supondo que o filtro evitará essa avaliação.

Quando usar

Use all_logger quando aplicações ou bibliotecas precisam de logging leve, testável e configurável sem adotar um framework de observabilidade completo. Ele funciona especialmente bem como porta de logging da arquitetura: o código produz registros e a composição define política, formato e destino.

O pacote não remove dados sensíveis, rotaciona arquivos, persiste logs ou envia telemetria por conta própria. Nunca registre senhas, tokens, chaves ou documentos completos. Outputs customizados possuem uma API síncrona; não faça I/O lento diretamente em write — use buffering ou encaminhamento adequado no adapter. Chame dispose para liberar os recursos do output.

Documentação

Consulte a referência, a arquitetura, o guia de contribuição e a política de segurança. Licença MIT.

Libraries

all_logger
Logging extensível em Dart puro.