高機能ロギングライブラリLog4j2を徹底解説！基本的な使い方から高度な設定まで

はじめに：Log4j2とは何か？

ステップ1：Log4j2の導入と最初のログ出力

まずは、ご自身のプロジェクトにLog4j2を導入し、最初のログを出力してみましょう。ここでは、ビルドツールとして一般的なMavenとGradleの例を紹介します。

依存関係の追加

Log4j2を利用するには、最低限 log4j-api と log4j-core の2つのライブラリが必要です。

<dependencies>
  <dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-api</artifactId>
    <version>2.23.1</version> <!-- 執筆時点の推奨バージョン -->
  </dependency>
  <dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.23.1</version> <!-- 執筆時点の推奨バージョン -->
  </dependency>
</dependencies>

dependencies {
  implementation 'org.apache.logging.log4j:log4j-api:2.23.1'   // 執筆時点の推奨バージョン
  implementation 'org.apache.logging.log4j:log4j-core:2.23.1'  // 執筆時点の推奨バージョン
}

注意：セキュリティの観点から、常に最新の安定バージョンを使用することを強く推奨します。過去のバージョンには重大な脆弱性が存在する可能性があります。

基本的なログ出力コード

依存関係を追加したら、実際にJavaコードからログを出力してみましょう。

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

public class MyApplication {

    // 各クラスでLoggerインスタンスを取得するのが基本
    private static final Logger logger = LogManager.getLogger(MyApplication.class);

    public static void main(String[] args) {
        // 各レベルでログを出力
        logger.trace("これは TRACE レベルのログです。");
        logger.debug("これは DEBUG レベルのログです。");
        logger.info("アプリケーションが起動しました。INFOレベルのログです。");
        logger.warn("警告：設定ファイルが見つかりません。WARNレベルのログです。");
        logger.error("エラーが発生しました。ERRORレベルのログです。", new RuntimeException("テスト用例外"));
        logger.fatal("致命的なエラー。アプリケーションを終了します。FATALレベルのログです。");
    }
}

このコードを実行すると、コンソールに何が表示されるでしょうか？ もし、まだLog4j2の設定ファイルを何も作成していない場合、デフォルトの動作としてERRORレベル以上のログ（ERRORとFATAL）が、非常にシンプルな形式でコンソールに出力されます。

ステップ2：Log4j2の心臓部！設定ファイルの詳解

Log4j2の真価は、柔軟な設定ファイルによって発揮されます。設定ファイルを使うことで、「どのログを」「どこに」「どのような形式で」出力するかを自由自在にコントロールできます。設定ファイルはXML、JSON、YAML、Properties形式で記述できますが、最も一般的で機能も豊富なXML形式を中心に解説します。

設定ファイルは、クラスパスのルートに `log4j2.xml` という名前で配置するのが一般的です。Maven/Gradleプロジェクトであれば、`src/main/resources/log4j2.xml` になります。

設定ファイル（log4j2.xml）の基本構造

まずは、コンソールにINFOレベル以上のログを、特定のフォーマットで出力するための基本的な設定ファイルを見てみましょう。

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">

  <!-- Appenders: ログの出力先を定義する場所 -->
  <Appenders>
    <!-- コンソールに出力するAppender -->
    <Console name="ConsoleAppender" target="SYSTEM_OUT">
      <!-- Layout: ログの出力形式を定義 -->
      <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %c{1} - %msg%n" />
    </Console>
  </Appenders>

  <!-- Loggers: どのログをどのAppenderに出力するかを定義する場所 -->
  <Loggers>
    <!-- Root Logger: すべてのログのデフォルト設定 -->
    <Root level="info">
      <!-- このロガーが使用するAppenderを参照 -->
      <AppenderRef ref="ConsoleAppender" />
    </Root>
  </Loggers>

</Configuration>

この設定ファイルは、大きく分けて <Appenders> と <Loggers> の2つの主要な要素で構成されています。それぞれの役割を詳しく見ていきましょう。

Appenders (アペンダー)：ログの出力先

Appenderは、ログをどこに出力するかを定義するコンポーネントです。代表的なAppenderには以下のようなものがあります。

例として、ファイル出力とローテーションを行う `RollingFileAppender` の設定を見てみましょう。

<Appenders>
  <!-- ... ConsoleAppender ... -->

  <!-- ローリングファイルAppender -->
  <RollingFile name="FileAppender"
               fileName="logs/app.log"
               filePattern="logs/app-%d{yyyy-MM-dd}-%i.log.gz">
    <PatternLayout>
      <Pattern>%d %p %c{1.} [%t] %m%n</Pattern>
    </PatternLayout>
    <Policies>
      <!-- 時間ベースのローテーション（毎日） -->
      <TimeBasedTriggeringPolicy />
      <!-- サイズベースのローテーション（10MBごと） -->
      <SizeBasedTriggeringPolicy size="10 MB" />
    </Policies>
    <!-- 保持するファイルの最大数 -->
    <DefaultRolloverStrategy max="10" />
  </RollingFile>
</Appenders>

この設定では、logs/app.log というファイルにログが書き込まれます。そして、「毎日」または「ファイルサイズが10MBを超えた」場合に、過去のログは `app-2025-07-14-1.log.gz` のような形式で圧縮・保存され、最大10個まで保持されます。

Layouts (レイアウト)：ログの出力形式

Layoutは、各Appender内でログをどのような文字列形式で出力するかを定義します。最も強力で一般的に使われるのが PatternLayout です。pattern 属性に特殊な変換パターンを指定することで、フォーマットをカスタマイズします。

主要な変換パターンは以下の通りです。

Loggers (ロガー)：ログの有効化と紐付け

Loggerは、どのパッケージ（またはクラス）のログを、どのレベル以上で、どのアペンダーに出力するかを定義する、設定の核となる部分です。

Loggersには2種類のロガーがあります。

1. Root Logger (<Root>): すべてのロガーの親となるデフォルトのロガーです。ここで設定したレベルやアペンダーは、個別の設定がないすべてのクラスに適用されます。
2. Named Logger (<Logger>): 特定のパッケージやクラスに対して個別の設定を行うためのロガーです。name属性にパッケージ名やクラス名を指定します。

例えば、以下のような設定を考えてみましょう。

<Loggers>
  <!-- 特定のライブラリ（例: org.hibernate）のログは多すぎるのでWARNレベル以上のみ表示 -->
  <Logger name="org.hibernate" level="warn" additivity="false">
    <AppenderRef ref="ConsoleAppender"/>
  </Logger>

  <!-- 自作アプリケーション（com.example）のログはDEBUGレベル以上をファイルにも出力 -->
  <Logger name="com.example" level="debug" additivity="false">
    <AppenderRef ref="ConsoleAppender"/>
    <AppenderRef ref="FileAppender"/>
  </Logger>

  <!-- その他のログはすべてINFOレベル以上をコンソールに出力 -->
  <Root level="info">
    <AppenderRef ref="ConsoleAppender"/>
  </Root>
</Loggers>

この設定のポイントは以下の通りです。

• ロガーは階層構造になっており、より具体的に指定された `<Logger>` の設定が優先されます。
• com.example.service.MyService のログは、まず `name=”com.example”` の設定にマッチします。
• org.apache.catalina.startup.HostConfig のログは、個別のLoggerにマッチしないため、`<Root>` の設定が適用されます。
• additivity="false" は非常に重要な属性です。これを設定しないと、`com.example` のログは `<Logger name=”com.example”>` と `<Root>` の両方の設定が適用され、同じログがコンソールに2回出力されてしまいます。`additivity=”false”` は、親ロガー（この場合はRoot）の設定を引き継がないことを意味します。

ステップ3：忘れてはならない脆弱性 – Log4Shell

Log4j2を語る上で避けては通れないのが、2021年12月に発覚した、極めて深刻な脆弱性「Log4Shell（CVE-2021-44228）」です。この脆弱性は、IT業界全体に大きな衝撃を与えました。

Log4Shellとは何か？

Log4Shellは、Log4j2が持つ「Lookup」という機能が悪用されることで発生する、リモートコード実行（RCE）の脆弱性です。攻撃者が、ログメッセージに特定の文字列（例: ${jndi:ldap://example.com/a}）を含めることができると、Log4j2がその文字列を解釈し、外部のサーバに接続して、任意のJavaコードをダウンロード・実行してしまう可能性がありました。

ユーザー名や検索クエリなど、外部からの入力値をログに出力しているWebアプリケーションなどが、特に高いリスクに晒されました。

影響を受けるバージョンと対策

この脆弱性の影響を受けるのは、Log4j 2.0-beta9 から 2.14.1 までのバージョンです。その後、複数の関連脆弱性が発見されたため、最終的な推奨事項は以下の通りです。

この事例は、利用しているライブラリのバージョンを常に把握し、セキュリティ情報を継続的に収集して、迅速にアップデートを適用することの重要性を、すべての開発者に教えてくれる教訓となりました。

ステップ4：より実践的な使い方 – SLF4Jとの連携

実際のアプリケーション開発では、Log4j2を直接使用するのではなく、SLF4J (Simple Logging Facade for Java) というライブラリを介して利用することが一般的です。

SLF4Jとは？

SLF4Jは、その名の通り「ロギングの窓口（Facade）」として機能するライブラリです。アプリケーションのコードはSLF4JのAPI（インターフェース）に対してコーディングし、実行時にはその背後で実際にログを処理するライブラリ（Log4j2, Logback, java.util.loggingなど）を自由に差し替えることができます。

このアプローチには、以下のような大きなメリットがあります。

• 疎結合： アプリケーションコードが、特定のロギング実装（Log4j2）に依存しなくなります。将来、Log4j2から別のライブラリ（例: Logback）に乗り換えたくなった場合でも、アプリケーションコードを一切変更することなく、依存ライブラリの差し替えだけで対応できます。
• ライブラリ利用時の統一： 複数の外部ライブラリを利用している場合、それぞれのライブラリが異なるロギング実装を使っていることがあります。SLF4Jのブリッジ機能を使えば、それらのログ出力をすべてLog4j2に集約して管理することが可能になります。

SLF4JとLog4j2を連携させる設定

連携は非常に簡単です。Maven/Gradleに、SLF4JのAPIと、SLF4JからLog4j2へのブリッジライブラリを追加するだけです。

<dependencies>
  <!-- Log4j2 本体 -->
  <dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-api</artifactId>
    <version>2.23.1</version>
  </dependency>
  <dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.23.1</version>
  </dependency>

  <!-- SLF4JからLog4j2へのブリッジ -->
  <dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-slf4j-impl</artifactId>
    <version>2.23.1</version>
  </dependency>
</dependencies>

dependencies {
  // Log4j2 本体
  implementation 'org.apache.logging.log4j:log4j-api:2.23.1'
  implementation 'org.apache.logging.log4j:log4j-core:2.23.1'

  // SLF4JからLog4j2へのブリッジ
  implementation 'org.apache.logging.log4j:log4j-slf4j-impl:2.23.1'
}

SLF4Jを使ったコーディング

コードの書き方も少し変わります。org.apache.logging.log4j のクラスではなく、org.slf4j のクラスを使います。

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class MySlf4jApplication {

    // SLF4JのAPIを使ってLoggerインスタンスを取得
    private static final Logger logger = LoggerFactory.getLogger(MySlf4jApplication.class);

    public void doSomething() {
        // メッセージのプレースホルダ {} を使うのがSLF4J流
        String userId = "user-001";
        logger.info("ユーザーID: {} の処理を開始します。", userId);

        try {
            // ... 何らかの処理 ...
            throw new IllegalArgumentException("無効な引数です");
        } catch (Exception e) {
            // 例外を渡す場合、最後の引数に指定する
            logger.error("処理中にエラーが発生しました。ユーザーID: {}", userId, e);
        }
    }
}

注目すべきは logger.info("メッセージ {}", value) の部分です。SLF4Jでは、{} をプレースホルダとして使い、対応する値を後ろの引数で渡すスタイルが推奨されます。これにより、ログレベルが無効で実際にはログが出力されない場合に、無駄な文字列連結（例: "ID: " + userId）のコストを回避できるというメリットがあります。

この方法でコーディングしておけば、ロギングの実行はLog4j2が担当し、その設定（log4j2.xml）はそのまま利用できます。そして将来、もしロギングライブラリを変更したくなったとしても、コードの変更は一切不要になります。

まとめ