For AI agents: the complete documentation index is available at /Practical-Introduction-to-Spring-Boot/llms.txt, the full documentation bundle is available at /Practical-Introduction-to-Spring-Boot/llms-full.txt, and this page is available as Markdown at /Practical-Introduction-to-Spring-Boot/SpringBoot入門/ロギング入門.md.

Spring Boot ロギング入門 - アクセスログ・業務ログを集める

講義の区切り

基本編の目安は 90 分です。終了条件は「アクセスログ・MDC・業務ログを確認」です。 発展内容・次回の目安: AOP・構造化ログ。基本の確認後に取り組んでください。 準備と前後の章は 学習ガイド で確認できます。

概要

Java / Spring Boot のロギングの基本を学ぶ勉強会です。ログの重要性、ログレベル、デフォルトのロギングライブラリである Logback について、設定方法、実践パターンを扱います。

対象読者

  • Java / Spring Boot でアプリケーションを開発しているが、ロギングを「なんとなく」使っている方
  • ログレベルやロギングライブラリの選び方を整理したい方
  • 本番運用を見据えたログ設計(構造化ログ、MDC、監査ログ)を学びたい方

前提知識と到達目標

Controller / Service の実装と DI を理解している方が対象です。Java 21 と Maven Wrapper を使います。 まずアクセスログを追加し、何が記録されるかを確認します。 その後、MDC で同じリクエストのログをつなげ、最後に Service の業務ログを完成させます。AOP と構造化ログは発展内容です。 完了時には、アクセス・業務・例外のログを読み、リクエスト ID で関連する処理を追えることを目指します。

この資料の構成

この資料は 2 部構成になっています。

  1. 触って学ぶロギング: サンプルアプリを実際に作りながら、アクセスログ・業務ログ・MDC を実装していくハンズオン
  2. 座学で学ぶロギング: ロギングの基本概念、ログレベル、SLF4J / Logback、構造化ログなどの理論を整理する座学

「触って学ぶ」で実装した内容を、「座学で学ぶ」で概念として整理し、復習する流れです。対応関係は次の表の通りです。

触って学ぶロギング

ログの重要性

ハンズオンを始める前に、この機能を使う目的を確認しましょう。ログは、アプリケーションの「行動記録」です。後から発生した事象を調査する手がかりになります。

このハンズオンでは、アクセスログ、業務ログ、MDC を実際に実装しながら、「ログを残す」ことの価値を体感していきます。ログの目的の詳細(デバッグ、障害調査、監視、監査、性能分析)は、後半の「座学で学ぶロギング」で整理します。

ログレベルの軽い導入

ログには重要度を表す「ログレベル」があります。レベルを設定することで、出力するログを絞り込めます。

レベル用途
TRACE最も詳細なデバッグ情報
DEBUG開発・デバッグ用の詳細情報
INFO通常運用で確認すべき情報
WARN注意が必要だが処理は継続
ERROR処理が失敗した場合

レベルは TRACE < DEBUG < INFO < WARN < ERROR の順に重要度が高く、設定したレベル以上のログだけが出力されます。例えば INFO に設定すると、INFO / WARN / ERROR が出力され、DEBUG / TRACE は出力されません。

このハンズオンでは、主に INFO と WARN を使います。詳細なレベルについては、後半の「座学で学ぶロギング」で改めて整理します。

Spring Initializr

次のリンクから Spring Initializr を開き、 Spring Boot プロジェクトを作成してください。

Spring Initializr

生成前に Spring Boot が 4.0 系であることを確認します。4.0.2 が表示されない場合は、利用可能な 4.0 系の安定版を選んでください。

生成したプロジェクトの pom.xml がある場所で ./mvnw spring-boot:run を実行します。 Java や設定ファイルを変更した後は、Ctrl+C で停止して起動し直してください。 以降の Java コードは、package 宣言に対応する src/main/java 配下へ配置します。

アプリの作成

このアプリでは、簡易的なユーザー管理APIを用意します。

  • /addUser: ユーザーを追加する
  • /removeUser: ユーザーを削除する
  • /getUsers: 登録済みユーザー一覧を取得する
  • /fireException: 例外を発生させ、失敗時のログを確認する

このサンプルはメモリ上のユーザー集合を使うため、再起動でデータが消えます。 追加は POST、削除は DELETE、一覧の取得は GET で行います。

サービスの作成

src/main/java/dev/mikoto2000/springboot/logging/service/UserService.java:

package dev.mikoto2000.springboot.logging.service;

import java.util.HashSet;
import java.util.concurrent.ConcurrentHashMap;
import java.util.Set;

import org.springframework.stereotype.Service;

/**
 * UserService
 */
@Service
public class UserService {

  private final Set<String> users = ConcurrentHashMap.newKeySet();

  public void addUser(String name) {
    users.add(name);
  }

  public void removeUser(String name) {
    users.remove(name);
  }

  public Set<String> getUsers() {
    return new HashSet<String>(users);
  }

  public void fireException() {
    throw new RuntimeException("Hello, Exception!!!");
  }
}

コントローラーの作成

src/main/java/dev/mikoto2000/springboot/logging/controller/UserController.java:

package dev.mikoto2000.springboot.logging.controller;

import java.util.Set;

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import dev.mikoto2000.springboot.logging.service.UserService;
import lombok.RequiredArgsConstructor;

/**
 * UserController
 */
@RequiredArgsConstructor
@RestController
public class UserController {

  private final UserService service;

  @PostMapping("addUser")
  public void addUser(
      @RequestParam String name
      ) {
    service.addUser(name);
  }

  @DeleteMapping("removeUser")
  public void removeUser(
      @RequestParam String name
      ) {
    service.removeUser(name);
  }

  @GetMapping("getUsers")
  public Set<String> getUsers() {
    return service.getUsers();
  }

  @GetMapping("fireException")
  public void fireException() {
    service.fireException();
  }
}

アクセスログの追加

各エンドポイントにアクセスしたことを記録する、アクセスログを追加します。

Filter は、Controller の前後でリクエストを処理する仕組みです。 chain.doFilter で後続の処理へ渡し、その前後で情報を記録します。 次の例では finally でログを残すため、後続処理が例外を投げた場合も記録できます。

アクセスログ用フィルタの作成

src/main/java/dev/mikoto2000/springboot/logging/filter/AccessLogFilter.java:

package dev.mikoto2000.springboot.logging.filter;

import java.io.IOException;
import java.util.concurrent.TimeUnit;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@Component
@Order(Ordered.LOWEST_PRECEDENCE)
public class AccessLogFilter extends OncePerRequestFilter {

    private static final Logger accessLogger = LoggerFactory.getLogger("ACCESS_LOG");

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain chain)
            throws ServletException, IOException {

        long start = System.nanoTime();

        // 接続元 IP 取得
        String ip = request.getRemoteAddr();

        // 成功・失敗フラグ
        boolean success = false;

        try {
            chain.doFilter(request, response);
            success = true;
        } finally {

            long time = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - start);

            accessLogger.info("ip={}, method={}, request_url={}, status={}, success={}, time={}ms",
                ip,
                request.getMethod(),
                request.getRequestURI(),
                response.getStatus(),
                success ? "SUCCESS" : "FAIL",
                time);
        }
    }
}

アクセスログの動作確認

curl コマンドで、それぞれのエンドポイントにアクセスしてみましょう。 ついでに存在しないエンドポイントにもアクセスしてみます。

curl -X POST "http://localhost:8080/addUser?name=mikoto2000"
curl http://localhost:8080/getUsers
curl -X DELETE "http://localhost:8080/removeUser?name=mikoto2000"
curl -i http://localhost:8080/fireException
curl http://localhost:8080/invalidEndpoint

次のようなログが出力されます。

2026-02-10T20:59:38.021Z  INFO 51208 --- [logging] [nio-8080-exec-1] ACCESS_LOG : ip=127.0.0.1, method=POST, request_url=/addUser, status=200, success=SUCCESS, time=22ms
2026-02-10T20:59:38.050Z  INFO 51208 --- [logging] [nio-8080-exec-2] ACCESS_LOG : ip=127.0.0.1, method=GET, request_url=/getUsers, status=200, success=SUCCESS, time=15ms
2026-02-10T20:59:38.064Z  INFO 51208 --- [logging] [nio-8080-exec-4] ACCESS_LOG : ip=127.0.0.1, method=DELETE, request_url=/removeUser, status=200, success=SUCCESS, time=1ms
2026-02-10T20:59:38.082Z  INFO 51208 --- [logging] [nio-8080-exec-5] ACCESS_LOG : ip=127.0.0.1, method=GET, request_url=/fireException, status=200, success=FAIL, time=6ms
2026-02-10T20:59:38.109Z  INFO 51208 --- [logging] [nio-8080-exec-6] ACCESS_LOG : ip=127.0.0.1, method=GET, request_url=/invalidEndpoint, status=404, success=SUCCESS, time=3ms
  • ip: アクセス元の IP アドレス ※実務では、プロキシ配下等の場合に IP の取得方法にひと工夫が必要である(今回は割愛)
  • method: HTTP メソッド(GET / POST など)
  • request_url: アクセスされたパス
  • status: この Filter を抜ける時点の HTTP ステータスコード(200 / 404 など)
  • success: 後続処理から例外が伝われば FAIL、それ以外は SUCCESS。HTTP ステータスの成功・失敗とは別の指標
  • time: 処理にかかった時間(ミリ秒)

例外時には、この Filter のログ出力後にサーバーがエラー応答を作ることがあります。 /fireException の status=200, success=FAIL は、最終的な応答が 200 という意味ではありません。 curl -i で最終的な 500 と比較してください。運用で最終ステータスが必要な場合は、サーバーのアクセスログも検討します。

また、注目してほしいのは 404 で応答したリクエストもちゃんとログに記録されているところです。success は後続処理から例外が伝わったかどうかの指標なので、404 でも SUCCESS になります。 Filter でアクセスログを取得しているため、コントローラーが呼ばれない場合でも記録できます。

Controller の開始・終了ログを追加

業務ログの一種として、Controller の開始・終了ログを出力します。これは境界ログとも呼ばれます。

発展トピック: AOP。

この章は AOP(Aspect Oriented Programming) を使った実装です。AOP は「共通処理を業務ロジックとは別のクラスに分離する」というやや発展的なテーマです。初めての方や難しく感じた方は、この章を読み飛ばして次の「MDC の追加」に進んでも問題ありません。あとで余裕ができたら戻ってきてください。

pom.xml の修正

開始・終了ログは、 AOP(Aspect Oriented Programming) の機能を使って実装していきます。 まずは Spring Boot で AOP が使えるように依存を追加します。

pom.xml:

既存の pom.xml 全体を置き換えず、dependencies の中に次を追加します。

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-aspectj</artifactId>
</dependency>

ログ出力コード実装

次に、ログを出力するコードを実装します。次のコードを追加してください。

src/main/java/dev/mikoto2000/springboot/logging/aop/LoggingAspect.java:

package dev.mikoto2000.springboot.logging.aop;

import java.util.concurrent.TimeUnit;

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

@Aspect
@Component
public class LoggingAspect {

  private static final Logger log = LoggerFactory.getLogger(LoggingAspect.class);

  @Around(
    "within(dev.mikoto2000.springboot.logging.controller..*)"
  )
  public Object logMethod(ProceedingJoinPoint pjp) throws Throwable {

    // メソッド情報取得
    String className = pjp.getTarget().getClass().getSimpleName();
    String methodName = pjp.getSignature().getName();

    log.info("START {}#{}", className, methodName);

    // 時間計測開始
    long startTime = System.nanoTime();
    try {

      Object result = pjp.proceed();

      // 時間計測終了
      long endTime = System.nanoTime();

      log.info("END   {}#{}, time={}ms", className, methodName, TimeUnit.NANOSECONDS.toMillis(endTime - startTime));

      return result;

    } catch (Throwable e) {

      // 時間計測終了
      long endTime = System.nanoTime();

      log.error("ERROR {}#{}, time={}ms", className, methodName, TimeUnit.NANOSECONDS.toMillis(endTime - startTime), e);

      throw e;
    }
  }
}
@Aspect と @Around について
@Aspect

AOP(Aspect Oriented Programming)では、ログ出力やトランザクション管理などの「共通処理」を業務ロジックとは別のクラスとして実装します。

この共通処理を定義するクラスには、@Aspect アノテーションを付与します。

@Aspect を付けることで、このクラスが「AOP の処理を定義するクラス(Aspect)」として Spring に認識されます。

@Around

@Around は、対象となるメソッドの実行を「前後から包み込む」ためのアノテーションです。

今回のサンプルでは、次のように定義することで、Controller のメソッドを実行する前後の処理を記述しています。

  "within(dev.mikoto2000.springboot.logging.controller..*)"

この記述方法は Pointcut と呼ばれます。Pointcut とは「どのメソッドに共通処理を適用するか」を指定する式のことです。今回の例では、within(...) という式を使って「controller パッケージ配下のすべてのメソッド」を対象にしています。

Pointcut の書き方を少し詳しく見てみましょう。

  • within(パッケージ..*): 指定したパッケージ配下のすべてのメソッドが対象
  • execution(戻り値 クラス.メソッド(引数)): 特定のクラス・メソッドを細かく指定
  • @annotation(アノテーション): 指定したアノテーションを持つメソッドを対象とする

今回の within(dev.mikoto2000.springboot.logging.controller..*) は、「controller パッケージ配下のすべてのメソッド」にログ出力を適用する、という意味です。..* の部分が「パッケージ配下のすべて」を表しています。

Pointcut は奥が深いテーマですが、まずは「どのメソッドに適用するかを式で指定するもの」という理解で十分です。詳しく学びたい方は、参考資料の「AOP の概念」を参照してください。

動作確認

ここまで来たらもう一度動作確認をしてみましょう。

curl -X POST "http://localhost:8080/addUser?name=mikoto2000"

次のようなログが表示されるようになっています。

2026-02-10T20:59:38.017Z INFO 51208 --- [logging] [nio-8080-exec-1] d.m.s.logging.aop.LoggingAspect : START UserController#addUser
2026-02-10T20:59:38.017Z INFO 51208 --- [logging] [nio-8080-exec-1] d.m.s.logging.aop.LoggingAspect : END   UserController#addUser, time=0ms

MDC(Mapped Diagnostic Context) の追加

MDC を使い、アクセスログと、この後に追加する業務ログを同じリクエスト ID で結び付けます。 AOP の発展演習まで進んだ場合は、Controller の開始・終了ログにも同じ ID が入ります。

MDC を使用するようにコードを修正

src/main/java/dev/mikoto2000/springboot/logging/filter/AccessLogFilter.java を、次のように修正します。

src/main/java/dev/mikoto2000/springboot/logging/filter/AccessLogFilter.java:

講義では処理の入口・finally の終了処理に注目します。完成コードは実装時に開いてください。

AccessLogFilter の完成コード
package dev.mikoto2000.springboot.logging.filter;

import java.io.IOException;
import java.util.concurrent.TimeUnit;
import java.util.UUID;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@Component
@Order(Ordered.LOWEST_PRECEDENCE)
public class AccessLogFilter extends OncePerRequestFilter {

    private static final Logger accessLogger = LoggerFactory.getLogger("ACCESS_LOG");

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain chain)
            throws ServletException, IOException {

        /* 追加ここから */
        // MDC に記録する値を取得
        String user = "dummy"; // Spring Security と連携すると取得できる
        String traceId = UUID.randomUUID().toString();

        // MDC に値をセット
        MDC.put("user", user);
        MDC.put("traceId", traceId);
        /* 追加ここまで */

        long start = System.nanoTime();

        // 接続元 IP 取得
        String ip = request.getRemoteAddr();

        // 成功・失敗フラグ
        boolean success = false;

        try {
            chain.doFilter(request, response);
            success = true;
        } finally {

            long time = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - start);

            accessLogger.info("ip={}, method={}, request_url={}, status={}, success={}, time={}ms",
                ip,
                request.getMethod(),
                request.getRequestURI(),
                response.getStatus(),
                success ? "SUCCESS" : "FAIL",
                time);

            /* 追加ここから */
            // MDC クリア
            MDC.remove("user");
            MDC.remove("traceId");
            /* 追加ここまで */
        }
    }
}

MDC を表示するように Logback を設定

MDC を表示したい場合には、 %X{xxx} 形式で、 PATTERN に記述します。

src/main/resources/logback-spring.xml:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- Spring Bootのデフォルト設定を読み込む(defaults.xmlで変数が定義される) -->
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>

    <!-- コンソールの出力パターンのみを上書き定義する -->
    <property name="CONSOLE_LOG_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId:-}] [%X{user:-}] %-5level %logger{36} - %msg%n"/>

    <!-- デフォルトのコンソールアペンダーを読み込む(上のpropertyが適用される) -->
    <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>

    <root level="INFO">
        <appender-ref ref="CONSOLE" />
    </root>
</configuration>

MDC の動作確認

もう一度 curl コマンドで、エンドポイントにアクセスしてみましょう。

curl -X POST "http://localhost:8080/addUser?name=mikoto2000"
curl -X DELETE "http://localhost:8080/removeUser?name=mikoto2000"

AOP も実装した場合は、次のように開始・終了ログとアクセスログが出力されます。

2026-02-11 00:22:56.046 [http-nio-8080-exec-3] [92a4a2a9-0db6-4072-bc81-2547f7d48da5] [dummy] INFO  d.m.s.logging.aop.LoggingAspect - START UserController#addUser
2026-02-11 00:22:56.047 [http-nio-8080-exec-3] [92a4a2a9-0db6-4072-bc81-2547f7d48da5] [dummy] INFO  d.m.s.logging.aop.LoggingAspect - END   UserController#addUser, time=0ms
2026-02-11 00:22:56.047 [http-nio-8080-exec-3] [92a4a2a9-0db6-4072-bc81-2547f7d48da5] [dummy] INFO  ACCESS_LOG - ip=127.0.0.1, method=POST, request_url=/addUser, status=200, success=SUCCESS, time=1ms
2026-02-11 00:24:08.395 [http-nio-8080-exec-5] [7154ca6d-5764-43ae-a045-956f6b0617ad] [dummy] INFO  d.m.s.logging.aop.LoggingAspect - START UserController#removeUser
2026-02-11 00:24:08.395 [http-nio-8080-exec-5] [7154ca6d-5764-43ae-a045-956f6b0617ad] [dummy] INFO  d.m.s.logging.aop.LoggingAspect - END   UserController#removeUser, time=0ms
2026-02-11 00:24:08.396 [http-nio-8080-exec-5] [7154ca6d-5764-43ae-a045-956f6b0617ad] [dummy] INFO  ACCESS_LOG - ip=127.0.0.1, method=DELETE, request_url=/removeUser, status=200, success=SUCCESS, time=2ms

AOP も実装した場合は、同じリクエストの開始・終了ログとアクセスログで traceId が一致します。 基本編では、リクエストごとにアクセスログの traceId が変わることを確認してください。

このようにすると、「traceId で grep をかけると見たいリクエストのみが時系列で追える」などのメリットが出てきます。

MDC 補足

MDC は「スレッドごとに記録できる Map」というイメージです。 こう捉えると、理解しやすいでしょう。 MDC に値をセットすると、そのスレッドで出力するログに、セットした値を含められます。

この教材の同期処理では、リクエストを処理するスレッドに値を設定します。 別スレッドや非同期処理には自動で引き継がれないため、必要ならコンテキストを受け渡す設計が必要です。 スレッドは再利用されるので、処理後は finally で設定したキーを削除します。

user 補足

今回は、 user に dummy という値をリテラルで設定していましたが、 本来であれば次のコードのように Spring Security と連携し、ユーザー情報を取得します。

Authentication auth =
  SecurityContextHolder.getContext().getAuthentication();

if (auth != null && auth.isAuthenticated()
    && !(auth instanceof AnonymousAuthenticationToken)) {
  MDC.put("user", auth.getName());
}

上記は Spring Security を導入した場合の断片例です。 Authentication、SecurityContextHolder、AnonymousAuthenticationToken を import して利用します。 このハンズオンには認証を導入していないため、まずは dummy のまま進めてください。

業務ログを完成させる

Controller の開始・終了ログを出力したことで、クラス名とメソッド名から「大体何をやっているか」は分かるようになりましたが、業務ログでは 5W1H が重要です。 Service にログを入れることで、業務ログを完成させましょう。

今回は例として Service 層に「誰を追加、削除したか」というログを追加します。 業務ではログ設計、ログ方針に応じてログを出力するようにしましょう。

Controller では処理の境界を、Service では業務上の意味を持つイベントをログに記録するというイメージです。

src/main/java/dev/mikoto2000/springboot/logging/service/UserService.java:

package dev.mikoto2000.springboot.logging.service;

import java.util.HashSet;
import java.util.concurrent.ConcurrentHashMap;
import java.util.Set;

import org.springframework.stereotype.Service;

import lombok.extern.slf4j.Slf4j;

/**
 * UserService
 */
@Service
@Slf4j
public class UserService {

  private final Set<String> users = ConcurrentHashMap.newKeySet();

  public void addUser(String name) {
    /* 修正ここから */
    if (users.add(name)) {
      log.info("Add user: name={}", logValue(name));
    } else {
      log.warn("Add user failed: name={}", logValue(name));
    }
    /* 修正ここまで */
  }

  public void removeUser(String name) {
    /* 修正ここから */
    if (users.remove(name)) {
      log.info("Remove user: name={}", logValue(name));
    } else {
      log.warn("Remove user failed: name={}", logValue(name));
    }
    /* 修正ここまで */
  }

  public Set<String> getUsers() {
    return new HashSet<String>(users);
  }

  // 外部入力の改行・制御文字を無害化し、ログの長さを制限する。
  private static String logValue(String value) {
    if (value == null) return "<null>";
    StringBuilder result = new StringBuilder();
    value.codePoints().limit(80).forEach(cp -> {
      if (Character.isISOControl(cp) || cp == 0x2028 || cp == 0x2029) {
        result.append('?');
      } else {
        result.appendCodePoint(cp);
      }
    });
    return result.toString();
  }

  public void fireException() {
    throw new RuntimeException("Hello, Exception!!!");
  }
}

ユーザー入力はログ専用の logValue で制御文字を置換し、80コードポイントまでに制限します。 プレースホルダーだけでは改行を無害化できません。保存する値とログに出す値は区別します。 個人情報を記録する必要性も判断し、実務では内部 ID など必要な項目だけを使います。

業務ログの動作確認

再起動後、同じ名前で /addUser を 2 回呼び、最初は INFO、2 回目は WARN になることを確認します。 次に /removeUser を 2 回呼び、削除できた場合と対象がいない場合を比べてください。 curl -X POST "http://localhost:8080/addUser?name=A%0AB" も実行し、業務ログの name が1行の A?B になることを確認します。 AOP を省略した場合も、Service のログとアクセスログに同じ traceId が入れば MDC の確認はできます。 今回の traceId はアプリ内のリクエスト識別子です。分散トレーシングの ID を自動で伝播しているわけではありません。

座学で学ぶロギング

この部のコードは概念説明の抜粋です。import や周辺クラスを省略しており、ファイル全体として配置しません。 ハンズオンの完成コードは前半に掲載しています。設定例は適用条件を確認して既存の設定へ反映します。

ロギングの基本概念と重要性

ロギングとは何をすることか

ロギングとは、アプリケーションの動作中に発生するイベントや状態変化を記録する仕組みです。プログラムが「何を」「いつ」「どのように」実行したかを、時系列のテキストとして残します。

具体的には、以下のようなことを行います。

  • イベントの記録: 起動、リクエスト受信、処理完了、例外発生などを記録する
  • 状態変化の記録: 変数の値、処理の分岐、リソースの利用状況などを記録する
  • 文脈情報の付与: ユーザー ID、リクエスト ID、処理時間などをログに含める
  • 原因調査の支援: 不具合発生時に、処理の流れや変数の値を再現して原因を特定するための記録(デバッグの手がかり)

つまりロギングは、アプリケーションの「行動記録」を残すことで、後から何が起きたかを再現し、調査できるようにするための仕組みです。

なぜログが必要か

ログは以下の目的で不可欠です。それぞれの「なぜ」を押さえると、ログ設計の判断基準が見えてきます。

  • デバッグ: 開発中に処理の流れや変数の値を確認し、不具合の原因を特定する。開発中は DEBUG レベルを活用し、詳細な情報を残す
  • 障害調査: 問題発生時に原因を特定するための手がかり。本番では INFO 以上を残し、トレース ID で相関を取れるようにする
  • 監視・アラート: システムの異常を早期に検知する。WARN / ERROR を監視対象にし、アラートの基準を決める
  • 監査・コンプライアンス: 誰がいつ何をしたかを記録する。改ざん防止や保存期間の要件を満たすため、通常のログと分離して保存する
  • 性能分析: 処理時間やリソース使用量の傾向を把握する。パフォーマンスログを残し、閾値を超えた処理を WARN で記録する

ログ・トレース・メトリクスの違い

ログ・トレース・メトリクスは「3 つの柱」として並べて語られることが多いですが、観測対象が異なるため、同列に扱うのではなく「何を見たいか」で使い分けるのが正しい理解です。

観点ログトレースメトリクス
目的イベント記録・状態把握リクエストの流れを追跡数値の集計・傾向把握
粒度個別イベント単位リクエスト全体単位集計値(時系列)
質問「何が起きたか」「どこで遅い・失敗したか」「どれくらい起きたか」
相関ログ単体では文脈が分かりにくいトレース ID で全体を俯瞰数値の増減で異常を検知
ツールLogback / Log4j2 などOpenTelemetry / Jaeger などPrometheus / Micrometer など
  • ログ: 個々のイベントの詳細(エラー内容、アクセス元など)。原因調査に強い
  • トレース: リクエストの流れを俯瞰し、遅延や失敗の箇所を特定する
  • メトリクス: CPU 使用率やリクエスト数などの数値を集計し、傾向把握・監視アラートに強い

ログは「点」、トレースは「線」、メトリクスは「面(数値の時系列)」で捉えると理解しやすいです。「ログで原因を探る、メトリクスで異常を検知する、トレースで全体像を掴む」と使い分けるのが定番です。三者を組み合わせることで、システム全体の可視性が向上します。

今回の資料の対象。

今回の資料はログについてを説明するものです。トレースやメトリクスの詳細は扱いませんが、ログを正しく理解するために、この違いを冒頭で押さえておきます。

良いログとは何か

ログは「誰が読むのか」を意識して設計すると、その価値が大きく変わります。ログの読み手は主に以下の 3 種類です。

  • 開発者: デバッグや障害調査で、処理の流れと原因を追う
  • 運用担当者: 監視・アラートで、異常の早期検知と対応判断に使う
  • 監査・セキュリティ担当: 誰が何をしたかの記録として、コンプライアンス要件を満たす

読み手が違えば必要な情報も変わります。開発者は詳細な変数の値やスタックトレースを、運用担当者は処理の開始、完了、失敗の要約を、監査担当者はユーザー ID と操作内容を求めます。ログは「誰の」「何の」ために残すかを決めてから設計するのが基本です。

また、ログには以下のような種類があります。

  • アクセスログ: 誰がいつどのリクエストを送ったか(HTTP アクセス、認証イベント)
  • アプリケーションログ: 業務処理の開始・完了・失敗、例外発生
  • 監査ログ: 誰が何をしたか(操作履歴、権限変更)
  • システムログ: 起動・停止、リソース状態、設定変更

このようにログは「記録の目的」ごとに分けて考えると、何を、どのレベルで、どういう形式で残すべきかが明確になります。次の「ログ出力の基本原則」は、こうしたログ設計の考え方を実践に落とし込むための指針です。

ログ出力の基本原則

  1. 適切なレベルで出力する — 重要度に応じてレベルを使い分ける
  2. 文脈情報を含める — ユーザー ID、リクエスト ID などをログに含める
  3. 機密情報を出さない — パスワード、個人情報、認証情報はログに含めない
  4. ログは構造化する — 機械的に解析できる形式で出力する
以降の章について。

以下では、ハンズオンで使ったログレベル、SLF4J、Logback、MDC を整理します。 構造化ログや監査ログは、基本のログを読めるようになってから進めてください。

ログレベル(TRACE / DEBUG / INFO / WARN / ERROR)とフィルタリング

ログレベルの一覧

レベル用途例
TRACE最も詳細なデバッグ情報SQL のバインドパラメータ、内部状態の遷移
DEBUG開発・デバッグ用の詳細情報メソッド呼び出し、変数の値
INFO通常運用で確認すべき情報起動、リクエスト受信、処理完了
WARN注意が必要だが処理は継続リトライ発生、リソース枯渇の兆候
ERROR処理が失敗した場合例外発生、DB 接続失敗
OFFログ出力を完全に停止特定パッケージのログを止めたい場合

OFF はログの重要度ではなく、出力を停止するための設定値です。

レベルの優先順位

TRACE < DEBUG < INFO < WARN < ERROR

設定したレベル以上のログだけが出力されます。例えば INFO に設定すると、INFO / WARN / ERROR が出力され、DEBUG / TRACE は出力されません。

フィルタリング

ログレベルによるフィルタリングは、以下の観点で行います。

  • パッケージ・クラス単位: 特定のパッケージだけ DEBUG にする
  • ロガー名単位: 特定のクラスだけ詳細ログを出す
  • 環境ごとの設定: 開発環境は DEBUG、本番環境は INFO など

レベル設定の実践例

application.yaml
logging:
  level:
    root: INFO                    # ルートロガーは INFO
    dev.mikoto2000.springboot.logging.service: DEBUG    # 特定パッケージは DEBUG
    dev.mikoto2000.springboot.logging.service.UserService: TRACE  # 特定クラスは TRACE

SLF4J と Logback(Spring Boot のデフォルト)

SLF4J(Simple Logging Facade for Java)

SLF4J はロギングライブラリのファサード(窓口)です。アプリケーションコードは SLF4J の API だけを使い、実際のロギング実装をプラグ可能にします。

SLF4J の使用例
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

private static final Logger log = LoggerFactory.getLogger(MyClass.class);
log.info("処理を開始します: {}", userId);

メリット:

  • 実装ライブラリを後から差し替えられる
  • コード変更なしで Logback → Log4j2 に移行可能
  • {} プレースホルダによって、出力しないログの文字列組み立てを避けられる

Logback

SLF4J の標準実装として最も広く使われています。Spring Boot のデフォルトです。

特徴:

  • 設定ファイル: logback.xml / logback-spring.xml
  • Spring Boot の標準設定と組み合わせて使える
  • 自動リロード、条件付き設定に対応
  • 豊富なアペンダー(コンソール、ファイル、DB、メールなど)

発展トピック: Log4j2

Apache が開発するロギングライブラリで、非同期ロギングの高性能さや豊富なフィルタリング機能が特徴です。ただし Spring Boot では別途依存追加が必要で、設定も複雑になります。

入門者へのアドバイス。

入門者はまず Logback を使い、高度な非同期や複雑なフィルタが必要になってから Log4j2 を検討するのがおすすめです。

Spring Boot でのロギング設定

application.yaml での設定

ここからは Spring Boot の標準ログ設定を使います。生成済みの src/main/resources/application.yaml に次の logging 設定を追記します。同名の logging キーがあれば、その中へ統合してください。別の application.yml は作成しません。 前節のレベル設定例を適用した場合は、logging.level からパッケージ単位・クラス単位の指定を削除し、次の root だけにします。個別に指定したレベルは、root を変更しても上書きされません。 先に logback-spring.xml を logback-spring.xml.disabled へ改名し、アプリを停止してください。 独自 XML の CONSOLE だけの設定では、次の logging.file.name を指定しても FILE appender は作られません。 ./mvnw clean spring-boot:run で起動し直します。clean で target/classes に残った旧 XML を取り除きます。 リクエストを送り、コンソールと logs/app.log の両方へ記録されることを確認します。 MDC を続けて表示する場合は、次の pattern に %X{traceId} と %X{user} を含めます。

application.yaml
logging:
  level:
    root: INFO          # ルートロガーのレベル
  file:
    name: logs/app.log  # ログファイル出力
  logback:
    rollingpolicy:
      max-file-size: 10MB
      max-history: 30
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} traceId=%X{traceId} user=%X{user} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} traceId=%X{traceId} user=%X{user} - %msg%n"

環境ごとの設定

application-{profile}.yaml を使うと、環境ごとにログレベルを変えられます。

application-dev.yaml
logging:
  level:
    root: DEBUG
application-prod.yaml
logging:
  level:
    root: INFO

共通設定には root: INFO だけを置き、開発時の DEBUG は application-dev.yaml に分けます。これにより、prod ではアプリのパッケージも INFO を継承します。

開発プロファイルの設定は src/main/resources/application-dev.yaml に保存し、次のように有効化して起動します。通常の INFO ログに加え、Spring の DEBUG ログが出ることを確認してください。

./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

PowerShell では .\mvnw.cmd spring-boot:run '-Dspring-boot.run.profiles=dev' を使います。

ログファイルのローテーション

ファイルサイズによるローテーション設定:

application.yaml
logging:
  logback:
    rollingpolicy:
      max-file-size: 10MB
      max-history: 30

標準の Logback 設定は日付とサイズの両方でローテーションします。 保存先や appender の構成を独自に変える場合に logback-spring.xml を使います。 Spring Boot のログ設定 を参照してください。

実践的なロギングパターン

例外ログ

例外をログに残す際のポイントです。

例外ログの良い例
// 良い例: 例外情報を詳細に残す
try {
    processOrder(orderId);
} catch (RuntimeException e) {
    log.error("注文処理に失敗しました。orderId={}", orderId, e);
    throw e;
}

このコードはメソッド内の抜粋です。例外を再送出し、呼び出し元へ失敗を伝えます。 トランザクション付き Service で捕捉して成功を返すと、ロールバックされない場合があります。 例外処理・エラー応答入門 の Advice でまとめて記録する場合、Service では同じ例外を重複して記録しません。

注意点:

  • スタックトレースを必ず含める(e を渡す)
  • 例外メッセージだけでなく、関連するパラメータもログに含める
  • e.printStackTrace() は避ける(標準エラー出力へ直接書き込み、ログ設定や文脈情報が反映されない)

パフォーマンスログ

処理時間を計測してログに残すパターンです。経過時間には System.nanoTime() の差を使い、TimeUnit.NANOSECONDS.toMillis(...) でミリ秒へ変換します。ログイベントの日時は Logback に任せます。以下の抜粋を使う場合は java.util.concurrent.TimeUnit を import してください。

パフォーマンスログ
long start = System.nanoTime();
try {
    // 処理
    result = heavyOperation();
} finally {
    long duration = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - start);
    log.info("処理完了: operation={}, duration={}ms", operationName, duration);
}

注意点:

パフォーマンスログの目的は「遅い処理を素早く見つける」ことです。ここを忘れると、ログがただのノイズになります。

  • 通常の詳細情報は DEBUG、運用で確認したい遅い処理は INFO とする。レベルは出力環境だけでなく、情報の重要度と用途から決める
  • 閾値を超えた処理は WARN にするなど、業務上の基準を設ける。例えば 100ms を閾値とし、監視の判断にも使う

つまり、DEBUG(全件)→ INFO(遅いもの)→ WARN(特に遅いもの) と段階を絞ることで、ログの量を抑えながら問題を見つけやすくするのがポイントです。

監査ログ

誰が何をしたかを記録するパターンです。セキュリティ要件やコンプライアンス要件で必要になります。

監査ログ
log.info("監査: user={}, action={}, target={}, result={}", userId, "DELETE", targetId, "SUCCESS");

注意点:

  • 監査ログは通常のログと分離して保存する
  • 改ざん防止のため、追記専用ファイルや署名を検討する
  • 個人情報を含めない

ログの肥大化対策

  • ローテーション設定: ファイルサイズ・日次でローテーション
  • レベル調整: 本番では INFO 以上に設定
  • 不要なログの削減: デバッグ用ログを本番で出力しない
  • サンプリング: 大量ログの場合は間引いて出力

MDC(Mapped Diagnostic Context)

MDC(Mapped Diagnostic Context)とは

MDC は、スレッドごとにキー・バリュー形式のコンテキスト情報を保持する SLF4J の機能です。 Logback の出力パターンに %X{キー名} を指定すると、リクエスト ID やユーザー ID をログに含められます。

MDC の使用例
import org.slf4j.MDC;

// リクエスト開始時に設定
MDC.put("requestId", requestId);
MDC.put("userId", userId);

// 出力パターンで指定したキーの値がログに含まれる
log.info("処理を開始");

// リクエスト終了時にクリア
MDC.remove("requestId");
MDC.remove("userId");

なぜ MDC が必要か

リクエスト ID をログメッセージの引数として渡す方法では、処理が深くなるほど、複数のメソッドで同じ値を受け渡すことになります。

フィルターで MDC に値を設定すると、値を削除するまで、同じスレッドで出力されるログがその値を参照できます。 同じ出力パターンを使うログでは、各メソッドで MDC を意識せずに同じリクエスト ID を記録できます。

  • コードの簡潔さ: 各メソッドに requestId を渡す必要がなくなる
  • 漏れの防止: 設定を忘れてログにコンテキストが欠落する事故を防げる
  • 一貫性: 例外やサードパーティのライブラリが出力するログにも自動で含まれる
  • スレッドごとの管理: 別スレッドには自動伝播しないため、非同期処理では受け渡しと後片付けが必要

これにより、ログの「相関」の利点(requestId で一連の処理を追跡)を、コードを汚さずに実現できます。

MDC のパターン設定

logback-spring.xml のパターンに MDC キーを組み込むと、すべてのログに自動で含まれます。

次の <pattern> は、既存の encoder に組み込む断片です。ハンズオンで作成した logback-spring.xml では、<property name="CONSOLE_LOG_PATTERN" value="..."/> の value 内の出力パターンに組み込みます。MDC キー名は、ハンズオンのフィルターが設定する traceId と user に合わせてください。

logback-spring.xml
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{traceId}] [%X{user}] %-5level %logger{36} - %msg%n</pattern>

フィルターでの MDC 利用

抜粋: RequestIdFilter.java(import・クラス周辺を省略)
// フィルターでリクエスト ID を MDC に設定
@Component
public class RequestIdFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        String requestId = UUID.randomUUID().toString();
        MDC.put("requestId", requestId);
        try {
            chain.doFilter(request, response);
        } finally {
            MDC.remove("requestId");
        }
    }
}

この抜粋はキー名が requestId の独立した例です。ハンズオンの AccessLogFilter に組み込む場合は、キー名を traceId と user に合わせてください。

構造化ロギング

「触って学ぶ」の方では、ログを JSON 形式で出力する方法は扱いませんでしたが、実務では構造化ロギングを扱う事も多いため紹介します。 ここでは構造化ロギングの概要と、Logback での JSON 出力方法を紹介します。

構造化ロギングとは

ログを JSON などの機械可読形式で出力する手法です。CloudWatch Logs、Datadog、Splunk などのログ収集基盤での検索・分析が容易になります。

JSON ログの例:

JSON ログの例
{
  "timestamp": "2025-01-15T10:30:00.123+09:00",
  "level": "INFO",
  "logger": "com.example.OrderService",
  "message": "注文処理を開始",
  "requestId": "abc-123",
  "userId": "user-456",
  "duration": 123
}

なぜ構造化ロギングが必要か

従来のテキスト形式のログは、人間が読むには優れていますが、機械による検索や集計には向きません。例えば「特定のユーザーの全操作」を追う場合、テキストログでは文字列を解析する必要があります。 フォーマットの揺れや改行の混入は、検索・集計を壊す原因になります。

構造化ロギングでは、各項目がキー・バリューで分離されているため、以下のようなことが容易になります。

  • 検索: userId = "user-456" のような条件で正確に絞り込める
  • 集計・分析: duration の平均・最大値をクエリで計算できる
  • 相関: requestId をキーに、複数サービスにまたがる一連の処理を追跡できる
  • 項目の明確化: 各値を名前付きで扱える。ただし、名前や型を変えるときは検索・集計への影響も確認する

特にマイクロサービスやサーバーレス構成では、ログを横断して追跡する機会が増えるため、機械可読な形式がほぼ必須になります。

Spring Boot の設定で JSON を出力する(発展)

Spring Boot 4.0 系では構造化ログの設定を利用できます。 logback-spring.xml がまだ有効なら、src/main/resources 内のファイル名を logback-spring.xml.disabled に変更します。 独自 XML のテキスト用アペンダーが残ったままでは、以下の設定が反映されません。

application.yaml に追加
logging:
  structured:
    format:
      console: logstash

アプリを停止し、./mvnw clean spring-boot:run で起動し直します。clean で target/classes に残った古い XML を取り除きます。 /getUsers にアクセスし、アクセスログが 1 行の JSON になり、MDC の traceId が含まれることを確認します。 上の JSON は項目の説明例で、実際の項目名は選択した形式に従います。 業務の数値を集計する場合は、メッセージに埋め込むだけでなく名前付きの項目として出力してください。 Spring Boot の構造化ログ に設定の詳細があります。

用語集

用語説明
ログアプリケーションの動作中に発生するイベントや状態変化を記録したもの
ログレベルログの重要度を表す指標。TRACE / DEBUG / INFO / WARN / ERROR。OFF は出力停止の設定値
フィルタリング設定したログレベル以上のログだけを出力する仕組み
SLF4JJava のロギングファサード。実装ライブラリをプラグ可能にする API
LogbackSLF4J の標準実装。Spring Boot のデフォルトロギングライブラリ
Log4j2Apache が開発するロギングライブラリ。非同期ロギングに強みがある
アペンダーログの出力先(コンソール、ファイル、DB、メールなど)を定義するコンポーネント
エンコーダーログメッセージを出力形式(テキスト、JSON など)に変換するコンポーネント
ローテーションログファイルが肥大化しないよう、サイズや日次でファイルを分割・入れ替える仕組み
構造化ロギングログを JSON などの機械可読形式で出力する手法。ログ収集基盤での検索・分析が容易になる
MDC(Mapped Diagnostic Context)スレッドごとにキー・バリュー形式のコンテキスト情報を保持する SLF4J の機能。リクエスト ID やユーザー ID をログに自動的に含められる
トレースリクエストの流れを追跡する仕組み。ログ(点)と対になる「線」の概念
ファサード複数の実装を共通 API で扱うための窓口。SLF4J はロギング実装のファサード
プレースホルダSLF4J の {} 記法。文字列連結を避け、出力時の文字列組み立てを効率化する
監査ログ誰がいつ何をしたかを記録するログ。セキュリティ・コンプライアンス要件で必要
パフォーマンスログ処理時間やリソース使用量を計測して記録するログ
スタックトレース例外発生時の呼び出し履歴。例外ログに含めることで原因特定が容易になる
プロファイルSpring Boot の環境設定(dev / prod など)。環境ごとにログレベルを切り替えられる

参考資料