| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.11.1 from target/generated-sources/site/xdoc/manual/customconfig.xml 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" /> |
| <title>Log4j – Extending Log4j 2 Configuration</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><a href="../manual/layouts.html" title="Layouts"><span class="icon-chevron-right"></span>Layouts</a></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 class="active"><a><span class="icon-chevron-down"></span>Programmatic Log4j Configuration</a> |
| <ul class="nav nav-list"> |
| <li><a href="../manual/customconfig.html#ConfigurationBuilder" title="ConfigurationBuilder API"><span class="none"></span>ConfigurationBuilder API</a></li> |
| <li><a href="../manual/customconfig.html#ConfigurationFactory" title="Understanding ConfigurationFactory"><span class="none"></span>Understanding ConfigurationFactory</a></li> |
| <li><a href="../manual/customconfig.html#Example" title="Example"><span class="none"></span>Example</a></li> |
| <li><a href="../manual/customconfig.html#Configurator" title="Using Configurator"><span class="none"></span>Using Configurator</a></li> |
| <li><a href="../manual/customconfig.html#Hybrid" title="Config File and Code"><span class="none"></span>Config File and Code</a></li> |
| <li><a href="../manual/customconfig.html#AddingToCurrent" title="After Initialization"><span class="none"></span>After Initialization</a></li> |
| <li><a href="../manual/customconfig.html#AppendingToWritersAndOutputStreams" title="Appending to Writers & OutputStreams"><span class="none"></span>Appending to Writers & OutputStreams</a></li> |
| </ul></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="Programmatic_Configuration"></a>Programmatic Configuration</h2> |
| |
| <p> |
| Log4j 2 provides a few ways for applications to create their own programmatic configuration: |
| </p> |
| |
| <ul> |
| |
| <li>Specify a custom ConfigurationFactory to start Log4j with a programmatic configuration</li> |
| |
| <li>Use the Configurator to replace the configuration after Log4j started</li> |
| |
| <li>Initialize Log4j with a combination of a configuration file and programmatic configuration</li> |
| |
| <li>Modify the current Configuration after initialization</li> |
| </ul> |
| <a name="ConfigurationBuilder"></a> |
| <section> |
| <h3><a name="The_ConfigurationBuilder_API"></a>The ConfigurationBuilder API</h3> |
| |
| <p> |
| Starting with release 2.4, Log4j provides a ConfigurationBuilder and a set of component builders that |
| allow a Configuration to be created fairly easily. |
| Actual configuration objects like LoggerConfig or Appender can be unwieldy; they require a lot |
| of knowledge about Log4j internals which makes them difficult to work with if all you want is to |
| create a Configuration. |
| </p> |
| |
| <p> |
| The new ConfigurationBuilder API (in the <code>org.apache.logging.log4j.core.config.builder.api</code> package) |
| allows users to create Configurations in code by constructing component <i>definitions</i>. |
| There is no need to work directly with actual configuration objects. |
| Component definitions are added to the ConfigurationBuilder, and once all the definitions have |
| been collected all the actual configuration objects (like Loggers and Appenders) are constructed. |
| </p> |
| |
| <p> |
| ConfigurationBuilder has convenience methods for the base components that can be configured such as |
| Loggers, Appenders, Filter, Properties, etc. |
| However, Log4j 2's plugin mechanism means that users can create any number of custom components. |
| As a trade-off, the ConfigurationBuilder API provides only a limited number of "strongly typed" |
| convenience methods like <code>newLogger()</code>, <code>newLayout()</code> etc. |
| The generic <code>builder.newComponent()</code> method can be used if no convenience method exists |
| for the component you want to configure. |
| </p> |
| |
| <p> |
| For example, the builder does not know what subcomponents can be configured on specific components |
| such as the RollingFileAppender vs. the RoutingAppender. To specify a triggering policy on a |
| RollingFileAppender you would use builder.newComponent(). |
| </p> |
| |
| <p> |
| Examples of using the ConfigurationBuilder API are in the sections that follow. |
| </p> |
| </section> |
| <a name="ConfigurationFactory"></a> |
| <section> |
| <h3><a name="Understanding_ConfigurationFactory"></a>Understanding ConfigurationFactory</h3> |
| |
| <p> |
| During initialization, Log4j 2 will search for available <a href="extending.html#ConfigurationFactory">ConfigurationFactories</a> |
| and then select the one to use. The |
| selected ConfigurationFactory creates the Configuration that Log4j will use. Here is how Log4j finds |
| the available ConfigurationFactories: |
| </p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>A system property named <code>log4j2.configurationFactory</code> can be set with the name of the ConfigurationFactory to be used.</li> |
| |
| <li><code>ConfigurationFactory.setConfigurationFactory(ConfigurationFactory)</code> can be called with the instance of the |
| ConfigurationFactory to be used. This must be called before any other calls to Log4j.</li> |
| |
| <li>A ConfigurationFactory implementation can be added to the classpath and configured as a plugin |
| in the "ConfigurationFactory" category. |
| The Order annotation can be used to specify the relative priority when multiple applicable |
| ConfigurationFactories are found.</li> |
| </ol> |
| |
| <p> |
| ConfigurationFactories have the concept of "supported types", which basically maps to the |
| file extension of the configuration file that the ConfigurationFactory can handle. |
| If a configuration file location is specified, ConfigurationFactories whose supported type |
| does not include "*" or the matching file extension will not be used. |
| </p> |
| </section> |
| <a name="Example"></a> |
| <section> |
| <h3><a name="Initialize_Log4j_Using_ConfigurationBuilder_with_a_Custom_ConfigurationFactory"></a>Initialize Log4j Using ConfigurationBuilder with a Custom ConfigurationFactory</h3> |
| |
| <p> |
| One way to programmatically configure Log4j 2 is to create a custom ConfigurationFactory |
| that uses the <a href="#ConfigurationBuilder">ConfigurationBuilder</a> to create a Configuration. |
| The below example overrides the <code>getConfiguration()</code> method to return a |
| Configuration created by the ConfigurationBuilder. |
| This will cause the Configuration to automatically be hooked into Log4j when the LoggerContext is created. |
| In the example below, because it specifies a supported type of "*" it will override any configuration files provided. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenum"> |
| @Plugin(name = "CustomConfigurationFactory", category = ConfigurationFactory.CATEGORY) |
| @Order(50) |
| public class CustomConfigurationFactory extends ConfigurationFactory { |
| |
| static Configuration createConfiguration(final String name, ConfigurationBuilder<BuiltConfiguration> builder) { |
| builder.setConfigurationName(name); |
| builder.setStatusLevel(Level.ERROR); |
| builder.add(builder.newFilter("ThresholdFilter", Filter.Result.ACCEPT, Filter.Result.NEUTRAL). |
| addAttribute("level", Level.DEBUG)); |
| AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE"). |
| addAttribute("target", ConsoleAppender.Target.SYSTEM_OUT); |
| appenderBuilder.add(builder.newLayout("PatternLayout"). |
| addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable")); |
| appenderBuilder.add(builder.newFilter("MarkerFilter", Filter.Result.DENY, |
| Filter.Result.NEUTRAL).addAttribute("marker", "FLOW")); |
| builder.add(appenderBuilder); |
| builder.add(builder.newLogger("org.apache.logging.log4j", Level.DEBUG). |
| add(builder.newAppenderRef("Stdout")). |
| addAttribute("additivity", false)); |
| builder.add(builder.newRootLogger(Level.ERROR).add(builder.newAppenderRef("Stdout"))); |
| return builder.build(); |
| } |
| |
| @Override |
| public Configuration getConfiguration(final LoggerContext loggerContext, final ConfigurationSource source) { |
| return getConfiguration(loggerContext, source.toString(), null); |
| } |
| |
| @Override |
| public Configuration getConfiguration(final LoggerContext loggerContext, final String name, final URI configLocation) { |
| ConfigurationBuilder<BuiltConfiguration> builder = newConfigurationBuilder(); |
| return createConfiguration(name, builder); |
| } |
| |
| @Override |
| protected String[] getSupportedTypes() { |
| return new String[] {"*"}; |
| } |
| }</pre></div> |
| |
| <p> |
| As of version 2.7, the <code>ConfigurationFactory.getConfiguration()</code> methods take an |
| additional <code>LoggerContext</code> parameter. |
| </p> |
| </section> |
| <a name="Configurator"></a> |
| <section> |
| <h3><a name="Reconfigure_Log4j_Using_ConfigurationBuilder_with_the_Configurator"></a>Reconfigure Log4j Using ConfigurationBuilder with the Configurator</h3> |
| |
| <p> |
| An alternative to a custom ConfigurationFactory is to configure with the <code>Configurator</code>. |
| Once a Configuration object has been constructed, it can be passed to one of the |
| <code>Configurator.initialize</code> methods to set up the Log4j configuration. |
| </p> |
| |
| <p> |
| Using the Configurator in this manner allows the application control over when Log4j is initialized. |
| However, should any logging be attempted before Configurator.initialize() is called then the |
| default configuration will be used for those log events. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenum"> |
| ConfigurationBuilder<BuiltConfiguration> builder = ConfigurationBuilderFactory.newConfigurationBuilder(); |
| builder.setStatusLevel(Level.ERROR); |
| builder.setConfigurationName("BuilderTest"); |
| builder.add(builder.newFilter("ThresholdFilter", Filter.Result.ACCEPT, Filter.Result.NEUTRAL) |
| .addAttribute("level", Level.DEBUG)); |
| AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").addAttribute("target", |
| ConsoleAppender.Target.SYSTEM_OUT); |
| appenderBuilder.add(builder.newLayout("PatternLayout") |
| .addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable")); |
| appenderBuilder.add(builder.newFilter("MarkerFilter", Filter.Result.DENY, Filter.Result.NEUTRAL) |
| .addAttribute("marker", "FLOW")); |
| builder.add(appenderBuilder); |
| builder.add(builder.newLogger("org.apache.logging.log4j", Level.DEBUG) |
| .add(builder.newAppenderRef("Stdout")).addAttribute("additivity", false)); |
| builder.add(builder.newRootLogger(Level.ERROR).add(builder.newAppenderRef("Stdout"))); |
| ctx = Configurator.initialize(builder.build()); |
| </pre></div> |
| |
| <p>This example shows how to create a configuration that includes a RollingFileAppender.</p> |
| |
| <div> |
| <pre class="prettyprint linenum"> |
| ConfigurationBuilder< BuiltConfiguration > builder = ConfigurationBuilderFactory.newConfigurationBuilder(); |
| |
| builder.setStatusLevel( Level.ERROR); |
| builder.setConfigurationName("RollingBuilder"); |
| // create a console appender |
| AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").addAttribute("target", |
| ConsoleAppender.Target.SYSTEM_OUT); |
| appenderBuilder.add(builder.newLayout("PatternLayout") |
| .addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable")); |
| builder.add( appenderBuilder ); |
| // create a rolling file appender |
| LayoutComponentBuilder layoutBuilder = builder.newLayout("PatternLayout") |
| .addAttribute("pattern", "%d [%t] %-5level: %msg%n"); |
| ComponentBuilder triggeringPolicy = builder.newComponent("Policies") |
| .addComponent(builder.newComponent("CronTriggeringPolicy").addAttribute("schedule", "0 0 0 * * ?")) |
| .addComponent(builder.newComponent("SizeBasedTriggeringPolicy").addAttribute("size", "100M")); |
| appenderBuilder = builder.newAppender("rolling", "RollingFile") |
| .addAttribute("fileName", "target/rolling.log") |
| .addAttribute("filePattern", "target/archive/rolling-%d{MM-dd-yy}.log.gz") |
| .add(layoutBuilder) |
| .addComponent(triggeringPolicy); |
| builder.add(appenderBuilder); |
| |
| // create the new logger |
| builder.add( builder.newLogger( "TestLogger", Level.DEBUG ) |
| .add( builder.newAppenderRef( "rolling" ) ) |
| .addAttribute( "additivity", false ) ); |
| |
| builder.add( builder.newRootLogger( Level.DEBUG ) |
| .add( builder.newAppenderRef( "rolling" ) ) ); |
| LoggerContext ctx = Configurator.initialize(builder.build()); |
| </pre></div> |
| </section> |
| |
| <a name="Hybrid"></a> |
| <section> |
| <h3><a name="Initialize_Log4j_by_Combining_Configuration_File_with_Programmatic_Configuration"></a>Initialize Log4j by Combining Configuration File with Programmatic Configuration</h3> |
| |
| <p> |
| Sometimes you want to configure with a configuration file but do some additional programmatic |
| configuration. A possible use case might be that you want to allow for a flexible configuration using XML |
| but at the same time make sure there are a few configuration elements that are always present that can't be removed. |
| </p> |
| |
| <p> |
| The easiest way to achieve this is to extend one of the standard Configuration classes |
| (XmlConfiguration, JSONConfiguration) and then create a new ConfigurationFactory for the extended class. |
| After the standard configuration completes the custom configuration can be added to it. |
| </p> |
| |
| <p> |
| The example below shows how to extend XmlConfiguration to manually add an Appender and a LoggerConfig |
| to the configuration. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| @Plugin(name = "MyXmlConfigurationFactory", category = "ConfigurationFactory") |
| @Order(10) |
| public class MyXmlConfigurationFactory extends ConfigurationFactory { |
| |
| /** |
| * Valid file extensions for XML files. |
| */ |
| public static final String[] SUFFIXES = new String[]{".xml", "*"}; |
| |
| /** |
| * Return the Configuration. |
| * |
| * @param source The InputSource. |
| * @return The Configuration. |
| */ |
| public Configuration getConfiguration(LoggerContext loggerContext, ConfigurationSource source) { |
| return new MyXmlConfiguration(loggerContext, source); |
| } |
| |
| /** |
| * Returns the file suffixes for XML files. |
| * |
| * @return An array of File extensions. |
| */ |
| public String[] getSupportedTypes() { |
| return SUFFIXES; |
| } |
| } |
| |
| public class MyXmlConfiguration extends XmlConfiguration { |
| public MyXmlConfiguration(final LoggerContext loggerContext, final ConfigurationSource configSource) { |
| super(loggerContext, configSource); |
| } |
| |
| @Override |
| protected void doConfigure() { |
| super.doConfigure(); |
| final LoggerContext context = (LoggerContext) LogManager.getContext(false); |
| final Configuration config = context.getConfiguration(); |
| final Layout layout = PatternLayout.createDefaultLayout(config); |
| final Appender fileAppender = FileAppender.newBuilder().setName("target/test.log").withFileName("File") |
| .withImmediateFlush(true).setIgnoreExceptions(false).withBufferedIo(false).withBufferSize(4000) |
| .setLayout(layout).withAdvertise(false).setConfiguration(config) |
| .build(); |
| fileAppender.start(); |
| addAppender(fileAppender); |
| AppenderRef[] refs = new AppenderRef[]{AppenderRef.createAppenderRef(fileAppender.getName(), null, null)}; |
| LoggerConfig loggerConfig = LoggerConfig.createLogger(false, Level.INFO, "org.apache.logging.log4j", |
| "true", refs, null, config, null); |
| loggerConfig.addAppender(fileAppender, null, null); |
| addLogger("org.apache.logging.log4j", loggerConfig); |
| } |
| }</pre></div> |
| </section> |
| <a name="AddingToCurrent"></a> |
| <section> |
| <h3><a name="Programmatically_Modifying_the_Current_Configuration_after_Initialization"></a>Programmatically Modifying the Current Configuration after Initialization</h3> |
| |
| <p> |
| Applications sometimes have the need to customize logging separate from the actual configuration. |
| Log4j allows this although it suffers from a few limitations: |
| </p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>If the configuration file is changed the configuration will be reloaded and the manual changes |
| will be lost.</li> |
| |
| <li>Modification to the running configuration requires that all the methods being called (addAppender |
| and addLogger) be synchronized.</li> |
| </ol> |
| |
| <p> |
| As such, the recommended approach for customizing a configuration is to extend one of the standard |
| Configuration classes, override the setup method to first do super.setup() and then add the custom |
| Appenders, Filters and LoggerConfigs to the configuration before it is registered for use. |
| </p> |
| |
| <p> |
| The following example adds an Appender and a new LoggerConfig using that Appender to the current |
| configuration. |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| final LoggerContext ctx = (LoggerContext) LogManager.getContext(false); |
| final Configuration config = ctx.getConfiguration(); |
| final Layout layout = PatternLayout.createDefaultLayout(config); |
| Appender appender = FileAppender.createAppender("target/test.log", "false", "false", "File", "true", |
| "false", "false", "4000", layout, null, "false", null, config); |
| appender.start(); |
| config.addAppender(appender); |
| AppenderRef ref = AppenderRef.createAppenderRef("File", null, null); |
| AppenderRef[] refs = new AppenderRef[] {ref}; |
| LoggerConfig loggerConfig = LoggerConfig.createLogger("false", "info", "org.apache.logging.log4j", |
| "true", refs, null, config, null ); |
| loggerConfig.addAppender(appender, null, null); |
| config.addLogger("org.apache.logging.log4j", loggerConfig); |
| ctx.updateLoggers(); |
| }</pre></div> |
| </section> |
| <a name="AppendingToWritersAndOutputStreams"></a> |
| <section> |
| <h3><a name="Appending_Log_Events_to_Writers_and_OutputStreams_Programmatically"></a>Appending Log Events to Writers and OutputStreams Programmatically</h3> |
| |
| <p> |
| Log4j 2.5 provides facilities to append log events to Writers and OutputStreams. For example, this |
| provides simple integration for JDBC Driver implementors that use Log4j internally and still want |
| to support the JDBC APIs <code>CommonDataSource.setLogWriter(PrintWriter)</code>, |
| <code>java.sql.DriverManager.setLogWriter(PrintWriter)</code>, and |
| <code>java.sql.DriverManager.setLogStream(PrintStream)</code>. |
| </p> |
| |
| <p> |
| Given any <code>Writer</code>, like a <code>PrintWriter</code>, you tell Log4j to append events to |
| that writer by creating a <code>WriterAppender</code> and updating the Log4j configuration: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| void addAppender(final Writer writer, final String writerName) { |
| final LoggerContext context = LoggerContext.getContext(false); |
| final Configuration config = context.getConfiguration(); |
| final PatternLayout layout = PatternLayout.createDefaultLayout(config); |
| final Appender appender = WriterAppender.createAppender(layout, null, writer, writerName, false, true); |
| appender.start(); |
| config.addAppender(appender); |
| updateLoggers(appender, config); |
| } |
| |
| private void updateLoggers(final Appender appender, final Configuration config) { |
| final Level level = null; |
| final Filter filter = null; |
| for (final LoggerConfig loggerConfig : config.getLoggers().values()) { |
| loggerConfig.addAppender(appender, level, filter); |
| } |
| config.getRootLogger().addAppender(appender, level, filter); |
| }</pre></div> |
| |
| <p> |
| You can achieve the same effect with an <code>OutputStream</code>, like a <code>PrintStream</code>: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| void addAppender(final OutputStream outputStream, final String outputStreamName) { |
| final LoggerContext context = LoggerContext.getContext(false); |
| final Configuration config = context.getConfiguration(); |
| final PatternLayout layout = PatternLayout.createDefaultLayout(config); |
| final Appender appender = OutputStreamAppender.createAppender(layout, null, outputStream, outputStreamName, false, true); |
| appender.start(); |
| config.addAppender(appender); |
| updateLoggers(appender, config); |
| }</pre></div> |
| </section> |
| |
| <p> |
| The difference is the use of <code>OutputStreamAppender</code> instead of <code>WriterAppender</code>. |
| </p> |
| </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> |