Class RotatingFileHandler

This handler extends the functionality of the FileHandler by "rotating" the log file when it reaches a certain size. maxBytes specifies the maximum size in bytes that the log file can grow to before rolling over to a new one. If the size of the new log message plus the current log file size exceeds maxBytes then a roll-over is triggered. When a roll-over occurs, before the log message is written, the log file is renamed and appended with .1. If a .1 version already existed, it would have been renamed .2 first and so on. The maximum number of log files to keep is specified by maxBackupCount. After the renames are complete the log message is written to the original, now blank, file.

Example: Given log.txt, log.txt.1, log.txt.2 and log.txt.3, a maxBackupCount of 3 and a new log message which would cause log.txt to exceed maxBytes, then log.txt.2 would be renamed to log.txt.3 (thereby discarding the original contents of log.txt.3 since 3 is the maximum number of backups to keep), log.txt.1 would be renamed to log.txt.2, log.txt would be renamed to log.txt.1 and finally log.txt would be created from scratch where the new log message would be written.

This handler uses a buffer for writing log messages to file. Logs can be manually flushed with fileHandler.flush(). Log messages with a log level greater than ERROR are immediately flushed. Logs are also flushed on process completion.

Additional notes on mode as described above:

  • 'a' Default mode. As above, this will pick up where the logs left off in rotation, or create a new log file if it doesn't exist.
  • 'w' in addition to starting with a clean filename, this mode will also cause any existing backups (up to maxBackupCount) to be deleted on setup giving a fully clean slate.
  • 'x' requires that neither filename, nor any backups (up to maxBackupCount), exist before setup.

This handler requires both --allow-read and --allow-write permissions on the log files.

Hierarchy

Constructors

constructor

Properties

formatter

Accessors

level levelName

Methods

[dispose] destroy flush format handle log rotateLogFiles setup

Constructors

constructor

Properties

formatter

formatter: FormatterFunction

The function that formats log records.

Example: Usage

import { BaseHandler } from "@std/log/base-handler";
import { LogRecord } from "@std/log/logger";
import { LogLevels } from "@std/log/levels";
import { assertEquals } from "@std/assert/equals";

class MyHandler extends BaseHandler {
 log(msg: string) {
  console.log(msg);
}
}

const handler = new MyHandler("INFO");
const record = new LogRecord({
  msg: "Hello, world!",
  args: ["foo", "bar"],
  level: LogLevels.INFO,
  loggerName: "example",
});
const formatted = handler.formatter(record);
assertEquals(formatted, "INFO Hello, world!");

Accessors

level

  • get level(): LogLevel

  • Getter for the log level that this handler will handle.

    Returns LogLevel

    The log level to handle.

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { LogLevels } from "@std/log/levels";
    import { assertEquals } from "@std/assert/equals";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    const handler = new MyHandler("INFO");
    assertEquals(handler.level, LogLevels.INFO);
  • set level(level): void

  • Setter for the log level that this handler will handle.

    Parameters

    • level: LogLevel

      The log level to handle.

    Returns void

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { LogLevels } from "@std/log/levels";
    import { assertEquals } from "@std/assert/equals";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    const handler = new MyHandler("INFO");
    handler.level = LogLevels.DEBUG;
    assertEquals(handler.level, LogLevels.DEBUG);

levelName

  • get levelName(): LevelName

  • Getter for the name of the log level that this handler will handle.

    Returns LevelName

    The name of the log level to handle.

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { assertEquals } from "@std/assert/equals";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    const handler = new MyHandler("INFO");
    assertEquals(handler.levelName, "INFO");
  • set levelName(levelName): void

  • Setter for the name of the log level that this handler will handle.

    Parameters

    • levelName: LevelName

      The name of the log level to handle.

    Returns void

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { assertEquals } from "@std/assert/equals";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    const handler = new MyHandler("INFO");
    handler.levelName = "DEBUG";
    assertEquals(handler.levelName, "DEBUG");

Methods

[dispose]

  • [dispose](): void

  • Automatically disposes of the handler when instantiated with the using keyword by calling the BaseHandler.destroy method.

    Returns void

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { LogRecord } from "@std/log/logger";
    import { assertInstanceOf } from "@std/assert/instance-of";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    using handler = new MyHandler("INFO");
    assertInstanceOf(handler, BaseHandler);

destroy

  • destroy(): void

  • Destroys the handler, performing any cleanup that is required and closes the file handler.

    Returns void

    Example: Usage

    import { FileHandler } from "@std/log/file-handler";
    import { assertInstanceOf } from "@std/assert/instance-of";

    const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
    handler.setup();
    handler.destroy();

    assertInstanceOf(handler, FileHandler);

flush

  • flush(): void

  • Immediately writes the contents of the buffer to the previously opened file.

    Returns void

    Example: Usage

    import { FileHandler } from "@std/log/file-handler";
    import { assertInstanceOf } from "@std/assert/instance-of";

    const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
    handler.setup();
    handler.log('Hello, world!');
    handler.flush(); // Writes buffered log messages to the file immediately.
    handler.destroy();

    assertInstanceOf(handler, FileHandler);

format

  • format(logRecord): string

  • Formats a log record.

    Parameters

    • logRecord: LogRecord

      The log record to format.

    Returns string

    A string representation of the log record.

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { LogRecord } from "@std/log/logger";
    import { LogLevels } from "@std/log/levels";
    import { assertEquals } from "@std/assert/equals";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    const handler = new MyHandler("INFO");
    const record = new LogRecord({
      msg: "Hello, world!",
      args: ["foo", "bar"],
      level: LogLevels.INFO,
      loggerName: "example",
    });
    const formatted = handler.format(record);
    assertEquals(formatted, "INFO Hello, world!");

handle

  • handle(logRecord): void

  • Handles a log record and flushes the buffer if the log level is higher than error.

    Parameters

    Returns void

    Example: Usage

    import { FileHandler } from "@std/log/file-handler";
    import { assertInstanceOf } from "@std/assert/instance-of";
    import { LogLevels } from "./levels.ts";
    import { LogRecord } from "./logger.ts";

    const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
    handler.setup();

    // Flushes the buffer immediately and logs "CRITICAL This log is very critical indeed." into the file.
    handler.handle(
      new LogRecord({
        msg: "This log is very critical indeed.",
        args: [],
        level: LogLevels.CRITICAL,
        loggerName: "INFO",
      }),
    );
    handler.destroy();

    assertInstanceOf(handler, FileHandler);

log

  • log(msg): void

  • Logs a message by adding it to the buffer, with flushing as needed.

    Parameters

    • msg: string

      The message to log.

    Returns void

    Example: Usage

    import { FileHandler } from "@std/log/file-handler";
    import { assertInstanceOf } from "@std/assert/instance-of";

    const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
    handler.setup();
    handler.log('Hello, world!');
    handler.flush();
    handler.destroy();

    assertInstanceOf(handler, FileHandler);

rotateLogFiles

setup

  • setup(): void

  • Sets up the file handler by opening the specified file and initializing resources.

    Returns void

    Example: Usage

    import { FileHandler } from "@std/log/file-handler";

    const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
    handler.setup(); // Opens the file and prepares the handler for logging.
    handler.destroy();

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods