winston-transport-vscode

A VS Code extension transport for Winston logger


---

- Installation
- Getting Started
- Transports
- OutputChannelTransport
- LogOutputChannelTransport
- Levels
- Format
- Usage
- Contributing
- License

---

Installation

``shell
npm install winston-transport-vscode
`

Getting Started

To use Winston logger in your VS Code extension, create an output channel for
your extension, using the
VS Code API,
create a Transport, giving it the output channel, and use that transport in your
winston logger instance.

`js
// 1. Require (or import)
const vscode = require('vscode');
const winston = require('winston');
const { LogOutputChannelTransport } = require('winston-transport-vscode');

// 2. Create a Log Output Channel for your extension with the VS Code API
const outputChannel = vscode.window.createOutputChannel('My extension', {
log: true,
});

// 3. Create the Winston logger giving it the Log Output Channel
const logger = winston.createLogger({
level: 'trace', // Recommended: set the highest possible level
levels: LogOutputChannelTransport.config.levels, // Recommended: use predefined VS Code log levels
format: LogOutputChannelTransport.format(), // Recommended: use predefined format
transports: [new LogOutputChannelTransport({ outputChannel })],
});

logger.info('Hello World!');
`

Transports

VS Code offers 2 types of output channels:

- OutputChannel -
a simple channel for plain text output
- LogOutputChannel -
an output channel dedicated to logging

$3

Send logs to an OutputChannel using the OutputChannelTransport

`js
const vscode = require('vscode');
const winston = require('winston');
const { OutputChannelTransport } = require('winston-transport-vscode');

const { combine, timestamp, prettyPrint } = winston.format;

const outputChannel = vscode.window.createOutputChannel('My extension');

const transport = new OutputChannelTransport({
outputChannel,
format: combine(timestamp(), simple()),
});

const logger = winston.createLogger({
transports: [transport],
});

logger.info('Hello World!');
`

$3

Send logs to a LogOutputChannel using the LogOutputChannelTransport.

`js
const vscode = require('vscode');
const winston = require('winston');
const { LogOutputChannelTransport } = require('winston-transport-vscode');

const outputChannel = vscode.window.createOutputChannel('My extension', {
log: true,
});

const logger = winston.createLogger({
level: 'trace',
levels: LogOutputChannelTransport.config.levels,
format: LogOutputChannelTransport.format(),
transports: [new LogOutputChannelTransport({ outputChannel })],
});

logger.info('Hello World!');
`

It is recommended to set the logger's level to the highest possible level
(trace), as VS Code's LogOutputChannel supports its own log level filtering.

Levels

VS Code's LogOutputChannel supports a dedicated set of log levels that differs
from Winston's default configuration. To use VS Code log levels with Winston,
winston-transport-vscode provides a levels configuration.

The log levels are as follows:

- error - 0
- warn - 1
- info - 2
- debug - 3
- trace - 4

Use LogOutputChannelTransport.config.levels when configuring your logger.

`js
const logger = winston.createLogger({
level: 'trace',

// winston-transport-vscode levels configuration
levels: LogOutputChannelTransport.config.levels,

format: LogOutputChannelTransport.format(),
transports: [new LogOutputChannelTransport({ outputChannel })],
});
`

Format

winston-transport-vscode provides a built-in formatter that easily integrates
with LogOutputChannel. LogOutputChannelTransport.format supports structured
logging for contextual value while outputting a more human-readable format than
JSON.

`js
const fmt = LogOutputChannelTransport.format();

fmt.transform({ level: 'info', message: 'Hello World!', extra: 'value' });
// {
// level: 'info',
// message: 'Hello World!',
// extra: 'info',
// [Symbol(level)]: 'info',
// [Symbol(message)]: 'Hello World! extra="value"'
// }

fmt.transform({
level: 'info',
message: 'Hello World!',
nested: { values: { are: { supported: true } } },
});
// {
// level: 'info',
// message: 'Hello World!',
// nested: { values: { are: [Object] } },
// [Symbol(level)]: 'info',
// [Symbol(message)]: 'Hello World! nested.values.are.accepted=true'
// }
`

$3

Use LogOutputChannelTransport.format when configuring your logger.

`js
const logger = winston.createLogger({
level: 'trace',
levels: LogOutputChannelTransport.config.levels,

// winston-transport-vscode format
format: LogOutputChannelTransport.format(),

transports: [new LogOutputChannelTransport({ outputChannel })],
});

logger.info('Hello World!', { extra: 'value', nested: { value: 'too' } });
// Output to log channel:
// 2024-02-12 21:18:36.382 [info] Hello World! extra="value" nested.value="too"
``

Contributing

PRs and issues are welcome on this repository.

License

Copyright 2024 Charles Francoise

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.