tslog

https://tslog.js.org/
Admin
A powerful, fast, and expressive logging library for TypeScript and JavaScript, providing a...
Tokens:5,265
Snippets:35
Trust Score:8.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Basic tslog Usage in Bun (TypeScript)

Source: https://tslog.js.org/index

Demonstrates how to import and use the tslog Logger within a Bun project. This example covers basic setup and logging.

```typescript
// main.ts
import { Logger } from "tslog";

const logger = new Logger();
logger.info("Hello from Bun");
```

--------------------------------

### Basic tslog Logger Initialization and Logging (TypeScript)

Source: https://tslog.js.org/index

Demonstrates the basic initialization of a tslog Logger and how to use various logging levels. This is a fundamental example for getting started with tslog.

```typescript
import { Logger, ILogObj } from "tslog";

const log: Logger<ILogObj> = new Logger();
log.silly("I am a silly log.");
```

--------------------------------

### tslog Installation (npm)

Source: https://tslog.js.org/index

Shows the command to install the tslog library using npm, the standard package manager for Node.js.

```bash
npm install tslog
```

--------------------------------

### Comprehensive tslog Example with Various Levels and Options (TypeScript)

Source: https://tslog.js.org/index

A detailed example showcasing the usage of tslog with different logging levels, including custom logger settings like the logger name. It demonstrates logging simple messages, objects, and errors.

```typescript
import { Logger } from "tslog";

const logger = new Logger({ name: "myLogger" });
logger.silly("I am a silly log.");
logger.trace("I am a trace log.");
logger.debug("I am a debug log.");
logger.info("I am an info log.");
logger.warn("I am a warn log with a json object:", { foo: "bar" });
logger.error("I am an error log.");
logger.fatal(new Error("I am a pretty Error with a stacktrace."));
```

--------------------------------

### Basic tslog Usage in Deno (TypeScript)

Source: https://tslog.js.org/index

Illustrates how to import and use the tslog Logger in a Deno environment. This example shows basic initialization and logging.

```typescript
// main.ts
import { Logger } from "npm:tslog";

const logger = new Logger();
logger.info("Hello from Deno");
```

--------------------------------

### Node.js Project Configuration for tslog with ESM

Source: https://tslog.js.org/index

Provides a sample package.json configuration for a Node.js project using tslog with ESM (ECMAScript Modules). It includes scripts for building and starting the application with source map support for accurate stack traces.

```json
{
  "name": "NAME",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc -p .",
    "start": "node --enable-source-maps dist/index.js"
  },
  "dependencies": {
    "tslog": "^4"
  }
}
```

--------------------------------

### Custom Console Output for Pretty Logs (TypeScript)

Source: https://tslog.js.org/index

Example demonstrating how to overwrite `transportFormatted` for 'pretty' logs to direct different log levels to specific `console` methods (`warn`, `error`, `info`, `log`). It parses the log level from the metadata or markup.

```typescript
    const logger = new Logger({
      type: "pretty",
      overwrite: {
        transportFormatted: (logMetaMarkup, logArgs, logErrors, logMeta) => {
          // Send different log levels to appropriate console methods
          const logLevel = logMeta?.logLevelName ?? logMetaMarkup.trim().split("\t")[1];
          switch (logLevel) {
            case "WARN":
              console.warn(logMetaMarkup, ...logArgs, ...logErrors);
              break;
            case "ERROR":
            case "FATAL":
              console.error(logMetaMarkup, ...logArgs, ...logErrors);
              break;
            case "INFO":
              console.info(logMetaMarkup, ...logArgs, ...logErrors);
              break;
            case "DEBUG":
            case "TRACE":
            case "SILLY":
            default:
              console.log(logMetaMarkup, ...logArgs, ...logErrors);
              break;
          }
      },
    });
```

--------------------------------

### Change tslog minLevel Setting at Runtime

Source: https://tslog.js.org/index

Modify logger settings, such as `minLevel`, dynamically after initialization. This example demonstrates how changing `minLevel` affects log visibility.

```javascript
const logger = new Logger({
  minLevel: 1
});

// visible
logger.log(1, "level_one", "LOG1");
// visible
logger.log(2, "level_two", "LOG2");

// change minLevel to 2
logger.settings.minLevel = 2;

// hidden
logger.log(1, "level_one", "LOG3");
// visible
logger.log(2, "level_two", "LOG4");
```

--------------------------------

### Add Custom Template Tokens in Tslog

Source: https://tslog.js.org/index

Demonstrates how to add custom template tokens to tslog by overriding `settings.overwrite.addPlaceholders`. The callback function receives the metadata object and placeholder map, allowing for the addition or modification of placeholder values. This example adds a 'custom' token that will be replaced with 'test'.

```typescript
const logger = new Logger({
  type: "pretty",
  prettyLogTemplate: "{{custom}} ",
  overwrite: {
    addPlaceholders: (logObjMeta: IMeta, placeholderValues: Record<string, string>) => {
      placeholderValues["custom"] = "test";
    },
  },
});
```

--------------------------------

### Bun Execution Command

Source: https://tslog.js.org/index

Provides the command to run a Bun script using tslog. It also suggests adding a 'dev' script to package.json for convenience.

```bash
bun run main.ts
# or add "dev": "bun run src/main.ts" to package.json scripts
```

--------------------------------

### Deno Execution Command

Source: https://tslog.js.org/index

Shows the command to run a Deno script that uses tslog. It also mentions the option to grant metadata access if needed.

```bash
deno run main.ts
# grant optional metadata access: deno run --allow-env main.ts
```

--------------------------------

### Basic Logger Usage in TypeScript

Source: https://tslog.js.org/index

Demonstrates the basic usage of the tslog Logger class in TypeScript, showing how to instantiate a logger and use its various logging levels (silly, trace, debug, info, warn, error, fatal). It also shows how to log objects and errors.

```typescript
import { Logger } from "tslog";

const log = new Logger();
log.silly("I am a silly log.");
log.trace("I am a trace log.");
log.debug("I am a debug log.");
log.info("I am an info log.");
log.warn("I am a warn log with a json object:", { foo: "bar" });
log.error("I am an error log.");
log.fatal(new Error("I am a pretty Error with a stacktrace."));
```

--------------------------------

### Initialize tslog Loggers with Different Output Types

Source: https://tslog.js.org/index

Instantiate tslog Loggers with various `type` settings: 'pretty' for formatted output, 'json' for machine-readable logs, and 'hidden' to suppress all output.

```javascript
// pretty output
const defaultPrettyLogger = new Logger();

// also pretty output
const prettyLogger = new Logger({type: "pretty"});

// JSON output
const jsonLogger = new Logger({type: "json"});

// hidden output
const hiddenLogger = new Logger({type: "hidden"});
```

--------------------------------

### TypeScript Configuration for Source Map Support

Source: https://tslog.js.org/index

Illustrates the necessary configuration within a tsconfig.json file to enable inline source map support for tslog. This ensures accurate line numbers in stack traces.

```json
// tsconfig.json
{
  // ...
  compilerOptions: {
    // ...
    "inlineSourceMap": true,  // <!-- here
    // we recommend using a current ES version
    "target": "es2020",
  },
}
```

--------------------------------

### tslog Usage in Browser

Source: https://tslog.js.org/index

Shows how to include and use tslog in an HTML file. It involves including the tslog script and then initializing and using the Logger within a script tag.

```html
<!doctype html>
<html lang="en">
<head>
<title>tslog example</title>
</head>
<body>
<h1>Example</h1>

<script src="tslog.js"></script>

<script>
  const logger = new tslog.Logger();
  logger.silly("I am a silly log.");
</script>

</body>
</html>
```

--------------------------------

### Configure tslog Logger Settings

Source: https://tslog.js.org/index

Initialize a tslog Logger with a settings object to customize its behavior. Settings include `type` (pretty, json, hidden), `name` for identification, and `minLevel` to filter logs.

```javascript
const logger = new Logger<ILogObj>({ /* SETTINGS */ }, defaultLogObject);
```

--------------------------------

### Rotating File Log Storage with Tslog

Source: https://tslog.js.org/index

Demonstrates how to implement rotating file logs using tslog and the 'rotating-file-stream' library. This method allows for managing log file size and automatically handles rotation and compression.

```bash
npm i rotating-file-stream
```

```javascript
import { Logger } from "tslog";
import { createStream } from "rotating-file-stream";

const stream = createStream("tslog.log", {
  size: "10M", // rotate every 10 MegaBytes written
  interval: "1d", // rotate daily
  compress: "gzip", // compress rotated files
});

const logger = new Logger();
logger.attachTransport((logObj) => {
  stream.write(JSON.stringify(logObject) + "\n");
});

logger.debug("I am a debug log.");
logger.info("I am an info log.");
logger.warn("I am a warn log with a json object:", { foo: "bar" });
```

--------------------------------

### Configure Pretty Log Templates and Styles in Tslog

Source: https://tslog.js.org/index

Configures various pretty logging options for tslog, including templates for logs, errors, and error stacks, as well as styling for different log levels and message components. It also sets the timezone for logs and defines options for inspecting objects in Node.js. The `stylePrettyLogs` option enables ANSI styling in server environments and CSS styling in browsers.

```typescript
const logger = new Logger({
  prettyLogTemplate: "{{yyyy}}.{{mm}}.{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}\t{{logLevelName}}\t[{{filePathWithLine}}{{name}}]\t",
  prettyErrorTemplate: "\n{{errorName}} {{errorMessage}}\nerror stack:\n{{errorStack}}",
  prettyErrorStackTemplate: "  • {{fileName}}\t{{method}}\n\t{{filePathWithLine}}",
  prettyErrorParentNamesSeparator: ":",
  prettyErrorLoggerNameDelimiter: "\t",
  stylePrettyLogs: true,
  prettyLogTimeZone: "UTC",
  prettyLogStyles: {
    logLevelName: {
      "*": ["bold", "black", "bgWhiteBright", "dim"],
      SILLY: ["bold", "white"],
      TRACE: ["bold", "whiteBright"],
      DEBUG: ["bold", "green"],
      INFO: ["bold", "blue"],
      WARN: ["bold", "yellow"],
      ERROR: ["bold", "red"],
      FATAL: ["bold", "redBright"],
    },
    dateIsoStr: "white",
    filePathWithLine: "white",
    name: ["white", "bold"],
    nameWithDelimiterPrefix: ["white", "bold"],
    nameWithDelimiterSuffix: ["white", "bold"],
    errorName: ["bold", "bgRedBright", "whiteBright"],
    fileName: ["yellow"],
    fileNameWithLine: "white",
  },
});
```

--------------------------------

### Prefixing Logs with Attributes in Tslog

Source: https://tslog.js.org/index

Demonstrates how to prefix log messages with an array of additional attributes using the Logger and getSubLogger methods. Prefixes are inherited by sub-loggers, aiding in tracing log origins.

```javascript
const logger = new Logger({
  prefix: ["main-prefix", "parent-prefix"],
});
logger.info("MainLogger message");
// Output:
// main-prefix parent-prefix MainLogger message

const childLogger = logger.getSubLogger({
  prefix: ["child1-prefix"],
});
childLogger.info("child1 message");
// Output:
// main-prefix parent-prefix child1-prefix MainLogger message

const grandchildLogger = childLogger.getSubLogger({
  prefix: ["grandchild1-prefix"],
});
grandchildLogger.silly("grandchild1 message");
// Output:
// main-prefix parent-prefix child1-prefix grandchild1-prefix grandchild1 message
```

--------------------------------

### Storing Logs in a File with Tslog

Source: https://tslog.js.org/index

Shows how to use tslog to append log messages to a file named 'logs.txt'. It requires importing the Logger from 'tslog' and the appendFileSync function from the 'fs' module.

```javascript
import { Logger } from "tslog";
import { appendFileSync } from "fs";

const logger = new Logger();
logger.attachTransport((logObj) => {
  appendFileSync("logs.txt", JSON.stringify(logObj) + "\n");
});

logger.debug("I am a debug log.");
logger.info("I am an info log.");
logger.warn("I am a warn log with a json object:", { foo: "bar" });
```

--------------------------------

### Create Sub-loggers with tslog

Source: https://tslog.js.org/index

Generate child loggers using `getSubLogger()`, inheriting settings from the parent. This is useful for modular applications, allowing easy configuration inheritance. LogObj can also be overridden for specific sub-loggers.

```javascript
const mainLogger = new Logger({ type: "pretty", name: "MainLogger" });
mainLogger.silly("foo bar");

const firstSubLogger = mainLogger.getSubLogger({ name: "FirstSubLogger" });
firstSubLogger.silly("foo bar 1");
```

```javascript
const mainLogObj = { main: true, sub: false };
const mainLogger = new Logger({ type: "pretty", name: "MainLogger" }, mainLogObj);
mainLogger.silly("foo bar");

const subLogObj = { main: false, sub: true };
const firstSubLogger = mainLogger.getSubLogger({ name: "FirstSubLogger" }, subLogObj);
firstSubLogger.silly("foo bar 1");
```

--------------------------------

### Customize Pretty Error Template and Stack Trace in TSLog

Source: https://tslog.js.org/index

Provides options to customize the appearance of error logs. `prettyErrorTemplate` defines the structure for error messages, while `prettyErrorStackTemplate` formats individual stack trace lines. Placeholders are available for error details and source location.

```javascript
const logger = new Logger({
  type: "pretty",
  prettyErrorTemplate: "{{errorName}} at {{filePathWithLine}} : {{errorMessage}}",
  prettyErrorStackTemplate: "  at {{method}} ({{fileNameWithLine}})`
});
```

--------------------------------

### Customize Pretty Log Message Template in TSLog

Source: https://tslog.js.org/index

Allows overwriting the default format for pretty log messages. The `prettyLogTemplate` option accepts a string with placeholders for date, time, log level, logger name, and file path information, enabling highly customizable log output.

```javascript
const logger = new Logger({
  type: "pretty",
  prettyLogTemplate: "[{{yyyy}}.{{mm}}.{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}] {{logLevelName}} {{name}}: {{message}}"
});
```

--------------------------------

### Define and Use Default Log Object (TypeScript)

Source: https://tslog.js.org/index

Illustrates how to define a custom interface for log objects (`ILogObj`) and provide a default object to the `tslog` constructor. This default object is cloned and merged into every log message, making it available in the output, especially useful for adding context like request IDs.

```typescript
interface ILogObj {
    foo: string;
}

const defaultLogObject: ILogObj = {
  foo: "bar",
};

const logger = new Logger<ILogObj>({ type: "json" }, defaultLogObject);
const logMsg = logger.info("Test");

// logMsg: {
//  '0': 'Test',
//  foo: 'bar',
//  _meta: {
//    runtime: 'server',
//    hostname: 'Eugenes-MBP.local',
//    date: 2022-10-23T10:51:08.857Z,
//    logLevelId: 3,
//    logLevelName: 'INFO',
//    path: {
//      fullFilePath: 'file:///[...]/tslog/examples/server/index.ts:113:23',
//      fileName: 'index.ts',
//      fileColumn: '23',
//      fileLine: '113',
//      filePath: '/examples/server/index.ts',
//      filePathWithLine: '/examples/server/index.ts:113'
//    }
//  }
//}
```

--------------------------------

### Node.js: Mark HTTP Calls with AsyncLocalStorage and tslog

Source: https://tslog.js.org/index

This snippet sets up a Koa.js server that uses AsyncLocalStorage to manage a requestId for each incoming HTTP request. All subsequent log messages generated within the same request context will automatically include this requestId, thanks to tslog's integration with AsyncLocalStorage.

```typescript
import { AsyncLocalStorage } from "async_hooks";
import Koa from "koa";
import { customAlphabet } from "nanoid";
import { Logger } from "tslog";

interface ILogObj {
  requestId?: string | (() => string | undefined);
}

const asyncLocalStorage: AsyncLocalStorage<{ requestId: string }> = new AsyncLocalStorage();

const defaultLogObject: ILogObj = {
  requestId: () => asyncLocalStorage.getStore()?.requestId,
};

const logger = new Logger<ILogObj>({ type: "json" }, defaultLogObject);
export { logger };

logger.info("Test log without requestId");

const koaApp = new Koa();

/** START AsyncLocalStorage requestId middleware **/
koaApp.use(async (ctx: Koa.Context, next: Koa.Next) => {
  // use x-request-id or fallback to a nanoid
  const requestId: string = (ctx.request.headers["x-request-id"] as string) ?? customAlphabet("1234567890abcdefghijklmnopqrstuvwxyz", 6)();
  // every other Koa middleware will run within the AsyncLocalStorage context
  await asyncLocalStorage.run({ requestId }, async () => {
    return next();
  });
});
/** END AsyncLocalStorage requestId middleware **/

// example middleware
koaApp.use(async (ctx: Koa.Context, next) => {

  // log request
  logger.silly({ originalUrl: ctx.originalUrl, status: ctx.response.status, message: ctx.response.message });

  // also works with a sub-logger
  const subLogger = logger.getSubLogger();
  subLogger.info("Log containing requestId"); // <-- will contain a requestId

  return await next();
});

koaApp.listen(3000);

logger.info("Server running on port 3000");

```

--------------------------------

### Overwrite Logger Behavior for All Log Types (TypeScript)

Source: https://tslog.js.org/index

Allows customization of the log processing lifecycle for every log message. This includes masking arguments, converting arguments to a LogObj, and adding metadata. Dependencies include the Logger class from 'tslog'.

```typescript
    const logger = new Logger({
  overwrite: {
    mask: (args: unknown[]): unknown[] => {
      // mask and return an array of log attributes for further processing
    },
    toLogObj: (args: unknown[], clonesLogObj?: LogObj): unknown => {
      // convert the log attributes to a LogObj and return it
    },
    addMeta: (logObj: any, logLevelId: number, logLevelName: string) => {
      // add meta information to the LogObj and return it
    }

  },
});
```

--------------------------------

### Configure Logger Name and Inherited Names in tslog

Source: https://tslog.js.org/index

Assign an optional `name` to a logger for easier identification in logs. This name is inherited by sub-loggers and displayed in the 'pretty' output and meta-object.

```javascript
new Logger({ name: "myLogger" });
```

```javascript
const mainLogger = new Logger({ type: "pretty", name: "MainLogger" });
mainLogger.silly("foo bar");

const firstSubLogger = mainLogger.getSubLogger({ name: "FirstSubLogger" });
firstSubLogger.silly("foo bar 1");

const secondSubLogger = firstSubLogger.getSubLogger({ name: "SecondSubLogger" });
secondSubLogger.silly("foo bar 2");
```

--------------------------------

### Collecting Logs in an Array with Tslog

Source: https://tslog.js.org/index

Illustrates how to attach a custom transport to a tslog Logger to collect all log objects into an array. This is useful for testing or debugging purposes by suppressing console output.

```javascript
const transports = [];
const logger = new Logger({ type: "hidden" });

logger.attachTransport((logObj) => {
  transports.push(logObj);
});

const logMsg = logger.info("Log message");
```

--------------------------------

### Overwrite Pretty Log Formatting and Transport (TypeScript)

Source: https://tslog.js.org/index

Customizes the formatting and transport of 'pretty' logs. This enables control over how log metadata and the entire log object are converted to strings and how they are ultimately outputted (e.g., to console or files).

```typescript
    const logger = new Logger({
      type: "pretty",
      overwrite: {
        formatMeta: (meta?: IMeta) => {
          // format LogObj meta object to a string and return it
        },
        formatLogObj: <LogObj>(maskedArgs: unknown[], settings: ISettings<LogObj>) => {
            // format LogObj attributes to a string and return it
        },
        transportFormatted: (
          logMetaMarkup: string,
          logArgs: unknown[],
          logErrors: string[],
          logMeta?: IMeta,
          settings?: ISettings<LogObj>
        ) => {
          // overwrite the default transport for formatted (e.g. pretty) log levels. e.g. replace console with StdOut, write to file etc.
        },
      },
    });
```

--------------------------------

### Define Custom Log Level with tslog BaseLogger

Source: https://tslog.js.org/index

Extend the BaseLogger class to create custom log levels. The `log` method accepts a logLevelId, logLevelName, and log attributes. This allows for flexible and granular logging beyond default levels.

```typescript
import { BaseLogger, ISettingsParam, ILogObjMeta, ILogObj } from "tslog";

export class CustomLogger<LogObj> extends BaseLogger<LogObj> {
  constructor(settings?: ISettingsParam<LogObj>, logObj?: LogObj) {
    super(settings, logObj, 5);
  }

  /**
   * Logs a _CUSTOM_ message.
   * @param args  - Multiple log attributes that should be logged.
   * @return LogObject with meta property, when log level is >= minLevel
   */
  public custom(...args: unknown[]): LogObj & ILogObjMeta | undefined {
    return super.log(8, "CUSTOM", ...args);
  }

}
```

--------------------------------

### Set Minimum Log Level in tslog

Source: https://tslog.js.org/index

Control log verbosity by setting a `minLevel` in the logger's settings. Logs with a severity lower than `minLevel` will be ignored.

```javascript
const suppressSilly = new Logger({ minLevel: 1 });
suppressSilly.silly("Will be hidden");
suppressSilly.trace("Will be visible");
```

--------------------------------

### Mask Secrets in Tslog Logs

Source: https://tslog.js.org/index

Configures tslog to mask sensitive information within log messages. This is achieved using options like `maskPlaceholder`, `maskValuesOfKeys`, `maskValuesOfKeysCaseInsensitive`, and `maskValuesRegEx`. The `maskPlaceholder` defines the string used to replace secrets, `maskValuesOfKeys` specifies which keys' values should be masked, and `maskValuesRegEx` allows for custom regular expression-based masking.

```typescript
const logger = new Logger({
  // ... other options
  maskPlaceholder: "[***]",
  maskValuesOfKeys: ["password", "secret"],
  maskValuesOfKeysCaseInsensitive: true,
  maskValuesRegEx: /\b\d{16,19}\b/g, // Example: masks 16-19 digit numbers
});
```

--------------------------------

### Configure Arguments Array Name in TSLog

Source: https://tslog.js.org/index

This option allows you to specify a custom name for the array that holds log parameters, which was the default behavior in tslog versions prior to 4. In newer versions, parameters are merged into the main log object by default. Setting `argumentsArrayName` enables retaining the older behavior if desired.

```javascript
const logger = new Logger({
  type: "json",
  argumentsArrayName: "argumentsArray",
});
const logMsg = logger.silly("Test1", "Test2");

// logMsg will be:
// {
//   argumentsArray: [ 'Test1', 'Test2' ],
//   _meta: {
//       [...] 
//     }
// }

```

--------------------------------

### Disable Log Position for Production in TSLog

Source: https://tslog.js.org/index

By default, TSLog includes the code position of log calls in the meta information to aid developers. For production environments, this feature can be disabled using `hideLogPositionForProduction: true` to improve performance and reduce execution overhead.

```javascript
const logger = new Logger({
  hideLogPositionForProduction: true
});
```

--------------------------------

### Overwrite JSON Log Transport (TypeScript)

Source: https://tslog.js.org/index

Overrides the default transport mechanism for 'json' type logs. This allows for custom handling of the entire JSON log object, such as sending it to a specific endpoint or storing it in a database. No formatting occurs before transport in JSON mode.

```typescript
    const logger = new Logger({
      type: "json",
      overwrite: {
        transportJSON: (logObjWithMeta: any) => {
          // transport the LogObj to console, StdOut, a file or an external service
        },
      },
    });
```
Tokens:
Raw