Log Class

Overview

The Log Class allows applications to log debug, informational, and error information that is produced during the course of execution of a script. Log entries can have different levels of severity. There are five different levels, in order of least severe to most severe: Debug, Info, Warn, Error, and Fatal. The log output may optionally be filtered, so that only desired error levels are placed into the output log file.

Constructor

Log(filename : String)

Methods

Log.close

Closes the log file

Log.debug

Adds a debug output line to the log

Log.erase

Truncates the log file to zero lines

Log.error

Adds a error output line to the log

Log.fatal

Adds a fatal output line to the log

Log.info

Adds an information output line to the log

Log.open

Opens a log file for appending

Log.setConsoleOutput

Activates or deactivates console output

Log.setFilterLevel

Sets the filter level for the log output

Log.warn

Adds a warning output line to the log

Example

// Log appends timestamped, severity-tagged lines to a file:
//
//     Sat Aug 16 09:14:02 2025 - [warn ] disk is nearly full
//
// The file is opened for appending, never truncated, so runs accumulate.

// (Environment.getTempPath() has no trailing separator)
const path = `${Environment.getTempPath()}/example.log`;

// the filename can go to the constructor, or to a later open(path) call
const log = new Log(path);

// start clean; erase() reopens the file, so the handle stays usable
log.erase();

// the five levels, least to most severe; each takes any number of
// arguments and writes one line per argument
log.debug("connecting");
log.info("connected", "schema version 14");
log.warn("query took 4.2 seconds");
log.error("could not write the summary table");
log.fatal("giving up");

// setFilterLevel() decides what reaches the file from here on.  The
// levels are bit flags; anything filtered out is dropped and the call
// returns false.  Log.LevelAll is the state a new Log starts in.
log.setFilterLevel(Log.LevelWarn | Log.LevelError | Log.LevelFatal);

const wrote_info = log.info("filtered out");
log.warn("still gets through");

log.close();

// read it back
let output = `${path}\n\n`;
const reader = File.openText(path);

let line;
while ((line = reader.readLine()) !== null) {
    output += `${line}\n`;
}

reader.close();

alert(`${output}\ninfo() while filtered returned ${wrote_info}`);