Introduction

Programmatic Log4j configuration is useful when logging settings depend on runtime conditions, test setup, or embedded deployment environments. Instead of loading log4j2.xml or log4j2.properties, you create the configuration in Java and attach it to a LoggerContext.

In modern Java projects, this usually means Log4j 2, not Log4j 1. The recommended approach is to build a Configuration with the builder API and activate it with Configurator.

When Programmatic Configuration Makes Sense

A static file is still the simplest choice for most applications. Programmatic configuration becomes attractive when:

• tests need isolated logging contexts
• appenders depend on runtime paths or credentials
• a framework wants to provide a default configuration in code
• you need to compose file-based and in-memory configuration pieces

If you just want a fixed console logger, a config file is simpler. If the setup is dynamic, the builder API is the right tool.

Building a Configuration in Code

The central objects are:

• 'ConfigurationBuilder, which creates the configuration model'
• 'Configurator, which binds that configuration to a LoggerContext'

Here is a complete Log4j 2 example with a console appender, a package-specific logger, and a root logger:

1import org.apache.logging.log4j.Level;
2import org.apache.logging.log4j.LogManager;
3import org.apache.logging.log4j.Logger;
4import org.apache.logging.log4j.core.LoggerContext;
5import org.apache.logging.log4j.core.config.Configurator;
6import org.apache.logging.log4j.core.config.Configuration;
7import org.apache.logging.log4j.core.config.builder.api.AppenderComponentBuilder;
8import org.apache.logging.log4j.core.config.builder.api.ConfigurationBuilder;
9import org.apache.logging.log4j.core.config.builder.api.ConfigurationBuilderFactory;
10import org.apache.logging.log4j.core.config.builder.impl.BuiltConfiguration;
11
12public class LoggingBootstrap {
13    public static void main(String[] args) {
14        ConfigurationBuilder<BuiltConfiguration> builder =
15            ConfigurationBuilderFactory.newConfigurationBuilder();
16
17        builder.setConfigurationName("runtime-logging");
18        builder.setStatusLevel(Level.ERROR);
19
20        AppenderComponentBuilder console = builder.newAppender("Console", "CONSOLE");
21        console.add(
22            builder.newLayout("PatternLayout")
23                .addAttribute("pattern", "%d [%t] %-5level %logger - %msg%n")
24        );
25
26        builder.add(console);
27        builder.add(
28            builder.newLogger("com.example.service", Level.DEBUG)
29                .add(builder.newAppenderRef("Console"))
30                .addAttribute("additivity", false)
31        );
32        builder.add(
33            builder.newRootLogger(Level.INFO)
34                .add(builder.newAppenderRef("Console"))
35        );
36
37        Configuration configuration = builder.build(false);
38
39        try (LoggerContext context = Configurator.initialize(configuration)) {
40            Logger logger = LogManager.getLogger("com.example.service");
41            logger.debug("Debug message");
42            logger.info("Info message");
43        }
44    }
45}

This approach is declarative even though it is written in code. You are describing the same concepts that a config file would contain: appenders, layouts, logger names, levels, and appender references.

Configuring Specific Loggers

Programmatic configuration becomes especially useful when different packages need different levels. For example, you might want your application code at DEBUG and third-party libraries at WARN.

That can be expressed by adding explicit named loggers and a broader root logger. The root logger catches everything else, while the named logger gives one package more detailed output.

Use additivity = false when you do not want messages from a named logger to bubble up and be written twice through the root logger’s appenders.

Reconfiguring an Existing Context

Sometimes logging has already started and you need to replace the active configuration at runtime. In that case, Configurator.reconfigure(...) is more appropriate than initializing a new context.

That said, reconfiguration should be deliberate. If any code logs before your programmatic setup runs, those earlier log events may use Log4j’s default configuration instead.

Common Pitfalls

The first pitfall is mixing Log4j versions. Log4j 1 and Log4j 2 have different APIs and configuration models. If you are using the builder API shown above, you need log4j-core from Log4j 2 on the classpath.

Another issue is reaching directly into mutable internal configuration objects and changing appenders by hand. That is possible, but it relies on Log4j Core internals and is more brittle than using the builder API.

Initialization order also matters. If loggers are used before your configuration is installed, those early messages may not follow the intended setup.

Finally, do not choose programmatic configuration just because it feels more flexible. If a plain config file can express the same thing, the file is usually easier to operate in production.

Summary

• For Log4j 2, the recommended programmatic path is ConfigurationBuilder plus Configurator.
• Programmatic configuration is useful for dynamic, test-specific, or embedded logging setups.
• Named loggers let you control levels and appenders for specific packages.
• 'additivity = false prevents duplicate logging when a named logger already has its own appender.'
• If the configuration is static, a log4j2.xml or log4j2.properties file is usually the simpler choice.