高度な設定

このページでは、高度な機能と設定について説明します。

TeeFilter

TeeFilterはロギング用にリクエストとレスポンスのボディ内容をキャプチャします。

Tomcat Servletアプリケーション限定

TeeFilterはTomcatベースのServlet Webアプリケーション（Spring MVC）が必要です。Jettyやリアクティブアプリケーション（Spring WebFlux）では使用できません。

TeeFilterの有効化

yaml

logback:
  access:
    tee-filter:
      enabled: true
      include-hosts: localhost,example.com
      exclude-hosts: internal.example.com

設定オプション

プロパティ	説明	デフォルト
`enabled`	ボディキャプチャの有効/無効	`false`
`include-hosts`	含めるホストのカンマ区切りリスト	全ホスト
`exclude-hosts`	除外するホストのカンマ区切りリスト	なし
`max-payload-size`	ログ出力する最大ペイロードサイズ（バイト）	`65536`
`allowed-content-types`	ボディキャプチャを許可するContent-Typeパターン（上書きモード）	下記参照

ボディ内容へのアクセス

%requestContentと%responseContentパターンを使用:

xml

<pattern>%h "%r" %s %requestContent %responseContent</pattern>

ボディキャプチャポリシー

ボディ内容はログ出力に含める前にキャプチャポリシーで評価されます。バイナリコンテンツタイプや巨大なペイロードは自動的に抑制され、センチネル値に置換されます。

デフォルトで許可されるコンテンツタイプ:

text/*（text/plain、text/htmlなど）
application/json
application/xml
application/*+json（application/vnd.api+jsonなど）
application/*+xml（application/atom+xmlなど）
application/x-www-form-urlencoded

センチネル値:

条件	センチネル
画像コンテンツ（`image/*`）	`[IMAGE CONTENTS SUPPRESSED]`
その他のバイナリコンテンツ	`[BINARY CONTENT SUPPRESSED]`
ペイロードが`max-payload-size`を超過	`[CONTENT TOO LARGE]`

カスタムコンテンツタイプ:

yaml

logback:
  access:
    tee-filter:
      enabled: true
      max-payload-size: 131072
      allowed-content-types:
        - "text/*"
        - "application/json"
        - "application/pdf"

allowed-content-typesを指定すると、デフォルトは完全に置換されます（上書きモード）。

WARNING

max-payload-size設定はキャプチャされたコンテンツがログ出力に含まれるかどうかのみを制御します。TeeFilterはこの制限に関係なく、完全なボディをメモリにバッファリングします。本番環境ではホストフィルタリングを使用してキャプチャ範囲を制限してください。

INFO

tee-filter.enabledがfalse（デフォルト）の場合、%requestContentと%responseContentは空の出力を生成します。これにはリクエストパラメータから再構成されるフォームデータ（application/x-www-form-urlencoded）も含まれます。TeeFilterを明示的に有効化しない限り、ボディキャプチャは完全に無効化されます。

文字エンコーディング

TeeFilterでキャプチャされたボディコンテンツは、リクエストまたはレスポンスのContent-Typeヘッダーで指定された文字エンコーディングを使用してバイトからテキストに変換されます。エンコーディングが指定されていない場合や、サポートされていないエンコーディングの場合は、UTF-8がフォールバックとして使用されます。

これにより、適切なContent-Typeのcharsetがクライアントまたはサーバーで設定されている場合、Shift_JISやISO-8859-1などの非ASCIIコンテンツが正しくデコードされます。

パフォーマンスへの影響

WARNING

ボディキャプチャはメモリ使用量を増加させ、パフォーマンスに影響を与える可能性があります。ホストフィルタリングを使用して、特定の環境に限定してキャプチャしてください。

URLフィルタリング

包含パターンと除外パターンを使用して、ログに記録するURLを制御します。

除外パターン

ヘルスチェックとアクチュエーターエンドポイントを除外:

yaml

logback:
  access:
    filter:
      exclude-url-patterns:
        - /actuator/.*
        - /health
        - /ready
        - /favicon.ico

包含パターン

APIエンドポイントのみをログに記録:

yaml

logback:
  access:
    filter:
      include-url-patterns:
        - /api/.*

パターン評価順序

包含パターンが定義されている場合、URLは少なくとも1つにマッチする必要がある
除外パターンが定義されている場合、マッチするURLは除外される
両方にマッチする場合、除外が優先

パターンマッチングの動作

パターンはJava正規表現を使用し、部分一致で評価します。パターンがリクエストURIの任意の位置に見つかればマッチします。完全一致にはアンカー（^、$）を使用してください。

パターン	マッチする	マッチしない
`/api/.*`	`/api/users`, `/v2/api/data`	`/apiary`
`/health`	`/health`, `/api/health-check`	`/heal`
`^/health$`	`/health`	`/api/health`, `/health/check`
`/users/[0-9]+`	`/users/123`, `/users/456`	`/users/abc`
`.*\\.json`	`/data.json`, `/api/config.json`	`/json-data`

TIP

完全一致にはアンカー付きパターンを使用してください。例えば、^/actuator/health$は/actuator/healthのみにマッチし、/actuator/health/livenessにはマッチしません。

JSONロギング

ログ集約システム向けにアクセスログをJSON形式で出力します。

Logstash Encoderの使用

依存関係を追加:

Gradle (Kotlin)Maven

kotlin

implementation("net.logstash.logback:logstash-logback-encoder:9.0")

xml

<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>9.0</version>
</dependency>

エンコーダーを設定:

xml

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="json" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="net.logstash.logback.encoder.LogstashAccessEncoder"/>
    </appender>
    <appender-ref ref="json"/>
</configuration>

カスタムJSONフィールド

JSON出力にカスタムフィールドを追加:

xml

<encoder class="net.logstash.logback.encoder.LogstashAccessEncoder">
    <customFields>{"service":"my-app","environment":"production"}</customFields>
</encoder>

出力例

json

{
  "@timestamp": "2026-01-01T12:00:00.000+09:00",
  "@version": "1",
  "message": "GET /api/users HTTP/1.1",
  "method": "GET",
  "protocol": "HTTP/1.1",
  "status_code": 200,
  "requested_url": "GET /api/users HTTP/1.1",
  "requested_uri": "/api/users",
  "remote_host": "192.168.1.100",
  "remote_user": "-",
  "content_length": 1234,
  "elapsed_time": 45,
  "service": "my-app",
  "environment": "production"
}

Spring Security連携

Spring Securityがクラスパスにある場合、スターターは認証済みユーザー名を自動的にキャプチャします。

Servletアプリケーション限定

ユーザー名の自動キャプチャにはServletベースのWebアプリケーション（Spring MVC）が必要です。リアクティブアプリケーション（Spring WebFlux）ではアクセスロギングは動作しますが、%u変数は-を表示します。

動作の仕組み

スターターは認証済みプリンシパルのSecurityContextHolderをチェックします:

認証済みリクエスト: ユーザー名が%uでキャプチャされる
匿名リクエスト: %u変数は-を表示

匿名認証トークン（AnonymousAuthenticationTokenなど）はAuthenticationTrustResolverを使用して除外されます。アクセスログには実際に認証されたユーザーのみが記録されます。

信頼解決のカスタマイズ

スターターはデフォルトのAuthenticationTrustResolver Bean（AuthenticationTrustResolverImpl）を提供します。独自のBeanを定義することでオーバーライドできます:

java

@Bean
public AuthenticationTrustResolver authenticationTrustResolver() {
    return new MyCustomTrustResolver();
}

カスタムプリンシパル抽出

スターターはデフォルトでSecurityContextHolder.getContext().getAuthentication().getName()を使用します。

複数Appender

ログを複数の宛先に送信:

xml

<configuration>
    <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%h %l %u [%t] "%r" %s %b</pattern>
        </encoder>
    </appender>

    <appender name="file" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/access.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>logs/access.%d{yyyy-MM-dd}.log</fileNamePattern>
        </rollingPolicy>
        <encoder>
            <pattern>%h %l %u [%t] "%r" %s %b</pattern>
        </encoder>
    </appender>

    <appender name="json" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="net.logstash.logback.encoder.LogstashAccessEncoder"/>
    </appender>

    <appender-ref ref="console"/>
    <appender-ref ref="file"/>
    <appender-ref ref="json"/>
</configuration>

パフォーマンスのヒント

アクセスロギングのパフォーマンスを最適化するには:

本番環境のファイルロギングにはサイズ制限付きのRollingFileAppenderを使用
URLフィルタリングを有効にしてログ量を削減
JSONロギングには、logstash-logback-encoderが独自の非同期機能を提供
ボディキャプチャが不要な場合はTeeFilterを無効化

トラブルシューティング

ログが表示されない

logback.access.enabledがtrueであることを確認
設定ファイルが存在し、有効なXMLであることを確認
Appender名のタイプミスをチェック

ユーザー名が表示されない

Spring Securityがクラスパスにあることを確認
ユーザーが実際に認証されていることを確認
ログフォーマットに%uパターンが含まれていることを確認

パフォーマンスの問題

ファイルロギングには非同期Appenderを使用
URLフィルタリングを有効にしてログ量を削減
不要な場合はボディキャプチャ（TeeFilter）を無効化
サイズ制限付きのローリングファイルAppenderを使用

高度な設定 ​

TeeFilter ​

TeeFilterの有効化 ​

設定オプション ​

ボディ内容へのアクセス ​

ボディキャプチャポリシー ​

文字エンコーディング ​

パフォーマンスへの影響 ​

URLフィルタリング ​

除外パターン ​

包含パターン ​

パターン評価順序 ​

パターンマッチングの動作 ​

JSONロギング ​

Logstash Encoderの使用 ​

カスタムJSONフィールド ​

出力例 ​

Spring Security連携 ​

動作の仕組み ​

信頼解決のカスタマイズ ​

カスタムプリンシパル抽出 ​

複数Appender ​

パフォーマンスのヒント ​

トラブルシューティング ​

ログが表示されない ​

ユーザー名が表示されない ​

パフォーマンスの問題 ​

関連ページ ​

高度な設定

TeeFilter

TeeFilterの有効化

設定オプション

ボディ内容へのアクセス

ボディキャプチャポリシー

文字エンコーディング

パフォーマンスへの影響

URLフィルタリング

除外パターン

包含パターン

パターン評価順序

パターンマッチングの動作

JSONロギング

Logstash Encoderの使用

カスタムJSONフィールド

出力例

Spring Security連携

動作の仕組み

信頼解決のカスタマイズ

カスタムプリンシパル抽出

複数Appender

パフォーマンスのヒント

トラブルシューティング

ログが表示されない

ユーザー名が表示されない

パフォーマンスの問題

関連ページ