Repository: logging-log4j2 Updated Branches: refs/heads/master 96436fb95 -> e0fd8e131
update Layout page to link to performance page in the section on including caller location and its performance impact Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/e0fd8e13 Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/e0fd8e13 Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/e0fd8e13 Branch: refs/heads/master Commit: e0fd8e13134e478a6a6747159d63b29ff531d0c1 Parents: 96436fb Author: rpopma <[email protected]> Authored: Sat May 21 14:51:34 2016 +0900 Committer: rpopma <[email protected]> Committed: Sat May 21 14:51:34 2016 +0900 ---------------------------------------------------------------------- src/site/xdoc/manual/layouts.xml.vm | 55 +++++++++++++++----------------- 1 file changed, 26 insertions(+), 29 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/e0fd8e13/src/site/xdoc/manual/layouts.xml.vm ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/layouts.xml.vm b/src/site/xdoc/manual/layouts.xml.vm index 80b8dba..3a9d175 100644 --- a/src/site/xdoc/manual/layouts.xml.vm +++ b/src/site/xdoc/manual/layouts.xml.vm @@ -45,8 +45,8 @@ 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> + 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> @@ -62,12 +62,12 @@ </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 + 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. + 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> <pre class="prettyprint linenums"> @@ -75,10 +75,10 @@ logger.info("Ignored", value1, value2, value3); </pre> <p> Which will create the CSV record: - </p> + </p> <pre class="prettyprint linenums"> value1, value2, value3 -</pre> +</pre> <p> Alternatively, you can use a <code>ObjectArrayMessage</code>, which only carries parameters: </p> @@ -99,9 +99,9 @@ logger.info(new ObjectArrayMessage(value1, value2, value3)); <td>format</td> <td>String</td> <td> - One of the predefined formats: <code>Default</code>, <code>Excel</code>, <code>MySQL</code>, + One of the predefined formats: <code>Default</code>, <code>Excel</code>, <code>MySQL</code>, <code>RFC4180</code>, <code>TDF</code>. - See + See <a href="https://commons.apache.org/proper/commons-csv/archives/1.2/apidocs/org/apache/commons/csv/CSVFormat.Predefined.html";>CSVFormat.Predefined</a>. </td> </tr> @@ -124,7 +124,7 @@ logger.info(new ObjectArrayMessage(value1, value2, value3)); <td>quoteMode</td> <td>String</td> <td> - Sets the output quote policy of the format to the specified value. One of: <code>ALL</code>, + 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> @@ -153,13 +153,13 @@ logger.info(new ObjectArrayMessage(value1, value2, value3)); <td>Sets the footer to include when the stream is closed.</td> <td>Desc.</td> </tr> - </table> + </table> <p> Logging as a CSV events looks like this: </p> <pre class="prettyprint linenums"> -logger.debug("one={}, two={}, three={}", 1, 2, 3); -</pre> +logger.debug("one={}, two={}, three={}", 1, 2, 3); +</pre> <p> Produces a CSV record with the following fields: <ol> @@ -178,10 +178,10 @@ logger.debug("one={}, two={}, three={}", 1, 2, 3); <li>Context Map</li> <li>Context Stack</li> </ol> - </p> + </p> <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> +</pre> </subsection> <a name="GELFLayout"/> <subsection name="GELF Layout"> @@ -514,14 +514,14 @@ WARN [main]: Message 2</pre> specifier can be optionally followed by <em>precision specifier</em>, 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 + <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. </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 + 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> @@ -2080,15 +2080,12 @@ source: 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 performance impact of taking a stack trace snapshot is even - higher for asynchronous loggers: logging with location is - 4 - 20 times slower than without location. - For this reason, asynchronous loggers and asynchronous - appenders do not include location information by default. + 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
