Log4mql (MT4) – library MetaTrader 4

Log4mql – a logging library similar to Log4j but for MQL.

Installation

• Unzip log4mqllib.zip to your Libraries folder
• Put log4mqllib.mqh into your Include folder
• Use one of the samples that shows the usage

Inputs

• Loglevel, supports Trace, Debug, Info, Warn, Error and Fatal
• Logmode, either Journal only, File only or Journal+File (rewrite or append)
• Logfile name, can contain %prgname, %date, %period or %symbol, can be prefixed with ‘common:’ for common folder
• Logfile textmode, either Ansi 8-bit or Unicode 16-bit
• Logfile roll policy, either Daily, 100K chunks, or no roll
• File roll pattern, like file name and also may contain %i, a roll counter
• Message pattern, a log4j-like log message pattern.

Pattern specifiers

The message pattern will be used to format each log message. Such a conversion pattern may be an arbitrary combination of plain text and conversion specifiers. Like with log4j, a specifier is recognized by its leading ‘%’ character and may be followed by arguments enclosed in braces ‘{…}’, see the table below.

Specifier	Description
%ask  %ask{SYMB}	The current symbol’s Ask.
%bid  %bid{SYMB}	The current symbol’s Bid.
%class	Class name of log event producer.
%date  %date{datespec}	The current server time, use datespec to format.
%digits	The current symbol’s digits.
%file	Source filename of log event location.
%func	Function name of log event producer.
%funcsig	Function signature of log event producer.
%lasterr	Last error code as known from GetLastError().
%level  %level{levelspec}	The current event’s log level.
%line	Line number of the log event location.
%local  %local{datespec}	The current local time, use datespec to format.
%location	Function name, file and line of log event location.
%logger	The logger’s name.
%micro	Microseconds from GetMicrosecondCount().
%message  %msg	The log message.
%method	Function short name of log event producer.
%n	A newline.
%nano	Nanoseconds (micro*1000).
%period	The current timeframe (M1 M5 etc).
%prgname	Advisor/indicator/script name.
%relative  %ticks	Milliseconds from GetTickCount().
%sequenceNumber  %seqnr	A sequence number increased by each log event.
%symbol	The current symbol name.
%%	The sequence %% outputs a single percent sign.

Examples: 

%date %level  %msg	2020.05.05 00:01:00 DEBUG  Log session started
%06.6micro [%.-3level] %method – %msg	000717 [DEB] CLogManager – Log session started
%06.6micro [%.-1level] %func – %msg	000717 [D] CLogManager::CLogManager – Log session started

 

Date specifiers

Any %date (and %local) field may be annotated with a date/time specification argument.

Specifier	Description
d	The day of the month, from 1 through 31.
dd	The day of the month, from 01 through 31.
ddd	The abbreviated name of the day of the week.
dddd	The full name of the day of the week.
h	The hour, using a 12-hour clock from 1 to 12.
hh	The hour, using a 12-hour clock from 01 to 12.
H	The hour, using a 24-hour clock from 0 to 23.
HH	The hour, using a 24-hour clock from 00 to 23.
mm	The minute, from 00 through 59.
M	The month, from 1 through 12.
MM	The month, from 01 through 12.
MMM	The abbreviated name of the month.
MMMM	The full name of the month.
ss	The second, from 00 through 59.
tt	The AM/PM designator.
yy	The year, from 00 to 99.
yyyy	The year as a four-digit number.

Example: %date{d.MMM h:mm:sstt} yields 5.May 1:01:00AM

Level specifiers

The %level field may be annotated with a level specification argument. It’s a comma-separated list of key=value pairs according to below table.

Specifier	Description
length=d	set levels maximum length to d characters
lowerCase=true (false)	set levels to lower (upper) case
TRACE=Trace (other)	set trace level name to Trace (or any other string)
DEBUG=…	like above
INFO=…	“
WARN=…	“
ERROR=…	“
FATAL=…	“

Example: %level{length=3,WARN=WRN,ERROR=Error,FATAL=Fatal} yields the names: TRA, DEB, INF, WRN, Error, Fatal

Format modifiers

Any pattern conversion specifier may be formatted to adjust its field width and justification. The same modifiers as known from log4j apply.

Format modifier	Description
%20c	Left pad with spaces if the field is less than 20 characters long.
%020c	Left pad with zeroes if the field is less than 20 characters long.
%-20c	Right pad with spaces if the field is less than 20 characters long.
%.30c	Truncate from the beginning if the field is longer than 30 characters.
%.-30c	Truncate from the end if the field is longer than 30 characters.
%20.30c	Left pad with spaces if the field is shorter than 20 characters.  However, if it’s longer than 30 characters, then truncate from the beginning.
%-20.30c	Right pad with spaces if the field is shorter than 20 characters.  However, if it’s longer than 30 characters, then truncate from the beginning.
%-20.-30c	Right pad with spaces if the field is shorter than 20 characters.  However, if it’s longer than 30 characters, then truncate from the end.

File Rolling

Depending on the chosen configuration, log files may be closed, renamed and reopened at certain points in time, which is called file rolling. The name of the rolled (previous) log file will be derived from the configured file roll pattern, and the name of the new log file will be derived from the log file name specifier again.

Filename Specifiers:

For specification of log file name and roll pattern the following conversion specifiers are supported.

Filename Specifier	Description
%date  %date{datespec}	The current local time, use datespec to format.
%i  %i{rollspec}	The roll counter, use rollspec to control the counter’s behavior.
%period	The current timeframe (M1 M5 etc).
%prgname	Advisor/indicator/script name.
%symbol	The current symbol name.

Roll spec:

A counter may be controlled by its roll specification. It’s a comma-separated list of key=value pairs that specifies the minimum, maximum and increment behavior.

Counter’s roll specifiers	Description
min=a	Set counter’s minimum value to a. Default is 1.
max=b	Set counter’s maximum value to b. Default is 3.
fileIndex=min (or max, or nomax)	Set counter’s increment behavior. Default is ‘max’.

Numbering of file via roll counter:

Like in the log4j default rollover strategy, three file numbering schemes are supported. To illustrate how it works, suppose that the min attribute is set to 1, the max attribute is set to 3, the file name is “%prgname.log”, and the file name pattern is “%prgname-%i.log”.

Counter behavior is ‘max’, the default:

Number of rollovers	Active log file	Archived log files	Description
0	ea.log	–	All logging is going to the initial file.
1	ea.log	ea-1.log	During the first rollover ea.log is renamed to ea-1.log. A new ea.log file is created and starts being written to.
2	ea.log	ea-2.log, ea-1.log	During the second rollover ea.log is renamed to ea-2.log. A new ea.log file is created and starts being written to.
3	ea.log	ea-3.log, ea-2.log, ea-1.log	During the third rollover ea.log is renamed to ea-3.log. A new ea.log file is created and starts being written to.
4	ea.log	ea-3.log, ea-2.log, ea-1.log	In the fourth and subsequent rollovers, ea-1.log is deleted, ea-2.log is renamed to ea-1.log, ea-3.log is renamed  to ea-2.log and ea.log is renamed to ea-3.log. A new ea.log file is created and starts being written to.

Counter behavior is set to ‘min’: (like in %i{fileIndex=min})

Number of rollovers	Active log file	Archived log files	Description
0	ea.log	–	All logging is going to the initial file.
1	ea.log	ea-1.log	During the first rollover ea.log is renamed to ea-1.log. A new ea.log file is created and starts being written to.
2	ea.log	ea-1.log, ea-2.log	During the second rollover ea-1.log is renamed to ea-2.log and ea.log is renamed to ea-1.log.  A new ea.log file is created and starts being written to.
3	ea.log	ea-1.log, ea-2.log, ea-3.log	During the third rollover ea-2.log is renamed to ea-3.log, ea-1.log is renamed to ea-2.log and ea.log is renamed to ea-1.log.  A new ea.log file is created and starts being written to.
4	ea.log	ea-1.log, ea-2.log, ea-3.log	In the fourth and subsequent rollovers, ea-3.log is deleted, ea-2.log is renamed to ea-3.log, ea-1.log is renamed to ea-2.log  and ea.log is renamed to ea-1.log. A new ea.log file is created and starts being written to.

If the counter behavior is set to ‘nomax’ there will be no limit in increasing the counter on rollovers, and the files will be created in ascending order (ea-1.log, ea-2.log etc).

Additional notes:

• Field width specifiers can be applied (like in %03i).
  
• Any filename pattern may start with ‘common:‘ to indicate MetaTrader’s common data folder location.
• In case the log or roll file name does not end with a suffix, ‘.log‘ is added.
• Compression of files (via .gz etc) is not implemented yet.