Java : LogManager (ログ) - API使用例

LogManager (Java SE 18 & JDK 18) の使用例まとめです。
だいたいのメソッドを網羅済みです。
API仕様のおともにどうぞ。

概要

Loggerとログ・サービスの共有状態のセットを管理するために使用される単一のグローバルLogManagerオブジェクトがあります。

クラス構成

LogManagerでは、

Logger オブジェクトを、名前空間で階層化された構造(親子関係)として管理
構成ファイル（設定のプロパティ）から、Logger や Handler、Formatterなどの初期設定

を行います。

通常のアプリケーションでは、LogManagerを直接使うことはあまりないでしょう。
LoggerやLogManagerを独自実装するときには、いろいろ必要となるかもしれません。

デフォルトの構成ファイルは、以下の場所に格納されています。

　java-home/conf/logging.properties

OpenJDK 18.0.2.1 の logging.properties を、参考までに一部抜粋します。

############################################################
#  	Global properties
############################################################

handlers= java.util.logging.ConsoleHandler

# Default global logging level.
.level= INFO

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

# Limit the messages that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

もし読み込む構成ファイルを変更したい場合は、

　java.util.logging.config.file

プロパティにパスを指定して java コマンドで渡します。

実際の例で見ていきましょう。
まず、sample.properties ファイルを用意します。

handlers=java.util.logging.ConsoleHandler
.level=ALL
java.util.logging.ConsoleHandler.level=ALL
java.util.logging.ConsoleHandler.formatter=java.util.logging.XMLFormatter

次にメインのクラスです。

import java.util.logging.ConsoleHandler;
import java.util.logging.Logger;

public class Main {

    public static void main(String[] args) {
        System.out.println(System.getProperty("java.util.logging.config.file")); // sample.properties

        final var logger = Logger.getLogger("");
        System.out.println(logger.getLevel()); // ALL

        final var handler = new ConsoleHandler();
        System.out.println(handler.getLevel()); // ALL
        System.out.println(handler.getFormatter()); // java.util.logging.XMLFormatter@3b07d329
    }
}

java コマンドで sample.properties ファイルを指定して、メインクラスを実行します。

java -D"java.util.logging.config.file=sample.properties" Main

関連：ロギング(ログ出力)の基本

フィールド

static final String LOGGING_MXBEAN_NAME

ロギング機能の管理インタフェースのObjectNameの文字列表現。

// java.util.logging:type=Logging
System.out.println(LogManager.LOGGING_MXBEAN_NAME);

コンストラクタ

LogManager ()

protectedコンストラクタです。

LogManagerのインスタンスを取得するには、getLogManager() を使います。

一般的には、LogManagerのサブクラスを作ることは少ないと思います。
そのため、コード例は割愛します。

メソッド

LogManager addConfigurationListener (Runnable listener)

ロギング構成が読み込まれるたびに呼び出される構成リスナーを追加します。

final var logManager = LogManager.getLogManager();

final Runnable listener = () -> {
    System.out.println("Listener OK!");
};

logManager.addConfigurationListener(listener);
logManager.updateConfiguration(null);

// 結果
// ↓
//Listener OK!

logManager.removeConfigurationListener(listener);
logManager.updateConfiguration(null);

// 結果
// ↓
//<なにも表示されません>

boolean addLogger (Logger logger)

名前付きロガーを追加します。

addLogger メソッドは、Logger.getLoggerでログを取得するときなど、必要に応じて自動で呼び出されます。

LoggerやLogManagerを独自実装しない限り、アプリケーションからこのメソッドを呼び出すことはなさそうです。
そのため、API使用例は割愛します。

void checkAccess ()

削除予定のため非推奨: このAPI要素は、将来のバージョンで削除される可能性があります。

非推奨です。

Logger getLogger (String name)

名前付きロガーを検出するメソッドです。

final var logManager = LogManager.getLogManager();

// まだ未登録のため null を返します。
final var ret1 = logManager.getLogger("com.example.logging");
System.out.println(ret1); // null

// LoggerがLogManagerに登録されます。
final var ret2 = Logger.getLogger("com.example.logging");
System.out.println(ret2.getName()); // com.example.logging

final var ret3 = logManager.getLogger("com.example.logging");
System.out.println(ret2 == ret3); // true

Enumeration<String> getLoggerNames ()

既知のロガーの名前の列挙を返します。

final var logManager = LogManager.getLogManager();

// デフォルトでは、ルートロガー(空文字)と Logger.GLOBAL_LOGGER_NAME が登録されています。
final var ret1 = logManager.getLoggerNames();
System.out.println(Collections.list(ret1)); // [, global]

final var loggerA = Logger.getLogger("com.example.logging");
System.out.println(loggerA.getName()); // com.example.logging

final var ret2 = logManager.getLoggerNames();
System.out.println(Collections.list(ret2)); // [, global, com.example.logging]

final var loggerB = Logger.getLogger("com.example");
System.out.println(loggerB.getName()); // com.example

final var ret3 = logManager.getLoggerNames();
System.out.println(Collections.list(ret3));  // [, global, com.example, com.example.logging]

static LoggingMXBean getLoggingMXBean ()

非推奨。 java.util.logging.LoggingMXBeanは非推奨され、java.lang.management.PlatformLoggingMXBeanに置き換えられました。

非推奨です。

static LogManager getLogManager ()

グローバルなLogManagerオブジェクトを返します。

final var logManager = LogManager.getLogManager();
System.out.println(logManager); // java.util.logging.LogManager@79acc4ff

String getProperty (String name)

ログのプロパティの値を返します。

// デフォルトのプロパティは
//    java-home/conf/logging.properties
// に定義されています。

final var logManager = LogManager.getLogManager();

// Global properties
final var ret1 = logManager.getProperty("handlers");
System.out.println(ret1); // java.util.logging.ConsoleHandler

final var ret2 = logManager.getProperty(".level");
System.out.println(ret2); // INFO

// ConsoleHandler
final var ret3 = logManager.getProperty("java.util.logging.ConsoleHandler.level");
System.out.println(ret3); // INFO

final var ret4 = logManager.getProperty("java.util.logging.ConsoleHandler.formatter");
System.out.println(ret4); // java.util.logging.SimpleFormatter

void readConfiguration ()

ロギング構成を読み込み、初期化します。
...
APIのノート:
このreadConfigurationメソッドは、LogManagerの初期化中に構成を初期化するためにのみ使用するか、"java.util.logging.config.class"プロパティで使用する必要があります。

LoggerやLogManagerを独自実装しない限り、アプリケーションからこのメソッドを呼び出すことはなさそうです。
そのため、API使用例は割愛します。

void readConfiguration (InputStream ins)

指定された入力ストリームからログ構成を読み込み、初期化します。
...
APIのノート:
このreadConfigurationメソッドは、LogManagerの初期化中に構成を初期化するためにのみ使用するか、"java.util.logging.config.class"プロパティで使用する必要があります。

"java.util.logging.config.class" プロパティを使う例です。

import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.util.logging.LogManager;

public class LoggerConfig {

    public LoggerConfig() throws IOException {

        // 参考：デフォルトの設定
        //   .level = INFO
        //   java.util.logging.ConsoleHandler.level = INFO
        //   java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

        // 上記のデフォルトとは違う設定にします。
        final var properties = """
                .level = ALL
                java.util.logging.ConsoleHandler.level = ALL
                java.util.logging.ConsoleHandler.formatter = java.util.logging.XMLFormatter
                """;

        try (final var ins = new ByteArrayInputStream(properties.getBytes())) {
            final var logManager = LogManager.getLogManager();
            logManager.readConfiguration(ins);
        }
    }
}

import java.util.logging.ConsoleHandler;
import java.util.logging.Logger;

public class Main {

    public static void main(String[] args) {

        final var ret = System.getProperty("java.util.logging.config.class");
        System.out.println(ret); // LoggerConfig

        final var logger = Logger.getLogger("");
        System.out.println(logger.getLevel()); // ALL

        final var handler = new ConsoleHandler();
        System.out.println(handler.getLevel()); // ALL
        System.out.println(handler.getFormatter()); // java.util.logging.XMLFormatter@3b07d329
    }
}

"java.util.logging.config.class"は java コマンドの -D オプションで指定します。

java -D"java.util.logging.config.class=LoggerConfig" Main

void removeConfigurationListener (Runnable listener)

以前に登録された構成リスナーを削除します。

removeConfigurationListener の使用例は、addConfigurationListener(Runnable listener) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

void reset ()

ログの構成をリセットします。

final var logger = Logger.getLogger("");
System.out.println(logger.getLevel()); // INFO

// ルートロガーをレベルを変えます。
logger.setLevel(Level.ALL);
System.out.println(logger.getLevel()); // ALL

final var logManager = LogManager.getLogManager();
logManager.reset();

System.out.println(logger.getLevel()); // INFO

void updateConfiguration (InputStream ins, Function<String,BiFunction<String,String,String>> mapper)

ロギング構成を更新します。

final var logManager = LogManager.getLogManager();

// 変更前のプロパティ
{
    final var ret1 = logManager.getProperty(".level");
    System.out.println(ret1); // INFO

    final var ret2 = logManager.getProperty("java.util.logging.ConsoleHandler.level");
    System.out.println(ret2); // INFO

    final var ret3 = logManager.getProperty("java.util.logging.ConsoleHandler.formatter");
    System.out.println(ret3); // java.util.logging.SimpleFormatter
}

final var properties = """
        .level=ALL
        java.util.logging.ConsoleHandler.level=ALL
        java.util.logging.ConsoleHandler.formatter=java.util.logging.XMLFormatter
        """;

// すべて新しい構成に置き換える例です。
try (final var ins = new ByteArrayInputStream(properties.getBytes())) {
    logManager.updateConfiguration(ins, null);
}

// 変更後のプロパティ
{
    final var ret1 = logManager.getProperty(".level");
    System.out.println(ret1); // ALL

    final var ret2 = logManager.getProperty("java.util.logging.ConsoleHandler.level");
    System.out.println(ret2); // ALL

    final var ret3 = logManager.getProperty("java.util.logging.ConsoleHandler.formatter");
    System.out.println(ret3); // java.util.logging.XMLFormatter
}

final var logManager = LogManager.getLogManager();

final var properties = """
        .level=ALL
        java.util.logging.ConsoleHandler.level=ALL
        java.util.logging.ConsoleHandler.formatter=java.util.logging.XMLFormatter
        """;

// 一部の値をカスタマイズする例です。
try (final var ins = new ByteArrayInputStream(properties.getBytes())) {
    logManager.updateConfiguration(ins, (k) -> (o, n) -> {
        if (k.equals(".level")) {
            // ルートロガーのレベルは、古い値でも新しい値でもない OFF にします。
            System.out.println(o); // INFO
            System.out.println(n); // ALL

            return "OFF";

        } else {
            // それ以外は新しい値を採用。
            return n;
        }
    });
}

// 変更後のプロパティ
final var ret1 = logManager.getProperty(".level");
System.out.println(ret1); // OFF

final var ret2 = logManager.getProperty("java.util.logging.ConsoleHandler.level");
System.out.println(ret2); // ALL

final var ret3 = logManager.getProperty("java.util.logging.ConsoleHandler.formatter");
System.out.println(ret3); // java.util.logging.XMLFormatter

void updateConfiguration (Function<String,BiFunction<String,String,String>> mapper)