Pattern Layout :: Apache Log4j (original) (raw)

This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.

Plugin attributes

Pattern Layout plugin configuration accepts the following attributes:

charset

Charset used for encoding the produced JSON into bytes

pattern

A composite pattern string of one or more Pattern converters.pattern and patternSelector are mutually exclusive, that is, only one can be specified.

| | If the provided pattern does not contain an exception converter and alwaysWriteExceptions is not disabled, an implicit %xEx is appended to the pattern. | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

patternSelector

A component that analyzes information in the LogEvent and determines which pattern should be used to format the event.patternSelector and pattern are mutually exclusive, that is, only one can be specified.

replace

Allows portions of the resulting String to be replaced. If configured, the replace element must specify the regular expression to match and the substitution.

alwaysWriteExceptions

If true and the user-provided pattern does not contain an exception converter, an implicit %xEx pattern is appended. This means that if you do not include a way to output exceptions in your pattern, the default exception formatter will be added to the end of the pattern. Setting this to false disables this behavior and allows you to exclude exceptions from your pattern output.

The optional header to include at the top of each log file

The optional footer to include at the bottom of each log file

disableAnsi

If true, do not output ANSI escape codes.

noConsoleNoAnsi

If true and System.console() is null, do not output ANSI escape codes

Plugin elements

Pattern Layout plugin configuration accepts the following elements:

RegexReplacement

Allows portions of the resulting String to be replaced. This performs a function similar to the replace converter but applies to the whole message while the converter only applies to the String its pattern generates.

It supports following attributes:

PatternSelector

Pattern Layout can be configured with a PatternSelector to allow it to choose a pattern to use based on attributes of the log event or other factors. A PatternSelector will normally be configured with a defaultPattern attribute, which is used when other criteria don’t match, and a set of PatternMatch elements that identify the various patterns that can be selected.

Predefined PatternSelectors are as follows:

LevelPatternSelector

The LevelPatternSelector selects patterns based on the level of the log event. Its configuration is similar to MarkerPatternSelector, with the difference that the key attribute of the PatternMatch element is matched against the log level associated with the log event.

MarkerPatternSelector

The MarkerPatternSelector selects patterns based on the marker included in the log event. If the marker in the log event is equal to or is an ancestor of the name specified on the key attribute of the PatternMatch element, then the pattern specified on that PatternMatch element will be used.

Below is a MarkerPatternSelector example switching from the [%-5level] %c{1.} %msg%n default pattern to [%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n, if the marker matches to FLOW:

• XML
• JSON
• YAML
• Properties

<PatternLayout>
  <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n">
    <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
  </MarkerPatternSelector>
</PatternLayout>

"PatternLayout": {
  "MarkerPatternSelector": {
    "defaultPattern": "[%-5level] %c{1.} %msg%n",
    "PatternMatch": [
      {
        "key": "FLOW",
        "pattern": "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"
      }
    ]
  }
}

PatternLayout:
  MarkerPatternSelector:
    defaultPattern: "%-5p [%t]: %m%n"
    PatternMatch:
      - key: "FLOW"
        pattern: "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"

appender.0.layout.type = PatternLayout
appender.0.layout.patternSelector.type = MarkerPatternSelector
appender.0.layout.patternSelector.defaultPattern = %-5p [%t]: %m%n
appender.0.layout.patternSelector.patternMatch.0.type = PatternMatch
appender.0.layout.patternSelector.patternMatch.0.key = FLOW
appender.0.layout.patternSelector.patternMatch.0.pattern = [%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n

ScriptPatternSelector

Below is an example using a script determining NoLocation or Flow keywords from a log event and matching it against two PatternMatches to configure the effective pattern:

• XML
• JSON
• YAML
• Properties

<PatternLayout>
  <ScriptPatternSelector defaultPattern="[%-5level] %c{1.} %C{1.}.%M.%L %msg%n">
    <Script name="BeanShellSelector" language="bsh"><![CDATA[
      if (logEvent.getLoggerName().equals("NoLocation")) {
        return "NoLocation";
      } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
        return "Flow";
      } else {
        return null;
      }]]>
    </Script>
    <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/>
    <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
  </ScriptPatternSelector>
</PatternLayout>

"PatternLayout": {
  "ScriptPatternSelector": {
    "defaultPattern": "[%-5level] %c{1.} %msg%n",
    "Script": {
      "name": "BeanShellSelector",
      "language": "bsh",
      "scriptText": "if (logEvent.getLoggerName().equals(\"NoLocation\")) { return \"NoLocation\"; } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf(\"FLOW\")) { return \"Flow\"; } else { return null; }"
    },
    "PatternMatch": [
      {
        "key": "NoLocation",
        "pattern": "[%-5level] %c{1.} %msg%n"
      },
      {
        "key": "Flow",
        "pattern": "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"
      }
    ]
  }
}

PatternLayout:
  ScriptPatternSelector:
    defaultPattern: "%-5p [%t]: %m%n"
    Script:
      name: "BeanShellSelector"
      language: "bsh"
      scriptText: |
        if (logEvent.getLoggerName().equals("NoLocation")) {
          return "NoLocation";
        } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
          return "Flow";
        } else {
          return null;
        }
    PatternMatch:
      - key: "NoLocation"
        pattern: "[%-5level] %c{1.} %msg%n"
      - key: "Flow"
        pattern: "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"

appender.0.layout.type = PatternLayout
appender.0.layout.patternSelector.type = ScriptPatternSelector
appender.0.layout.patternSelector.defaultPattern = [%-5level] %c{1.} %C{1.}.%M.%L %msg%n
appender.0.layout.patternSelector.script.type = Script
appender.0.layout.patternSelector.script.name = BeanShellSelector
appender.0.layout.patternSelector.script.language = bsh
appender.0.layout.patternSelector.script.scriptText =\
if (logEvent.getLoggerName().equals("NoLocation")) {\
  return "NoLocation";\
} else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {\
  return "Flow";\
} else {\
  return null;\
}
appender.0.layout.patternSelector.0.type = PatternMatch
appender.0.layout.patternSelector.0.key = NoLocation
appender.0.layout.patternSelector.0.pattern = [%-5level] %c{1.} %msg%n
appender.0.layout.patternSelector.1.type = PatternMatch
appender.0.layout.patternSelector.1.key = Flow
appender.0.layout.patternSelector.1.pattern = [%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n

Pattern converters

The Pattern Layout conversion pattern is composed of literal text and format control expressions called conversion specifiers – refer to Usage for details.Plugins implementing PatternConverter are admitted to the pattern converter registry of Pattern Layout, and used to resolve the conversion specifiers.

The predefined set of pattern converters will be shared in the following sections. While doing so, their syntax will be documented in a certain notation. Consider the following example for the syntax of Date pattern converter:

%d{dateSpecifier}[{timezone}]

This means that

• %d identifies the associated pattern converter
• {dateSpecifier} indicates that the converter accepts a required dateSpecifier parameter
• [{timezone}] indicates that the converter accepts an optional timezone parameter

If you want to have %d{something} literal in your pattern without matching for the actual %d pattern converter, you can escape the % as follows: %%d{something}.

Class

Outputs the fully qualified class name of the caller issuing the logging request

C{precision}
class{precision}

This conversion specifier can be optionally followed by a precision specifier that follows the same rules as the logger name converter.

| | Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.The logger name converter can generally be used as a zero-cost substitute. See this section of the layouts page for details. | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

Date

Outputs the instant of the log event

d{pattern}[{timezone}]
date{pattern}[{timezone}]

The date conversion specifier may be followed by a set of braces containing a date and time formatting pattern per DateTimeFormatter. The predefined named formats are:

You can also use a set of braces containing a time zone id per TimeZone#getTimeZone(String). If no date format specifier is given, then the DEFAULT format is used.

You can also define custom date formats, see following examples:

%d{UNIX} outputs the epoch time in seconds, i.e., the difference in seconds between the current time and 1970-01-01 00:00:00 (UTC).%d{UNIX_MILLIS} outputs the epoch time in milliseconds.

Note that the granularity of the sub-second formatters depends on the platform. Users may revert to a millisecond-precision clock when running on Java 9 by setting the log4j2.clock system property to SystemMillisClock.

| | Except UNIX and UNIX_MILLIS named patterns, the rest of the date & time formatters are not garbage-free. | | ------------------------------------------------------------------------------------------------------------ |

Encode

Encodes and escapes special characters suitable for output in specific markup languages

enc{pattern}{[HTML|XML|JSON|CRLF]}
encode{pattern}{[HTML|XML|JSON|CRLF]}

By default, this encodes for HTML if only one option is specified. The second option is used to specify which encoding format should be used.

A typical usage would encode the message (i.e., %enc{%m}), but the input could come from other locations as well (e.g., from a Thread Context entry: %enc{%mdc{key}}).

Using the HTML encoding format, the following characters are replaced:

Using the XML encoding format, this follows the escaping rules specified by the XML specification:

Using the JSON encoding format, this follows the escaping rules specified by RFC 4627 section 2.5:

| | If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement structured logging using Pattern Layout – please, don’t!Use JSON Template Layout instead. | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

Using the CRLF encoding format, the following characters are replaced:

End-of-batch

Outputs the EndOfBatch status of the log event as true or false

Equals

Replaces occurrences of a string (test) with its replacement (substitution) in the string resulting from the evaluation of the pattern:

equals{pattern}{test}{substitution}
equalsIgnoreCase{pattern}{test}{substitution}

For example, %equals{[%marker]}{[]}{} will replace [] strings produced by events without markers with an empty string.

The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.

Exception

Outputs information extracted from the Throwable attached to the log event. It features two modes:

1. Rendering the exception stack trace (the default mode)
2. Extracting an exception property (message, class name, line number, etc.)

| | Exception converter is not garbage-free. | | ------------------------------------------- |

Exception stack trace

In this mode, the exception stack trace will be rendered according to the configuration provided.

| | All rendered exception stack traces are ensured to be prefixed with a new line obtained using System.lineSeparator(). | | ------------------------------------------------------------------------------------------------------------------------ |

ex|exception|throwable
  { "none"
  | "short"
  | depth
  | "full"
  }
  {filters(package,package,...)}
  {separator(text)}
  {suffix(pattern)}

If this mode is employed without any configuration, the output will be identical to the one obtained from Throwable#printStackTrace().

none

Suppress the output of the converter

short

Outputs the first two lines of the stack trace (analogous to %ex{2})

depth

Outputs the first depth lines of the stack trace (%ex{0} is analogous to %ex{none})

full

Outputs the complete stack trace (analogous to no configuration)

filters(package,package,…​)

Suppresses stack trace elements of classes located in packages whose names start with the package names provided. Suppressed stack trace elements will be denoted in the output. For instance, %ex{filters(org.junit)} can be used to suppress JUnit classes in the rendered stack trace.

separator(text)

suffix(pattern)

You can change the used line separator in multiple ways:

• Use separator(text) to set the separator string literal. It defaults to System.lineSeparator(). The contents of text will be rendered verbatim without being subject to any processing.
• suffix(pattern) is identical to {separator(text)} with the exception that the provided pattern will be processed as a Pattern Layout conversion pattern before being rendered. Exception-rendering directives in the pattern (%ex, %rEx, etc.) will be discarded.

{separator(text)} and {suffix(pattern)} get concatenated to produce the effective line separator as follows:

String effectiveLineSeparator(String separator, String suffix, LogEvent event) {
    String formattedSuffix = format(suffix, event);
    return isNotBlank(formattedSuffix)
           ? (' ' + formattedSuffix + lineSeparator)
           : lineSeparator;
}

| | You are strongly advised to avoid using both separator(text) and suffix(pattern) at the same time; simply use one instead. | | ----------------------------------------------------------------------------------------------------------------------------- |

Exception property

In this mode, extracted attributes of the Throwable are injected verbatim. That is, no newlines, suffixes, prefixes, etc. will be added.

ex|exception|throwable
  { "short.className"
  | "short.fileName"
  | "short.lineNumber"
  | "short.methodName"
  | "short.message"
  | "short.localizedMessage"
  }

short.className

Class name of the first stack trace element in the causal chain

short.fileName

File name of the first stack trace element in the causal chain

short.lineNumber

Line number of the first stack trace element in the causal chain

short.methodName

Method name of the first stack trace element in the causal chain

short.message

Exception message

short.message

Localized exception message

Exception (Extended)

The same as the exception converter, but additionally includes class packaging information in the rendered stack traces.

xEx|xException|xThrowable
  [... same as the exception converter grammar ...]

Each stack trace element is suffixed with 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. If the information is uncertain, then the class packaging information will be preceded by a ~ (tilde) character.

File

Outputs the file name where the logging request was issued

| | Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free. See this section of the layouts page for details. | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

FQCN

Outputs the fully qualified class name of the logger

Highlight

Adds ANSI colors to the result of the enclosed pattern based on the current event’s logging level. Windows users should refer to ANSI styling on Windows.

highlight{pattern}{style}

The style parameter is a comma-separated list of the following directives:

Table 1. Style parameter syntax

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=magenta}

You can highlight only 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 of 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}

Level

Outputs the level of the log event

p|level{level=label, level=label, ...}
p|level{length=n}
p|level{lowerCase=true|false}

You provide a level name map in the form level=value, level=value, where the 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:

If the length is greater than a level name length, the layout uses the normal level name.

You can combine the two kinds of options:

%level{ERROR=Error, length=2}

This gives you the Error level name and all other level names of length 2.

Finally, you can output lower-case level names (the default is upper-case):

Line

Outputs the line number from where the log request was issued

| | Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free. See this section of the layouts page for details. | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

Location

Outputs location information of the caller which generates the logging event

LocationPatternConverter specifier grammar

The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.

Logger

Outputs the name of the logger that published the log event

c{precision}
logger{precision}

By default, the layout prints the logger name in full.

A logger conversion specifier can be optionally followed by a precision specifier, which consists of a decimal integer, or a pattern starting with a decimal integer.

• When the precision specifier is an integer value, it reduces the size of the logger name. If the number is positive, the layout prints the corresponding number of the rightmost logger name components. If negative, the layout removes the corresponding number of leftmost logger name components.
• If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern. If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
• If the precision contains any non-integer characters, then the layout abbreviates the name based on the pattern. If the precision integer is less than one, the layout still prints the right-most token in full.

See the table below for abbreviation examples:

Marker

Outputs the marker, if one is present

marker outputs the full name of the marker, including its parents. Whereas, markerSimpleName outputs the simple name of the marker without its parents.

Map

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 of the map corresponding to the key will be output. If no additional sub-option is specified, then all map entries are output using a {{key1,val1},{key2,val2}} format.

Max. length

Outputs the result of evaluating the given pattern and truncating the result

maxLen{pattern}{length}
maxLength{pattern}{length}

If the length is greater than 20, then the output will contain a trailing ellipsis. If the provided length is invalid, a default value of 100 is used.

For instance, %maxLen{%p: %c{1} - %m%notEmpty{ ⇒%ex{short}}}{160} will be limited to 160 characters with a trailing ellipsis.%maxLen{%m}{20} will be limited to 20 characters and no trailing ellipsis.

Message

Outputs the message associated with the log event

m{lookups}{ansi}
msg{lookups}{ansi}
message{lookups}{ansi}

Add {ansi} to render messages with ANSI escape codes. Windows users should refer to ANSI styling on Windows.

The default syntax for embedded ANSI codes is:

For example, to render the message Hello in green, use:

To render the message Hello in bold and red, use:

You can also define custom style names in the configuration with the syntax:

%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n

For example:

%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n

The call site can look like this:

logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());

Method

Outputs the method name where the logging request was issued

| | Capturing the source location information to generate the method name of the caller is an expensive operation, and is not garbage-free. See this section of the layouts page for details. | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

Nanoseconds

Outputs the result of System.nanoTime() at the time the log event was created

Not empty

Outputs the result of evaluating the pattern, if and only if all variables in the pattern are not empty

variablesNotEmpty{pattern}
varsNotEmpty{pattern}
notEmpty{pattern}

For example:

Process ID

Outputs the process ID, if supported by the underlying platform

pid{defaultValue}
processId{defaultValue}

An optional defaultValue may be specified to be shown, if the platform does not support process IDs.

Relative

Outputs the number of milliseconds elapsed since the JVM was started until the creation of the log event

Repeat

Produces a string containing the requested number of instances of the specified string

R{string}{count}
repeat{string}{count}

For example, %repeat{*}{2} will result in the string **.

Replace

Replaces occurrences of a regular expression (regex) with its replacement (substitution) in the string resulting from the evaluation of the pattern

replace{pattern}{regex}{substitution}

For example, %replace{%msg}{\s}{} will remove all spaces contained in the event message.

The 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.

Root exception

Same as the exception converter, but the stack trace causal chain is processed in reverse order.

rEx|rException|rThrowable
  [... same as the exception converter grammar ...]

| | Note that the inverted causal chain will not only affect the stack trace, but also extracted properties. That is, for instance, %rEx{short.className} and %ex{short.className} might yield different results. | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

Sequence number

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

Use ANSI escape sequences to style the result of the enclosed pattern. The syntax of the style_expression parameter is described in Style modifiers. Windows users should also refer to ANSI styling on Windows.

style{pattern}{style_expression}

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}{bold 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}

Thread context stack

Outputs the Thread Context stack (aka. Nested Diagnostic Context or NDC) associated with the thread that generated the log event

Thread context map

Outputs the Thread Context map (aka. Mapped Diagnostic Context or MDC) associated with the thread that generated the log event

X{key[,key2...]}
mdc{key[,key2...]}
MDC{key[,key2...]}

The X conversion character can be followed by one or more keys 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 a list of keys is provided, such as %X{name, number}, then each key that is present in the thread context will be output using the format {name=val1, number=val2}. The key/value pairs will be printed in the order they appear in the list.

If no sub-options are specified then the entire contents of the MDC key-value pair set is output using a format {key1=val1, key2=val2}. The key/value pairs will be printed in sorted order.

Thread ID

Outputs the ID of the thread that generated the log event

Thread name

Outputs the name of the thread that generated the log event

Thread priority

Outputs the priority of the thread that generated the log event

UUID

Includes either a random or a time-based UUID

u{RANDOM|TIME}
uuid{RANDOM|TIME}

The time-based UUID is a Type 1 UUID generated using the MAC address of each host To ensure uniqueness across multiple JVMs and/or class loaders 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. See also log4j2.uuidSequence. Because time-based UUIDs contain the MAC address and timestamp, they should be used with care.

Format modifiers

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. To use zeros as the padding character prepend the minimum field width with a zero.

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, if 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 String#format(), where truncation is done from the end.

Truncation from the end is possible by appending a minus character right after the period. In that case, if the maximum field width is eight and the data item is ten characters long, then the last two characters of the data item are dropped.

Below are various format modifier examples for the category conversion specifier.

Style modifiers

Pattern Layout supports styling your text using a variety of ANSI escape sequence, which can be used through the %highlight and %style pattern converters.

The generic syntax of a style expression is a space-separated list of:

• constants from theAnsiEscape class
• or expressions of the form #rrggbb or BG_#rrggbb, were r, g and b are hexadecimal digits

In EBNF form the syntax of a style expression is:

<style_expression> ::= <style_expression> ( " " <style_expression> )*
<style_modifier> ::= "#" <hex> <hex> <hex> <hex> <hex> <hex>
                   | "bg_#" <hex> <hex> <hex> <hex> <hex> <hex>
                   | <keyword>
<hex> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7"
        | "8" | "9" | "a" | "b" | "c" | "d" | "e" | "f"
<keyword> ::= "normal" | "bold" | "dim" | "underline"
            | "blink" | "reverse" | "hidden"
            | "black" | "bg_black" | "bright_black" | "bg_bright_black"
            | "red" | "bg_red" | "bright_red" | "bg_bright_red"
            | "green" | "bg_green" | "bright_green" | "bg_bright_green"
            | "yellow" | "bg_yellow" | "bright_yellow" | "bg_bright_yellow"
            | "blue" | "bg_blue" | "bright_blue" | "bg_bright_blue"
            | "magenta" | "bg_magenta" | "bright_magenta" | "bg_bright_magenta"
            | "cyan" | "bg_cyan" | "bright_cyan" | "bg_bright_cyan"
            | "white" | "bg_white" | "bright_white" | "bg_bright_white"

For example, you can use underline blue bg_bright_yellow to specify a blue underlined text on a bright yellow background.

normal

Reverts all parameters to their default value

bold

Increases the font weight or the color intensity

dim

Decreases the fond weight or the color intensity

underline

Underlines the text on some terminals

blink

Causes the text to blink

reverse

Swaps foreground and background colors

hidden

Hides the text

Colors

The color of the text or the background can be specified with the following style modifiers:

Table 2. Color table (8 or 16 color terminals)

If your terminal supports 24-bit colors, you can specify:

• the text color using the #rrggbb syntax, e.g. #dc143c will color your text crimson,
• the background color using the bg_#rrggbb syntax, e.g. bg_#87ceeb will use a sky blue background.

ANSI styling on Windows

ANSI escape sequences are supported natively on many platforms, but are disabled by default in cmd.exe on Windows. To enable ANSI escape sequences, create a registry key named HKEY_CURRENT_USER\Console\VirtualTerminalLevel of type DWORD and set its value to 0x1.

Garbage-free configuration

Pattern Layout with the following limited set of conversion patterns is garbage-free. Format modifiers to control such things as field width, padding, left, and right justification will not generate garbage.

Patterns containing regular expressions and location information are not garbage-free.