@vscode-logging/logger

@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.

Support

Please open issues on github.

Contributing

See CONTRIBUTING.md.

License

Copyright (c) 2021 SAP SE or an SAP affiliate company. All rights reserved. This file is licensed under the Apache Software License, v. 2 except as noted otherwise in the LICENSE file.

Changelog

2.0.0 (2024-01-05)

Bug Fixes

• add .npmignore files to remove unneeded contents in published pkgs (998b1f8)
• convert timestamp format according to ISO-8601 (b4ab3e4)
• source Location Tracking not affecting ChildLoggers (72b151a), closes #15
• typo in the logging.level configuration description (#181) (c05b17d)
• update yarn.lock (#144) (33ec5ac)
• upgrade lodash version due to CVE-2021-23337 (c514c16)
• logger: vscode-logging/types package should be a dependency (e2ea6c7)

Features

• wrapper: remove dep to @types/vscode (#167) (b362e5c)
• logger wrapper package (#163) (fc6abc5)
• support console as log target (#109) (ea16211)
• logger: a memory leak when creating 9 or more ChildLogger's (#76) (482c708)
• aPI Fixes (dummy change to force minor version) (0fb0fb6)
• initial Commit (ee780af)

Reverts

• Revert "chore: include release number in release commit" (d9d9c68)

• Make OutputChannel optional. (#55) (b7fa564), closes #55 #55

BREAKING CHANGES

• wrapper: getConfigurations and onDidChangeConfiguration properties were removed from the configureLogger public API
• OutputChannel will not be created inside the logger as today. Alternatively, it will be added as an optional parameter. The VS Code Extension will be able to create the OutputChannel and send it to the logger as a parameter.