Provides a logging framework for Lazarus applications.

LazLogger.pas provides logging facilities to write message to a file or stdout device. Messages can be logged plain, or enclosed in begin/end like blocks, adding indent to all messages between to points (blocks can be nested). It also has the ability to filter groups of messages.

It can read the command line and environment to find the desired filename. By default it looks for a --debug-log= argument on the command line or "appname"_debuglog in the system environment.

If no log name is found StdOut is used.

The easiest method is to use the unit and put "DebugLn"/ "DbgOut" / "DebugLnEnter"/ "DebugLnExit" in your code. This works without any further setup.

LazLogger.pas is part of the LazUtils package.

Alias for the PLazLoggerLogGroup type in the LazLoggerBase unit. Alias for the TLazLoggerWriteExEventInfo type in lazloggerbase.pas. LazLoggerBase.TLazLoggerWriteExEventInfo Writes a message to the log.

Calls the DebuglnStack method for the logger class instance.

Writes a message to the log.

Writes the text to the log. Does not append a new line. The Argument can be:

One or more string(s)
An open array of const: All values are converted to string and joined
A single string and open array of const: Will be passed to Format
Any of the above with a PLazLoggerLogGroup as filter

This is a forwarder to the log TLazLogger object. See there for details.

Writes the text to the log. Does append a new line.

The Argument can be:

One or more string
An open array of const: All values are converted to string and joined
A single string and open array of const: Will be passed to Format
Any of the above with a PLazLoggerLogGroup as filter

This is a forwarder to the log TLazLogger object. See there for details.

Writes the text to the log. Does append a new line. Increases the current intend.

The Argument can be:

One or more string
An open array of const: All values are converted to string and joined
A single string and open array of const: Will be passed to Format
Any of the above with a PLazLoggerLogGroup as filter

This is a forwarder to the log TLazLogger object. See there for details.

Writes the text to the log. Does append a new line. Increases the current indentation level.

The Argument can be:

One or more string
An open array of const: All values are converted to string and joined
A single string and open array of const: Will be passed to Format
Any of the above with a PLazLoggerLogGroup as filter
This is a forwarder to the log TLazLogger object. See there for details.

GetDebugLogger SetDebugLogger String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. String argument for the routine. Generates a debugger message formatted with the value(s) for the specified type(s). String with the formatted content for the specified value(s). Cardinal value for the message. Integer (LongInt, Int64) value for the message. QWord value for the message. TRect value for the message. Untyped pointer value for the message. Extended value for the message. Number of decimal places for the Extended value in the message. Boolean value for the message. TMethod value for the message. String value for the message. Integer value for the message. Integer value for the message. Integer value for the message. Integer value for the message. TShiftStateEnum value for the message. Generates a debugger message with the combined values of the specified arguments. Message with the values in s1 and s2 combined into a single string. String value for the message. String value for the message. Generates a message with the optional name and class type for the specified object.

DbgSName generates a log message with the optional name and class type for the object in p.

When p has not been assigned, the return value contains:

'Nil'

When p is a TComponent descendant, the return value contains a value like:

TComponent.Name + ':' + TComponent.ClassName

Otherwise, the return value is set to:

TObject.ClassName

If the LazLogger_Dummy unit has been included in the application, the return value is an empty string.

Formatted message with the optional name and class type for the specified value. TObject instance examined in the routine. Generates a message with the hexadecimal-encoded memory content for the specified object instance. String with hexadecimal-encoded values for the specified object instance. Object instance examined in the routine. Generates a message with the hexadecimal representation for the specified Int64 value. String with the hexadecimal representation for the specified value. Int64 value converted in the routine. Generates a message with the tick count for the computer system. String with the tick count for the system. Generates a message with the hexadecimal-encoded content for the specified block of memory and size. Untyped pointer to the byte values examined in the routine. Number of bytes from the pointer to include in the message. Maximum number of columns to use in the formatted message string. A LineEnd sequence is inserted in the message when Width is exceeded. Generates a message with the hexadecimal-encoded values from the specified memory stream. Write the stack trace back when an exception is detected.

Calls the DumpExceptionBackTrace method for the logger in the DebugLogger variable.

Implements the Assign (':=') operator using a Pointer to a logger group for the TLazLoggerLogEnabled type. Implements the Assign (':=') operator using a Boolean argument for the TLazLoggerLogEnabled type. Implements the logical And operator for TLazLoggerLogEnabled types. Implements the logical Or operator for TLazLoggerLogEnabled types. Generates a debugger message with the content from the specified value.

Calls the DbgStr routine in LazLoggerBase unit to write the value(s).

LazLoggerBase.DbgStr Generates a debugger message with the specified WideString content.

Calls the DbgWideStr routine in LazLoggerBase unit to write the value(s).

LazLoggerBase.DbgWideStr Represents a file or device handle for a logger class instance.

Provides functionality to write messages to a log file. The file is represented by a Text member stored internally. TLazLoggerFileHandle allows filtering and changing indent level.

TLazLoggerFileHandle can parse options from command line for log filename and filter settings.

An application can subclass the logger handle to provide additional functionality.

Used in the implementation of the TLazLoggerFile class.

Constructor for the class instance. Create sets the default values for members and properties in the class instance. Destructor for the class instance.

Calls the inherited destructor on entry. Ensures that the Text handle to LogName is closed when it is in use. Sets the value in ActiveLogText to Nil.

Opens the output handle for the logger when CloseLogFileBetweenWrites is False.

Calls a private method to ensure that a Text handle is allocated for the output destination. No actions are performed when:

ActiveLogText has already been assigned.
Previous access to the output handle has failed.
LogName is an empty string ('') and UseStdOut is set to False.

To use an output file, set LogName to a valid file path and name which allows write access prior to calling OpenFile.

To use the stdout device, set LogName to an empty string and UseStdOut to True prior to calling OpenFile.

RTL routines like Assign, Append, or Rewrite are called to associate the Text handle for the logger and to establish the FileMode for write access. On successful completion of the method, ActiveLogText is updated with the TextRec for the file name or stdout device in Output. If an exception occurs, it is caught and an error message is written to the stdout device.

Closes the output handle for the logger. Resets the value in WriteFailedCount to 0 (zero). Writes the specified log message to the output handle for the class instance.

WriteToFile ensures that the OnWidgetsetDbgOut routine is signalled (when assigned for the unit) to perform the write operation. If the message is handled in OnWidgetsetDbgOut, no additional actions are performed in the method.

Otherwise, the output handle is opened when not already assigned. If ActiveLogText is unassigned after trying to open the output handle, no additional actions are performed in the method.

The RTL Write routine is called to write the value in S to the output handle for the TextRec. The Flush routine is called when needed for the platform.

When CloseLogFileBetweenWrites is set to True, the output handle is closed and released.

If an exception occurs during output to the handle, it is caught and the values in WriteFailedCount and LastWriteFailed are updated to reflect the error condition.

Log message written in the method. Logger class instance passed to the OnWidgetsetDbgOut handler. Writes the specified log message to the output handle for the class instance.

WriteLnToFile ensures that the OnWidgetSetDebugLn routine is signalled (when assigned for the unit) to perform the write operation. If the message is handled in OnWidgetSetDebugLn, no additional actions are performed in the method.

Otherwise, the output handle is opened when not already assigned. If ActiveLogText is unassigned after trying to open the output handle, no additional actions are performed in the method.

The RTL WriteLn routine is called to write the value in S to the output handle for the TextRec.

When CloseLogFileBetweenWrites is set to True, the output handle is closed and released.

If an exception occurs during output to the handle, it is caught and the values in WriteFailedCount and LastWriteFailed are updated to reflect the error condition.

Log message written in the method. Logger class instance passed to the OnWidgetSetDebugLn handler. The name of the log file. This can be set by the application. Alternatively it can be determined according to ParamForLogFileName and EnvironmentForLogFileName Enables writing to STDOUT, if LogName is not set. Enable opening and closing the log for each write. Indicates whether logger output is directed to a File or the STDOUT device.

The property contains a value from the TLazLoggerWriteTarget enumeration.

lwtNone: A handle or output destination has not been or cannot be determined.
lwtTextFile: The output destination is a Text instance representing the file in LogName.
lwtStdOut: The output destination is the STDOUT device.

Contains the Text instance for the output destination, or Nil when unassigned. Indicates the cumulative number of failed write operations for the output handle.

WriteFailedCount is updated in methods which perform write operations to the output handle, such WriteToFile and WriteLnToFile. Its value is reset using the ResetWriteFailedCounter method.

Indicates if the last write attempt encountered an exception or otherwise failed.

The value is updated in methods which perform write operations to the output handle, like WriteToFile and WriteLnToFIle.

Performs file operations using a critical section.

TLazLoggerFileHandleThreadSave is a TLazLoggerFileHandle descendant which implements a threaded file logger. TLazLoggerFileHandleThreadSave uses a TRTLCriticalSection class instance to lock the log file during file output operations. Requires that DoOpenFile is called by the main application thread. Otherwise the filehandle may get closed.

Constructor for the class instance.

Initializes the critical section used to protect write access to the handle for the class instance. Calls the inherited constructor prior to exiting from the method.

Destructor for the class instance.

Finalizes the critical section used to protect write access to the handle for the class instance. Calls the inherited destructor prior to exiting from the method.

Re-implements the method to use a critical section to protect write access to the handle for the class instance. Re-implements the method to use a critical section to protect write access to the handle for the class instance. Represents a File handle for logger operations queued in the main thread.

TLazLoggerFileHandleMainThread is a TLazLoggerFileHandle descendant which implements a file-based logger which queues file operations for the main thread in an application.

Constructor for the class instance.

Initializes the critical section used to protect write access to the handle for the class instance. Calls the inherited constructor prior to exiting from the method.

Destructor for the class instance.

Ensures the event handler used to write log messages in the main thread is removed from the thread manager. Calls the inherited destructor, and finalizes the critical section used to protect write access to the handle for the class instance.

Re-implements the method used to write log messages in the main thread for the application. Re-implements the method used to write log messages in the main thread for the application. Implements a logger which uses a file or the STDOUT device as the destination for log messages.

TLazLoggerFile is a TLazLoggerWithGroupParam descendant. It provides properties and methods needed to implement the handle-based logger class. It also provides event handlers used to perform DbgOut and DebugLn write events (when assigned).

TLazLoggerFileHandle provides a FileHandle property (TLazLoggerFileHandle instance) to represent the handle for the output device or file.

Various methods from ancestor classes are overridden to perform actions needed to format log messages for the destination.

Use LogName to specify a file name where log messages are stored.

Use the UseStdOut property to indicate that the STDOUT device is used (instead of a file name) to output the log messages for the class instance. Set LogName to an empty string ('') to ensure that STDOUT is used.

Use CloseLogFileBetweenWrites to force the output handle to be closed and released when a write operation is completed. This is the default behavior for the WinCE platform.

Performs actions to initialize the file-based logger class instance. Performs actions to finalize the file-based logger class instance. Increases the indentation (nesting) level for messages written using the logger. Decreases the indentation (nesting) level for messages written using the logger. Performs actions needed to create an indentation spacing string for the current nesting level.

Calls CreateIndent to prepare the string prefix inserted at the start of a log message.

Creates a string with spaces characters used as the prefix for log messages. Gets the value for the indexed BlockHandler property. Value for the indexed BlockHandler property. Ordinal position for the TLazLoggerBlockHandler value in the property. Removes all block handlers for the logger class created using AddBlockHandler.

Calls RemoveBlockHandler to remove each of the block handlers from the internal list of handlers, and releases the references to the block handler class instances.

Performs actions needed to implement the DbgOut method for the logger class type.

DoDbgOut is overridden in TLazLoggerFile to ensure that log message formatting and event handlers are used when the DbgOut method is called. Space characters are inserted at the start of the log message to reflect the current nesting level for the logger class. For multi-threaded usage, an internal critical section is used to protect the current nesting level while preparing the indentation spaces for the message.

DoDbgOut signals the OnDbgOutEx (when assigned) allow user-specified actions to be performed to handle the indentation level and information for the logger group specified in AGroup. If the log entry is handled in the OnDbgOutEx event handler, no additional actions are performed in the method.

The OnDbgOut event handler is signalled (when assigned) to allow user-specified actions to be performed when writing the log message. If the write operation is handled in the event handler, no additional actions are performed in the method. Otherwise, the WriteToFile method in FileHandle is called to write the log message to the device or file.

Modified in LazUtils version 3.0 to write logger group information. Log message formatted and written in the method. Performs actions needed to implement the DebugLn method for the logger class type. Modified in LazUtils version 3.0 to include the AGroup argument. Modified in LazUtils version 3.0 to include the AGroup argument. TLazLoggerFileHandle instance representing the file or device where log messages are written.

Resources are allocated for the member when the FileHandle property is accessed. At run-time, a TLazLoggerFileHandleMainThread instance is created and assigned to the member for the property.

Read and write access to some property values in the logger class instance are re-directed to the corresponding properties in FileHandle, including:

LogName
UseStdOut
CloseLogFileBetweenWrites

Methods in TLazLoggerFile may call the corresponding methods in FileHandle which implement the methods, including:

DoInit
DoFinish
DoDbgOut
DoDebugLn
DoDebugLnStack

Constructor for the class instance.

Creates allocates and initializes resources for the block handler list and a critical section used in the class instance. The default value for CurrentIndentLevel is set to 0.

Create ensures that ParamForLogFileName and EnvironmentForLogFileName are set to the default values for the platform or widgetset. For WinCE, that requires the properties to be set empty strings ('').

Destructor for the class instance.

Destroy is the overridden destructor for the class instance. It ensures that all block handlers assigned to the class instance are removed from the internal list and released. The inherited destructor is called to finalize the logger class instance.

Destory frees resources allocated for the FileHandle property, the internal list used for block handlers, and the critical section used to protect access to the current nesting level.

Implements object persistence for the TLazLoggerFile class type.

Assign is an overridden method used to implement object persistence for the TLazLoggerFile class type.

Src is the TLazLogger instance with the values copied into the current class instance. The inherited method is called to handle group parameters and block handlers assigned in Src.

When Src is derived from TLazLoggerFile, the following property values are also copied:

CloseLogFileBetweenWrites
EnvironmentForLogFileName
LogName
ParamForLogFileName
UseStdOut
OnDbgOut
OnDebugLn

These property values are not copied when Src is not derived from TLazLoggerFile.

TLazLogger instance with values copies in the method. Gets the current indentation (nesting) level for messages written using the logger.

Indicates the number of space characters prepended to a message to format the output for the logger class.

Current nesting level for the logger class instance. Name of the command line parameter that has the log file name for the class instance.

ParamForLogFileName is a command line parameter that may contain the name for the log file (if not already set). For example: --debug-log=/path/to/filename.ext.

If LogName is empty and ParamForLogFileName has been assigned, the command line will be checked for a parameter with the specified name. LogName will be set to the file name in the parameter, if found. The default value for the property is '--debug-log='. Please note that the dashes and equal sign must be present.

Name of the environment variable with the log file name for the class instance.

If LogName is empty and con not be found from ParamForLogFileName, then the environment variable specified will be checked. LogName will be set, if found.

An * character will be replaced with the value from param(0) (the name for the application).

The default value for the property is: '*_debuglog'.

Event handler signalled to write a full line in the log (DebugLn, DebugLnEnter or DebugLnExit).

OnDebugLn allows user-specified actions to be performed when writing a log message. Arguments passed to the event handler identify the log message and the logger class instance used for the operation. A Handled variable parameter is also provided that can be set to True to prevent the default action (writing to log) from being performed in the DoDebugLn method.

Event handler signalled to write a log message (DbgOut).

OnDbgOut allows user-specified actions to be performed when writing a log message. Arguments passed to the event handler identify the log message and the logger class instance used for the operation. A Handled variable parameter is also provided that can be set to True to prevent the default action (writing to log) from being performed in the DoDbgOut method.

Event handler signalled to generate an extended log message with log group information. Added in LazUtils version 3.0. Event handler signalled to generate an extended log message with log group information. Added in LazUtils version 3.0. Adds the specified block handler to the internal list of block handlers for the logger. Block handler added to the internal list of block handlers. Removes the specified block handler from the internal list of block handlers. Block handler removed from the internal list of block handlers. Gets the number of block handlers in the internal list. Number of block handler instances in the internal list. The qualified name for the log file where log messages are written.

The property value can be set by the application. Alternatively, it can be determined using ParamForLogFileName or EnvironmentForLogFileName.

Enables writing to STDOUT when LogName has not been assigned. Enables opening and closing the output handle for the logger following each write operation. Gets the value for the DebugLogger property. Value for the DebugLogger property. Sets the value for the DebugLogger property. New value for the DebugLogger property. Contains the class instance for the file-based logger.

DebugLogger is a TLazLoggerFile property with the class instance for the logger used to write its output to a file.