Logger Library for VSCode Extensions
npm install @vscode-logging/loggerA 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.
With npm:
- npm install @vscode-logging/logger --save
With Yarn:
- yarn add @vscode-logging/logger
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.
The only function exposed (directly) by @vscode-logging/logger is getExtensionLogger which
should be invoked by a VSCode extension's activate() function.
``javascript
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
// {
// "label": "MyExtName",
// "level": "warn",
// "message": "Hello World",
// "time": "2020-01-10 15:29:52.038Z"
// }
}
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.
`javascript
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 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 simplygetChildLogger
expend with the additional suffixes.
- Child Loggers are cached using their label as the key, so repeatedly calling
using the same on the same Logger object would return the same childLogger object.
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:
`json`
{
"label": "osem",
"level": "error",
"message": "Hip Hip Hurray, the
"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][vscode-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.
[vscode-bundling]: https://code.visualstudio.com/api/working-with-extensions/bundling-extension
Please open issues on github.
See CONTRIBUTING.md.
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.