Concepts

Core Concepts

Core Concepts

GPAL.Logger: Turning Events Into Files

What It Is

GPAL.Logger is a small fluent wrapper that writes whatever you pass to .Log() to a destination you configure once. By default it writes to a file in the current working directory, but WithRootDirectory and WithFilename point it wherever you like. Because writing is done through GPALConverter under the hood, the file extension you give WithFilename decides the output format -- .log or .txt for plain lines, .csv for delimited rows, .json or .xml if you'd rather log structured data. Each entry is automatically prefixed with a timestamp and the name of the method that called .Log(), so you don't have to add that yourself. WithLogType(LogType.INFO | WARNING | ERROR | EXCEPTION) tags the next entry with a severity level -- it applies to a single .Log() call and then resets back to INFO.

GPAL.Logger

.WithRootDirectory(@"C:Logs")

.WithFilename("automation.log")

.Log("Login step completed");


// Tag a single entry as a warning - resets to INFO afterward

GPAL.Logger

.WithRootDirectory(@"C:Logs")

.WithFilename("automation.log")

.WithLogType(LogType.WARNING)

.Log("Retry limit reached, continuing");

Organizing Log Files: Directories and Filenames

Long-running or repeated automations generate a lot of log entries, so GPAL.Logger gives you three independent controls for organizing them. WithDirectoryStructure builds a date-based folder hierarchy under your root directory. The folders are created automatically the first time they are needed. WithFilenamePattern appends a timestamp to the filename itself so the logger naturally rotates into a new file as time passes without any extra code. WithLoggingFormat sets the timestamp format written at the start of each individual log entry. It is independent of both the directory structure and the filename pattern, and controls only what appears inside the file on every line.

GPAL.Logger

.WithRootDirectory(@"C:Logs")

.WithDirectoryStructure(DirectoryStructure.YMD)

.WithFilenamePattern(FilenamePattern.YMDHMS)

.WithFilename("automation.log")

.WithLoggingFormat(LogDateFormat.YMD_HMS)

.Log("Run started");


// Writes to, e.g.:

// C:Logs2026612automation_20260612091500.log

NOTE

Directory structure, filename pattern, and entry timestamp format can each be configured on its own. Use all three together for fully organized, rotated, timestamped logs -- or any combination you need.

Logging to a Database Instead of a File

WithDatabase(GPALDatabase) redirects .Log() entirely. Instead of writing to a file, each entry is saved as a row via GPALConverter.SaveTo(database), using whatever table the GPALDatabase object was configured with. This is useful when several processes or machines need to log to one shared, queryable place rather than separate local files.

var auditLog = GPAL.Database

.WithConnectionString("...")

.WithTableName("AutomationLog")

.ToGPALObject();


GPAL.Logger

.WithDatabase(auditLog)

.Log("Invoice batch completed");

NOTE

If GPAL.Logger can't write an entry (bad path, unreachable database, and so on), it doesn't throw. It reports the problem on the GPAL.InformationHandler/ExceptionHandler channels from The Event System, just like everything else in GPAL.

On this page

Core Concepts
GPAL.Logger: Turning Events Into Files
  • What It Is
  • Organizing Log Files: Directories and Filenames
  • Logging to a Database Instead of a File
    • 💬 Ask GPAL