Winston para JavaScript (Node.js): guia completo com exemplos

O que é Winston e para que serve?

\n\n

Winston é uma biblioteca poderosa e flexível para registro de logs (logging) no ambiente Node.js. Foi criada por Charlie Robbins e é uma das bibliotecas mais populares para logging no ecossistema JavaScript. Winston permite que desenvolvedores registrem mensagens com diferentes níveis de importância (info, warn, error, debug, etc.), configurem formatos de saída (JSON, texto simples, com carimbos de data/hora), e direcionem os logs para diferentes destinos (console, arquivos, bancos de dados, serviços externos).

\n\n

Para que serve o Winston? Em qualquer aplicação séria, o logging não é um luxo, mas uma necessidade. Ele ajuda a:

\n

\n
• Depurar a aplicação: Os logs permitem entender o que estava acontecendo no sistema no momento do erro.
\n
• Monitorar o desempenho: É possível registrar o tempo de execução das requisições e identificar gargalos.
\n
• Analisar o comportamento dos usuários: Os logs ajudam a entender como os usuários interagem com a aplicação.
\n
• Manter um histórico: Todos os eventos podem ser armazenados em arquivos ou bancos de dados para análise posterior.
\n
• Garantir a segurança: Os logs podem registrar ações suspeitas e tentativas de invasão.
\n

\n\n

O Winston resolve essas tarefas de forma elegante e eficiente, fornecendo uma interface unificada para trabalhar com logs.

\n\n

Instalação do Winston

\n\n

A instalação do Winston é feita através do gerenciador de pacotes npm. Abra o terminal na pasta raiz do seu projeto e execute o comando:

\n\n

npm install winston

\n\n

Se você usa yarn:

\n\n

yarn add winston

\n\n

Após a instalação, você pode importar o Winston para o seu projeto:

\n\n

const winston = require('winston');

\n\n

Para projetos que usam ES modules (type: "module" no package.json):

\n\n

import winston from 'winston';

\n\n

Início rápido com exemplo de código

\n\n

Vamos criar um logger simples que exibe mensagens no console e em um arquivo:

\n\n

// logger.js\nconst winston = require('winston');\n\n// Criamos um logger com dois transports: console e arquivo\nconst logger = winston.createLogger({\n    level: 'info', // Nível mínimo de logging\n    format: winston.format.json(), // Formato de saída — JSON\n    transports: [\n        new winston.transports.Console(), // Saída no console\n        new winston.transports.File({ filename: 'combined.log' }) // Gravação em arquivo\n    ]\n});\n\n// Usamos o logger\nlogger.info('Aplicação iniciada');\nlogger.warn('Aviso: nível baixo de memória');\nlogger.error('Erro de conexão com o banco de dados');\n\nconsole.log('Logs registrados. Verifique o arquivo combined.log');

\n\n

Após executar este código, você verá os logs no console e também encontrará o arquivo combined.log na pasta raiz do projeto.

\n\n

Principais métodos e funções do Winston

\n\n

O Winston oferece uma API rica. Vamos explorar 10 métodos e funções principais com exemplos.

\n\n

1. winston.createLogger(options)

\n

O que faz: Cria uma nova instância de logger com a configuração especificada. Esta é a principal forma de criar um logger.

\n

Parâmetros:

\n

\n
• options.level (string): Nível mínimo de logging (por exemplo, 'info', 'debug', 'error').
\n
• options.format (Format): Formato de saída dos logs (por exemplo, winston.format.json(), winston.format.simple()).
\n
• options.transports (Transport[]): Array de transports que definem para onde os logs serão enviados.
\n
• options.defaultMeta (Object): Metadados que serão adicionados a cada mensagem.
\n
• options.exitOnError (boolean): Se true, o processo será encerrado em caso de erro de logging (padrão é true).
\n

\n

Exemplo:

\n

const lo