log4j.properties
,
log4j2.xml
, logback.xml
, ...), in a line similar to:(Log4j v1.x config) | log4j.appender.FILE.layout.ConversionPattern=%6p (%F:%L) - %m%n |
(Log4j v2.x XML config) | <PatternLayout pattern="%d{HH:mm:ss.SSS} [%thread] %-5level %logger{8} - %msg%n" /> |
(Logback XML config) | <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> |
LogMX calls "Tag" the sequence defined by:
|
%-20logger{4}
, %d{HH:mm:ss,SSS}
, %p
Conversion word / Option | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
caller{depth} caller{depth, evaluator-1, ... evaluator-n}{precision} |
[Logback only] Outputs location information of the caller which generated the logging event. The location information depends on the JVM implementation but usually consists of the fully qualified name of the calling method followed by the caller's source, the file name and line number between parentheses. A integer can be added to the caller conversion specifier's options to configure the depth of the information to be displayed. For example, %caller{2} would display the following excerpt: 0 [main] DEBUG - logging statement Caller+0 at mainPackage.sub.sample.Bar.sampleMethodName(Bar.java:22) Caller+1 at mainPackage.sub.sample.Bar.createLoggingRequest(Bar.java:17) And %caller{3} would display this other excerpt: 16 [main] DEBUG - logging statement Caller+0 at mainPackage.sub.sample.Bar.sampleMethodName(Bar.java:22) Caller+1 at mainPackage.sub.sample.Bar.createLoggingRequest(Bar.java:17) Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38) This conversion word can also use evaluators to test logging events against a given criterion before computing caller data. For example, using %caller{3, CALLER_DISPLAY_EVAL} will display three lines of stacktrace, only if the evaluator called CALLER_DISPLAY_EVAL returns a positive answer. Evaluators are described below. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
c{precision} lo{precision} logger{precision} |
Outputs the name of the logger that published the logging event. The logger conversion specifier can be optionally followed by precision specifier, which consists of a decimal integer, or a pattern starting with a decimal integer. If a precision specifier is given and it is an integer value, then only the corresponding number of right most components of the logger name will be printed. If the precision contains other non-integer characters then the name will be abbreviated based on the pattern. If the precision integer is less than one the right-most token will still be printed in full. By default the logger name is printed in full.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
C{precision} class{precision} |
Outputs the fully qualified class name of the caller issuing the logging request. This conversion specifier can be optionally followed by precision specifier, that follows the same rules as the logger name converter. Generating the class name of the caller (location information) is an expensive operation and may impact performance. Use with caution. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
contextName cn{precision} |
[Logback only] Outputs the name of the logger context to which the logger at the origin of the event was attached to. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
d{pattern} date{pattern} |
Outputs the date of the logging event. The date conversion specifier may be
followed by a set of braces containing a date and time pattern string per
SimpleDateFormat. The predefined formats are ABSOLUTE, COMPACT, DATE, ISO8601, ISO8601_BASIC, UNIX, and UNIX_MILLIS. You can also use a set of braces containing a time zone id per java.util.TimeZone.getTimeZone. If no date format specifier is given then ISO8601 format is assumed (this used ISO8601 format does not assume a 'T' character between the date and the time, unlike the strict ISO8601 format expects it).
%d{UNIX} outputs the UNIX time in seconds. %d{UNIX_MILLIS} outputs the UNIX time in milliseconds. The UNIX time is the difference, in seconds for UNIX and in milliseconds for UNIX_MILLIS, between the current time and midnight, January 1, 1970 UTC. While the time unit is milliseconds, the granularity depends on the operating system (Windows). This is an efficient way to output the event time because only a conversion from long to String takes place, there is no Date formatting involved. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ex|exception|throwable {["none" |"full" |depth |"short" |"short.className" |"short.fileName" |"short.lineNumber" |"short.methodName" |"short.message" |"short.localizedMessage"]} |
Outputs the Throwable trace bound to the LoggingEvent, by default this will output the full trace as one would normally find with a call to Throwable.printStackTrace(). You can follow the throwable conversion word with an option in the form %throwable{option}. %throwable{short} outputs the first line of the Throwable. %throwable{short.className} outputs the name of the class where the exception occurred. %throwable{short.methodName} outputs the method name where the exception occurred. %throwable{short.fileName} outputs the name of the class where the exception occurred. %throwable{short.lineNumber} outputs the line number where the exception occurred. %throwable{short.message} outputs the message. %throwable{short.localizedMessage} outputs the localized message. %throwable{n} outputs the first n lines of the stack trace. Specifying %throwable{none} or %throwable{0} suppresses output of the exception. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
F file |
Outputs the file name where the logging request was issued. Generating the file information (location information) is an expensive operation and may impact performance. Use with caution. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
highlight{pattern}{style} (Log4j syntax only) |
Adds ANSI colors to the result of the enclosed pattern based on the current event's logging level. The default colors for each level are:
The color names are ANSI names defined in the AnsiEscape class. The color and attribute names and are standard, but the exact shade, hue, or value.
You can use the default colors with: %highlight{%d [%t] %-5level: %msg%n%throwable} You can override the default colors in the optional {style} option. For example: %highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue} You can highlight only the a portion of the log event: %d [%t] %highlight{%-5level: %msg%n%throwable} You can style one part of the message and highlight the rest the log event: %style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable} You can also use the STYLE key to use a predefined group of colors: %highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
highlight(pattern) (Logback syntax only) |
The %highlight conversion word prints its sub-pattern in bold-red for events of level ERROR, in red for WARN, in BLUE for INFO, and in the default color for other levels. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
black|red|green|yellow |blue|magenta|cyan|white |gray|boldRed|boldGreen |boldYellow|boldBlue |boldMagenta|boldCyan |boldWhite(pattern) (Logback syntax only) |
These conversions words print its sub-pattern using their color name. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
K{key} map{key} MAP{key} |
Outputs the entries in a MapMessage, if one is present in the event. The K conversion character can be followed by the key for the map placed between braces, as in %K{clientNumber} where clientNumber is the key. The value in the Map corresponding to the key will be output. If no additional sub-option is specified, then the entire contents of the Map key value pair set is output using a format {{key1,val1},{key2,val2}} |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
l location |
Outputs location information of the caller which generated the logging event. The location information depends on the JVM implementation but usually consists of the fully qualified name of the calling method followed by the callers source the file name and line number between parentheses. Generating location information is an expensive operation and may impact performance. Use with caution. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
L line |
Outputs the line number from where the logging request was issued. Generating line number information (location information) is an expensive operation and may impact performance. Use with caution. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
m msg message |
Outputs the application supplied message associated with the logging event. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
M method |
Outputs the method name where the logging request was issued. Generating the method name of the caller (location information) is an expensive operation and may impact performance. Use with caution. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
marker | The name of the marker, if one is present. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
n |
Outputs the platform dependent line separator character or characters. This conversion character offers practically the same performance as using non-portable line separator strings such as "\n", or "\r\n". Thus, it is the preferred way of specifying a line separator. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nopex nopexception |
[Logback only] Although it pretends to handle stack trace data, this conversion word does not output any data, thus, effectively ignoring exceptions. The %nopex conversion word allows the user to override
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
p|le|level{level=label, level=label, ...} p|le|level{length=n} p|le|level{lowerCase=true|false} |
Outputs the level of the logging event. You provide a level name map in the form "level=value, level=value" where level is the name of the Level and value is the value that should be displayed instead of the name of the Level. For example: %level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info} Alternatively, for the compact-minded: %level{WARN=W, DEBUG=D, ERROR=E, TRACE=T, INFO=I} More succinctly, for the same result as above, you can define the length of the level label: %level{length=1} You can combine the two kinds of options: %level{ERROR=Error, length=2} Finally, you can output lower-case level names (the default is upper-case): %level{lowerCase=true} |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
property{key} | [Logback only] Outputs the value associated with a property named
key. The the relevant docs on how to define ion
entitled define
variables and variable
scopes.
If key is not a property of
the logger context, then key will be looked up in the
System properties.
There is no default value for key. If it is omitted, the returned value will be "Property_HAS_NO_KEY", expliciting the error condition. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
r relative |
Outputs the number of milliseconds elapsed since the JVM was started until the creation of the logging event. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
replace{pattern}{regex}{substitution} (Log4j syntax only) |
Replaces occurrences of 'regex', a regular expression, with its replacement 'substitution' in the string resulting from evaluation of the pattern 'pattern'. For example, "%replace{%msg}{\s}{}" will remove all spaces contained in the event message. The pattern 'pattern' can be arbitrarily complex and in particular can contain multiple conversion keywords. For instance, "%replace{%logger %msg}{\.}{/}" will replace all dots in the logger or the message of the event with a forward slash. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
replace(pattern){regex,substitution} (Logback syntax only) |
Replaces occurrences of 'regex', a regular expression, with its replacement 'substitution' in the string resulting from evaluation of the pattern 'pattern'. For example, "%replace(%msg){'\s', ''}" will remove all spaces contained in the event message. The pattern 'pattern' can be arbitrarily complex and in particular can contain multiple conversion keywords. For instance, "%replace(%logger %msg){'\.', '/'}" will replace all dots in the logger or the message of the event with a forward slash. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
rEx|rException|rThrowable{ "none"|"short"|"full"|depth} rEx|rException|rThrowable{ "none"|"short"|"full"|depth, filters(packages)} |
The same as the %throwable conversion word but the stack trace is printed starting with the first exception that was thrown followed by each subsequent wrapping exception. The throwable conversion word can be followed by an option in the form %rEx{short} which will only output the first line of the Throwable or %rEx{n} where the first n lines of the stacktrace will be printed. The conversion word can also be followed by "filters(packages)" where packages is a list of package names that should be suppressed from stack traces. Specifying %rEx{none} or %rEx{0} will suppress printing of the exception. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
rootException{depth} rootException{depth, evaluator-1, ..., evaluator-n} |
[Logback only] The %rootException converter admits the same optional parameters as the %xException converter described above, including depth and evaluators. It outputs also packaging information. In short, %rootException is very similar to %xException, only the order of exception output is reversed. Tomasz Nurkiewicz, the author of %rootException converter, documents his contribution in a blog entry entitled "Logging exceptions root cause first". |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sn sequenceNumber |
Includes a sequence number that will be incremented in every event. The counter is a static variable so will only be unique within applications that share the same converter Class object. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
style{pattern}{ANSI style} |
Uses ANSI escape sequences to style the result of the enclosed pattern. The style can consist of a comma separated list of style names from the following table.
For example: %style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green} You can also combine styles: %d %highlight{%p} %style{%logger}{bright,cyan} %C{1.} %msg%n You can also use % with a color like %black, %blue, %cyan, and so on. For example: %black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable} |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
t thread |
Outputs the name of the thread that generated the logging event. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
x NDC |
Outputs the Thread Context Stack (also known as the Nested Diagnostic Context or NDC) associated with the thread that generated the logging event. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X{key} mdc{key} MDC{key} |
Outputs the Thread Context Map (also known as the Mapped Diagnostic Context or MDC) associated with the thread that generated the logging event. The X conversion character can be followed by the key for the map placed between braces, as in %X{clientNumber} where clientNumber is the key. The value in the MDC corresponding to the key will be output. If no additional sub-option is specified, then the entire contents of the MDC key value pair set is output using a format {{key1,val1},{key2,val2}} See the ThreadContext class for more details. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
u{"RANDOM" | "TIME"} uuid |
Includes either a random or a time-based UUID. The time-based UUID is a Type 1 UUID that can
generate up to 10,000 unique ids per millisecond, will use the MAC address of each host, and to
try to insure uniqueness across multiple JVMs and/or ClassLoaders on the same host a
random number between 0 and 16,384 will be associated with each instance of the UUID generator
Class and included in each time-based UUID generated. Because time-based UUIDs contain
the MAC address and timestamp they should be used with care as they can cause a security
vulnerability. Note : Since LogMX v5.1.0, the tag %u{UserDefinedField} (as defined in LogMX v5.0.x and older) is replaced with %mx{UserDefinedField}. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
xEx|xException|xThrowable{ "none"|"short"|"full"|depth} xEx|xException|xThrowable{ "none"|"short"|"full"|depth, filters(packages)} |
The same as the %throwable conversion word but also includes class packaging information. At the end of each stack element of the exception, a string containing the name of the jar file that contains the class or the directory the class is located in and the "Implementation-Version" as found in that jar's manifest will be added. If the information is uncertain, then the class packaging data will be preceded by a tilde, i.e. the '~' character. The throwable conversion word can be followed by an option in the form %xEx{short} which will only output the first line of the Throwable or %xEx{n} where the first n lines of the stacktrace will be printed. The conversion word can also be followed by "filters(packages)" where packages is a list of package names that should be suppressed from stack traces. Specifying %xEx{none} or %xEx{0} will suppress printing of the exception. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mx{FieldName} |
[LogMX-specific conversion word] Used to add a named user-defined log entry field.
The name of this new field must be specified in the associated option (i.e. between |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
% | The sequence %% outputs a single percent sign. |
You may need to specify the data type of each Tag because sorting log entries according to this Tag may be wrong for your use case: by default, all fields are Strings, so LogMX sorts your log entries using alphanumeric order. That means that "a" will come before "b" but also that "1000" will come before "9". If you know that a log entry field will always contain numeric data, you can use the following Tag syntax to enforce a specific type to be used by LogMX:
Option | Meaning | Example of data |
---|---|---|
%mx{NumberOfThreads::int} | User-defined field named "NumberOfThreads" containing only integers: digits (0~9) and the optional "-" prefix for negative numbers | 204 |
%mx{Rate::double} | User-defined field named "Rate" containing floating-point numbers: digits (0~9), an optional "-" prefix for negative numbers, and an optional "." before the fractional part | 56.55 |
%mx{Client} | User-defined field named "Client" containing any characters | John-Doe-1245 |
By default the relevant information is output as is. However, with the aid of format modifiers it is possible to change the minimum field width, the maximum field width and justification.
The optional format modifier is placed between the percent sign and the conversion character.
The first optional format modifier is the left justification flag which is just the minus (-) character. Then comes the optional minimum field width modifier. This is a decimal constant that represents the minimum number of characters to output. If the data item requires fewer characters, it is padded on either the left or the right until the minimum width is reached. The default is to pad on the left (right justify) but you can specify right padding with the left justification flag. The padding character is space. If the data item is larger than the minimum field width, the field is expanded to accommodate the data. The value is never truncated.
This behavior can be changed using the maximum field width modifier which is designated by a period followed by a decimal constant. If the data item is longer than the maximum field, then the extra characters are removed from the beginning of the data item and not from the end. For example, it the maximum field width is eight and the data item is ten characters long, then the first two characters of the data item are dropped. This behavior deviates from the printf function in C where truncation is done from the end.
Below are various format modifier examples for the "category" conversion word (i.e. %c).
Format modifier | left justify | minimum width | maximum width | comment |
---|---|---|---|---|
%20c | false | 20 | none | Left pad with spaces if the category name is less than 20 characters long. |
%-20c | true | 20 | none | Right pad with spaces if the category name is less than 20 characters long. |
%.30c | NA | none | 30 | Truncate from the beginning if the category name is longer than 30 characters. |
%20.30c | false | 20 | 30 | Left pad with spaces if the category name is shorter than 20 characters. However, if category name is longer than 30 characters, then truncate from the beginning. |
%-20.30c | true | 20 | 30 | Right pad with spaces if the category name is shorter than 20 characters. However, if category name is longer than 30 characters, then truncate from the beginning. |