| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.11.1 from target/generated-sources/site/xdoc/manual/layouts.xml.vm at 2024-03-06 |
| | Rendered using Apache Maven Fluido Skin 1.11.2 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> |
| <meta name="author" content="Ralph Goers" /> |
| <meta name="author" content="Gary Gregory" /> |
| <title>Log4j – Log4j 2 Layouts</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.11.2.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script src="../js/apache-maven-fluido-1.11.2.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="../../.." id="bannerLeft"><img src="../images/ls-logo.jpg" alt="" style="" /></a></div> |
| <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/logo.png" alt="" style="" /></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2024-03-06<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.23.1</li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://github.com/apache/logging-log4j2" class="externalLink" title="GitHub">GitHub</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="../../../" title="Logging Services">Logging Services</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a></li> |
| <li class="pull-right"><a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="externalLink" title="Logging Wiki">Logging Wiki</a></li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/home.png" alt="Apache Log4j™ 2" style="border: 0;" /> Apache Log4j™ 2</li> |
| <li><a href="../index.html" title="About"><span class="none"></span>About</a></li> |
| <li><a href="../download.html" title="Download"><span class="none"></span>Download</a></li> |
| <li><a href="../support.html" title="Support"><span class="none"></span>Support</a></li> |
| <li><a href="../maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts"><span class="icon-chevron-right"></span>Maven, Ivy, Gradle Artifacts</a></li> |
| <li><a href="../release-notes.html" title="Release Notes"><span class="none"></span>Release Notes</a></li> |
| <li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a></li> |
| <li><a href="../performance.html" title="Performance"><span class="icon-chevron-right"></span>Performance</a></li> |
| <li><a href="../articles.html" title="Articles and Tutorials"><span class="none"></span>Articles and Tutorials</a></li> |
| <li><a href="../security.html" title="Security"><span class="icon-chevron-right"></span>Security</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/book.png" alt="Manual" style="border: 0;" /> Manual</li> |
| <li><a href="../manual/index.html" title="Introduction"><span class="none"></span>Introduction</a></li> |
| <li><a href="../manual/architecture.html" title="Architecture"><span class="none"></span>Architecture</a></li> |
| <li><a href="../manual/api-separation.html" title="API Separation"><span class="none"></span>API Separation</a></li> |
| <li><a href="../manual/migration.html" title="Log4j 1.x Migration"><span class="icon-chevron-right"></span>Log4j 1.x Migration</a></li> |
| <li><a href="../manual/api.html" title="Java API"><span class="icon-chevron-right"></span>Java API</a></li> |
| <li><a href="../../kotlin" title="Kotlin API"><span class="none"></span>Kotlin API</a></li> |
| <li><a href="../../scala" title="Scala API"><span class="none"></span>Scala API</a></li> |
| <li><a href="../manual/configuration.html" title="Configuration"><span class="icon-chevron-right"></span>Configuration</a></li> |
| <li><a href="../manual/usage.html" title="Usage"><span class="icon-chevron-right"></span>Usage</a></li> |
| <li><a href="../manual/webapp.html" title="Web Applications and JSPs"><span class="icon-chevron-right"></span>Web Applications and JSPs</a></li> |
| <li><a href="../manual/lookups.html" title="Lookups"><span class="icon-chevron-right"></span>Lookups</a></li> |
| <li><a href="../manual/appenders.html" title="Appenders"><span class="icon-chevron-right"></span>Appenders</a></li> |
| <li class="active"><a><span class="icon-chevron-down"></span>Layouts</a> |
| <ul class="nav nav-list"> |
| <li><a href="../manual/layouts.html#CSVLayouts" title="CSV"><span class="none"></span>CSV</a></li> |
| <li><a href="../manual/layouts.html#GELFLayout" title="GELF"><span class="none"></span>GELF</a></li> |
| <li><a href="../manual/layouts.html#HTMLLayout" title="HTML"><span class="none"></span>HTML</a></li> |
| <li><a href="../manual/layouts.html#JSONLayout" title="JSON"><span class="none"></span>JSON</a></li> |
| <li><a href="../manual/json-template-layout.html" title="JSON Template"><span class="none"></span>JSON Template</a></li> |
| <li><a href="../manual/layouts.html#PatternLayout" title="Pattern"><span class="none"></span>Pattern</a></li> |
| <li><a href="../manual/layouts.html#RFC5424Layout" title="RFC-5424"><span class="none"></span>RFC-5424</a></li> |
| <li><a href="../manual/layouts.html#SerializedLayout" title="Serialized"><span class="none"></span>Serialized</a></li> |
| <li><a href="../manual/layouts.html#SyslogLayout" title="Syslog"><span class="none"></span>Syslog</a></li> |
| <li><a href="../manual/layouts.html#XMLLayout" title="XML"><span class="none"></span>XML</a></li> |
| <li><a href="../manual/layouts.html#YamlLayout" title="YAML"><span class="none"></span>YAML</a></li> |
| <li><a href="../manual/layouts.html#LocationInformation" title="Location Information"><span class="none"></span>Location Information</a></li> |
| </ul></li> |
| <li><a href="../manual/filters.html" title="Filters"><span class="icon-chevron-right"></span>Filters</a></li> |
| <li><a href="../manual/async.html" title="Async Loggers"><span class="icon-chevron-right"></span>Async Loggers</a></li> |
| <li><a href="../manual/garbagefree.html" title="Garbage-free Logging"><span class="icon-chevron-right"></span>Garbage-free Logging</a></li> |
| <li><a href="../manual/jmx.html" title="JMX"><span class="none"></span>JMX</a></li> |
| <li><a href="../manual/logsep.html" title="Logging Separation"><span class="none"></span>Logging Separation</a></li> |
| <li><a href="../manual/extending.html" title="Extending Log4j"><span class="icon-chevron-right"></span>Extending Log4j</a></li> |
| <li><a href="../manual/plugins.html" title="Plugins"><span class="icon-chevron-right"></span>Plugins</a></li> |
| <li><a href="../manual/customconfig.html" title="Programmatic Log4j Configuration"><span class="icon-chevron-right"></span>Programmatic Log4j Configuration</a></li> |
| <li><a href="../manual/customloglevels.html" title="Custom Log Levels"><span class="icon-chevron-right"></span>Custom Log Levels</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/pencil.png" alt="For Contributors" style="border: 0;" /> For Contributors</li> |
| <li><a href="../guidelines.html" title="Guidelines"><span class="none"></span>Guidelines</a></li> |
| <li><a href="../javastyle.html" title="Style Guide"><span class="none"></span>Style Guide</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/cog.png" alt="Components" style="border: 0;" /> Components</li> |
| <li><a href="../log4j-api.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="../log4j-jcl.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="../log4j-1.2-api.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="../log4j-slf4j-impl.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="../log4j-jul.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="../log4j-jpl.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</a></li> |
| <li><a href="../log4j-to-slf4j.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="../log4j-flume-ng.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="../log4j-taglib.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="../log4j-jmx-gui.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="../log4j-web.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="../log4j-jakarta-web.html" title="Log4j Jakarta Web Application Support"><span class="none"></span>Log4j Jakarta Web Application Support</a></li> |
| <li><a href="../log4j-appserver.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="../log4j-couchdb.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="../log4j-mongodb3.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="../log4j-mongodb4.html" title="Log4j MongoDB4 appender"><span class="none"></span>Log4j MongoDB4 appender</a></li> |
| <li><a href="../log4j-cassandra.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="../log4j-iostreams.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="../log4j-docker.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="../log4j-kubernetes.html" title="Log4j Kubernetes Support"><span class="none"></span>Log4j Kubernetes Support</a></li> |
| <li><a href="../log4j-spring-boot.html" title="Log4j Spring Boot"><span class="none"></span>Log4j Spring Boot</a></li> |
| <li><a href="../log4j-spring-cloud-config-client.html" title="Log4j Spring Cloud Config Client"><span class="none"></span>Log4j Spring Cloud Config Client</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/tag.png" alt="Related Projects" style="border: 0;" /> Related Projects</li> |
| <li><a href="../../../chainsaw/2.x/index.html" title="Chainsaw"><span class="none"></span>Chainsaw</a></li> |
| <li><a href="../../../log4cxx/latest_stable/index.html" title="Log4Cxx"><span class="none"></span>Log4Cxx</a></li> |
| <li><a href="../../../log4j-audit/latest/index.html" title="Log4j Audit"><span class="none"></span>Log4j Audit</a></li> |
| <li><a href="../../kotlin" title="Log4j Kotlin"><span class="none"></span>Log4j Kotlin</a></li> |
| <li><a href="../../scala" title="Log4j Scala"><span class="none"></span>Log4j Scala</a></li> |
| <li><a href="../../transform" title="Log4j Transform"><span class="none"></span>Log4j Transform</a></li> |
| <li><a href="../../../log4net/index.html" title="Log4Net"><span class="none"></span>Log4Net</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/link.png" alt="Legacy Sites" style="border: 0;" /> Legacy Sites</li> |
| <li><a href="../../log4j-2.12.4/" title="Log4j 2.12.4 - Java 7"><span class="none"></span>Log4j 2.12.4 - Java 7</a></li> |
| <li><a href="../../log4j-2.3.2/" title="Log4j 2.3.2 - Java 6"><span class="none"></span>Log4j 2.3.2 - Java 6</a></li> |
| <li><a href="../../1.2/" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/info.png" alt="Project Information" style="border: 0;" /> Project Information</li> |
| <li><a href="../team.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="https://www.apache.org/licenses/LICENSE-2.0" class="externalLink" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="https://github.com/apache/logging-log4j2" class="externalLink" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="../runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="../javadoc.html" title="Javadoc"><span class="none"></span>Javadoc</a></li> |
| <li><a href="../thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10" > |
| |
| |
| <section> |
| <h2><a name="Layouts"></a>Layouts</h2> |
| |
| <p>An Appender uses a Layout to format a LogEvent into a form that meets the needs of whatever will be |
| consuming the log event. In Log4j 1.x and Logback Layouts were expected to transform an event into a |
| String. In Log4j 2 Layouts return a byte array. This allows the result of the Layout to be useful in |
| many more types of Appenders. However, this means you need to configure most Layouts with a <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Charset</a> to |
| ensure the byte array contains correct values. |
| </p> |
| |
| <p> |
| The root class for layouts that use a Charset is <code>org.apache.logging.log4j.core.layout.AbstractStringLayout</code> |
| where the default is UTF-8. Each layout that extends <code>AbstractStringLayout</code> |
| can provide its own default. See each layout below. |
| </p> |
| |
| <p> |
| A custom character encoder was added to Log4j 2.4.1 for the ISO-8859-1 and US-ASCII charsets, |
| to bring some of the performance improvements built-in to Java 8 to Log4j for use on Java 7. |
| For applications that log only ISO-8859-1 characters, specifying this charset will improve performance significantly. |
| </p> |
| <a name="CSVLayouts"></a> |
| <section> |
| <h3><a name="CSV_Layouts"></a>CSV Layouts</h3> |
| |
| <p> |
| This layout creates <a class="externalLink" href="https://en.wikipedia.org/wiki/Comma-separated_values">Comma Separated Value (CSV)</a> |
| records and requires <a class="externalLink" href="https://commons.apache.org/proper/commons-csv/">Apache Commons CSV</a>. |
| </p> |
| |
| <p> |
| The CSV layout can be used in two ways: First, using <code>CsvParameterLayout</code> to log event parameters |
| to create a custom database, usually to a logger and file appender uniquely configured for this purpose. |
| Second, using <code>CsvLogEventLayout</code> to log events to create a database, as an alternative to using a |
| full DBMS or using a JDBC driver that supports the CSV format. |
| </p> |
| |
| <p> |
| The <code>CsvParameterLayout</code> converts an event's parameters into a CSV record, ignoring the message. |
| To log CSV records, you can use the usual Logger methods <code>info()</code>, <code>debug()</code>, and so on: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| logger.info("Ignored", value1, value2, value3); |
| </pre></div> |
| |
| <p> |
| Which will create the CSV record: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| value1, value2, value3 |
| </pre></div> |
| |
| <p> |
| Alternatively, you can use a <code>ObjectArrayMessage</code>, which only carries parameters: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| logger.info(new ObjectArrayMessage(value1, value2, value3)); |
| </pre></div> |
| |
| <p> |
| The layouts <code>CsvParameterLayout</code> and <code>CsvLogEventLayout</code> are configured with the following parameters: |
| </p> |
| |
| <table border="0" class="table table-striped"><caption>CsvParameterLayout and CsvLogEventLayout</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">format</td> |
| |
| <td>String</td> |
| |
| <td> |
| One of the predefined formats: <code>Default</code>, <code>Excel</code>, <code>MySQL</code>, |
| <code>RFC4180</code>, <code>TDF</code>. |
| See |
| <a class="externalLink" href="https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.Predefined.html">CSVFormat.Predefined</a>. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">delimiter</td> |
| |
| <td>Character</td> |
| |
| <td>Sets the delimiter of the format to the specified character.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">escape</td> |
| |
| <td>Character</td> |
| |
| <td>Sets the escape character of the format to the specified character.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">quote</td> |
| |
| <td>Character</td> |
| |
| <td>Sets the quoteChar of the format to the specified character.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">quoteMode</td> |
| |
| <td>String</td> |
| |
| <td> |
| Sets the output quote policy of the format to the specified value. One of: <code>ALL</code>, |
| <code>MINIMAL</code>, <code>NON_NUMERIC</code>, <code>NONE</code>. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">nullString</td> |
| |
| <td>String</td> |
| |
| <td>Writes null as the given nullString when writing records.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">recordSeparator</td> |
| |
| <td>String</td> |
| |
| <td>Sets the record separator of the format to the specified String.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">charset</td> |
| |
| <td>Charset</td> |
| |
| <td>The output Charset.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">header</td> |
| |
| <td>Sets the header to include when the stream is opened.</td> |
| |
| <td>Desc.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">footer</td> |
| |
| <td>Sets the footer to include when the stream is closed.</td> |
| |
| <td>Desc.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Logging as a CSV events looks like this: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| logger.debug("one={}, two={}, three={}", 1, 2, 3); |
| </pre></div> |
| |
| <p> |
| Produces a CSV record with the following fields: |
| </p> |
| <ol style="list-style-type: decimal"> |
| |
| <li>Time Nanos</li> |
| |
| <li>Time Millis</li> |
| |
| <li>Level</li> |
| |
| <li>Thread ID</li> |
| |
| <li>Thread Name</li> |
| |
| <li>Thread Priority</li> |
| |
| <li>Formatted Message</li> |
| |
| <li>Logger FQCN</li> |
| |
| <li>Logger Name</li> |
| |
| <li>Marker</li> |
| |
| <li>Thrown Proxy</li> |
| |
| <li>Source</li> |
| |
| <li>Context Map</li> |
| |
| <li>Context Stack</li> |
| </ol> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| 0,1441617184044,DEBUG,main,"one=1, two=2, three=3",org.apache.logging.log4j.spi.AbstractLogger,,,,org.apache.logging.log4j.core.layout.CsvLogEventLayoutTest.testLayout(CsvLogEventLayoutTest.java:98),{},[] |
| </pre></div> |
| |
| <p> |
| Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using CSV layouts. |
| </p> |
| </section> |
| <a name="GELFLayout"></a> |
| <section> |
| <h3><a name="GELF_Layout"></a>GELF Layout</h3> |
| |
| |
| <p> |
| Lays out events in the Graylog Extended Log Format (GELF) 1.1. |
| </p> |
| |
| <p> |
| This layout compresses JSON to GZIP or ZLIB (the <code>compressionType</code>) if log event data is larger than 1024 bytes |
| (the <code>compressionThreshold</code>). This layout does not implement chunking. |
| </p> |
| |
| <p> |
| Configure as follows to send to a Graylog 2.x server with UDP: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <Appenders> |
| <Socket name="Graylog" protocol="udp" host="graylog.domain.com" port="12201"> |
| <GelfLayout host="someserver" compressionType="ZLIB" compressionThreshold="1024"/> |
| </Socket> |
| </Appenders> |
| </pre></div> |
| |
| <p> |
| Configure as follows to send to a Graylog 2.x server with TCP: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <Appenders> |
| <Socket name="Graylog" protocol="tcp" host="graylog.domain.com" port="12201"> |
| <GelfLayout host="someserver" compressionType="OFF" includeNullDelimiter="true"/> |
| </Socket> |
| </Appenders> |
| </pre></div> |
| |
| <table border="0" class="table table-striped"><caption align="top">GelfLayout Parameters</caption> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">host</td> |
| |
| <td>String</td> |
| |
| <td>The value of the <code>host</code> property (optional, defaults to local host name).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">compressionType</td> |
| |
| <td><code>GZIP</code>, <code>ZLIB</code> or <code>OFF</code></td> |
| |
| <td>Compression to use (optional, defaults to <code>GZIP</code>)</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">compressionThreshold</td> |
| |
| <td>int</td> |
| |
| <td>Compress if data is larger than this number of bytes (optional, defaults to 1024)</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">includeMapMessage</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to include fields from MapMessages as additional fields (optional, default to true).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">includeNullDelimiter</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to include NULL byte as delimiter after each event (optional, default to false). |
| Useful for Graylog GELF TCP input. Cannot be used with compression.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">includeStacktrace</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to include full stacktrace of logged Throwables (optional, default to true). |
| If set to false, only the class name and message of the <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html">Throwable</a> |
| will be included.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">includeThreadContext</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to include thread context as additional fields (optional, default to true).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">mapMessageExcludes</td> |
| |
| <td>String</td> |
| |
| <td>A comma separated list of attributes from the MapMessage to exclude when formatting the event. This |
| attribute only applies when includeMapMessage="true" is specified. If mapMessageIncludes |
| are also specified this attribute will be ignored.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">mapMessageIncludes</td> |
| |
| <td>String</td> |
| |
| <td>A comma separated list of attributes from the MapMessageto include when formatting the event. This |
| attribute only applies when includeMapMessage="true" is specified. If mapMessageExcludes |
| are also specified this attribute will override them. MapMessage fields specified here that |
| have no value will be omitted.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">mapPrefix</td> |
| |
| <td>String</td> |
| |
| <td>A String to prepend to all elements of the MapMessage when rendered as a field. Defaults to an |
| empty String.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">messagePattern</td> |
| |
| <td>String</td> |
| |
| <td>The pattern to use to format the String. A messagePattern and patternSelector cannot both be |
| specified. If both are present the message pattern will be ignored and an error will be logged. |
| If not supplied only the text derived from the logging message will be used. See |
| <a href="#PatternLayout">PatternLayout</a> for information on the pattern strings.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">omitEmptyFields</td> |
| |
| <td>boolean</td> |
| |
| <td>If true fields which are null or are zero-length strings will not be included as a field in |
| the Gelf JSON. This setting will not affect whether those fields appear in the message fields. The |
| default value is false.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">patternSelector</td> |
| |
| <td>PatternSelector</td> |
| |
| <td>The PatternSelector to use to format the String. A messagePattern and patternSelector cannot both be |
| specified. If both are present the message pattern will be ignored and an error will be logged. |
| If not supplied only the text derived from the logging message will be used. |
| See <a href="#PatternSelectors">PatternSelectors</a> for information on how to specify a |
| PatternSelector. |
| See <a href="#PatternLayout">PatternLayout</a> for information on the pattern strings.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">threadContextExcludes</td> |
| |
| <td>String</td> |
| |
| <td>A comma separated list of ThreadContext attributes to exclude when formatting the event. This |
| attribute only applies when includeThreadContext="true" is specified. If threadContextIncludes |
| are also specified this attribute will be ignored.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">threadContextIncludes</td> |
| |
| <td>String</td> |
| |
| <td>A comma separated list of ThreadContext attributes to include when formatting the event. This |
| attribute only applies when includeThreadContext="true" is specified. If threadContextExcludes |
| are also specified this attribute will override them. ThreadContext fields specified here that |
| have no value will be omitted.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">ThreadContextPrefix</td> |
| |
| <td>String</td> |
| |
| <td>A String to prepend to all elements of the ThreadContextMap when rendered as a field. Defaults to an |
| empty String.</td> |
| </tr> |
| |
| </table> |
| |
| <p> |
| To include any custom field in the output, use following syntax: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <GelfLayout includeThreadContext="true" threadContextIncludes="loginId,requestId"> |
| <MessagePattern>%d %5p [%t] %c{1} %X{loginId, requestId} - %m%n</MessagePattern> |
| <KeyValuePair key="additionalField1" value="constant value"/> |
| <KeyValuePair key="additionalField2" value="$${ctx:key}"/> |
| </GelfLayout></pre></div> |
| |
| <p> |
| Custom fields are included in the order they are declared. The values support <a href="lookups.html">lookups</a>. |
| </p> |
| |
| <p> |
| See also: |
| </p> |
| |
| <ul> |
| |
| <li>The <a class="externalLink" href="https://docs.graylog.org/en/latest/pages/gelf.html#gelf">GELF specification</a></li> |
| </ul> |
| </section> |
| <a name="HTMLLayout"></a> |
| <section> |
| <h3><a name="HTML_Layout"></a>HTML Layout</h3> |
| |
| <p>The HtmlLayout generates an HTML page and adds each LogEvent to a row in a table. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">HtmlLayout Parameters</caption> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">charset</td> |
| |
| <td>String</td> |
| |
| <td>The character set to use when converting the HTML String to a byte array. The value must be |
| a valid <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Charset</a>. If not specified, this layout uses UTF-8.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">contentType</td> |
| |
| <td>String</td> |
| |
| <td>The value to assign to the Content-Type header. The default is "text/html".</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">locationInfo</td> |
| |
| <td>boolean</td> |
| |
| <td> |
| <a name="HtmlLocationInfo"></a> |
| |
| <p>If true, the filename and line number will be included in the HTML output. The default value is |
| false.</p> |
| |
| <p>Generating <a href="#LocationInformation">location information</a> |
| is an expensive operation and may impact performance. Use with caution.</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">title</td> |
| |
| <td>String</td> |
| |
| <td>A String that will appear as the HTML title.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">fontName</td> |
| |
| <td>String</td> |
| |
| <td>The <code>font-family</code> to use. The default is "arial,sans-serif".</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">fontSize</td> |
| |
| <td>String</td> |
| |
| <td>The <code>font-size</code> to use. The default is "small".</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">datePattern</td> |
| |
| <td>String</td> |
| |
| <td>The date format of the logging event. The default is "JVM_ELAPSE_TIME", which outputs the |
| milliseconds since JVM started. For other valid values, refer to the |
| <a href="#PatternDate">date pattern</a> of PatternLayout.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">timezone</td> |
| |
| <td>String</td> |
| |
| <td>The timezone id of the logging event. If not specified, this layout uses the |
| <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getDefault()"> |
| java.util.TimeZone.getDefault</a> as default timezone. |
| Like <a href="#PatternDate">date pattern</a> of PatternLayout, you can use timezone id from |
| <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)"> |
| java.util.TimeZone.getTimeZone</a>.</td> |
| </tr> |
| |
| </table> |
| |
| <p> |
| Configure as follows to use dataPattern and timezone in HtmlLayout: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <Appenders> |
| <Console name="console"> |
| <HtmlLayout datePattern="ISO8601" timezone="GMT+0"/> |
| </Console> |
| </Appenders> |
| </pre></div> |
| </section> |
| <a name="JSONLayout"></a> |
| <section> |
| <h3><a name="JSON_Layout"></a>JSON Layout</h3> |
| |
| <p> |
| <b>Note:</b> JsonTemplate is considered deprecated. JsonTemplateLayout provides more capabilitites and |
| should be used instead. |
| </p> |
| |
| |
| <p> |
| Appends a series of JSON events as strings serialized as bytes. |
| </p> |
| <section> |
| <h4><a name="Complete_well-formed_JSON_vs._fragment_JSON"></a>Complete well-formed JSON vs. fragment JSON</h4> |
| |
| <p> |
| If you configure <code>complete="true"</code>, the appender outputs a well-formed JSON document. By default, |
| with <code>complete="false"</code>, you should include the output as an <i>external file</i> in a |
| separate file to form a well-formed JSON document. |
| </p> |
| |
| <p> |
| If <code>complete="false"</code>, the appender does not write the JSON open array character "[" at the start |
| of the document, "]" and the end, nor comma "," between records. |
| </p> |
| |
| <p> |
| Log event follows this pattern: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums">{ |
| "instant" : { |
| "epochSecond" : 1493121664, |
| "nanoOfSecond" : 118000000 |
| }, |
| "thread" : "main", |
| "level" : "INFO", |
| "loggerName" : "HelloWorld", |
| "marker" : { |
| "name" : "child", |
| "parents" : [ { |
| "name" : "parent", |
| "parents" : [ { |
| "name" : "grandparent" |
| } ] |
| } ] |
| }, |
| "message" : "Hello, world!", |
| "thrown" : { |
| "commonElementCount" : 0, |
| "message" : "error message", |
| "name" : "java.lang.RuntimeException", |
| "extendedStackTrace" : [ { |
| "class" : "logtest.Main", |
| "method" : "main", |
| "file" : "Main.java", |
| "line" : 29, |
| "exact" : true, |
| "location" : "classes/", |
| "version" : "?" |
| } ] |
| }, |
| "contextStack" : [ "one", "two" ], |
| "endOfBatch" : false, |
| "loggerFqcn" : "org.apache.logging.log4j.spi.AbstractLogger", |
| "contextMap" : { |
| "bar" : "BAR", |
| "foo" : "FOO" |
| }, |
| "threadId" : 1, |
| "threadPriority" : 5, |
| "source" : { |
| "class" : "logtest.Main", |
| "method" : "main", |
| "file" : "Main.java", |
| "line" : 29 |
| } |
| }</pre></div> |
| |
| <p> |
| If <code>complete="false"</code>, the appender does not write the JSON open array character "[" at the start |
| of the document, "]" and the end, nor comma "," between records. |
| </p> |
| </section><section> |
| <h4><a name="Pretty_vs._compact_JSON"></a>Pretty vs. compact JSON</h4> |
| |
| <p> |
| The compact attribute determines whether the output will be "pretty" or not. The default value is "false", |
| which means the appender uses end-of-line characters and indents lines to format the text. If |
| <code>compact="true"</code>, then no end-of-line or indentation is used, which will cause the output |
| to take less space. Of course, the message content may contain, escaped end-of-lines. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">JsonLayout Parameters</caption> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">charset</td> |
| |
| <td>String</td> |
| |
| <td>The character set to use when converting to a byte array. The value must be a valid <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Charset</a>. |
| If not specified, UTF-8 will be used.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">compact</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, the appender does not use end-of-lines and indentation. Defaults to false.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">eventEol</td> |
| |
| <td>boolean</td> |
| |
| <td> |
| If true, the appender appends an end-of-line after each record. Defaults to false. |
| Use with eventEol=true and compact=true to get one record per line. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">endOfLine</td> |
| |
| <td>String</td> |
| |
| <td> |
| If set, overrides the default end-of-line string. E.g. set it to "\n" and use with eventEol=true and compact=true |
| to have one record per line separated by "\n" instead of "\r\n". Defaults to null (i.e. not set). |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">complete</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, the appender includes the JSON header and footer, and comma between records. Defaults to false.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">properties</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, the appender includes the thread context map in the generated JSON. Defaults to false.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">propertiesAsList</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, the thread context map is included as a list of map entry objects, where each entry has |
| a "key" attribute (whose value is the key) and a "value" attribute (whose value is the value). |
| Defaults to false, in which case the thread context map is included as a simple map of key-value pairs.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">locationInfo</td> |
| |
| <td>boolean</td> |
| |
| <td> |
| |
| <p>If true, the appender includes the location information in the generated JSON. Defaults to false.</p> |
| |
| <p>Generating <a href="#LocationInformation">location information</a> |
| is an expensive operation and may impact performance. Use with caution.</p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">includeStacktrace</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, include full stacktrace of any logged <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html">Throwable</a> |
| (optional, default to true).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">includeTimeMillis</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, the timeMillis attribute is included in the Json payload instead of the instant. timeMillis |
| will contain the number of milliseconds since midnight, January 1, 1970 UTC.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">stacktraceAsString</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to format the stacktrace as a string, and not a nested object (optional, defaults to false).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">includeNullDelimiter</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to include NULL byte as delimiter after each event (optional, default to false).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">objectMessageAsJsonObject</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, ObjectMessage is serialized as JSON object to the "message" field of the output log. Defaults to false.</td> |
| </tr> |
| |
| </table> |
| |
| <p> |
| To include any custom field in the output, use following syntax: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <JsonLayout> |
| <KeyValuePair key="additionalField1" value="constant value"/> |
| <KeyValuePair key="additionalField2" value="$${ctx:key}"/> |
| </JsonLayout> |
| </pre></div> |
| |
| <p> |
| Custom fields are always last, in the order they are declared. The values support <a href="lookups.html">lookups</a>. |
| </p> |
| |
| <p> |
| Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using JsonLayout. |
| </p> |
| </section></section> |
| <a name="JsonTemplateLayout"></a> |
| <section> |
| <h3><a name="JSON_Template_Layout"></a>JSON Template Layout</h3> |
| |
| <p> |
| <code>JsonTemplateLayout</code> is a customizable, efficient, and |
| garbage-free JSON emitting layout. It encodes <code>LogEvent</code>s |
| according to the structure described by the JSON template provided. |
| For instance, given the following JSON template modelling the |
| <a class="externalLink" href="https://github.com/logstash/log4j-jsonevent-layout">the |
| official Logstash <code>JSONEventLayoutV1</code></a> |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| { |
| "mdc": { |
| "$resolver": "mdc" |
| }, |
| "exception": { |
| "exception_class": { |
| "$resolver": "exception", |
| "field": "className" |
| }, |
| "exception_message": { |
| "$resolver": "exception", |
| "field": "message" |
| }, |
| "stacktrace": { |
| "$resolver": "exception", |
| "field": "stackTrace", |
| "stackTrace": { |
| "stringified": true |
| } |
| } |
| }, |
| "line_number": { |
| "$resolver": "source", |
| "field": "lineNumber" |
| }, |
| "class": { |
| "$resolver": "source", |
| "field": "className" |
| }, |
| "@version": 1, |
| "source_host": "${hostName}", |
| "message": { |
| "$resolver": "message", |
| "stringified": true |
| }, |
| "thread_name": { |
| "$resolver": "thread", |
| "field": "name" |
| }, |
| "@timestamp": { |
| "$resolver": "timestamp" |
| }, |
| "level": { |
| "$resolver": "level", |
| "field": "name" |
| }, |
| "file": { |
| "$resolver": "source", |
| "field": "fileName" |
| }, |
| "method": { |
| "$resolver": "source", |
| "field": "methodName" |
| }, |
| "logger_name": { |
| "$resolver": "logger", |
| "field": "name" |
| } |
| }</pre></div> |
| |
| <p> |
| in combination with the below Log4j configuration: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <JsonTemplateLayout eventTemplateUri="classpath:LogstashJsonEventLayoutV1.json"/></pre></div> |
| |
| <p> |
| JSON Template Layout will render JSON documents as follows: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| { |
| "exception": { |
| "exception_class": "java.lang.RuntimeException", |
| "exception_message": "test", |
| "stacktrace": "java.lang.RuntimeException: test\n\tat org.apache.logging.log4j.JsonTemplateLayoutDemo.main(JsonTemplateLayoutDemo.java:11)\n" |
| }, |
| "line_number": 12, |
| "class": "org.apache.logging.log4j.JsonTemplateLayoutDemo", |
| "@version": 1, |
| "source_host": "varlik", |
| "message": "Hello, error!", |
| "thread_name": "main", |
| "@timestamp": "2017-05-25T19:56:23.370+02:00", |
| "level": "ERROR", |
| "file": "JsonTemplateLayoutDemo.java", |
| "method": "main", |
| "logger_name": "org.apache.logging.log4j.JsonTemplateLayoutDemo" |
| }</pre></div> |
| |
| <p> |
| See <a href="json-template-layout.html">JSON Template Layout</a> |
| page for the complete documentation. |
| </p> |
| </section> |
| <a name="PatternLayout"></a> |
| <section> |
| <h3><a name="Pattern_Layout"></a>Pattern Layout</h3> |
| |
| <p>A flexible layout configurable with pattern string. The goal of this class is to format a LogEvent and |
| return the results. The format of the result depends on the <i>conversion pattern</i>. |
| </p> |
| |
| <p>The conversion pattern is closely related to the conversion pattern of the printf function in C. |
| A conversion pattern is composed of literal text and format control expressions called |
| <i>conversion specifiers</i>. |
| </p> |
| |
| <p><i>Note that any literal text, including <b>Special Characters</b>, may be included in the conversion |
| pattern.</i> Special Characters include <b>\t</b>, <b>\n</b>, <b>\r</b>, <b>\f</b>. Use <b>\\</b> to |
| insert a single backslash into the output. |
| </p> |
| |
| <p>Each conversion specifier starts with a percent sign (%) and is followed by optional <i>format |
| modifiers</i> and a <i>conversion character</i>. The conversion character specifies the type of |
| data, e.g. category, priority, date, thread name. The format modifiers control such things as field width, |
| padding, left and right justification. The following is a simple example. |
| </p> |
| |
| <p>Let the conversion pattern be <b>"%-5p [%t]: %m%n"</b> and assume that the Log4j environment was set to |
| use a PatternLayout. Then the statements |
| </p> |
| <div> |
| <pre>Logger logger = LogManager.getLogger("MyLogger"); |
| logger.debug("Message 1"); |
| logger.warn("Message 2");</pre></div> |
| would yield the output |
| |
| <div> |
| <pre>DEBUG [main]: Message 1 |
| WARN [main]: Message 2</pre></div> |
| |
| |
| <p>Note that there is no explicit separator between text and conversion specifiers. The pattern parser |
| knows when it has reached the end of a conversion specifier when it reads a conversion character. |
| In the example above the conversion specifier <b>%-5p</b> means the priority of the logging event should |
| be left justified to a width of five characters. |
| </p> |
| |
| <p> |
| If the pattern string does not contain a specifier to handle a Throwable being logged, parsing of the |
| pattern will act as if the "%xEx" specifier had be added to the end of the string. To suppress |
| formatting of the Throwable completely simply add "%ex{0}" as a specifier in the pattern string. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">PatternLayout Parameters</caption> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">charset</td> |
| |
| <td>String</td> |
| |
| <td>The character set to use when converting the syslog String to a byte array. The String must be |
| a valid <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Charset</a>. If not specified, this layout uses the platform default character set. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">pattern</td> |
| |
| <td>String</td> |
| |
| <td>A composite pattern string of one or more conversion patterns from the table below. Cannot be |
| specified with a PatternSelector.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">patternSelector</td> |
| |
| <td>PatternSelector</td> |
| |
| <td>A component that analyzes information in the LogEvent and determines which pattern should be |
| used to format the event. The pattern and patternSelector parameters are mutually exclusive.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">replace</td> |
| |
| <td>RegexReplacement</td> |
| |
| <td>Allows portions of the resulting String to be replaced. If configured, the replace element must |
| specify the regular expression to match and the substitution. This performs a function similar to |
| the RegexReplacement converter but applies to the whole message while the converter only |
| applies to the String its pattern generates. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">alwaysWriteExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>If <code>true</code> (it is by default) exceptions are always written even if the pattern contains no |
| exception conversions. 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 |
| <code>false</code> disables this behavior and allows you to exclude exceptions from your pattern |
| output.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">header</td> |
| |
| <td>String</td> |
| |
| <td>The optional header string to include at the top of each log file.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">footer</td> |
| |
| <td>String</td> |
| |
| <td>The optional footer string to include at the bottom of each log file.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">disableAnsi</td> |
| |
| <td>boolean</td> |
| |
| <td>If <code>true</code>, do not output ANSI escape codes. Parameter default value is platform dependent. |
| If run on Windows, it defaults to <code>true</code>, unless system property <code>log4j.skipJansi</code> |
| is set to <code>false</code>. On other platforms, it defaults to <code>false</code>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">noConsoleNoAnsi</td> |
| |
| <td>boolean</td> |
| |
| <td>If <code>true</code> (default is false) and <code>System.console()</code> is null, do not output ANSI escape codes.</td> |
| </tr> |
| |
| </table> |
| |
| <table border="0" class="table table-striped"><caption align="top">RegexReplacement Parameters</caption> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">regex</td> |
| |
| <td>String</td> |
| |
| <td>A Java-compliant regular expression to match in the resulting string. See |
| <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html">Pattern</a> |
| .</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">replacement</td> |
| |
| <td>String</td> |
| |
| <td>The string to replace any matched sub-strings with.</td> |
| </tr> |
| |
| </table> |
| <section> |
| <h4><a name="Patterns"></a>Patterns</h4> |
| |
| <p>The conversions that are provided with Log4j are: |
| </p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Conversion Pattern</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <b>c</b>{precision}<br /> |
| <b>logger</b>{precision} |
| </td> |
| |
| <td> |
| |
| <p>Outputs the name of the logger that published the logging event. The logger conversion |
| specifier can be optionally followed by <i>precision specifier</i>, which consists of a |
| decimal integer, or a pattern starting with a decimal integer. |
| </p> |
| |
| <p>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 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. See the table below for abbreviation examples. |
| </p> |
| |
| <p> |
| 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. By default, the layout prints the logger name in full. |
| </p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Conversion Pattern</th> |
| |
| <th>Logger Name</th> |
| |
| <th>Result</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%c{1}</td> |
| |
| <td>org.apache.commons.Foo</td> |
| |
| <td>Foo</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%c{2}</td> |
| |
| <td>org.apache.commons.Foo</td> |
| |
| <td>commons.Foo</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%c{10}</td> |
| |
| <td>org.apache.commons.Foo</td> |
| |
| <td>org.apache.commons.Foo</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%c{-1}</td> |
| |
| <td>org.apache.commons.Foo</td> |
| |
| <td>apache.commons.Foo</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%c{-2}</td> |
| |
| <td>org.apache.commons.Foo</td> |
| |
| <td>commons.Foo</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%c{-10}</td> |
| |
| <td>org.apache.commons.Foo</td> |
| |
| <td>org.apache.commons.Foo</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%c{1.}</td> |
| |
| <td>org.apache.commons.Foo</td> |
| |
| <td>o.a.c.Foo</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%c{1.1.~.~}</td> |
| |
| <td>org.apache.commons.test.Foo</td> |
| |
| <td>o.a.~.~.Foo</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%c{.}</td> |
| |
| <td>org.apache.commons.test.Foo</td> |
| |
| <td>....Foo</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%c{1.1.1.*}</td> |
| |
| <td>org.apache.commons.test.Foo</td> |
| |
| <td>o.a.c.test.Foo</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%c{1.2.*}</td> |
| |
| <td>org.apache.commons.test.Foo</td> |
| |
| <td>o.a.c.test.Foo</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%c{1.3.*}</td> |
| |
| <td>org.apache.commons.test.Foo</td> |
| |
| <td>o.a.commons.test.Foo</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%c{1.8.*}</td> |
| |
| <td>org.apache.commons.test.Foo</td> |
| |
| <td>org.apache.commons.test.Foo</td> |
| </tr> |
| </table> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternClass"></a> |
| <b>C</b>{precision}<br /> |
| <b>class</b>{precision} |
| </td> |
| |
| <td> |
| |
| <p>Outputs the fully qualified class name of the caller issuing the logging request. |
| This conversion specifier can be optionally followed by <i>precision specifier</i>, that |
| follows the same rules as the logger name converter. |
| </p> |
| |
| <p>Generating the class name of the caller (<a href="#LocationInformation">location information</a>) |
| is an expensive operation and may impact performance. Use with caution.</p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternDate"></a> |
| <b>d</b>{pattern}<br /> |
| <b>date</b>{pattern} |
| </td> |
| |
| <td> |
| |
| <p>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 |
| <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat</a> |
| . |
| </p> |
| |
| <p>The predefined <i>named</i> formats are:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Pattern</th> |
| |
| <th>Example</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%d{DEFAULT}</td> |
| |
| <td>2012-11-02 14:34:02,123</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%d{DEFAULT_MICROS}</td> |
| |
| <td>2012-11-02 14:34:02,123456</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%d{DEFAULT_NANOS}</td> |
| |
| <td>2012-11-02 14:34:02,123456789</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%d{ISO8601}</td> |
| |
| <td>2012-11-02T14:34:02,781</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%d{ISO8601_BASIC}</td> |
| |
| <td>20121102T143402,781</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%d{ISO8601_OFFSET_DATE_TIME_HH}</td> |
| |
| <td>2012-11-02'T'14:34:02,781-07</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%d{ISO8601_OFFSET_DATE_TIME_HHMM}</td> |
| |
| <td>2012-11-02'T'14:34:02,781-0700</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%d{ISO8601_OFFSET_DATE_TIME_HHCMM}</td> |
| |
| <td>2012-11-02'T'14:34:02,781-07:00</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%d{ABSOLUTE}</td> |
| |
| <td>14:34:02,781</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%d{ABSOLUTE_MICROS}</td> |
| |
| <td>14:34:02,123456</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%d{ABSOLUTE_NANOS}</td> |
| |
| <td>14:34:02,123456789</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%d{DATE}</td> |
| |
| <td>02 Nov 2012 14:34:02,781</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%d{COMPACT}</td> |
| |
| <td>20121102143402781</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%d{UNIX}</td> |
| |
| <td>1351866842</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%d{UNIX_MILLIS}</td> |
| |
| <td>1351866842781</td> |
| </tr> |
| </table> |
| |
| <p>You can also use a set of braces containing a time zone id per |
| <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)"> |
| java.util.TimeZone.getTimeZone</a>. If no date format specifier is given then the DEFAULT format is used. |
| </p> |
| |
| <p>You can define custom date formats:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Pattern</th> |
| |
| <th>Example</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%d{HH:mm:ss,SSS}</td> |
| |
| <td>14:34:02,123</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%d{HH:mm:ss,nnnn} to %d{HH:mm:ss,nnnnnnnnn}</td> |
| |
| <td>14:34:02,1234 to 14:34:02,123456789</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%d{dd MMM yyyy HH:mm:ss,SSS}</td> |
| |
| <td>02 Nov 2012 14:34:02,123</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%d{dd MMM yyyy HH:mm:ss,nnnn} to %d{dd MMM yyyy HH:mm:ss,nnnnnnnnn}</td> |
| |
| <td>02 Nov 2012 14:34:02,1234 to 02 Nov 2012 14:34:02,123456789</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%d{HH:mm:ss}{GMT+0}</td> |
| |
| <td>18:34:02</td> |
| </tr> |
| </table> |
| |
| <p> |
| %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 |
| (<a class="externalLink" href="https://msdn.microsoft.com/en-us/windows/hardware/gg463266.aspx">Windows</a>). |
| 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. |
| </p> |
| |
| <p> |
| Log4j 2.11 adds limited support for timestamps more precise than milliseconds when running on Java 9. |
| Note that not all |
| <a class="externalLink" href="https://docs.oracle.com/javase/9/docs/api/java/time/format/DateTimeFormatter.html">DateTimeFormatter</a> |
| formats are supported. |
| Only timestamps in the formats mentioned in the table above may use the "nano-of-second" |
| pattern letter <code>n</code> instead of the "fraction-of-second" pattern letter <code>S</code>. |
| </p> |
| |
| <p> |
| Users may revert back to a millisecond-precision clock when running on Java 9 by setting system property |
| <code>log4j2.Clock</code> to <code>SystemMillisClock</code>. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <b>enc</b>{<i>pattern</i>}{[HTML|XML|JSON|CRLF]}<br /> |
| <b>encode</b>{<i>pattern</i>}{[HTML|XML|JSON|CRLF]} |
| </td> |
| |
| <td> |
| |
| <p> |
| Encodes and escapes special characters suitable for output in specific markup languages. |
| 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. This converter is particularly useful for encoding |
| user provided data so that the output data is not written improperly or insecurely. |
| </p> |
| |
| <p> |
| A typical usage would encode the message |
| <code>%enc{%m}</code> |
| but user input could come from other locations as well, such as the MDC |
| <code>%enc{%mdc{key}}</code> |
| </p> |
| |
| <p>Using the HTML encoding format, the following characters are replaced:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="b"> |
| |
| <th>Character</th> |
| |
| <th>Replacement</th> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">'\r', '\n'</td> |
| |
| <td>Converted into escaped strings "\\r" and "\\n" respectively</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">&, <, >, ", ', /</td> |
| |
| <td>Replaced with the corresponding HTML entity</td> |
| </tr> |
| </table> |
| |
| <p>Using the XML encoding format, this follows the escaping rules specified by |
| <a class="externalLink" href="https://www.w3.org/TR/xml/">the XML specification</a>:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Character</th> |
| |
| <th>Replacement</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">&, <, >, ", '</td> |
| |
| <td>Replaced with the corresponding XML entity</td> |
| </tr> |
| </table> |
| |
| <p> |
| Using the JSON encoding format, this follows the escaping rules specified by |
| <a class="externalLink" href="https://www.ietf.org/rfc/rfc4627.txt">RFC 4627 section 2.5</a>: |
| </p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Character</th> |
| |
| <th>Replacement</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">U+0000 - U+001F</td> |
| |
| <td>\u0000 - \u001F</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">Any other control characters</td> |
| |
| <td>Encoded into its <code>\uABCD</code> equivalent escaped code point</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">"</td> |
| |
| <td>\"</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">\</td> |
| |
| <td>\\</td> |
| </tr> |
| </table> |
| |
| <p> |
| For example, the pattern <code>{"message": "%enc{%m}{JSON}"}</code> could be used to output a |
| valid JSON document containing the log message as a string value. |
| </p> |
| |
| <p>Using the CRLF encoding format, the following characters are replaced:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Character</th> |
| |
| <th>Replacement</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">'\r', '\n'</td> |
| |
| <td>Converted into escaped strings "\\r" and "\\n" respectively</td> |
| </tr> |
| </table> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <b>equals</b>{pattern}{test}{substitution}<br /> |
| <b>equalsIgnoreCase</b>{pattern}{test}{substitution} |
| </td> |
| |
| <td> |
| |
| <p>Replaces occurrences of 'test', a string, with its replacement 'substitution' in the |
| string resulting from evaluation of the pattern. For example, "%equals{[%marker]}{[]}{}" will |
| replace '[]' strings produces by events without markers with an empty string. |
| </p> |
| |
| <p>The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <b>ex</b>|<b>exception</b>|<b>throwable</b><br /> |
| {<br /> |
|   [ "none"<br /> |
|    | "full"<br /> |
|    | depth<br /> |
|    | "short"<br /> |
|    | "short.className"<br /> |
|    | "short.fileName"<br /> |
|    | "short.lineNumber"<br /> |
|    | "short.methodName"<br /> |
|    | "short.message"<br /> |
|    | "short.localizedMessage"]<br /> |
| }<br /> |
|   {filters(package,package,...)}<br /> |
|   {suffix(<i>pattern</i>)}<br /> |
|   {separator(<i>separator</i>)}<br /> |
| </td> |
| |
| <td> |
| |
| <p> |
| Outputs the Throwable trace bound to the logging event, by default this will output the full trace |
| as one would normally find with a call to <code>Throwable.printStackTrace()</code>. |
| </p> |
| |
| <p> |
| You can follow the throwable conversion word with an option in the form <code>%throwable{option}</code>. |
| </p> |
| |
| <p> |
| <code>%throwable{short}</code> outputs the first line of the Throwable. |
| </p> |
| |
| <p> |
| <code>%throwable{short.className}</code> outputs the name of the class where the exception occurred. |
| </p> |
| |
| <p> |
| <code>%throwable{short.methodName}</code> outputs the method name where the exception occurred. |
| </p> |
| |
| <p> |
| <code>%throwable{short.fileName}</code> outputs the name of the class where the exception occurred. |
| </p> |
| |
| <p> |
| <code>%throwable{short.lineNumber}</code> outputs the line number where the exception occurred. |
| </p> |
| |
| <p> |
| <code>%throwable{short.message}</code> outputs the message. |
| </p> |
| |
| <p> |
| <code>%throwable{short.localizedMessage}</code> outputs the localized message. |
| </p> |
| |
| <p> |
| <code>%throwable{n}</code> outputs the first n lines of the stack trace. |
| </p> |
| |
| <p> |
| Specifying <code>%throwable{none}</code> or <code>%throwable{0}</code> suppresses output of the exception. |
| </p> |
| |
| <p> |
| Use <code>{filters(<i>packages</i>)}</code> where <i>packages</i> is a list of package names to |
| suppress matching stack frames from stack traces. |
| </p> |
| |
| <p> |
| Use <code>{suffix(<i>pattern</i>)}</code> to add the output of <i>pattern</i> at the end of each stack frames. |
| </p> |
| |
| <p> |
| Use a <code>{separator(...)}</code> as the end-of-line string. For example: <code>separator(|)</code>. |
| The default value is the <code>line.separator</code> system property, which is operating system dependent. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternFile"></a> |
| <b>F</b><br /> |
| <b>file</b> |
| </td> |
| |
| <td> |
| <p>Outputs the file name where the logging request was issued.</p> |
| |
| <p>Generating the file information (<a href="#LocationInformation">location information</a>) |
| is an expensive operation and may impact performance. Use with caution.</p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <b>highlight</b>{pattern}{style} |
| </td> |
| |
| <td> |
| |
| <p>Adds ANSI colors to the result of the enclosed pattern based on the current event's logging level. |
| (See Jansi <a href="#enable-jansi">configuration</a>.) |
| </p> |
| |
| <p>The default colors for each level are: |
| </p> |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Level</th> |
| |
| <th>ANSI color</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">FATAL</td> |
| |
| <td>Bright red</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">ERROR</td> |
| |
| <td>Bright red</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">WARN</td> |
| |
| <td>Yellow</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">INFO</td> |
| |
| <td>Green</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">DEBUG</td> |
| |
| <td>Cyan</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">TRACE</td> |
| |
| <td>Black (looks dark grey)</td> |
| </tr> |
| </table> |
| |
| |
| <p>The color names are ANSI names defined in the |
| <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/pattern/AnsiEscape.html" class="javadoc">AnsiEscape</a> class. |
| </p> |
| |
| <p>The color and attribute names and are standard, but the exact shade, hue, or value. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption>Color table</caption> |
| |
| <tbody> |
| |
| <tr class="a"> |
| |
| <th>Intensity Code</th> |
| |
| <th>0</th> |
| |
| <th>1</th> |
| |
| <th>2</th> |
| |
| <th>3</th> |
| |
| <th>4</th> |
| |
| <th>5</th> |
| |
| <th>6</th> |
| |
| <th>7</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <th>Normal</th> |
| |
| <td style="background: black;color:white">Black</td> |
| |
| <td style="background: maroon;color:white">Red</td> |
| |
| <td style="background: green;color:white">Green</td> |
| |
| <td style="background: olive;color:white">Yellow</td> |
| |
| <td style="background: navy;color:white">Blue</td> |
| |
| <td style="background: purple;color:white">Magenta</td> |
| |
| <td style="background: teal;color:white">Cyan</td> |
| |
| <td style="background: silver;color:black">White</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <th>Bright</th> |
| |
| <td style="background: gray;color:white">Black</td> |
| |
| <td style="background: red;color:black">Red</td> |
| |
| <td style="background: lime;color:black">Green</td> |
| |
| <td style="background: yellow;color:black">Yellow</td> |
| |
| <td style="background: blue;color:white">Blue</td> |
| |
| <td style="background: fuchsia;color:black">Magenta</td> |
| |
| <td style="background: cyan;color:black">Cyan</td> |
| |
| <td style="background: white;color:black">White</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p>You can use the default colors with: |
| </p> |
| <div> |
| <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}</pre></div> |
| |
| |
| <p>You can override the default colors in the optional {style} option. For example: |
| </p> |
| <div> |
| <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=bright_blue, INFO=black, DEBUG=bright_green, TRACE=blue}</pre></div> |
| |
| |
| <p>At the same time it is possible to use true colors (24 bit). For example: |
| </p> |
| <div> |
| <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=bg_#5792e6 fg_#eef26b bold, INFO=black, DEBUG=#3fe0a8, TRACE=blue}</pre></div> |
| |
| |
| <p>You can highlight only the a portion of the log event: |
| </p> |
| <div> |
| <pre>%d [%t] %highlight{%-5level: %msg%n%throwable}</pre></div> |
| |
| |
| <p>You can style one part of the message and highlight the rest the log event: |
| </p> |
| <div> |
| <pre>%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}</pre></div> |
| |
| |
| <p>You can also use the STYLE key to use a predefined group of colors: |
| </p> |
| <div> |
| <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}</pre></div> |
| The STYLE value can be one of: |
| |
| <table border="0" class="table table-striped"> |
| |
| |
| <tr class="a"> |
| |
| <th>Style</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">Default</td> |
| |
| <td>See above</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">Logback</td> |
| |
| <td> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="b"> |
| |
| <th>Level</th> |
| |
| <th>ANSI color</th> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">FATAL</td> |
| |
| <td>Blinking bright red</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">ERROR</td> |
| |
| <td>Bright red</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">WARN</td> |
| |
| <td>Red</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">INFO</td> |
| |
| <td>Blue</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">DEBUG</td> |
| |
| <td>Normal</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">TRACE</td> |
| |
| <td>Normal</td> |
| </tr> |
| </table> |
| </td> |
| </tr> |
| </table> |
| |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternMap"></a> |
| <b>K</b>{key}<br /> |
| <b>map</b>{key}<br /> |
| <b>MAP</b>{key} |
| </td> |
| |
| <td> |
| |
| <p>Outputs the entries in a |
| <a href="../log4j-api/apidocs/org/apache/logging/log4j/message/MapMessage.html" class="javadoc">MapMessage</a>, |
| if one is present in the event. The <b>K</b> conversion character can be followed by the key |
| for the map placed between braces, as in |
| <b>%K{clientNumber}</b> where <code>clientNumber</code> 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}} |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternLocation"></a> |
| <b>l</b><br /> |
| <b>location</b> |
| </td> |
| |
| <td> |
| |
| <p>Outputs location information of the caller which generated the logging event. |
| </p> |
| |
| <p>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. |
| </p> |
| |
| <p>Generating <a href="#LocationInformation">location information</a> |
| is an expensive operation and may impact performance. Use with caution.</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternLine"></a> |
| <b>L</b><br /> |
| <b>line</b> |
| </td> |
| |
| <td> |
| <p>Outputs the line number from where the logging request |
| was issued.</p> |
| |
| <p>Generating line number information (<a href="#LocationInformation">location information</a>) |
| is an expensive operation and may impact performance. Use with caution.</p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternMessage"></a> |
| <b>m</b>{ansi}<br /> |
| <b>msg</b>{ansi}<br /> |
| <b>message</b>{ansi} |
| </td> |
| |
| <td> |
| |
| <p> |
| Outputs the application supplied message associated with the logging event. |
| </p> |
| |
| <p> |
| From Log4j 2.16.0, support for lookups in log messages has been removed for security reasons. |
| Both the<code>{lookups}</code> and the <code>{nolookups}</code> options on the %m, %msg and %message |
| pattern are now ignored. If either is specified a message will be logged. |
| </p> |
| |
| |
| <p> |
| Add <code>{ansi}</code> to render messages with ANSI escape codes (requires JAnsi, |
| see <a href="#enable-jansi">configuration</a>.) |
| </p> |
| |
| <p> |
| The default syntax for embedded ANSI codes is: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums">@|<i>code</i>(,<i>code</i>)* <i>text</i>|@</pre></div> |
| |
| <p> |
| For example, to render the message <code>"Hello"</code> in green, use: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums">@|green Hello|@</pre></div> |
| |
| <p> |
| To render the message <code>"Hello"</code> in bold and red, use: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums">@|bold,red Warning!|@</pre></div> |
| |
| <p> |
| You can also define custom style names in the configuration with the syntax: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums">%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n</pre></div> |
| |
| <p> |
| For example: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums">%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n</pre></div> |
| |
| <p> |
| The call site can look like this: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums">logger.info("@|KeyStyle {}|@ = @|ValueStyle {}|@", entry.getKey(), entry.getValue());</pre></div> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternMethod"></a> |
| <b>M</b><br /> |
| <b>method</b> |
| </td> |
| |
| <td> |
| <p>Outputs the method name where the logging request was issued.</p> |
| |
| <p>Generating the method name of the caller (<a href="#LocationInformation">location information</a>) |
| is an expensive operation and may impact performance. Use with caution.</p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternMarker"></a> |
| <b>marker</b> |
| </td> |
| |
| <td>The full name of the marker, including parents, if one is present.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternMarkerSimpleName"></a> |
| <b>markerSimpleName</b> |
| </td> |
| |
| <td>The simple name of the marker (not including parents), if one is present.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternMaxLength"></a> |
| <b>maxLen</b><br /> |
| <b>maxLength</b> |
| </td> |
| |
| <td> |
| |
| <p> |
| Outputs the result of evaluating the pattern and truncating the result. 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. |
| </p> |
| |
| <p> |
| Example syntax: <code>%maxLen{%p: %c{1} - %m%notEmpty{ =>%ex{short}}}{160}</code> will be limited to |
| 160 characters with a trailing ellipsis. Another example: <code>%maxLen{%m}{20}</code> will be |
| limited to 20 characters and no trailing ellipsis. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternNewLine"></a> |
| <b>n</b> |
| </td> |
| |
| <td> |
| |
| <p>Outputs the platform dependent line separator character or characters. |
| </p> |
| |
| <p>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. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="NanoTime"></a> |
| <b>N</b><br /> |
| <b>nano</b> |
| </td> |
| |
| <td> |
| <p>Outputs the result of <code>System.nanoTime()</code> at the time the log event was created.</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="Process_ID"></a> |
| <b>pid</b>{[defaultValue]}<br /> |
| <b>processId</b>{[defaultValue]} |
| </td> |
| |
| <td> |
| <p>Outputs the process ID if supported by the underlying platform. An optional default value may be |
| specified to be shown if the platform does not support process IDs.</p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="VariablesNotEmpty"></a> |
| <b>variablesNotEmpty</b>{pattern}<br /> |
| <b>varsNotEmpty</b>{pattern}<br /> |
| <b>notEmpty</b>{pattern} |
| </td> |
| |
| <td> |
| |
| <p> |
| Outputs the result of evaluating the pattern if and only if all variables in the pattern are not empty. |
| </p> |
| |
| <p> |
| For example: |
| </p> |
| <div> |
| <pre>%notEmpty{[%marker]}</pre></div> |
| |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternLevel"></a> |
| <b>p</b>|<b>level</b>{<i>level</i>=<i>label</i>, <i>level</i>=<i>label</i>, ...} |
| <b>p</b>|<b>level</b>{length=<i>n</i>} |
| <b>p</b>|<b>level</b>{lowerCase=<i>true</i>|<i>false</i>} |
| </td> |
| |
| <td> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| For example: |
| </p> |
| <div> |
| <pre>%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}</pre></div> |
| |
| |
| <p> |
| Alternatively, for the compact-minded: |
| </p> |
| <div> |
| <pre>%level{WARN=W, DEBUG=D, ERROR=E, TRACE=T, INFO=I}</pre></div> |
| |
| |
| <p> |
| More succinctly, for the same result as above, you can define the length of the level label: |
| </p> |
| <div> |
| <pre>%level{length=1}</pre></div> |
| If the length is greater than a level name length, the layout uses the normal level name. |
| |
| |
| <p> |
| You can combine the two kinds of options: |
| </p> |
| <div> |
| <pre>%level{ERROR=Error, length=2}</pre></div> |
| This give you the <code>Error</code> level name and all other level names of length 2. |
| |
| |
| <p> |
| Finally, you can output lower-case level names (the default is upper-case): |
| </p> |
| <div> |
| <pre>%level{lowerCase=true}</pre></div> |
| |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternRelative"></a> |
| <b>r</b><br /> |
| <b>relative</b> |
| </td> |
| |
| <td>Outputs the number of milliseconds elapsed since the JVM was started until the creation |
| of the logging event. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternRepeat"></a> |
| <b>R</b>{string}{length}<br /> |
| <b>repeat</b>{string}{length} |
| </td> |
| |
| <td>Produces a string containing the requested number of instances of the specified string. For example, |
| "%repeat{*}{2}" will result in the string "**". |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternReplace"></a> |
| <b>replace</b>{pattern}{regex}{substitution} |
| </td> |
| |
| <td> |
| |
| <p>Replaces occurrences of 'regex', a regular expression, with its replacement 'substitution' in the |
| string resulting from evaluation of the pattern. For example, "%replace{%msg}{\s}{}" will remove |
| all spaces contained in the event message. |
| </p> |
| |
| <p>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. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternException"></a> |
| <b>rEx</b>|<b>rException</b>|<b>rThrowable</b><br /> |
|   {<br /> |
|     ["none" | "short" | "full" | depth]<br /> |
|     [,filters(package,package,...)]<br /> |
|     [,separator(<i>separator</i>)]<br /> |
|   }<br /> |
|   {ansi(<br /> |
|     Key=Value,Value,...<br /> |
|     Key=Value,Value,...<br /> |
|     ...)<br /> |
|   }<br /> |
|   {suffix(<i>pattern</i>)}<br /> |
| </td> |
| |
| <td> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| The throwable conversion word can be followed by an option in the form |
| <code>%rEx{short}</code> which will only output the first line of the Throwable or |
| <code>%rEx{n}</code> where the first n lines of the stack trace will be printed. |
| </p> |
| |
| <p> |
| Specifying <code>%rEx{none}</code> or <code>%rEx{0}</code> will suppress printing of the exception. |
| </p> |
| |
| <p> |
| Use <code>filters(<i>packages</i>)</code> where <i>packages</i> is a list of package names to |
| suppress matching stack frames from stack traces. |
| </p> |
| |
| <p> |
| Use a <code>separator</code> string to separate the lines of a stack trace. For example: |
| <code>separator(|)</code>. The default value is the <code>line.separator</code> system property, |
| which is operating system dependent. |
| </p> |
| |
| <p> |
| Use <code>rEx{suffix(<i>pattern</i>)</code> to add the output of <i>pattern</i> to the output only |
| when there is a throwable to print. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternSequenceNumber"></a> |
| <b>sn</b><br /> |
| <b>sequenceNumber</b> |
| </td> |
| |
| <td>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.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternStyle"></a> |
| <b>style</b>{pattern}{ANSI style} |
| </td> |
| |
| <td> |
| |
| <p>Uses ANSI escape sequences to style the result of the enclosed pattern. The style can consist of |
| a whitespace separated list of style names from the following table. |
| (See Jansi <a href="#enable-jansi">configuration</a>.) |
| </p> |
| <table border="0" class="table table-striped"> |
| |
| <tr class="b"> |
| |
| <th>Style Name</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">Normal</td> |
| |
| <td>Normal display</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">Bright</td> |
| |
| <td>Bold</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">Dim</td> |
| |
| <td>Dimmed or faint characters</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">Underline</td> |
| |
| <td>Underlined characters</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">Blink</td> |
| |
| <td>Blinking characters</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">Reverse</td> |
| |
| <td>Reverse video</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">Hidden</td> |
| |
| <td></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">Black or FG_Black</td> |
| |
| <td>Set foreground color to black</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">Red or FG_Red</td> |
| |
| <td>Set foreground color to red</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">Green or FG_Green</td> |
| |
| <td>Set foreground color to green</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">Yellow or FG_Yellow</td> |
| |
| <td>Set foreground color to yellow</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">Blue or FG_Blue</td> |
| |
| <td>Set foreground color to blue</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">Magenta or FG_Magenta</td> |
| |
| <td>Set foreground color to magenta</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">Cyan or FG_Cyan</td> |
| |
| <td>Set foreground color to cyan</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">White or FG_White</td> |
| |
| <td>Set foreground color to white</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">Default or FG_Default</td> |
| |
| <td>Set foreground color to default (white)</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">BG_Black</td> |
| |
| <td>Set background color to black</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">BG_Red</td> |
| |
| <td>Set background color to red</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">BG_Green</td> |
| |
| <td>Set background color to green</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">BG_Yellow</td> |
| |
| <td>Set background color to yellow</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">BG_Blue</td> |
| |
| <td>Set background color to blue</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">BG_Magenta</td> |
| |
| <td>Set background color to magenta</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">BG_Cyan</td> |
| |
| <td>Set background color to cyan</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">BG_White</td> |
| |
| <td>Set background color to white</td> |
| </tr> |
| </table> |
| |
| |
| <p>For example: |
| </p> |
| <div> |
| <pre>%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}</pre></div> |
| |
| |
| <p>You can also combine styles: |
| </p> |
| <div> |
| <pre>%d %highlight{%p} %style{%logger}{bright cyan} %C{1.} %msg%n</pre></div> |
| |
| |
| <p>You can also use <code>%</code> with a color like <code>%black</code>, <code>%blue</code>, <code>%cyan</code>, and so on. For example: |
| </p> |
| <div> |
| <pre>%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}</pre></div> |
| |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternThreadId"></a> |
| <b>T</b><br /> |
| <b>tid</b><br /> |
| <b>threadId</b> |
| </td> |
| |
| <td>Outputs the ID of the thread that generated the logging event.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternThreadName"></a> |
| <b>t</b><br /> |
| <b>tn</b><br /> |
| <b>thread</b><br /> |
| <b>threadName</b> |
| </td> |
| |
| <td>Outputs the name of the thread that generated the logging event.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternThreadPriority"></a> |
| <b>tp</b><br /> |
| <b>threadPriority</b> |
| </td> |
| |
| <td>Outputs the priority of the thread that generated the logging event.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternLoggerFqcn"></a> |
| <b>fqcn</b> |
| </td> |
| |
| <td>Outputs the fully qualified class name of the logger.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="EndOfBatch"></a> |
| <b>endOfBatch</b> |
| </td> |
| |
| <td>Outputs the EndOfBatch status of the logging event, as "true" or "false".</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternNDC"></a> |
| <b>x</b><br /> |
| <b>NDC</b> |
| </td> |
| |
| <td>Outputs the Thread Context Stack (also known as the Nested Diagnostic Context or NDC) |
| associated with the thread that generated the logging event. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternMDC"></a> |
| <b>X</b>{key[,key2...]}<br /> |
| <b>mdc</b>{key[,key2...]}<br /> |
| <b>MDC</b>{key[,key2...]} |
| </td> |
| |
| <td> |
| |
| <p>Outputs the Thread Context Map (also known as the Mapped Diagnostic Context or MDC) |
| associated with the thread that generated the logging event. The |
| <b>X</b> |
| conversion character can be followed by one or more keys for the |
| map placed between braces, as in |
| <b>%X{clientNumber}</b> |
| where |
| <code>clientNumber</code> |
| is the key. The value in the MDC |
| corresponding to the key will be output.</p> |
| |
| <p>If a list of keys are provided, such as <b>%X{name, number}</b>, then each key that is present in the |
| ThreadContext 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.</p> |
| |
| <p>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. |
| </p> |
| |
| <p>See the |
| <a href="../log4j-api/apidocs/org/apache/logging/log4j/ThreadContext.html" class="javadoc">ThreadContext</a> |
| class for more details. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternUUID"></a> |
| <b>u</b>{"RANDOM" | "TIME"}<br /> |
| <b>uuid</b> |
| </td> |
| |
| <td>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. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"> |
| <a name="PatternExtendedException"></a> |
| <b>xEx</b>|<b>xException</b>|<b>xThrowable</b><br /> |
|   {<br /> |
|     ["none" | "short" | "full" | depth]<br /> |
|     [,filters(package,package,...)]<br /> |
|     [,separator(<i>separator</i>)]<br /> |
|   }<br /> |
|   {ansi(<br /> |
|     Key=Value,Value,...<br /> |
|     Key=Value,Value,...<br /> |
|     ...)<br /> |
|   }<br /> |
|   {suffix(<i>pattern</i>)}<br /> |
| </td> |
| |
| <td> |
| |
| <p>The same as the %throwable conversion word but also includes class packaging information. |
| </p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p>The throwable conversion word can be followed by an option in the form |
| <code>%xEx{short}</code> |
| which will only output the first line of the Throwable or <code>%xEx{n}</code> where |
| the first n lines of the stack trace will be printed. Specifying <code>%xEx{none}</code> |
| or <code>%xEx{0}</code> will suppress printing of the exception. |
| </p> |
| |
| <p> |
| Use <code>filters(<i>packages</i>)</code> where <i>packages</i> is a list of package names to |
| suppress matching stack frames from stack traces. |
| </p> |
| |
| <p> |
| Use a <code>separator</code> string to separate the lines of a stack trace. For example: |
| <code>separator(|)</code>. The default value is the <code>line.separator</code> system property, |
| which is operating system dependent. |
| </p> |
| |
| <p> |
| The <code>ansi</code> option renders stack traces with ANSI escapes code using the JAnsi library. |
| (See <a href="#enable-jansi">configuration</a>.) |
| Use <code>{ansi}</code> to use the default color mapping. You can specify your own mappings with |
| <code>key=value</code> pairs. The keys are: |
| </p> |
| |
| <ul> |
| |
| <li>Prefix</li> |
| |
| <li>Name</li> |
| |
| <li>NameMessageSeparator</li> |
| |
| <li>Message</li> |
| |
| <li>At</li> |
| |
| <li>CauseLabel</li> |
| |
| <li>Text</li> |
| |
| <li>More</li> |
| |
| <li>Suppressed</li> |
| |
| <li>StackTraceElement.ClassName</li> |
| |
| <li>StackTraceElement.ClassMethodSeparator</li> |
| |
| <li>StackTraceElement.MethodName</li> |
| |
| <li>StackTraceElement.NativeMethod</li> |
| |
| <li>StackTraceElement.FileName</li> |
| |
| <li>StackTraceElement.LineNumber</li> |
| |
| <li>StackTraceElement.Container</li> |
| |
| <li>StackTraceElement.ContainerSeparator</li> |
| |
| <li>StackTraceElement.UnknownSource</li> |
| |
| <li>ExtraClassInfo.Inexact</li> |
| |
| <li>ExtraClassInfo.Container</li> |
| |
| <li>ExtraClassInfo.ContainerSeparator</li> |
| |
| <li>ExtraClassInfo.Location</li> |
| |
| <li>ExtraClassInfo.Version</li> |
| </ul> |
| |
| <p> |
| The values are names from JAnsi's |
| <a class="externalLink" href="https://fusesource.github.io/jansi/documentation/api/org/fusesource/jansi/AnsiRenderer.Code.html">Code</a> |
| class like <code>blue</code>, <code>bg_red</code>, and so on (Log4j ignores case.) |
| </p> |
| |
| <p> |
| The special key <code>StyleMapName</code> can be set to one of the following predefined maps: |
| <code>Spock</code>, <code>Kirk</code>. |
| </p> |
| |
| <p> |
| As with %throwable, the <b>%xEx{suffix(<i>pattern</i>)</b> conversion will add the output of |
| <i>pattern</i> to the output only if there is a throwable to print. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"> |
| <a name="PatternPercentLiteral"></a> |
| <b>%</b> |
| </td> |
| |
| <td>The sequence %% outputs a single percent sign. |
| </td> |
| </tr> |
| </table> |
| |
| <p>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. |
| </p> |
| |
| <p>The optional format modifier is placed between the percent sign |
| and the conversion character. |
| </p> |
| |
| <p>The first optional format modifier is the |
| <i>left justification |
| flag |
| </i> |
| which is just the minus (-) character. Then comes the |
| optional |
| <i>minimum field width</i> |
| 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 <i>minimum field width</i> with a zero. |
| </p> |
| |
| <p>This behavior can be changed using the |
| <i>maximum field |
| width |
| </i> |
| 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 |
| <i>beginning</i> |
| 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. |
| </p> |
| |
| <p>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. |
| </p> |
| |
| <p>Below are various format modifier examples for the category |
| conversion specifier. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">Pattern Converters</caption> |
| |
| <tr class="a"> |
| |
| <th>Format modifier</th> |
| |
| <th>left justify</th> |
| |
| <th>minimum width</th> |
| |
| <th>maximum width</th> |
| |
| <th>comment</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%20c</td> |
| |
| <td align="center">false</td> |
| |
| <td align="center">20</td> |
| |
| <td align="center">none</td> |
| |
| <td>Left pad with spaces if the category name is less than 20 |
| characters long. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%-20c</td> |
| |
| <td align="center">true</td> |
| |
| <td align="center">20</td> |
| |
| <td align="center">none</td> |
| |
| <td>Right pad with |
| spaces if the category name is less than 20 characters long. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%.30c</td> |
| |
| <td align="center">NA</td> |
| |
| <td align="center">none</td> |
| |
| <td align="center">30</td> |
| |
| <td>Truncate from the beginning if the category name is longer than 30 |
| characters. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%20.30c</td> |
| |
| <td align="center">false</td> |
| |
| <td align="center">20</td> |
| |
| <td align="center">30</td> |
| |
| <td>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. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">%-20.30c</td> |
| |
| <td align="center">true</td> |
| |
| <td align="center">20</td> |
| |
| <td align="center">30</td> |
| |
| <td>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. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">%-20.-30c</td> |
| |
| <td align="center">true</td> |
| |
| <td align="center">20</td> |
| |
| <td align="center">30</td> |
| |
| <td>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 end. |
| </td> |
| </tr> |
| |
| </table> |
| <a name="enable-jansi"></a> |
| </section><section> |
| <h4><a name="ANSI_Styling_on_Windows"></a>ANSI Styling on Windows</h4> |
| |
| <p>ANSI escape sequences are supported natively on many platforms but are not by default on Windows. To |
| enable ANSI support add the <a class="externalLink" href="https://jansi.fusesource.org/">Jansi</a> jar to your application |
| and set property <code>log4j.skipJansi</code> to <code>false</code>. |
| This allows Log4j to use Jansi to add ANSI escape codes when writing to the console. |
| </p> |
| |
| <p>NOTE: Prior to Log4j 2.10, Jansi was enabled by default. The fact that Jansi requires native code |
| means that Jansi can only be loaded by a single class loader. For web applications this means the |
| Jansi jar has to be in the web container's classpath. To avoid causing problems for web applications, |
| Log4j will no longer automatically try to load Jansi without explicit configuration from Log4j 2.10 onward.</p> |
| </section><section> |
| <h4><a name="Example_Patterns"></a>Example Patterns</h4> |
| <section> |
| <h5><a name="Filtered_Throwables"></a>Filtered Throwables</h5> |
| |
| <p>This example shows how to filter out classes from unimportant packages in stack traces. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><properties> |
| <property name="filters">org.junit,org.apache.maven,sun.reflect,java.lang.reflect</property> |
| </properties> |
| ... |
| <PatternLayout pattern="%m%xEx{filters(${filters})}%n"/></pre></div> |
| |
| <p>The result printed to the console will appear similar to: |
| </p> |
| |
| <div> |
| <pre>Exception java.lang.IllegalArgumentException: IllegalArgument |
| at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:72) [test-classes/:?] |
| ... suppressed 26 lines |
| at $Proxy0.invoke(Unknown Source)} [?:?] |
| ... suppressed 3 lines |
| Caused by: java.lang.NullPointerException: null pointer |
| at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:71) ~[test-classes/:?] |
| ... 30 more</pre></div> |
| </section><section> |
| <h5><a name="ANSI_Styled"></a>ANSI Styled</h5> |
| |
| <p>The log level will be highlighted according to the event's log level. All the content that follows |
| the level will be bright green.</p> |
| |
| <div> |
| <pre class="prettyprint linenums"><PatternLayout> |
| <pattern>%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n</pattern> |
| </PatternLayout></pre></div> |
| <a name="PatternSelectors"></a> |
| </section></section><section> |
| <h4><a name="Pattern_Selectors"></a>Pattern Selectors</h4> |
| |
| <p> |
| The PatternLayout 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. |
| </p> |
| |
| <section> |
| <h5><a name="LevelPatternSelector"></a>LevelPatternSelector</h5> |
| |
| <p> |
| The LevelPatternSelector selects patterns based on the log level of |
| the log event. If the Level in the log event is equal to (ignoring case) |
| the name specified on the PatternMatch key attribute, then |
| the pattern specified on that PatternMatch element will be used. |
| </p> |
| </section><section> |
| <h5><a name="MarkerPatternSelector"></a>MarkerPatternSelector</h5> |
| |
| <p> |
| 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 PatternMatch key attribute, then the |
| pattern specified on that PatternMatch element will be used. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><PatternLayout> |
| <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n"> |
| <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/> |
| </MarkerPatternSelector> |
| </PatternLayout></pre></div> |
| </section><section> |
| <h5><a name="ScriptPatternSelector"></a>ScriptPatternSelector</h5> |
| |
| <p> |
| The ScriptPatternSelector executes a script as described in the <a href="../configuration.html#Scripts">Scripts</a> section of the |
| Configuration chapter. The script is passed all the properties configured in the Properties section of the |
| configuration, the StrSubstitutor used by the Configuration in the "substitutor" variables, and the |
| log event in the "logEvent" variable, and is expected to return the value of the PatternMatch key that |
| should be used, or null if the default pattern should be used. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><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></pre></div> |
| </section></section></section> |
| <a name="RFC5424Layout"></a> |
| <section> |
| <h3><a name="RFC5424_Layout"></a>RFC5424 Layout</h3> |
| |
| <p>As the name implies, the Rfc5424Layout formats LogEvents in accordance with |
| <a class="externalLink" href="https://tools.ietf.org/html/rfc5424">RFC 5424</a>, the enhanced Syslog specification. Although the specification |
| is primarily directed at sending messages via Syslog, this format is quite useful for |
| other purposes since items are passed in the message as self-describing key/value pairs. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">Rfc5424Layout Parameters</caption> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">appName</td> |
| |
| <td>String</td> |
| |
| <td>The value to use as the APP-NAME in the RFC 5424 syslog record.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">charset</td> |
| |
| <td>String</td> |
| |
| <td>The character set to use when converting the syslog String to a byte array. The String must be |
| a valid <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Charset</a>. If not specified, the default system Charset will be used.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">enterpriseNumber</td> |
| |
| <td>integer</td> |
| |
| <td>The IANA enterprise number as described in |
| <a class="externalLink" href="https://tools.ietf.org/html/rfc5424#section-7.2.2">RFC 5424</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">exceptionPattern</td> |
| |
| <td>String</td> |
| |
| <td>One of the conversion specifiers from PatternLayout that defines which ThrowablePatternConverter |
| to use to format exceptions. Any of the options that are valid for those specifiers may be included. |
| The default is to not include the Throwable from the event, if any, in the output.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">facility</td> |
| |
| <td>String</td> |
| |
| <td>The facility is used to try to classify the message. The facility option must be set to one of |
| "KERN", "USER", "MAIL", "DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV", |
| "FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2", "LOCAL3", "LOCAL4", "LOCAL5", |
| "LOCAL6", or "LOCAL7". These values may be specified as upper or lower case characters.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">format</td> |
| |
| <td>String</td> |
| |
| <td>If set to "RFC5424" the data will be formatted in accordance with RFC 5424. Otherwise, it will |
| be formatted as a BSD Syslog record. Note that although BSD Syslog records are required to be |
| 1024 bytes or shorter the SyslogLayout does not truncate them. The RFC5424Layout also does not |
| truncate records since the receiver must accept records of up to 2048 bytes and may accept records |
| that are longer.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">id</td> |
| |
| <td>String</td> |
| |
| <td>The default structured data id to use when formatting according to RFC 5424. If the LogEvent contains |
| a StructuredDataMessage the id from the Message will be used instead of this value.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">includeMDC</td> |
| |
| <td>boolean</td> |
| |
| <td>Indicates whether data from the ThreadContextMap will be included in the RFC 5424 Syslog record. |
| Defaults to true.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">loggerFields</td> |
| |
| <td>List of KeyValuePairs</td> |
| |
| <td>Allows arbitrary PatternLayout patterns to be included as specified ThreadContext fields; no default |
| specified. To use, include a <LoggerFields> nested element, containing one or more |
| <KeyValuePair> elements. Each <KeyValuePair> must have a key attribute, which |
| specifies the key name which will be used to identify the field within the MDC Structured Data element, |
| and a value attribute, which specifies the PatternLayout pattern to use as the value.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">mdcExcludes</td> |
| |
| <td>String</td> |
| |
| <td>A comma separated list of mdc keys that should be excluded from the LogEvent. This is mutually |
| exclusive with the mdcIncludes attribute. This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">mdcIncludes</td> |
| |
| <td>String</td> |
| |
| <td>A comma separated list of mdc keys that should be included in the FlumeEvent. Any keys in the MDC |
| not found in the list will be excluded. This option is mutually exclusive with the mdcExcludes |
| attribute. This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">mdcRequired</td> |
| |
| <td>String</td> |
| |
| <td>A comma separated list of mdc keys that must be present in the MDC. If a key is not present a |
| LoggingException will be thrown. This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">mdcPrefix</td> |
| |
| <td>String</td> |
| |
| <td>A string that should be prepended to each MDC key in order to distinguish it from event attributes. |
| The default string is "mdc:". This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">mdcId</td> |
| |
| <td>String</td> |
| |
| <td>A required MDC ID. This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">messageId</td> |
| |
| <td>String</td> |
| |
| <td>The default value to be used in the MSGID field of RFC 5424 syslog records. </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">newLine</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, a newline will be appended to the end of the syslog record. The default is false.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">newLineEscape</td> |
| |
| <td>String</td> |
| |
| <td>String that should be used to replace newlines within the message text.</td> |
| </tr> |
| |
| </table> |
| </section> |
| <a name="SerializedLayout"></a> |
| <section> |
| <h3><a name="Serialized_Layout"></a>Serialized Layout</h3> |
| |
| <p>The SerializedLayout simply serializes the LogEvent into a byte array using Java Serialization. |
| The SerializedLayout accepts no parameters. |
| </p> |
| |
| <p> |
| This layout is deprecated since version 2.9. Java Serialization has inherent security weaknesses, |
| using this layout is no longer recommended. An alternative layout containing the same information |
| is <a href="#JSONLayout">JsonLayout</a>, configured with <code>properties="true"</code>. |
| </p> |
| </section> |
| <a name="SyslogLayout"></a> |
| <section> |
| <h3><a name="Syslog_Layout"></a>Syslog Layout</h3> |
| |
| <p>The SyslogLayout formats the LogEvent as BSD Syslog records matching the same format used by |
| Log4j 1.2. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">SyslogLayout Parameters</caption> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">charset</td> |
| |
| <td>String</td> |
| |
| <td>The character set to use when converting the syslog String to a byte array. The String must be |
| a valid <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Charset</a>. If not specified, this layout uses UTF-8.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">facility</td> |
| |
| <td>String</td> |
| |
| <td>The facility is used to try to classify the message. The facility option must be set to one of |
| "KERN", "USER", "MAIL", "DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV", |
| "FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2", "LOCAL3", "LOCAL4", "LOCAL5", |
| "LOCAL6", or "LOCAL7". These values may be specified as upper or lower case characters.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">newLine</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, a newline will be appended to the end of the syslog record. The default is false.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">newLineEscape</td> |
| |
| <td>String</td> |
| |
| <td>String that should be used to replace newlines within the message text.</td> |
| </tr> |
| |
| </table> |
| </section> |
| <a name="XMLLayout"></a> |
| <section> |
| <h3><a name="XML_Layout"></a>XML Layout</h3> |
| |
| <p> |
| |
| Appends a series of <code>Event</code> elements as defined in the <a href="log4j.dtd">log4j.dtd</a>. |
| </p> |
| <section> |
| <h4><a name="Complete_well-formed_XML_vs._fragment_XML"></a>Complete well-formed XML vs. fragment XML</h4> |
| |
| <p> |
| If you configure <code>complete="true"</code>, the appender outputs a well-formed XML document where the |
| default namespace is the Log4j namespace <code>"https://logging.apache.org/log4j/2.0/events"</code>. By default, |
| with <code>complete="false"</code>, you should include the output as an <i>external entity</i> in a |
| separate file to form a well-formed XML document, in which case the appender uses |
| <code>namespacePrefix</code> with a default of <code>"log4j"</code>. |
| </p> |
| |
| <p> |
| A well-formed XML document follows this pattern: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><Event xmlns="htthttps://ging.apache.org/log4j/2.0/events" |
| level="INFO" |
| loggerName="HelloWorld" |
| endOfBatch="false" |
| thread="main" |
| loggerFqcn="org.apache.logging.log4j.spi.AbstractLogger" |
| threadId="1" |
| threadPriority="5"> |
| <Instant epochSecond="1493121664" nanoOfSecond="118000000"/> |
| <Marker name="child"> |
| <Parents> |
| <Marker name="parent"> |
| <Parents> |
| <Marker name="grandparent"/> |
| </Parents> |
| </Marker> |
| </Parents> |
| </Marker> |
| <Message>Hello, world!</Message> |
| <ContextMap> |
| <item key="bar" value="BAR"/> |
| <item key="foo" value="FOO"/> |
| </ContextMap> |
| <ContextStack> |
| <ContextStackItem>one</ContextStackItem> |
| <ContextStackItem>two</ContextStackItem> |
| </ContextStack> |
| <Source |
| class="logtest.Main" |
| method="main" |
| file="Main.java" |
| line="29"/> |
| <Thrown commonElementCount="0" message="error message" name="java.lang.RuntimeException"> |
| <ExtendedStackTrace> |
| <ExtendedStackTraceItem |
| class="logtest.Main" |
| method="main" |
| file="Main.java" |
| line="29" |
| exact="true" |
| location="classes/" |
| version="?"/> |
| </ExtendedStackTrace> |
| </Thrown> |
| </Event> |
| </pre></div> |
| |
| <p> |
| If <code>complete="false"</code>, the appender does not write the XML processing instruction and the root |
| element. |
| </p> |
| </section><section> |
| <h4><a name="Marker"></a>Marker</h4> |
| |
| <p>Markers are represented by a <code>Marker</code> element within the <code>Event</code> element. |
| The <code>Marker</code> element appears only when a marker is used in the log message. The name of the marker's |
| parent will be provided in the <code>parent</code> attribute of the <code>Marker</code> element. |
| </p> |
| </section><section> |
| <h4><a name="Pretty_vs._compact_XML"></a>Pretty vs. compact XML</h4> |
| |
| <p> |
| By default, the XML layout is not compact (a.k.a. not "pretty") with <code>compact="false"</code>, which |
| means the appender uses end-of-line characters and indents lines to format the XML. If |
| <code>compact="true"</code>, then no end-of-line or indentation is used. Message content may contain, |
| of course, end-of-lines. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">XmlLayout Parameters</caption> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">charset</td> |
| |
| <td>String</td> |
| |
| <td>The character set to use when converting to a byte array. The value must be a valid <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Charset</a>. |
| If not specified, UTF-8 will be used.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">compact</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, the appender does not use end-of-lines and indentation. Defaults to false.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">complete</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, the appender includes the XML header and footer. Defaults to false.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">properties</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, the appender includes the thread context map in the generated XML. Defaults to false.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">locationInfo</td> |
| |
| <td>boolean</td> |
| |
| <td> |
| |
| <p>If true, the appender includes the location information in the generated XML. Defaults to false.</p> |
| |
| <p>Generating <a href="#LocationInformation">location information</a> |
| is an expensive operation and may impact performance. Use with caution.</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">includeStacktrace</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, include full stacktrace of any logged <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html">Throwable</a> |
| (optional, default to true).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">stacktraceAsString</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to format the stacktrace as a string, and not a nested object (optional, defaults to false).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">includeNullDelimiter</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to include NULL byte as delimiter after each event (optional, default to false).</td> |
| </tr> |
| |
| </table> |
| |
| <p> |
| To include any custom field in the output, use following syntax: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <XmlLayout> |
| <KeyValuePair key="additionalField1" value="constant value"/> |
| <KeyValuePair key="additionalField2" value="$${ctx:key}"/> |
| </XmlLayout> |
| </pre></div> |
| |
| <p> |
| Custom fields are always last, in the order they are declared. The values support <a href="lookups.html">lookups</a>. |
| </p> |
| |
| <p> |
| Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using XmlLayout. |
| </p> |
| </section></section> |
| <a name="YamlLayout"></a> |
| <section> |
| <h3><a name="YAML_Layout"></a>YAML Layout</h3> |
| |
| <p> |
| Appends a series of YAML events as strings serialized as bytes. |
| </p> |
| |
| <p> |
| A YAML log event follows this pattern: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums">--- |
| instant: |
| epochSecond: 1493121664 |
| nanoOfSecond: 118000000 |
| thread: "main" |
| level: "INFO" |
| loggerName: "HelloWorld" |
| marker: |
| name: "child" |
| parents: |
| - name: "parent" |
| parents: |
| - name: "grandparent" |
| message: "Hello, world!" |
| thrown: |
| commonElementCount: 0 |
| message: "error message" |
| name: "java.lang.RuntimeException" |
| extendedStackTrace: |
| - class: "logtest.Main" |
| method: "main" |
| file: "Main.java" |
| line: 29 |
| exact: true |
| location: "classes/" |
| version: "?" |
| contextStack: |
| - "one" |
| - "two" |
| endOfBatch: false |
| loggerFqcn: "org.apache.logging.log4j.spi.AbstractLogger" |
| contextMap: |
| bar: "BAR" |
| foo: "FOO" |
| threadId: 1 |
| threadPriority: 5 |
| source: |
| class: "logtest.Main" |
| method: "main" |
| file: "Main.java" |
| line: 29 |
| </pre></div> |
| |
| <table border="0" class="table table-striped"><caption align="top">YamlLayout Parameters</caption> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">charset</td> |
| |
| <td>String</td> |
| |
| <td>The character set to use when converting to a byte array. The value must be a valid <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Charset</a>. |
| If not specified, UTF-8 will be used.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">properties</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, the appender includes the thread context map in the generated YAML. Defaults to false.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">locationInfo</td> |
| |
| <td>boolean</td> |
| |
| <td> |
| |
| <p>If true, the appender includes the location information in the generated YAML. Defaults to false.</p> |
| |
| <p>Generating <a href="#LocationInformation">location information</a> |
| is an expensive operation and may impact performance. Use with caution.</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">includeStacktrace</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, include full stacktrace of any logged <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html">Throwable</a> |
| (optional, default to true).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">stacktraceAsString</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to format the stacktrace as a string, and not a nested object (optional, defaults to false).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">includeNullDelimiter</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to include NULL byte as delimiter after each event (optional, default to false).</td> |
| </tr> |
| |
| </table> |
| |
| <p> |
| To include any custom field in the output, use following syntax: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <YamlLayout> |
| <KeyValuePair key="additionalField1" value="constant value"/> |
| <KeyValuePair key="additionalField2" value="$${ctx:key}"/> |
| </YamlLayout> |
| </pre></div> |
| |
| <p> |
| Custom fields are always last, in the order they are declared. The values support <a href="lookups.html">lookups</a>. |
| </p> |
| |
| <p> |
| Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using YamlLayout. |
| </p> |
| </section> |
| <a name="LocationInformation"></a> |
| <section> |
| <h3><a name="Location_Information"></a>Location Information</h3> |
| |
| <p> |
| If one of the layouts is |
| configured with a location-related attribute like |
| HTML <a href="#HtmlLocationInfo">locationInfo</a>, |
| or one of the patterns |
| <a href="#PatternClass">%C or %class</a>, |
| <a href="#PatternFile">%F or %file</a>, |
| <a href="#PatternLocation">%l or %location</a>, |
| <a href="#PatternLine">%L or %line</a>, |
| <a href="#PatternMethod">%M or %method</a>, |
| Log4j will take a snapshot of the |
| stack, and walk the stack trace to find the location information. |
| </p> |
| |
| <p> |
| This is an expensive operation: 1.3 - 5 times slower for |
| synchronous loggers. Synchronous loggers wait as |
| long as possible before they take this stack snapshot. If no |
| location is required, the snapshot will never be taken. |
| </p> |
| <p> |
| However, asynchronous loggers need to make this decision before passing the |
| log message to another thread; the location information will be lost after that point. |
| The <a href="../performance.html#asyncLoggingWithLocation">performance impact</a> |
| of taking a stack trace snapshot is even higher for asynchronous loggers: |
| logging with location is 30-100 times slower than without location. |
| For this reason, asynchronous loggers and asynchronous appenders do not include location information by default. |
| </p> |
| <p> |
| You can override the default behaviour in your logger |
| or asynchronous appender configuration |
| by specifying |
| <code>includeLocation="true"</code>. |
| </p> |
| |
| <p> |
| </p> |
| </section> |
| </section> |
| |
| |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p align="center">Copyright © 1999-2024 <a class="external" href="https://www.apache.org">The Apache Software Foundation</a>. All Rights Reserved.<br> |
| Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| </div> |
| </div> |
| </footer> |
| <script> |
| if(anchors) { |
| anchors.add(); |
| } |
| </script> |
| </body> |
| </html> |
