Log4j 2
  1. Log4j 2
  2. LOG4J2-225

Improve documentation on use of location in pattern layouts

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 2.0-beta5
    • Fix Version/s: 2.0-beta6
    • Component/s: Documentation
    • Labels:
      None

      Description

      I think the sample configurations should avoid using location-based layouts like %C, %M, %location etc.
      That is, unless the sample demonstrates the location-based capabilities, of course.
      The performance impact of location-based layouts is quite large (something like 5x slower), and I'd hate to give people the first impression that log4j2 is slow because of our own example configs...

      Here is the sample File configuration in http://logging.apache.org/log4j/2.x/manual/appenders.html#FileAppender with my proposed changes:

      <?xml version="1.0" encoding="UTF-8"?>
      <configuration status="warn" name="MyApp" packages="">
      <appenders>
      <File name="MyFile" fileName="logs/app.log">
      <PatternLayout>
      <pattern>%d %p %c

      {1.}

      [%t] %m%n</pattern> <!-- avoid location %C in examples -->
      </PatternLayout>
      </File>
      </appenders>
      <loggers>
      <root level="error">
      <appender-ref ref="MyFile"/>
      </root>
      </loggers>
      </configuration>

      As per discussion on the dev mailing list, there should also be a section heading somewhere called Location Information that specifically identifies each of the location patterns and discusses the overhead of each.

        Activity

        Hide
        Remko Popma added a comment -

        Fixed in revision 1476820.

        Changed most sample pattern layouts that used %C to %c.
        I did not change the sample layout patterns that had %C %M, but added comment in the config XML.

        Appenders page: clarified that the default for immediateFlush is true.

        Layouts page: added a new section Location Information.
        Also added a paragraph to all location-related patterns. For example, class name: "Generating the class name of the caller is an expensive operation and may impact performance. Use with caution."

        Flow Tracing page: added comment in config XML.

        Affected files:
        src/site/site.xml
        src/site/xdoc/manual/appenders.xml
        src/site/xdoc/manual/async.xml
        src/site/xdoc/manual/configuration.xml.vm
        src/site/xdoc/manual/filters.xml
        src/site/xdoc/manual/flowtracing.xml
        src/site/xdoc/manual/layouts.xml.vm
        src/site/xdoc/manual/lookups.xml

        Please review.

        Show
        Remko Popma added a comment - Fixed in revision 1476820. Changed most sample pattern layouts that used %C to %c. I did not change the sample layout patterns that had %C %M, but added comment in the config XML. Appenders page: clarified that the default for immediateFlush is true. Layouts page: added a new section Location Information. Also added a paragraph to all location-related patterns. For example, class name: "Generating the class name of the caller is an expensive operation and may impact performance. Use with caution." Flow Tracing page: added comment in config XML. Affected files: src/site/site.xml src/site/xdoc/manual/appenders.xml src/site/xdoc/manual/async.xml src/site/xdoc/manual/configuration.xml.vm src/site/xdoc/manual/filters.xml src/site/xdoc/manual/flowtracing.xml src/site/xdoc/manual/layouts.xml.vm src/site/xdoc/manual/lookups.xml Please review.

          People

          • Assignee:
            Unassigned
            Reporter:
            Remko Popma
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development