Spring Bootログ設定｜logback-spring.xml全文と設定対応表

Spring Boot のログ設定は、application.yml の logging.* プロパティで書く方法と、logback-spring.xml で書く方法の2つがあり、レベル・出力先・ローテーション・JSON 出力まではプロパティだけで設定できます。 プロファイルごとに出力先の構成そのものを変えたいときや、独自の appender を足したいときに logback-spring.xml を使います。

この記事では、logback-spring.xml の全文テンプレート、同じ内容を application.yml だけで書いた版、logging.* プロパティと XML 要素の対応表、どちらを使うかの判断表、構造化ログ3形式とロググループをまとめます。SLF4J の書き方や Logback 単体の設定は扱わず、Spring Boot 固有の部分に絞っています。

確認環境：Spring Boot 4.1.1 の公式リファレンスで確認（2026年10月7日）。Logback 単体で再現できる部分は Java 21（OpenJDK 21.0.10）と Logback 1.2.11 で、JSON の読み取りは Python 3.11.15 で実行しています。

Spring Bootログ設定の早見表

設定ファイルの名前は logback.xml ではなく logback-spring.xml にします。公式リファレンスは「可能な限り -spring の付いた名前を使う。標準の場所を使うと、Spring がログの初期化を完全には制御できない」と説明しています。

Spring Bootのログの既定の動き

公式リファレンス（4.1.1）に書かれている既定の動きです。

公式リファレンスに載っている既定の出力例です（先頭2行）。

2026-08-17T10:51:28.508Z  INFO 11390 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : Starting MyApplication using Java 25.0.4 with PID 11390 (/opt/apps/myapp.jar started by myuser in /opt/apps/)
2026-08-17T10:51:28.527Z  INFO 11390 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : No active profile set, falling back to 1 default profile: "default"

左から順に、日時（ISO-8601、ミリ秒まで）、レベル、プロセス ID、区切りの ---、アプリ名（spring.application.name を設定した場合）、スレッド名、ロガー名、メッセージです。spring.application.group を設定するとアプリのグループ名が、トレーシングを有効にすると相関 ID も加わります。

logback-spring.xmlの全文テンプレート

開発中（prod 以外）はコンソールに詳しく、prod ではファイルにローテーションつきで出す構成です。src/main/resources/logback-spring.xml として置きます。

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- Spring Boot が用意している既定値（CONSOLE_LOG_PATTERN、FILE_LOG_PATTERN など） -->
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>

    <!-- application.yml の値を Logback の変数として取り込む -->
    <springProperty scope="context" name="appName" source="spring.application.name" defaultValue="app"/>
    <springProperty scope="context" name="logDir" source="app.log.dir" defaultValue="logs"/>

    <!-- コンソール出力 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>${CONSOLE_LOG_PATTERN}</pattern>
            <charset>${CONSOLE_LOG_CHARSET:-UTF-8}</charset>
        </encoder>
    </appender>

    <!-- ファイル出力（日付とサイズでローテーション） -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${logDir}/${appName}.log</file>
        <encoder>
            <pattern>${FILE_LOG_PATTERN}</pattern>
            <charset>${FILE_LOG_CHARSET:-UTF-8}</charset>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${logDir}/${appName}.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>10MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>1GB</totalSizeCap>
        </rollingPolicy>
    </appender>

    <!-- prod 以外（dev やプロファイル指定なし）: コンソールに詳しく出す -->
    <springProfile name="!prod">
        <logger name="com.example.shop" level="DEBUG"/>
        <root level="INFO">
            <appender-ref ref="CONSOLE"/>
        </root>
    </springProfile>

    <!-- prod: ファイルに出す -->
    <springProfile name="prod">
        <root level="INFO">
            <appender-ref ref="FILE"/>
        </root>
    </springProfile>
</configuration>

合わせて使う application.yml です。<springProperty> の source に書いたキーがここから読まれます。

spring:
  application:
    name: shop

app:
  log:
    dir: logs

テンプレートの読み方

<springProfile> の name には、公式リファレンスにある次の3つの書き方が使えます。

<springProfile name="staging">
    <!-- configuration to be enabled when the "staging" profile is active -->
</springProfile>

<springProfile name="dev | staging">
    <!-- configuration to be enabled when the "dev" or "staging" profiles are active -->
</springProfile>

<springProfile name="!production">
    <!-- configuration to be enabled when the "production" profile is not active -->
</springProfile>

<springProfile> は <configuration> の中ならどこにでも書けます。

テンプレートのうち Logback 標準の部分（appender・ローテーション・文字コード）は、Logback 1.2.11 単体に読ませてエラーが出ないことと、logs/app.log が作られることを確かめています。

最小の書き方（Bootの部品をincludeする）

appender を自分で書かず、Spring Boot が用意している部品を取り込む書き方です。公式 How-to の例をそのまま載せます。

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    <include resource="org/springframework/boot/logging/logback/console-appender.xml" />
    <root level="INFO">
        <appender-ref ref="CONSOLE" />
    </root>
    <logger name="org.springframework.web" level="DEBUG"/>
</configuration>

取り込める部品は次の6つです（org/springframework/boot/logging/logback/ の下）。

同じ内容をapplication.ymlだけで書く

上のテンプレートと同じ「prod 以外はコンソール、prod はファイル＋ローテーション」を、XML なしで書いた版です。--- で区切った2つ目のブロックは、prod プロファイルのときだけ有効になります。

# すべてのプロファイルに共通
spring:
  application:
    name: shop

logging:
  level:
    root: info
    com.example.shop: debug
---
# prod プロファイルのときだけ有効
spring:
  config:
    activate:
      on-profile: prod

logging:
  level:
    com.example.shop: info
  console:
    enabled: false
  file:
    name: logs/shop.log
  logback:
    rollingpolicy:
      file-name-pattern: logs/shop.%d{yyyy-MM-dd}.%i.log.gz
      max-file-size: 10MB
      max-history: 30
      total-size-cap: 1GB

この範囲であれば、application.yml だけで同じ構成になります。 application-prod.yml のようにプロファイルごとのファイルに分ける書き方もあり、その場合はプロファイル用のファイルの値が共通のファイルの値より優先されます。

logging.*プロパティの一覧とXMLとの対応

既定値は、公式リファレンスの Logging の章に書かれているものだけを載せ、記載のないものは「—」としています。「変数名」は、Spring Boot がプロパティの値を渡すときのシステムプロパティ名で、logback-spring.xml の中で ${変数名} として参照できます。

出力先とレベル

logging.file.name と logging.file.path の組み合わせは次のとおりです。

レベルに指定できる値は TRACE・DEBUG・INFO・WARN・ERROR・FATAL・OFF です。Logback には FATAL が無いため、ERROR として扱われます。環境変数でも LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG のように指定できますが、これはパッケージ単位の指定に限られます。

--debug（または debug=true）は、組み込みコンテナ・Hibernate・Spring Boot など主要なロガーを詳しくするもので、アプリ全体を DEBUG にする設定ではありません。

パターンと文字コード

ローテーション（Logback）

... は logging.logback の省略です。変数名は LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN のように、プロパティ名を大文字とアンダースコアにしたものです。Log4j2 を使う場合は logging.log4j2.rollingpolicy.*（strategy・cron・time-interval など）が別に用意されています。

構造化ログ

XML で構造化ログを書く場合は、encoder に Spring Boot の StructuredLogEncoder を指定します（公式リファレンスの例）。

<encoder class="org.springframework.boot.logging.logback.StructuredLogEncoder">
    <format>${CONSOLE_LOG_STRUCTURED_FORMAT}</format>
    <charset>${CONSOLE_LOG_CHARSET}</charset>
</encoder>

自分で appender を書いた logback-spring.xml では、logging.file.name などの値は自動では反映されません。 ${LOG_FILE} のように対応する変数を XML の中で参照したときに、プロパティの値が使われます。

プロパティで足りる場合とXMLが要る場合

公式 How-to も、プロパティで足りない細かな調整（独自の appender など）にはログの仕組みそのものの設定ファイルが必要、と説明しています。まずプロパティで書き、足りなくなった時点で logback-spring.xml を足す順番が手間のかからない進め方です。

知っておくとよい点がもう1つあります。ログは ApplicationContext が作られる前に初期化されるため、@Configuration クラスの @PropertySource で読み込んだ値ではログを制御できません。ログの設定は application.yml、環境変数、起動時の引数に書きます。

logback.xmlに書いてspringProfileが効かない例

直す前

次の内容を logback.xml という名前で置いた場合です。

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} %-5level %logger - %msg%n</pattern>
        </encoder>
    </appender>

    <springProfile name="dev">
        <root level="DEBUG">
            <appender-ref ref="CONSOLE"/>
        </root>
    </springProfile>

    <springProfile name="prod">
        <root level="WARN">
            <appender-ref ref="CONSOLE"/>
        </root>
    </springProfile>
</configuration>

公式リファレンスには「標準の logback.xml は読み込まれるのが早すぎるため、その中では拡張機能を使えない。logback-spring.xml を使うか、logging.config プロパティを指定する」とあります。Logback 自身は <springProfile> というタグを知らないためです。

このファイルを Logback 1.2.11 単体に読ませて、log.info(...) と log.debug(...) を1回ずつ呼んだときの出力です。

22:35:09,190 |-INFO in ch.qos.logback.core.joran.action.NestedComplexPropertyIA - Assuming default type [ch.qos.logback.classic.encoder.PatternLayoutEncoder] for [encoder] property
22:35:09,261 |-ERROR in ch.qos.logback.core.joran.spi.Interpreter@9:31 - no applicable action for [springProfile], current ElementPath  is [[configuration][springProfile]]
22:35:09,261 |-ERROR in ch.qos.logback.core.joran.spi.Interpreter@10:29 - no applicable action for [root], current ElementPath  is [[configuration][springProfile][root]]
22:35:09,261 |-ERROR in ch.qos.logback.core.joran.spi.Interpreter@11:42 - no applicable action for [appender-ref], current ElementPath  is [[configuration][springProfile][root][appender-ref]]
…（省略）…
22:35:09,262 |-INFO in ch.qos.logback.classic.joran.action.ConfigurationAction - End of configuration.

<springProfile> とその中身がまるごと読み飛ばされ、root に appender が付かないので、アプリのログは1行も出ませんでした。 公式リファレンスにも、同じ形のメッセージが例として載っています。

ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProperty], current ElementPath is [[configuration][springProperty]]
ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProfile], current ElementPath is [[configuration][springProfile]]

直した後

git mv src/main/resources/logback.xml src/main/resources/logback-spring.xml

3つ目は、公式リファレンスに「拡張機能は Logback の設定ファイルの自動再読み込み（configuration scanning）とは併用できない」とあるためです。

構造化ログ3形式の設定と使い分け

構造化ログは、ログを決まった形（JSON）で出して機械で読みやすくする方法です。Spring Boot は ecs・gelf・logstash の3形式を標準で持ち、プロパティ1行で切り替えられます。

spring:
  application:
    name: shop
    version: 1.0.0

logging:
  structured:
    format:
      console: ecs        # ecs / gelf / logstash のいずれか
    ecs:
      service:
        environment: prod
        node-name: shop-1
    json:
      add:
        team: platform
      stacktrace:
        root: first
        max-length: 2048
---
spring:
  config:
    activate:
      on-profile: file-json

logging:
  file:
    name: logs/shop.json
  structured:
    format:
      file: logstash

1つ目のブロックはコンソールを ecs 形式にし、環境名・ノード名・固定の項目 team を足して、スタックトレースを原因が先に来る並びにしています。2つ目のブロックは file-json プロファイルのときに、ファイルへ logstash 形式で出す例です。コンソールとファイルで別の形式を選べます。

公式リファレンスの出力例

ecs

{"@timestamp":"2024-01-01T10:15:00.067462556Z","log":{"level":"INFO","logger":"org.example.Application"},"process":{"pid":39599,"thread":{"name":"main"}},"service":{"name":"simple"},"message":"No active profile set, falling back to 1 default profile: \"default\"","ecs":{"version":"8.11"}}

gelf

{"version":"1.1","short_message":"No active profile set, falling back to 1 default profile: \"default\"","timestamp":1725958035.857,"level":6,"_level_name":"INFO","_process_pid":47649,"_process_thread_name":"main","_log_logger":"org.example.Application"}

logstash

{"@timestamp":"2024-01-01T10:15:00.111037681+02:00","@version":"1","message":"No active profile set, falling back to 1 default profile: \"default\"","logger_name":"org.example.Application","thread_name":"main","level":"INFO","level_value":20000}

同じ情報がどのキーに入るかを調べる

3つの出力例を読み込み、キーを一覧にするスクリプトです。ログを検索するときに、形式ごとのキー名を確かめる用途に使えます。

"""公式リファレンスに載っている3形式のログ1行を読み、同じ情報がどのキーに入るかを並べる。"""
import json

SAMPLES = {
    "ecs": r'''{"@timestamp":"2024-01-01T10:15:00.067462556Z","log":{"level":"INFO","logger":"org.example.Application"},"process":{"pid":39599,"thread":{"name":"main"}},"service":{"name":"simple"},"message":"No active profile set, falling back to 1 default profile: \"default\"","ecs":{"version":"8.11"}}''',
    "gelf": r'''{"version":"1.1","short_message":"No active profile set, falling back to 1 default profile: \"default\"","timestamp":1725958035.857,"level":6,"_level_name":"INFO","_process_pid":47649,"_process_thread_name":"main","_log_logger":"org.example.Application"}''',
    "logstash": r'''{"@timestamp":"2024-01-01T10:15:00.111037681+02:00","@version":"1","message":"No active profile set, falling back to 1 default profile: \"default\"","logger_name":"org.example.Application","thread_name":"main","level":"INFO","level_value":20000}''',
}


def flatten(obj, prefix=""):
    for key, value in obj.items():
        path = f"{prefix}{key}"
        if isinstance(value, dict):
            yield from flatten(value, path + ".")
        else:
            yield path, value


for name, line in SAMPLES.items():
    print(f"[{name}]")
    for path, value in flatten(json.loads(line)):
        text = str(value)
        print(f"  {path:<24} = {text if len(text) <= 40 else text[:37] + '...'}")

実行結果

[ecs]
  @timestamp               = 2024-01-01T10:15:00.067462556Z
  log.level                = INFO
  log.logger               = org.example.Application
  process.pid              = 39599
  process.thread.name      = main
  service.name             = simple
  message                  = No active profile set, falling back t...
  ecs.version              = 8.11
[gelf]
  version                  = 1.1
  short_message            = No active profile set, falling back t...
  timestamp                = 1725958035.857
  level                    = 6
  _level_name              = INFO
  _process_pid             = 47649
  _process_thread_name     = main
  _log_logger              = org.example.Application
[logstash]
  @timestamp               = 2024-01-01T10:15:00.111037681+02:00
  @version                 = 1
  message                  = No active profile set, falling back t...
  logger_name              = org.example.Application
  thread_name              = main
  level                    = INFO
  level_value              = 20000

「—」は、公式の出力例の1行に含まれていなかった項目です。

使い分け

どの形式でも、MDC に入れたキーと値は JSON の項目として加わります。 ecs では SLF4J の fluent API の addKeyValue で足した値も出力され、logstash ではマーカーが tags という文字列の配列に入ります。

3形式で合わない場合は、StructuredLogFormatter を実装したクラスを作り、そのクラス名を logging.structured.format.console（または file）に指定します。公式リファレンスの例です。

import ch.qos.logback.classic.spi.ILoggingEvent;

import org.springframework.boot.logging.structured.StructuredLogFormatter;

class MyCustomFormat implements StructuredLogFormatter<ILoggingEvent> {

    @Override
    public String format(ILoggingEvent event) {
        return "time=" + event.getInstant() + " level=" + event.getLevel() + " message=" + event.getMessage() + "\n";
    }

}

ロググループ（web・sql）の使い方

ロググループは、関連するロガーに1つの名前を付けて、まとめてレベルを変える仕組みです。Spring Boot には最初から次の2つが定義されています。

logging:
  level:
    web: debug      # 定義済みグループ: リクエスト処理まわり
    sql: debug      # 定義済みグループ: 発行される SQL
    batch: info
  group:
    batch: "com.example.shop.batch,org.springframework.batch"

パッケージ名を覚えていなくても web・sql の2語で切り替えられるのが便利なところです。調査が終わったら元のレベルに戻しておくと、ログの量を抑えられます。

版ごとの違い

公式のリリースノートと Migration Guide で確認できたものです。

Boot 3 から上げるときにログで見直すのは、文字コードを明示していなかった場合の出力と、logging.console.enabled を使ってファイル出力だけにできるようになった点の2つです。

よくある質問

Q. logback.xml と logback-spring.xml のどちらを置けばよいですか？ A. logback-spring.xml です。<springProfile> と <springProperty> はこちらでだけ使え、公式リファレンスも -spring の付いた名前を勧めています。

Q. logging.file.name と logging.file.path を両方書くとどうなりますか？ A. logging.file.name が使われ、logging.file.path は使われません。ファイル名まで決めたいなら name、フォルダだけ決めて spring.log という名前でよければ path を選びます。

Q. --debug を付ければ全部 DEBUG になりますか？ A. なりません。組み込みコンテナ・Hibernate・Spring Boot など主要なロガーが詳しくなるだけです。自分のアプリを DEBUG にするには logging.level.com.example.shop: debug のようにパッケージを指定します。

Q. JSON で出すのに logback-spring.xml は必要ですか？ A. 不要です。logging.structured.format.console: ecs のように1行足せば切り替わります。項目の追加や名前の変更も logging.structured.json.* で設定できます。

まとめ

• レベル・ファイル出力・ローテーション・JSON 出力は logging.* プロパティだけで設定できる
• XML が要るのは、appender の構成そのものを変えるとき。 ファイル名は logback-spring.xml
• <springProfile> と <springProperty> は logback.xml では使えない。 no applicable action が出たらファイル名を確かめる
• プロパティは LOG_FILE などの変数として XML に渡る。 自作の appender では変数を参照して初めて反映される
• 構造化ログは ecs・gelf・logstash の3形式。 集める先に合わせて選び、MDC の値はどの形式でも出る
• web・sql のロググループで、関連するロガーをまとめて切り替えられる
• Boot 4 ではログファイルの既定の文字コードが UTF-8、コンソール出力は logging.console.enabled で止められる

参考・出典

いずれも 2026年10月7日に確認しました。

• Spring Boot リファレンス 4.1.1「Logging」: https://docs.spring.io/spring-boot/reference/features/logging.html
• Spring Boot How-to「Logging」: https://docs.spring.io/spring-boot/how-to/logging.html
• Spring Boot リファレンス 4.1.1「Externalized Configuration」: https://docs.spring.io/spring-boot/reference/features/external-config.html
• Spring Boot 4.0 Migration Guide: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
• Spring Boot 4.0 Release Notes: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes
• Spring Boot 3.4 Release Notes: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.4-Release-Notes
• Spring Boot プロジェクトページ: https://spring.io/projects/spring-boot

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。