Introduction

Logback lets you split a large logback.xml file into smaller XML fragments. The mechanism is the <include> element, which can pull configuration from another file, a classpath resource, or a URL.

Include Another XML Fragment with <include>

The main configuration file stays rooted at configuration. Inside it, add an include directive before you reference the included appenders or loggers.

1<configuration>
2  <include resource="logging/appenders.xml"/>
3
4  <root level="INFO">
5    <appender-ref ref="CONSOLE"/>
6  </root>
7</configuration>

The included XML file must not use configuration as its root. According to the Logback manual, included content must be wrapped in an included element.

1<included>
2  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
3    <encoder>
4      <pattern>%d %-5level %logger - %msg%n</pattern>
5    </encoder>
6  </appender>
7</included>

That requirement is the detail most people miss. If you put a full second configuration block inside the included file, Logback will not treat it as a valid include fragment.

file, resource, and url Variants

Logback supports three ways to locate the included XML:

• 'file for a filesystem path'
• 'resource for a classpath resource'
• 'url for a remote XML location'

Examples:

<include file="/etc/myapp/logback-appenders.xml"/>

<include resource="logging/appenders.xml"/>

<include url="http://config.example.com/logback-appenders.xml"/>

In most application code, resource is the cleanest choice because the file travels with the application on the classpath.

Optional Includes

If an included file is environment-specific and may not exist everywhere, mark it optional:

<include resource="logging/local-overrides.xml" optional="true"/>

Without optional="true", Logback reports a status warning when it cannot find the target. That warning is useful for required files, but noisy for local-only overrides.

A Practical Layout Pattern

A common way to organize Logback configuration is:

• keep logback.xml as the top-level composition file
• move shared appenders into one included fragment
• move environment-specific logger levels into another fragment

That keeps the root file readable and reduces copy-paste across services.

It also makes reuse easier across multiple applications. For example, a company-wide console appender pattern can live in one shared classpath resource, while each service keeps only its own logger names and thresholds in the top-level file.

Watch Out for Relative File Paths

When you use the file attribute, relative paths can be misleading. The Logback manual notes that the current directory is defined by the application and is not necessarily related to the location of logback.xml.

That means this:

<include file="config/appenders.xml"/>

may work in one launch setup and fail in another. If the file lives in your application resources, resource is usually more portable than file.

Common Pitfalls

The most common mistake is giving the included file a configuration root instead of included. Logback expects a fragment, not a second full top-level configuration document.

Another issue is referencing an appender before the include has loaded it. Keep include statements near the top of the main configuration so later sections can safely refer to the imported names.

Be careful with relative filesystem paths. They depend on the process working directory, which may differ between local runs, tests, and production.

If an include seems ignored, enable Logback status output during startup and check the reported resource path. Most include bugs turn out to be either the wrong root element or the wrong location attribute.

Summary

• Use <include> inside logback.xml to load XML fragments from a file, resource, or URL.
• Wrap the target fragment in an included root element, not another configuration element.
• Prefer resource for bundled classpath configuration files.
• Use optional="true" for environment-specific includes that may be absent.
• Be cautious with relative file paths because they depend on the application's working directory.