Appender¶
Appenderは、以下の役割を担います。
- ログの出力先の決定
Appenderは設定ファイルに <appender> で設定します。im_logger.xml に記載する場合は以下のとおりです。
1 2 3 4 5 6 7 8 9 10 11 <?xml version="1.0" encoding="UTF-8"?> <configuration> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <outputPatternAsHeader>true</outputPatternAsHeader> <pattern>[%level] %logger{10} - %msg%n</pattern> </encoder> </appender> </configuration>この例では、識別子 STDOUT に対して「ConsoleAppender」を割り当てています。<appender> で指定可能な属性設定は以下の通りです。
属性 必須設定 説明 name ○ このAppenderに対しての識別子を指定します。「Logger」ではここで指定した識別子を指定して利用するAppenderを設定します。class ○ Appenderの完全修飾クラス名を指定します。 Appenderに対しての設定は <appender> の子要素で指定します。設定可能な値(プロパティ)は、Appenderの実装により異なります。Appenderの実装クラスとその他のクラスとの関連クラスの情報は以下の通りです。以下では各種Appenderの実装を紹介します。コラム
本書に記述されていないAppenderについては「LogbackのWebサイト」を参照してください。
ConsoleAppender¶
ログをコンソールに出力するAppenderです。
プロパティ¶
プロパティ名 タイプ 必須設定 説明 filter Filter × 「Filter」を指定します。<filter> を複数記述することで複数指定可能です。encoder Encoder ○ 「Encoder」を指定します。target String × 出力先を指定します。指定可能な出力先は以下の通りです。
- System.out : 標準出力
- System.err : 標準エラー
immediateFlush boolean × バッファリングしている内容を即時書き込むかを指定します。未指定の場合は、true を設定したものとして扱われます。2019 Spring(Violette) 以前のバージョンでは、immediateFlush タグを appender タグの下から encoder タグの下へ移動させてください。詳細は FAQ を確認ください。
FileAppender¶
ログをファイルに出力するためのAppenderです。
コラム
ログのローテートを行う場合は「RollingFileAppender」を利用してください。
プロパティ¶
プロパティ名 タイプ 必須設定 説明 filter Filter × 「Filter」を指定します。<filter> を複数記述することで複数指定可能です。append boolean × ログ出力開始時に既にファイルが存在した場合に追記を行うかを指定します。true を指定した場合は、存在するファイルの末尾からログを追記します。false を指定した場合は、ファイルを削除し、新規ファイルにログを出力します。未指定の場合は、true を設定したものとして扱われます。encoder Encoder ○ 「Encoder」を指定します。file String ○ ファイルの出力先を指定します。指定したディレクトリ/ファイルが存在しない場合は、自動的に生成されます。Windows環境で \ を利用してファイルパスを指定する場合は、エスケープを行ってください。例)C:\var\log\system.log にファイルを出力する場合は、 C:\\var\\log\\system.log と指定します。prudent boolean × prudent モードでログ出力を行うかを指定します。prudent モードを利用した場合、排他ロックを行いながらログの出力を行うため、異なるJVMからの同一ファイルへ安全に書き込むことが可能です。ただし、排他ロックを行うため、パフォーマンスの低下につながることに注意してください。未指定の場合は、false を設定したものとして扱われます。immediateFlush boolean × バッファリングしている内容を即時書き込むかを指定します。未指定の場合は、true を設定したものとして扱われます。2019 Spring(Violette) 以前のバージョンでは、immediateFlush タグを appender タグの下から encoder タグの下へ移動させてください。詳細は FAQ を確認ください。注意
パラメータ prudent に true を指定した場合は パラメータ append は強制的に true を設定したものとして扱われます。
RollingFileAppender¶
ログファイルのローテートを行うAppenderです。
プロパティ¶
プロパティ名 タイプ 必須設定 説明 filter Filter × 「Filter」を指定します。<filter> を複数記述することで複数指定可能です。append boolean × ログ出力開始時に既にファイルが存在した場合に追記を行うかを指定します。true を指定した場合は、存在するファイルの末尾からログを追記します。false を指定した場合は、ファイルを削除し、新規ファイルにログを出力します。未指定の場合は、true を設定したものとして扱われます。encoder Encoder ○ 「Encoder」を指定します。file String ○ ファイルの出力先を指定します。指定したディレクトリ/ファイルが存在しない場合は、自動的に生成されます。Windows環境で \ を利用してファイルパスを指定する場合は、エスケープを行ってください。例)C:\var\log\system.log にファイルを出力する場合は、 C:\\var\\log\\system.log と指定します。rollingPolicy RollingPolicy ○ 「RollingPolicy」を指定します。必須の設定ですが、triggeringPolicy に指定する値によっては指定すべきでは無い場合があります。triggeringPolicy TriggeringPolicy ○ 「TriggeringPolicy」を指定します。必須の設定ですが、rollingPolicy に指定する値によっては指定すべきでは無い場合があります。prudent boolean × prudent モードでログ出力を行うかを指定します。prudent モードを利用した場合、排他ロックを行いながらログの出力を行うため、異なるJVMからの同一ファイルへ安全に書き込むことが可能です。ただし、排他ロックを行うため、パフォーマンスの低下につながることに注意してください。未指定の場合は、false を設定したものとして扱われます。immediateFlush boolean × バッファリングしている内容を即時書き込むかを指定します。未指定の場合は、true を設定したものとして扱われます。2019 Spring(Violette) 以前のバージョンでは、immediateFlush タグを appender タグの下から encoder タグの下へ移動させてください。詳細は FAQ を確認ください。注意
パラメータ prudent に true を指定した場合は パラメータ append は強制的に true を設定したものとして扱われます。
SMTPAppender¶
ログをメールで送信するAppenderです。詳細はLogbackのWebサイト「SMTPAppender」を参照してください。
プロパティ¶
プロパティ名 タイプ 必須設定 説明 filter Filter × 「Filter」を指定します。<filter> を複数記述することで複数指定可能です。layout Layout ○ 「Layout」を指定します。smtpHost String × SMTPサーバのホスト名を指定します。<sessionViaJNDI> が false (未指定も含む)である場合、必ず指定してください。smtpPort int × SMTPサーバのポート番号を指定します。未指定の場合は、25 を設定したものとして扱われます。to String × メールの送信先のアドレスを指定します。この設定は <to> を複数記述することで複数指定可能です。<sessionViaJNDI> が false (未指定も含む)である場合、必ず指定してください。from String × メールの送信元のアドレスを指定します。未指定の場合は、javax.mail.internet.InternetAddress#getLocalAddress(Session) で取得した値が指定されます。subject String × discriminator Discriminator × 「Discriminator」を指定します。evaluator EventEvaluator × 「EventEvaluator」を指定します。EventEvaluatorを指定することで、メールを送信するタイミングを変更することが可能です。未指定の場合は、ログレベルが ERROR の時のみメールを送信する「OnErrorEvaluator」を設定したものとして扱われます。cyclicBufferTracker CyclicBufferTracker × CyclicBufferTrackerを指定します。CyclicBufferTrackerから作成したCyclicBufferにより、循環バッファの動作が決定します。「Discriminator」により分別が行われている場合、CyclicBufferは分別された値ごとに作成されます。詳細はLogbackのWebサイト「SMTPAppender」を参照してください。未指定の場合は、循環バッファ数は 256 が指定されます。username String × 平文でのSMTP認証を行う場合に、ユーザ名を指定します。 password String × 平文でのSMTP認証を行う場合に、パスワードを指定します。 STARTTLS boolean × STARTLS を利用してSMTPサーバに接続を行うかを指定します。true の場合、STARTLS を利用します。false の場合、STARTLS を利用しません。SSLとは異なり、初回の接続は暗号化されません。未指定の場合は、false が指定されます。SSL boolean × SSL を利用してSMTPサーバに接続を行うかを指定します。true の場合、SSLを利用します。false の場合、SSLを利用しません。未指定の場合は、false が指定されます。charsetEncoding String × メールのメッセージのエンコーディングを指定します。未指定の場合は、UTF-8 が指定されます。localhost String × SMTPの HELO コマンドまたは EHLO コマンドで使用するローカルホストのドメイン名を指定します。未指定の場合は、java.net.InetAddress#getLocalhost().getHostName() で取得した値が指定されます。asynchronousSending boolean × メールを非同期で送信するかどうかを指定します。true の場合、メールを非同期で送信します。false の場合、メールを非同期で送信しません。非同期で送信する場合、アプリケーションの終了直前に出力されたログが送信されない場合があるので注意してください。未指定の場合は、true が指定されます。includeCallerData boolean × 呼び出し元の情報を含めるかどうかを指定します。true の場合、呼び出し元の情報を含めます。false の場合、呼び出し元の情報を含めません。未指定の場合は、true が指定されます。sessionViaJNDI boolean × JNDIを利用したメール送信を行うかどうかを指定します。true を指定した場合、ネーミング・サービスに紐づいたメール設定で送信を行います。false を指定した場合、SMTPAppenderへの設定情報を元にメール送信を行います。未指定の場合は、false が指定されます。jndiLocation String × JNDIのロケーションを指定します。JNDIを利用してメール送信を行う場合は、<sessionViaJNDI> に true を指定する必要があります。JNDIを利用したメール送信を行わない場合は、指定する必要がありません。
SiftingAppender¶
出力イベント(内容)により出力先を「ふるい」にかけ、分別を行うAppenderです。「ふるい」により、分別された値ごとにAppenderを作成し内包します。内包するAppenderは <timeout> で指定した時間の間利用されない場合、次に自身のAppender(SiftingAppender)により書き込みを行った際に削除されます。<sift> 内のAppenderでは <discriminator> で「ふるい」にかけられた値はプロパティとして利用可能です。
例)「MDCBasedDiscriminator」を利用し、<key>application.key</key> と指定した場合、${application.key} と記述することで MDC.get("application.key") で取得された値が利用できます。プロパティの利用方法、詳細については「プロパティ」を参照してください。コラム
同名のプロパティが既に存在している(ログ設定ファイルなどで同名のプロパティを定義している)場合でも、ここで利用可能になるプロパティが優先されます。
プロパティ¶
プロパティ名 タイプ 必須設定 説明 filter Filter × 「Filter」を指定します。<filter> を複数記述することで複数指定可能です。timeout Duration × 内包するAppenderのタイムアウト時間を設定します。指定は数値 + 単位で行います。数値は、小数を利用した指定が可能です。単位は、ミリ秒(millisecond/milliseconds)、秒(second/seconds)、分(minute/minutes)、時(hour/hours)、と、日(day/days)で指定可能です。例)30 minutes : 30分1 hour : 1時間0.5 day : 12時間未指定の場合は、タイムアウト時間は 30分 が設定されます。maxAppenderCount int × SiftingAppenderが内包可能なAppenderの数を指定します。未指定の場合は、Javaの Integer.MAX_VALUE が指定されます。discriminator Discriminator ○ 「Discriminator」を指定します。
SystemStorageAppender¶
ログをシステムストレージに出力するためのAppenderです。
プロパティ¶
プロパティ名 タイプ 必須設定 説明 filter Filter × 「Filter」を指定します。<filter> を複数記述することで複数指定可能です。append boolean × ログ出力開始時に既にファイルが存在した場合に追記を行うかを指定します。true を指定した場合は、存在するファイルの末尾からログを追記します。false を指定した場合は、ファイルを削除し、新規ファイルにログを出力します。未指定の場合は、true が指定されます。encoder Encoder ○ 「Encoder」を指定します。file String ○ ファイルの出力先を指定します。指定したディレクトリ/ファイルが存在しない場合は、自動的に生成されます。システムストレージのルートからの相対パスで指定します。prudent boolean × prudent モードでログ出力を行うかを指定します。prudent モードを利用した場合、排他ロックを行いながらログの出力を行うため、異なるJVMからの同一ファイルへ安全に書き込むことが可能です。ただし、排他ロックを行うため、パフォーマンスの低下につながることに注意してください。未指定の場合は、false を設定したものとして扱われます。immediateFlush boolean × バッファリングしている内容を即時書き込むかを指定します。未指定の場合は、true を設定したものとして扱われます。2019 Spring(Violette) 以前のバージョンでは、immediateFlush タグを appender タグの下から encoder タグの下へ移動させてください。詳細は FAQ を確認ください。注意
パラメータ prudent に true を指定した場合は パラメータ append は強制的に true を設定したものとして扱われます。
RollingPolicy¶
この設定は「RollingFileAppender」などの一部のAppenderで利用可能です。<rollingPolicy> で設定します。RollingPolicyは以下の役割を担います。
- ログのローテート時における、ファイルのローテート方法の決定
<rollingPolicy> で指定可能な属性設定は以下の通りです。
属性 必須設定 説明 class ○ RollingPolicyの実装クラスの完全修飾クラス名を指定します。 RollingPolicyの実装クラスとその他のクラスとの関連クラスの情報は以下の通りです。
TimeBasedRollingPolicy¶
日時毎でのログファイルを出力します。注意
TimeBasedRollingPolicyは「TriggeringPolicy」の機能も兼ね備えています。TimeBasedRollingPolicyをRollingPolicyとして指定する場合は、TriggerPolicyは指定しないでください。
プロパティ¶
プロパティ名 タイプ 必須設定 説明 fileNamePattern String ○ バックアップファイルのパターンを指定します。値に %d を指定することで日時を含むパターンを指定することが可能です。また、%d{ と } の間に日時書式形式を指定することが可能です。指定可能な形式は java.text.SimpleDateFormat と同様です。%d の後ろに {} を指定しなかった場合、yyyy-MM-dd 形式として扱われます。fileNamePattern の接尾辞が .zip、または、.gz の場合、バックアップファイルがそれぞれの形式に圧縮されます。maxHistory int × バックアップファイルとして残す期間を指定します。ログ出力時に、指定した期間を超えたログ履歴ファイルは削除されます。指定する期間の単位は、 fileNamePattern の指定に依存します。例えば、以下の設定がされていた場合、fileNamePattern の最小単位が「日」となるため、「10日」が経過したバックアップファイルは削除されます。
- fileNamePattern : %d{yyyy-MM-dd}.log
- maxHistory : 10
0 が指定された場合、無制限にバックアップファイルを残します。未指定の場合は、0 を設定したものとして扱われます。timeBasedFileNamingAndTriggeringPolicy TimeBasedFileNamingAndTriggeringPolicy × 未指定の場合は、「DefaultTimeBasedFileNamingAndTriggeringPolicy」が利用されます。cleanHistoryOnStart boolean × Appender起動時にバックアップファイルを削除するかどうかを指定します。true を指定した場合は、存在するバックアップファイルの削除を行います。false を指定した場合は、バックアップファイルの削除を行いません。maxHistory の値が 0 の場合は、バックアップファイルの削除を行いません。未指定の場合は、false を設定したものとして扱われます。
ログの出力例¶
im_logger.xml に以下のような設定が行われていたとします。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 <?xml version="1.0" encoding="UTF-8"?> <configuration> <!-- 省略 --> <appender name="SAMPLE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>${im.log}/platform/sample.log</file> <append>true</append> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <fileNamePattern>${im.log}/platform/sample-%d{yyyy-MM-dd-HH-mm}.log</fileNamePattern> <maxHistory>2</maxHistory> </rollingPolicy> <encoder> <pattern>%logger{10} - %msg</pattern> </encoder> </appender> </configuration>最新のログは、%CONTEXT_PATH%/WEB-INF/log/platform/sample.log に出力され、古いログは sample.log が生成されるタイミング(このサンプルの場合、日時形式に指定されているの最小の時間単位は mm であるため毎分)で sample-yyyy-MM-dd-HH-mm.log というファイル名のバックアップファイルに移されます。また、maxHistory が 2 であるため、「2分」が経過したログファイルは削除されます。以下は、実行時間ごとのログファイルとその推移です。(毎分ログ出力が行われている前提とします。)
日時 ログファイル 説明 2013-10-01 00:00 sample.log sample.log が生成されます。 2013-10-01 00:01 sample.logsample-2013-10-01-00-00.log sample.log が sample-2013-10-01-00-00.log にリネームされます。新たに sample.log が生成されます。2013-10-01 00:02 sample.logsample-2013-10-01-00-00.logsample-2013-10-01-00-01.log sample.log が sample-2013-10-01-00-01.log にリネームされます。新たに sample.log が生成されます。2013-10-01 00:03 sample.logsample-2013-10-01-00-00.logsample-2013-10-01-00-01.logsample-2013-10-01-00-02.log sample.log が sample-2013-10-01-00-02.log にリネームされます。新たに sample.log が生成されます。maxHistory で指定したファイル数を超えるため、sample-2013-10-01-00-00.log が削除されます。また、ログ出力が実行されない場合は、指定された時間が経過してもログファイルのローテート処理は行われません。以下では、ログが 00:03 ~ 00:10 の間は出力されず、00:10 以降に出力された場合の推移です。
日時 ログファイル 説明 2013-10-01 00:09 sample.logsample-2013-10-01-00-01.logsample-2013-10-01-00-02.log ログの出力が行われていないため、ログファイルの状態は変更されません。2013-10-01 00:10 sample.logsample-2013-10-01-00-01.logsample-2013-10-01-00-02.logsample-2013-10-01-00-09.log 00:10 過ぎにログ出力が実行されたため、 sample.log が sample-2013-10-01-00-09.log にリネームされます。新たに sample.log が生成されます。maxHistory で指定したファイル数を超えるため、sample-2013-10-01-00-01.log、および、sample-2013-10-01-00-02.log が削除されます。
FixedWindowRollingPolicy¶
ローテート時に固定的な数値が付与されたファイル名のバックアップファイル生成します。
プロパティ¶
プロパティ名 タイプ 必須設定 説明 fileNamePattern String ○ バックアップファイルのパターンを指定します。値に %i を指定することでローテートにより生成された数値を含むパターンを指定することが可能です。fileNamePattern の接尾辞が .zip、または、.gz の場合、バックアップファイルがそれぞれの形式に圧縮されます。minIndex int × ローテート時に付与される数値の開始番号を指定します。未指定の場合は、1 が指定されます。maxIndex int × ローテート時に付与される数値の終了番号を指定します。未指定の場合は、7 が指定されます。注意
生成可能なバックアップファイルの最大数は以下の通りです。minIndex プロパティと maxIndex プロパティには、最大ファイル数以内となる値を設定してください。
iAP の バージョン 最大ファイル数 2013 Summer(Damask) 以前 13 2013 Autumn(Eden) 以降 21
ログの出力例¶
triggeringPolicy プロパティには「SizeBasedTriggeringPolicy」を利用します。im_logger.xml に以下のような設定が行われていたとします。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 <?xml version="1.0" encoding="UTF-8"?> <configuration> <!-- 省略 --> <appender name="SAMPLE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>${im.log}/platform/sample.log</file> <append>true</append> <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> <fileNamePattern>${im.log}/platform/sample%i.log</fileNamePattern> <minIndex>1</minIndex> <maxIndex>2</maxIndex> </rollingPolicy> <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> <maxFileSize>10KB</maxFileSize> </triggeringPolicy> <encoder> <pattern>%logger{10} - %msg</pattern> </encoder> </appender> </configuration>最新のログは、%CONTEXT_PATH%/WEB-INF/log/platform/sample.log に出力され、古いログは sample.log が生成されるタイミング(このサンプルの場合、「SizeBasedTriggeringPolicy」を利用しているため、sample.log のファイルサイズが10KByteを超える)で sample1.log というファイル名のバックアップファイルに移されます。以下は、ログファイルとその推移です。
trigger ログファイル 説明 - sample.log sample.log が生成されます。 sample.logローテート時 sample.logsample1.log sample.log が sample1.log にリネームされます。新たに sample.log が生成されます。sample.logローテート時 sample.logsample1.logsample2.log sample1.log が sample2.log にリネームされます。sample.log が sample1.log にリネームされます。新たに sample.log が生成されます。sample.logローテート時 sample.logsample1.logsample2.log maxHistory で指定したファイル数を超えるため、sample2.log が削除されます。sample1.log が sample2.log にリネームされます。sample.log が sample1.log にリネームされます。新たに sample.log が生成されます。
TriggeringPolicy¶
この設定は「RollingFileAppender」などの一部のAppenderで利用可能です。<triggeringPolicy> で設定します。TriggeringPolicyは以下の役割を担います。
- ログのローテートの発生条件の決定
<triggeringPolicy> で指定可能な属性設定は以下の通りです。
属性 必須設定 説明 class ○ TriggeringPolicyの実装クラスの完全修飾クラス名を指定します。 TriggeringPolicyの実装クラスとその他のクラスとの関連クラスの情報は以下の通りです。
SizeBasedTriggeringPolicy¶
ローテート元であるログファイルが特定のサイズ以上である場合にローテートを行います。Appenderによるログ出力時に、以下の条件に一致した場合ローテートを行います。
- ローテート元であるログファイルが特定のサイズ以上である
TimeBasedFileNamingAndTriggeringPolicy¶
この設定は「TimeBasedRollingPolicy」で利用します。<timeBasedFileNamingAndTriggeringPolicy> で設定可能です。TimeBasedFileNamingAndTriggeringPolicyは以下の役割を担います。
- TimeBasedRollingPolicy利用時のログのローテートの発生条件の決定
<timeBasedFileNamingAndTriggeringPolicy> で指定可能な属性設定は以下の通りです。
属性 必須設定 説明 class ○ TimeBasedFileNamingAndTriggeringPolicyの実装クラスの完全修飾クラス名を指定します。 TimeBasedFileNamingAndTriggeringPolicyの実装クラスとその他のクラスとの関連クラスの情報は以下の通りです。
DefaultTimeBasedFileNamingAndTriggeringPolicy¶
TimeBasedFileNamingAndTriggeringPolicyの標準の実装です。TimeBasedRollingPolicyでTimeBasedFileNamingAndTriggeringPolicyの設定を指定しなかった場合に利用されます。Appenderによるログ出力時に、以下の条件に一致した場合ローテートを行います。
- TimeBasedRollingPolicyで指定したバックアップファイルのパターン(fileNamePattern 設定)に含まれる日時形式の最小単位の時間が、以前ログを出力した時間を超えている
SizeAndTimeBasedFNATP¶
日時毎とファイルサイズ毎にローテートを行います。Appenderによるログ出力時に、以下のいずれかの条件に一致した場合ローテートを行います。
- TimeBasedRollingPolicyで指定したバックアップファイルのパターン(fileNamePattern 設定)に含まれる日時形式の最小単位の時間が、以前ログを出力した時間を超えている
- ローテート元であるログファイルが特定のサイズ以上である
このTimeBasedFileNamingAndTriggeringPolicyを利用する場合は、TimeBasedRollingPolicyの fileNamePattern 設定値 に %i を指定することでローテートにより生成された数値を含むパターンを指定します。%i の要素数は 0 から始まります。
Discriminator¶
Discriminatorは、以下の役割を担います。
- ログ出力の分別を行う単位の決定
分別された情報の扱い方は、利用するAppenderごとに異なります。<discriminator> で指定可能な属性設定は以下の通りです。
属性 必須設定 説明 class × Discriminatorの実装クラスの完全修飾クラス名を指定します。 コラム
class 属性省略時に利用されるDiscriminatorの実装クラスについては、各Appenderの設定を参照してください。
Discriminatorの実装クラスとその他のクラスとの関連クラスの情報は以下の通りです。
DefaultDiscriminator¶
分別を行わないDiscriminatorの実装です。