@vscode-logging/logger

A Logging Library for VSCode Extension which supports the following features:

JSON structure log entries output.
Logging to a VSCode outputChannel.
Logging to rolling file logs.
Source Location Tracking.

Installation

With npm:

npm install @vscode-logging/logger --save

With Yarn:

yarn add @vscode-logging/logger

Usage

Please see the TypeScript Definitions for full API details.

Runnable and documented usage examples can be found in the examples folder. It is recommended to review these examples as integrating @vscode-logging/logger into a VSCode Extension necessitates multiple changes, mainly around managing the configuration options as user exposed settings.

Basic Usage

The only function exposed (directly) by @vscode-logging/logger is getExtensionLogger which should be invoked by a VSCode extension's activate() function.

const { getExtensionLogger } = require("@vscode-logging/logger");

function activate(context) {
  const extLogger = getExtensionLogger({
    extName: "MyExtName",
    level: "info", // See LogLevel type in @vscode-logging/types for possible logLevels
    logPath: context.logPath, // The logPath is only available from the `vscode.ExtensionContext`
    logOutputChannel: logOutputChannel, // OutputChannel for the logger
    sourceLocationTracking: false,
    logConsol: false // define if messages should be logged to the consol
  });

  extLogger.warn("Hello World");
  // Will Log The following entry to **both**
  //   - To outputChannel `logOutputChannel`
  //   - To log files in `logPath`
  // {
  //   "label": "MyExtName",
  //   "level": "warn",
  //   "message": "Hello World",
  //   "time": "2020-01-10 15:29:52.038Z"
  // }
}

On ChildLoggers

The getChildLogger API is available on the interface returned by getExtensionLogger. This can be used to obtain sub logger which log to the same targets (outChannel/files) as the root logger, but with a more specific label.

const { getExtensionLogger } = require("@vscode-logging/logger");

const extLogger = getExtensionLogger({ extName: "MyExtName" /* ... */ });

const childLogger = extLogger.getChildLogger({ label: "MyClass" });
childLogger.warn("Hello World");
// Will Log to the same targets as extLogger but with a suffix added to the `label`
// {
//   "label": "MyExtName.MyClass", // Note the `.MyClass` suffix in the label
//   "level": "warn",
//   "message": "Hello World",
//   "time": "2020-01-10 15:29:52.038Z"
// }

const grandChildLogger = childLogger.getChildLogger({ label: "MyMethod" });
grandChildLogger.warn("Hip Hip Hurray");
// {
//   "label": "MyExtName.MyClass.MyMethod", // Note the `.MyMethod` suffix in the label
//   "level": "warn",
//   "message": "Hello World",
//   "time": "2020-01-10 15:30:52.038Z"
// }

Important notes on child loggers:

They share the same configuration (e.g logging level) as the root extension logger.
Child Loggers cannot change their configuration, all configuration mutation must be done via the root extension logger.
Child Loggers can be created from other child loggers, the label property would simply expend with the additional suffixes.
Child Loggers are cached using their label as the key, so repeatedly calling getChildLogger using the same label on the same Logger object would return the same childLogger object.

On `sourceLocationTracking`

When enabled the sourceLocationTracking will augment the log entries with the function name and location (file/line/column) where the log method was invoked, e.g:

{
  "label": "osem",
  "level": "error",
  "message": "Hip Hip Hurray, the <Hello World> Command was executed! counter: <1>",
  "source": {
    "function": "registerCalback",
    "location": "c:\\workspace\\vscode-logging\\examples\\extension\\lib\\commands.js:21:19"
  },
  "time": "2020-01-11 11:51:48.659Z"
}

Important things to note on sourceLocationTracking

This functionality is not guaranteed to always work.
e.g anonymous functions have no name...
Obtaining the source location information is very slow.
- This means that this feature should not be used in productive flows.
- Therefore A "Fatal" log entry will be logged each time this option is enabled.
Processes which manipulate the source code such as bundling or compilation (TypeScript/Babel) may make the information produced less relevant due to the lack of sourceMaps support. Therefore this feature may be more useful during development flows rather then productive flows.