Gathering detailed insights and metrics for tslog
Gathering detailed insights and metrics for tslog
📝 tslog - Universal Logger for TypeScript and JavaScript
Installations
npm install tslogDeveloper Guide
BETA
Typescript
Yes
Module System
ESM, UMD
Min. Node Version
>=16
Node Version
20.6.1
NPM Version
10.8.1
Score
99.4
Supply Chain
100
Quality
76.2
Maintenance
100
Vulnerability
100
License
Releases
93
Languages
4
TypeScript
JavaScript
HTML
Shell
TypeScript (98.4%)
JavaScript (1.38%)
HTML (0.12%)
Shell (0.1%)
Developer
Download Statistics
Total Downloads
21,222,279
Last Day
8,566
Last Week
191,746
Last Month
735,821
Last Year
7,125,238
GitHub Statistics
MIT License
1,426 Stars
752 Commits
67 Forks
7 Watchers
5 Branches
23 Contributors
Updated on Jul 01, 2025
Bundle Size
17.56 kB
Minified
5.79 kB
Minified + Gzipped
Sponsor this package
Maintainers
1
Package Meta Information
Latest Version
4.9.3
Package Id
tslog@4.9.3
Unpacked Size
170.57 kB
Size
32.54 kB
File Count
45
NPM Version
10.8.1
Node Version
20.6.1
Published on
Jun 08, 2024
Total Downloads
Cumulative downloads
Total Downloads
21,222,279
Last Day
0.2%
8,566
Compared to previous day
Last Week
4.3%
191,746
Compared to previous week
Last Month
3.8%
735,821
Compared to previous month
Last Year
30.6%
7,125,238
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dev Dependencies
22
📝 tslog: Beautiful logging experience for TypeScript and JavaScript
Powerful, fast and expressive logging for TypeScript and JavaScript
Highlights
⚡ Fast and powerful
🪶 Lightweight and flexible
🏗 Universal: Works in Browsers and Node.js
👮️ Fully typed with TypeScript support (native source maps)
🗃 Pretty or JSON output
📝 Customizable log level
⭕️ Supports circular structures
🦸 Custom pluggable loggers
💅 Object and error interpolation
🤓 Stack trace and pretty errors
👨👧👦 Sub-logger with inheritance
🙊 Mask/hide secrets and keys
📦 CJS & ESM with tree shaking support
✍️ Well documented and tested
Example
1import { Logger, ILogObj } from "tslog"; 2 3const log: Logger<ILogObj> = new Logger(); 4log.silly("I am a silly log.");
Become a Sponsor
Donations help me allocate more time for my open source work.
Install
1npm install tslog
In order to run a native ES module in Node.js, you have to do two things:
- Set
"type": "module"inpackage.json. - For now, start with
--experimental-specifier-resolution=node
Example package.json
1{ 2 "name": "NAME", 3 "version": "1.0.0", 4 "main": "index.js", 5 // here: 6 "type": "module", 7 "scripts": { 8 "build": "tsc -p .", 9 // and here: 10 "start": "node --enable-source-maps --experimental-specifier-resolution=node index.js" 11 }, 12 "dependencies": { 13 "tslog": "^4" 14 }, 15 "devDependencies": { 16 "typescript": "^4" 17 }, 18 "engines": { 19 "node": ">=16" 20 } 21}
With this package.json you can simply build and run it:
1npm run build 2npm start
Otherwise:
ESM: Node.js with JavaScript:
1node --enable-source-maps --experimental-specifier-resolution=node
CJS: Node.js with JavaScript:
1node --enable-source-maps
ESM: Node.js with TypeScript and ts-node:
1node --enable-source-maps --experimental-specifier-resolution=node --no-warnings --loader ts-node/esm
CJS: Node.js with TypeScript and ts-node:
1node --enable-source-maps --no-warnings --loader ts-node/cjs
Browser:
1<!doctype html> 2<html lang="en"> 3<head> 4<title>tslog example</title> 5</head> 6<body> 7<h1>Example</h1> 8 9<script src="tslog.js"></script> 10 11<script> 12 const logger = new tslog.Logger(); 13 logger.silly("I am a silly log."); 14</script> 15 16</body> 17</html>
Enable TypeScript source map support:
This feature enables tslog to reference a correct line number in your TypeScript source code.
1// tsconfig.json 2{ 3 // ... 4 compilerOptions: { 5 // ... 6 "inlineSourceMap": true, // <!-- here 7 // we recommend using a current ES version 8 target: "es2020", 9 }, 10}
Simple example
1import { Logger } from "tslog"; 2 3const logger = new Logger({ name: "myLogger" }); 4logger.silly("I am a silly log."); 5logger.trace("I am a trace log."); 6logger.debug("I am a debug log."); 7logger.info("I am an info log."); 8logger.warn("I am a warn log with a json object:", { foo: "bar" }); 9logger.error("I am an error log."); 10logger.fatal(new Error("I am a pretty Error with a stacktrace."));
All Features
- Universal: Works in browsers and Node.js
- Tested: Great code coverage, CI
- Super customizable: Every aspect can be overwritten
- Fully typed: Written in TypeScript, with native TypeScript support
- Default log level:
silly,trace,debug,info,warn,error,fatal(different colors) - Customizable log level: BaseLogger with configurable log level
- Pretty & JSON output: Structured/pretty,
JSONor suppressed output - Attachable transports: Send logs to an external log aggregation services, file system, database, or email/slack/sms/you name it...
- Minimum log level per output:
minLevellevel can be set individually per transport - Native source maps lookup: Shows exact position also in TypeScript code (compile-to-JS), one click to IDE position
- Pretty Error: Errors and stack traces printed in a structured way and fully accessible through JSON (e.g. external Log services)
- ES Modules: import syntax with (tree-shaking)
- Object/JSON highlighting: Nicely prints out objects
- Instance Name: (Server-side only) Logs capture instance name (default host name) making it easy to distinguish logs coming from different instances
- Named Logger: Logger can be named (e.g. useful for packages/modules and monorepos)
- Sub-logger with inheritance: Powerful sub-loggers with settings inheritance, also at runtime
- Secrets masking: Prevent passwords and secrets from sneaking into log files by masking them
- Short paths: Paths are relative to the root of the application folder
- Prefixes: Prefix log messages and bequeath prefixes to child loggers
API documentation
tslog >= v4is a major rewrite and introduces breaking changes.
Please, follow this documentation when migrating.
Lifecycle of a log message
Every incoming log message runs through a number of steps before being displayed or handed over to a "transport". Every step can be overwritten and adjusted.
- log message Log message comes in through the
BaseLogger.log()method - mask If masking is configured, log message gets recursively masked
- toLogObj Log message gets transformed into a log object: A default typed log object can be passed to constructor as a second parameter and will be cloned and enriched with the incoming log parameters. Error properties will be handled accordingly. If there is only one log property, and it's an object, both objects (cloned default
logObjas well as the log property object) will be merged. If there are more than one, they will be put into properties called "0", "1", ... and so on. Alternatively, log message properties can be put into a property with a name configured with theargumentsArrayNamesetting. - addMetaToLogObj Additional meta information, like date, runtime and source code position of the log will be gathered and added to the
_metaproperty or any other one configured with the settingmetaProperty. - format In case of "pretty" configuration, a log object will be formatted based on the templates configured in settings. Meta will be formatted by the method
_prettyFormatLogObjMetaand the actual log payload will be formatted byprettyFormatLogObj. Both steps can be overwritten with the settingsformatMetaandformatLogObj. - transport Last step is to "transport" a log message to every attached transport from the setting
attachedTransports. Last step is the actual transport, either JSON (transportJSON), formatted (transportFormatted) or omitted, if its set to "hidden". Both default transports can also be overwritten by the corresponding setting.
❗Performance
By default, tslog is optimized for the best developer experience and includes some default settings that may impact performance in production environments.
To ensure optimal performance in production, we recommend modifying these settings, such as hideLogPositionForProduction(s. below), as needed.
Default log level
tslog comes with default log level 0: silly, 1: trace, 2: debug, 3: info, 4: warn, 5: error, 6: fatal.
Tip: Each logging method has a return type, which is a JSON representation of the log message (
ILogObj).
1import { Logger } from "tslog"; 2 3const log = new Logger(); 4log.silly("I am a silly log."); 5log.trace("I am a trace log."); 6log.debug("I am a debug log."); 7log.info("I am an info log."); 8log.warn("I am a warn log with a json object:", { foo: "bar" }); 9log.error("I am an error log."); 10log.fatal(new Error("I am a pretty Error with a stacktrace."));
Custom log level
In addition to the default log level, custom log level can be defined in the same way tslog does it under the hood, by extending the BaseLogger and utilizing the log method.
log method expects the following parameters:
- logLevelId - Log level ID e.g. 0
- logLevelName - Log level name e.g. silly
- args - Multiple log attributes that should be logged.
Tip: Also the generic logging method (log()) returns a JSON representation of the log message (
ILogObject).
1import { BaseLogger, ILogObjMeta, ISettingsParam, ILogObj } from "./BaseLogger"; 2 3export class CustomLogger<LogObj> extends BaseLogger<LogObj> { 4 constructor(settings?: ISettingsParam<LogObj>, logObj?: LogObj) { 5 super(settings, logObj, 5); 6 } 7 8 /** 9 * Logs a _CUSTOM_ message. 10 * @param args - Multiple log attributes that should be logged. 11 * @return LogObject with meta property, when log level is >= minLevel 12 */ 13 public custom(...args: unknown[]): LogObj & ILogObjMeta | undefined { 14 return super.log(8, "CUSTOM", ...args); 15 } 16 17}
Sub-logger
Each tslog-Logger instance can create sub-loggers and bequeath its settings to a child.
It is also possible to overwrite the LogObj when creating a child.
Sub-loggers are a powerful feature when building a modular application and due to its inheritance make it easy to configure the entire application.
Use getSubLogger() to create a child logger based on the current instance.
Example:
1const mainLogger = new Logger({ type: "pretty", name: "MainLogger" }); 2mainLogger.silly("foo bar"); 3 4const firstSubLogger = mainLogger.getSubLogger({ name: "FirstSubLogger" }); 5firstSubLogger.silly("foo bar 1");
Sub-logger with LogObj
You can also overwrite the LogObj(s. below), when you create a sub-logger:
1const mainLogObj = { main: true, sub: false }; 2const mainLogger = new Logger({ type: "pretty", name: "MainLogger" }, mainLogObj); 3mainLogger.silly("foo bar"); 4 5const subLogObj = { main: false, sub: true }; 6const firstSubLogger = mainLogger.getSubLogger({ name: "FirstSubLogger" }, subLogObj); 7firstSubLogger.silly("foo bar 1");
Settings
tslog is highly customizable and pretty much every aspect can be either configured or overwritten.
A settings object is the first parameter passed to the tslog constructor:
1const logger = new Logger<ILogObj>({ /* SETTINGS */ }, defaultLogObject);
Changing settings at runtime
settings is a public property and can also be changed on runtime.
Example on changing minLevel on runtime:
1 const logger = new Logger({ 2 minLevel: 1 3 }); 4 5 // visible 6 logger.log(1, "level_one", "LOG1"); 7 // visible 8 logger.log(2, "level_two", "LOG2"); 9 10 // change minLevel to 2 11 logger.settings.minLevel = 2; 12 13 // hidden 14 logger.log(1, "level_one", "LOG3"); 15 // visible 16 logger.log(2, "level_two", "LOG4");
Type: pretty, json, hidden
prettyDefault setting prints out a formatted structured "pretty" log entry.jsonprints out aJSONformatted log entry.hiddensuppresses any output whatsoever and can be used with attached loggers for example.
Hint: Each JSON log is printed in one line, making it easily parsable by external services.
1// pretty output 2const defaultPrettyLogger = new Logger(); 3 4// also pretty output 5const prettyLogger = new Logger({type: "pretty"}); 6 7// JSON output 8const jsonLogger = new Logger({type: "json"}); 9 10// hidden output 11const hiddenLogger = new Logger({type: "hidden"});
name
Each logger has an optional name.
You can find the name of the logger responsible for a log inside the Meta-object or printed in pretty mode.
Names get also inherited to sub-loggers and can be found inside the Meta-object parentNames as well as printed out with a separator (e.g. :) in pretty mode.
Simple name example:
1new Logger({ name: "myLogger" });
Sub-loggers with an inherited name:
1const mainLogger = new Logger({ type: "pretty", name: "MainLogger" }); 2mainLogger.silly("foo bar"); 3 4const firstSubLogger = mainLogger.getSubLogger({ name: "FirstSubLogger" }); 5firstSubLogger.silly("foo bar 1"); 6 7const secondSubLogger = firstSubLogger.getSubLogger({ name: "SecondSubLogger" }); 8secondSubLogger.silly("foo bar 2");
Output:
12022-11-17 10:45:47.705 SILLY [/examples/nodejs/index2.ts:51 MainLogger] foo bar 22022-11-17 10:45:47.706 SILLY [/examples/nodejs/index2.ts:54 MainLogger:FirstSubLogger ] foo bar 1 32022-11-17 10:45:47.706 SILLY [/examples/nodejs/index2.ts:57 MainLogger:FirstSubLogger:SecondSubLogger] foo bar 2
minLevel
You can ignore every log message from being processed until a certain severity.
Default severities are:
0: silly, 1: trace, 2: debug, 3: info, 4: warn, 5: error, 6: fatal
1 2const suppressSilly = new Logger({ minLevel: 1 }); 3suppressSilly.silly("Will be hidden"); 4suppressSilly.trace("Will be visible");
argumentsArrayName
tslog < 4 wrote all parameters into an arguments array. In tslog >= 4 the main object becomes home for all log parameters, and they get merged with the default logObj.
If you still want to put them into a separated parameter, you can do so by defining the argumentsArrayName.
1 2const logger = new Logger({ 3 type: "json", 4 argumentsArrayName: "argumentsArray", 5}); 6const logMsg = logger.silly("Test1", "Test2"); 7 8//logMsg : { 9// argumentsArray: [ 'Test1', 'Test2' ], 10// _meta: { 11// [...] 12// } 13// } 14// } 15
hideLogPositionForProduction (default: false)
By default, tslog gathers and includes the log code position in the meta information of a logObj o improve the developer experience.
However, this can significantly impact performance and slow down execution times in production.
To improve performance, you can disable this functionality by setting the option hideLogPositionForProduction to true.
Pretty templates and styles (color settings)
Enables you to overwrite the looks of a formatted "pretty" log message by providing a template string. Following settings are available for styling:
-
Templates:
prettyLogTemplate: template string for log messages. Possible placeholders:{{yyyy}}: year{{mm}}: month{{dd}}: day{{hh}}: hour{{MM}}: minute{{ss}}: seconds{{ms}}: milliseconds{{dateIsoStr}}: Shortcut for{{yyyy}}.{{mm}}.{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}{{rawIsoStr}}: Renders the date and time in ISO format (e.g.: YYYY-MM-DDTHH:mm:ss.SSSZ){{logLevelName}}: name of the log level{{name}}: optional name of the current logger and his parents (e.g. "ParentLogger:ThisLogger"){{nameWithDelimiterPrefix}}: optional name of the current logger (s. above) with a delimiter in the beginning{{nameWithDelimiterSuffix}}: optional name of the current logger (s. above) with a delimiter at the end{{fullFilePath}}: a full path starting from/root{{filePathWithLine}}: a full path below the project path with line number{{fileNameWithLine}}: file name with line number
prettyErrorTemplate: template string for error message. Possible placeholders:{{errorName}}: name of the error{{errorMessage}}: error message{{errorStack}}: Placeholder for all stack lines defined byprettyErrorStackTemplate
prettyErrorStackTemplate: template string for error stack trace lines. Possible placeholders:{{fileName}}: name of the file{{fileNameWithLine}}: file name with line number{{filePathWithLine}}: a full path below the project path with a line number{{method}}: optional name of the invoking method
prettyErrorParentNamesSeparator: separator to be used when joining names ot the parent logger, and the current one (default::)prettyErrorLoggerNameDelimiter: if a logger name is set this delimiter will be added afterwardsprettyInspectOptions: Available options
Customizing template tokens
It's possible to add user defined tokes, by overwriting the
addPlaceholdersin thesettings.overwrite. this callback allows to add or overwrite tokens in theplaceholderValues. for example, to add the token:{{custom}};1const logger = new Logger({ 2 type: "pretty", 3 prettyLogTemplate: "{{custom}} ", 4 overwrite: { 5 addPlaceholders: (logObjMeta: IMeta, placeholderValues: Record<string, string>) => { 6 placeholderValues["custom"] = "test"; 7 }, 8 }, 9});this would yield in the token
{{custom}}being replaced with"test" -
Styling:
stylePrettyLogs: defines whether logs should be styled and colorizedprettyLogStyles: provides colors and styles for different placeholders and can also be dependent on the value (e.g. log level)- Level 1: template placeholder (defines a style for a certain template placeholder, s. above, without brackets).
- Level 2: Either a string with one style (e.g.
white), or an array of styles (e.g.["bold", "white"]), or a nested object with key being a value. - Level 3: Optional nested style based on placeholder values. Key is the value of the template placeholder and value is either a string of a style, or an array of styles (s. above), e.g.
{ SILLY: ["bold", "white"] }which means: value "SILLY" should get a style of "bold" and "white".*means any value other than the defined.
prettyInspectOptions: When a (potentially nested) object is printed out in Node.js, we useutil.formatWithOptionsunder the hood. WithprettyInspectOptionsyou can define the output. Possible values
-
Time zone support:
prettyLogTimeZone: Set timezone of pretty log messages to eitherUTC(default) orlocal(based on your server/browser configuration)
Log meta information
tslog collects meta information for every log, like runtime, code position etc. The meta information collected depends on the runtime (browser or Node.js) and is accessible through the LogObj.
You can define the property containing this meta information with metaProperty, which is "_meta" by default.
Pretty templates and styles (color settings)
1 2const logger = new Logger({ 3 prettyLogTemplate: "{{yyyy}}.{{mm}}.{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}\t{{logLevelName}}\t[{{filePathWithLine}}{{name}}]\t", 4 prettyErrorTemplate: "\n{{errorName}} {{errorMessage}}\nerror stack:\n{{errorStack}}", 5 prettyErrorStackTemplate: " • {{fileName}}\t{{method}}\n\t{{filePathWithLine}}", 6 prettyErrorParentNamesSeparator: ":", 7 prettyErrorLoggerNameDelimiter: "\t", 8 stylePrettyLogs: true, 9 prettyLogTimeZone: "UTC", 10 prettyLogStyles: { 11 logLevelName: { 12 "*": ["bold", "black", "bgWhiteBright", "dim"], 13 SILLY: ["bold", "white"], 14 TRACE: ["bold", "whiteBright"], 15 DEBUG: ["bold", "green"], 16 INFO: ["bold", "blue"], 17 WARN: ["bold", "yellow"], 18 ERROR: ["bold", "red"], 19 FATAL: ["bold", "redBright"], 20 }, 21 dateIsoStr: "white", 22 filePathWithLine: "white", 23 name: ["white", "bold"], 24 nameWithDelimiterPrefix: ["white", "bold"], 25 nameWithDelimiterSuffix: ["white", "bold"], 26 errorName: ["bold", "bgRedBright", "whiteBright"], 27 fileName: ["yellow"], 28 fileNameWithLine: "white", 29 }, 30}); 31
Masking secrets in logs
One of the most common ways of a password/secret breach is through log files.
Given the central position of tslog as the collecting hub of all application logs, it's only natural to use it as a filter.
There are multiple ways of masking secrets, before they get exposed:
maskPlaceholder: Placeholder to replaced masked secrets with, Default:[***]maskValuesOfKeys: Array of keys to replace the values with the placeholder (maskPlaceholder). Default:["password"]maskValuesOfKeysCaseInsensitive: Should the keys be matched case-insensitive (e.g. "password" would replace "password" as well as "Password", and "PASSWORD"). Default:falsemaskValuesRegEx: For even more flexibility, you can also replace strings and object values with a RegEx.
Prefixing logs
Prefix every log message with an array of additional attributes.
Prefixes propagate to sub-loggers and can help to follow a chain of promises.
In addition to AsyncLocalStorage, prefixes can help further distinguish different parts of a request.
Hint: A good example could be a GraphQL request, that by design could consist of multiple queries and/or mutations.
Example:
1const logger = new Logger({ 2 prefix: ["main-prefix", "parent-prefix"], 3}); 4logger.info("MainLogger message"); 5// Output: 6// main-prefix parent-prefix MainLogger message 7 8const childLogger = logger.getSubLogger({ 9 prefix: ["child1-prefix"], 10}); 11childLogger.info("child1 message"); 12// Output: 13// main-prefix parent-prefix child1-prefix MainLogger message 14 15const grandchildLogger = childLogger.getSubLogger({ 16 prefix: ["grandchild1-prefix"], 17}); 18grandchildLogger.silly("grandchild1 message"); 19// Output: 20// main-prefix parent-prefix child1-prefix grandchild1-prefix grandchild1 message
Attach additional transports
tslog focuses on the one thing it does well: capturing logs.
Therefore, there is no built-in file system logging, log rotation, or similar.
Per default all logs go to console, which can be overwritten (s. below).
However, you can easily attach as many transports as you wish, enabling you to do fancy stuff like sending messages to Slack or Telegram in case of an urgent error or forwarding them to a log aggregator service.
Attached transports are also inherited by sub-loggers.
Simple transport example
Here is a very simple implementation used in our jest tests.
This example will suppress logs from being sent to console (type: "hidden") and will instead collect them in an array.
1const transports: any[] = []; 2const logger = new Logger({ type: "hidden" }); 3 4logger.attachTransport((logObj) => { 5 transports.push(logObj); 6}); 7 8const logMsg = logger.info("Log message");
Storing logs in a file
Here is an example of how to store all logs in a file.
1import { Logger } from "tslog"; 2import { appendFileSync } from "fs"; 3 4const logger = new Logger(); 5logger.attachTransport((logObj) => { 6 appendFileSync("logs.txt", JSON.stringify(logObj) + "\n"); 7}); 8 9logger.debug("I am a debug log."); 10logger.info("I am an info log."); 11logger.warn("I am a warn log with a json object:", { foo: "bar" }); 12
Storing logs in a file system with rotating files
If you want to limit the file size of the stored logs, a good practice is to use file rotation, where old logs will be deleted automatically.
There is a great library called rotating-file-stream solving this problem for us and even adding features like compression, file size limit etc.
- First you need to install this library:
1 npm i rotating-file-stream
- Combine it with
tslog:
1import { Logger } from "tslog"; 2import { createStream } from "rotating-file-stream"; 3 4const stream = createStream("tslog.log", { 5 size: "10M", // rotate every 10 MegaBytes written 6 interval: "1d", // rotate daily 7 compress: "gzip", // compress rotated files 8}); 9 10const logger = new Logger(); 11logger.attachTransport((logObj) => { 12 stream.write(JSON.stringify(logObject) + "\n"); 13}); 14 15logger.debug("I am a debug log."); 16logger.info("I am an info log."); 17logger.warn("I am a warn log with a json object:", { foo: "bar" }); 18
Overwriting default behavior
One of the key advantages of tslog >= 4 is that you can overwrite pretty much every aspect of the log processing described in "Lifecycle of a log message".
For every log:
1 const logger = new Logger({ 2 overwrite: { 3 mask: (args: unknown[]): unknown[] => { 4 // mask and return an array of log attributes for further processing 5 }, 6 toLogObj: (args: unknown[], clonesLogObj?: LogObj): unknown => { 7 // convert the log attributes to a LogObj and return it 8 }, 9 addMeta: (logObj: any, logLevelId: number, logLevelName: string) => { 10 // add meta information to the LogObj and return it 11 } 12 13 }, 14});
For pretty logs:
1 const logger = new Logger({ 2 type: "pretty", 3 overwrite: { 4 formatMeta: (meta?: IMeta) => { 5 // format LogObj meta object to a string and return it 6 }, 7 formatLogObj: <LogObj>(maskedArgs: unknown[], settings: ISettings<LogObj>) => { 8 // format LogObj attributes to a string and return it 9 }, 10 transportFormatted: (logMetaMarkup: string, logArgs: unknown[], logErrors: string[], settings: unknown) => { 11 // overwrite the default transport for formatted (e.g. pretty) log levels. e.g. replace console with StdOut, write to file etc. 12 }, 13 }, 14 });
For JSON logs (no formatting happens here):
1 const logger = new Logger({ 2 type: "json", 3 overwrite: { 4 transportJSON: (logObjWithMeta: any) => { 5 // transport the LogObj to console, StdOut, a file or an external service 6 }, 7 }, 8 });
Defining and accessing logObj
As described in "Lifecycle of a log message", every log message goes through some lifecycle steps and becomes an object representation of the log with the name logObj.
A default logObj can be passed to the tslog constructor and will be cloned and merged into the log message. This makes tslog >= 4 highly configurable and easy to integrate into any 3rd party service.
The entire logObj will be printed out in JSON mode and also returned by every log method.
Tip: All properties of the default
LogObjcontaining function calls will be executed for every log message making use cases possible likerequestId(s. below).
1interface ILogObj { 2 foo: string; 3} 4 5const defaultLogObject: ILogObj = { 6 foo: "bar", 7}; 8 9const logger = new Logger<ILogObj>({ type: "json" }, defaultLogObject); 10const logMsg = logger.info("Test"); 11 12// logMsg: { 13// '0': 'Test', 14// foo: 'bar', 15// _meta: { 16// runtime: 'Nodejs', 17// hostname: 'Eugenes-MBP.local', 18// date: 2022-10-23T10:51:08.857Z, 19// logLevelId: 3, 20// logLevelName: 'INFO', 21// path: { 22// fullFilePath: 'file:///[...]/tslog/examples/nodejs/index.ts:113:23', 23// fileName: 'index.ts', 24// fileColumn: '23', 25// fileLine: '113', 26// filePath: '/examples/nodejs/index.ts', 27// filePathWithLine: '/examples/nodejs/index.ts:113' 28// } 29// } 30//}
Backwards compatibility
tslogfollows a semantic release policy. A major version change indicates breaking changes.
tslog >=4is less limiting when it comes to configuration. There are many use cases (especially when it comes to integration with 3rd party services) that now can be achieved elegantly and were not possible before.
RequestID: Mark a request (e.g. HTTP) call with AsyncLocalStorage and tslog
Node.js 13.10 introduced a new feature called AsyncLocalStorage.
** Keep track of all subsequent calls and promises originated from a single request (e.g. HTTP).**
In a real world application a call to an API would lead to many logs produced across the entire application.
When debugging it can be quite handy to be able to group all logs based on a unique identifier, e.g. requestId.
Some providers (e.g. Heroku) already set a X-Request-ID header, which we are going to use or fallback to a short ID generated by nanoid.
In this example every subsequent logger is a sub-logger of the main logger and thus inherits all of its settings making requestId available throughout the entire application without any further ado.
tslog works with any API framework (like Express, Koa, Hapi and so on), but in this example we are using Koa.
1 import { AsyncLocalStorage } from "async_hooks"; 2 import Koa from "koa"; 3 import { customAlphabet } from "nanoid"; 4 import { Logger } from "tslog"; 5 6 interface ILogObj { 7 requestId?: string | (() => string | undefined); 8 } 9 10 const asyncLocalStorage: AsyncLocalStorage<{ requestId: string }> = new AsyncLocalStorage(); 11 12 const defaultLogObject: ILogObj = { 13 requestId: () => asyncLocalStorage.getStore()?.requestId, 14 }; 15 16 const logger = new Logger<ILogObj>({ type: "json" }, defaultLogObject); 17 export { logger }; 18 19 logger.info("Test log without requestId"); 20 21 const koaApp = new Koa(); 22 23 /** START AsyncLocalStorage requestId middleware **/ 24 koaApp.use(async (ctx: Koa.Context, next: Koa.Next) => { 25 // use x-request-id or fallback to a nanoid 26 const requestId: string = (ctx.request.headers["x-request-id"] as string) ?? customAlphabet("1234567890abcdefghijklmnopqrstuvwxyz", 6)(); 27 // every other Koa middleware will run within the AsyncLocalStorage context 28 await asyncLocalStorage.run({ requestId }, async () => { 29 return next(); 30 }); 31 }); 32 /** END AsyncLocalStorage requestId middleware **/ 33 34 // example middleware 35 koaApp.use(async (ctx: Koa.Context, next) => { 36 37 // log request 38 logger.silly({ originalUrl: ctx.originalUrl, status: ctx.response.status, message: ctx.response.message }); 39 40 // also works with a sub-logger 41 const subLogger = logger.getSubLogger(); 42 subLogger.info("Log containing requestId"); // <-- will contain a requestId 43 44 return await next(); 45 }); 46 47 koaApp.listen(3000); 48 49 logger.info("Server running on port 3000");
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
Found 3/7 approved changesets -- score normalized to 4
Reason
dependency not pinned by hash detected -- score normalized to 4
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/fullstack-build/tslog/ci.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/fullstack-build/tslog/ci.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/fullstack-build/tslog/ci.yml/master?enable=pin
- Info: 0 out of 2 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 1 third-party GitHubAction dependencies pinned
- Info: 1 out of 1 npmCommand dependencies pinned
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/ci.yml:1
- Info: no jobLevel write permissions found
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 27 are checked with a SAST tool
Reason
38 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp
- Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7
- Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x
- Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx
- Warn: Project is vulnerable to: GHSA-593f-38f6-jp5m
- Warn: Project is vulnerable to: GHSA-x2rg-q646-7m2v
- Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55
- Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j
- Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w
- Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
- Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg
- Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p
- Warn: Project is vulnerable to: GHSA-67mh-4wv8-2f99
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
- Warn: Project is vulnerable to: GHSA-8266-84wp-wv5c
- Warn: Project is vulnerable to: GHSA-64vr-g452-qvp3
- Warn: Project is vulnerable to: GHSA-9cwx-2883-4wfx
- Warn: Project is vulnerable to: GHSA-vg6x-rcgg-rjx6
- Warn: Project is vulnerable to: GHSA-x574-m823-4x7w
- Warn: Project is vulnerable to: GHSA-4r4m-qw57-chr8
- Warn: Project is vulnerable to: GHSA-xcj6-pq6g-qj4x
- Warn: Project is vulnerable to: GHSA-356w-63v5-8wf4
- Warn: Project is vulnerable to: GHSA-859w-5945-r5v3
- Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8
- Warn: Project is vulnerable to: GHSA-8hc4-vh64-cxmj
- Warn: Project is vulnerable to: GHSA-jr5f-v2jv-69x6
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-pfrx-2q88-qq97
- Warn: Project is vulnerable to: GHSA-4r62-v4vq-hr96
- Warn: Project is vulnerable to: GHSA-5v2h-r2cx-5xgj
- Warn: Project is vulnerable to: GHSA-rrrm-qjm4-v8hf
- Warn: Project is vulnerable to: GHSA-x7hr-w5r2-h6wg
- Warn: Project is vulnerable to: GHSA-pq67-2wwv-3xjx
- Warn: Project is vulnerable to: GHSA-8cj5-5rvv-wf4v
- Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q
Score
3.4
/10
Last Scanned on 2025-06-23
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More