Analytics > Log & Crash Search > Logback SDK使用ガイド

Log & Crash Logback SDKは、Log & Crash Search収集サーバーにログを転送する機能を提供します。Log & Crash Searchで、転送されたログの照会および検索が可能で、マルチスレッド環境で動作します。

1. Log & Crash Logback SDK追加

logncrash-java-sdk3-3.0.4.jarを依存性に追加します。 NHN Cloud DocumentでLog & Crash Logback SDKをダウンロードできます。

[DOCUMENTS] > [Download] > [Analytics > Log & Crash Search] > [Logback SDK]クリック
  • Log & Crash Logback SDKは、logback-classic 1.2.3+, apache httpclient 4.5+, json 20171018+のライブラリに依存性を持っています。
  • 参照するlibraryが重複する場合、問題が発生することがあるため、上位バージョンの使用を推奨します。

2. Log & Crash Logback SDKに必要な依存性を追加

2.1 Mavenインストール

pom.xmlにdependencyを追加します。

<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20171018</version>
</dependency>
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5</version>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.2.3</version>
</dependency>

2.2 Gradleインストール

dependencies {
    compile 'org.json:json:20171018'
    compile 'org.apache.httpcomponents:httpclient:4.5'
    compile 'ch.qos.logback:logback-classic:1.2.3'
}

3. Logger設定およびオプション

logback.xmlを基準に説明します。

  • LogbackのAsyncAppenderをデフォルトで使用し、ログを非同期で収集してログ収集サーバーに転送します。
  • Log & Crash Logback SDKのLogNCrashHttpAppenderで、転送ログの詳細項目を設定できます。
<appender name="user-logger" class="ch.qos.logback.classic.AsyncAppender">
    <!-- LogbackのAsyncAppenderオプション -->
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
        <level>INFO</level>
    </filter>
    <param name="includeCallerData" value="false"/>
    <param name="queueSize" value="2048"/>
    <param name="neverBlock" value="true"/>
    <param name="maxFlushTime" value="60000"/>

    <!-- Log & Crash Logback SDKのLogNCrashHttpAppenderオプション -->
    <appender name="logNCrashHttp" class="com.toast.java.logncrash.logback.LogNCrashHttpAppender">
        <param name="appKey" value="アプリケーションキー"/>
        <param name="logSource" value="運営"/>
        <param name="version" value="1.0.0"/>
        <param name="logType" value="監査ログ"/>
        <param name="debug" value="true"/>
        <param name="category" value="ログサービス"/>
        <param name="errorCodeType" value="action"/>
    </appender>
</appender>

<logger name="user-logger" additivity="false">
    <appender-ref ref="user-logger"/>
</logger>

3.1 LogbackのAsyncAppenderオプション

  • 設定値の詳細な情報は、公式文書を参照してください。
キー 説明
includeCallerData 送信者の情報(class名、行番号など)が追加され、収集サーバーに転送するかどうかを決定します。
trueに設定すると、性能が低下することがあります。
queueSize blocking queueの最大収容個数で、デフォルト値は256です。
neverBlock falseに設定した場合、キューがいっぱいの状況でappenderはメッセージの消失を防ぐためにapplicationをblockします。
trueに設定した場合、applicationを止めないようにメッセージを捨てます。
maxFlushTime LoggerContextが停止すると、AsyncAppenderのstopメソッドは作業スレッドがtimeoutするまで待機します。
maxFlushTimeを使用すると、timeout時間をミリ秒で設定できます。
該当時間内に処理できなかったイベントは削除されます。

3.2 Log & Crash Logback SDKのLogNCrashHttpAppenderオプション

appKeyを除いた残りの値は、任意項目です。paramを記入しない場合、デフォルト値が入力されます。

キー 説明 デフォルト値
appKey logncrahコンソールで有効にしたprojectKeyです。 必須値
logSource alpha、beta、realなど、実行される環境設定情報です。
Spring Profileを使用する場合、 ${spring.profiles.active}を使用します。
http-logback
version 送信者のプロジェクトバージョンを明示します。 1.0.0
logType 収集するlogのtypeを明示します。 log
debug boolean値。consoleにsdkログ情報の出力が必要かどうかを決定します。 true
category 収集するlogのcategoryを明示します。
errorCodeType エラー発生時に収集されるエラー情報のタイプを設定します。default、action、message、mdcタイプが存在します。
- default: Throwable情報を使用します。
- action: URL pathの情報も含めてエラーを返します。
- message: loggerに設定したメッセージのみ返します。
- mdc: MDCのerrorCode項目値を設定して使用します。
default

3.3ユーザー定義オプション

slf4jのMDCを使用して、Log & CrashのLogNCrashHttpAppenderで定義されていない項目を追加できます。 (ただしcategoryは変更できます。)

MDC.put("userid", "nhnent-userId");
MDC.put("userIp", "127.0.0.1");
...
MDC.clear();

MDCで変更できない予約語(大文字/小文字を区別しません。)

projectName clientIp projectVersion url logSource headers
form logType cookie body agent logLevel
host referer sendTime dmpData dmpFormat

4. LogNCrash SDK使用例

Javaで次のように使用します。

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

public class LogNCrash {
    private static final Logger USER_LOG = LoggerFactory.getLogger("user-logger");

    public void logging() {
        logger.debug("LogNCrash Debug.") ;

        // Log & Crashで予約された項目以外のユーザー定義項目を使用する時にMDCを活用
        MDC.put("userid", "nhnent-userId");
        logger.warn("Customize items...") ;
        MDC.clear();

        try {
            String logncrash = null;
            if(true) {
                System.out.print(logncrash.toString());
            }    
        } catch(Exception e) {
            logger.error("LogNCrash Exception.", e)
        }   
    }
}

5. FAQ

Q. Log & Crash Logback SDKのLogNCrashHttpAppenderだけでログを転送することはできませんか?

Log & Crash Logback SDKのLogNCrashHttpAppenderは、sync方式で収集サーバーにログを転送するので、可能です。 ログの消失が最小化されますが、Log & Crash Logbackシステム障害の時は、Applicationの性能低下が発生することがあるため、Async Appenderの使用を推奨します。

Q. batch program(project)でlogncrash clientを使用するには?

batchプログラムの最後に数秒間、待機するコードを追加します。

try {
    Thread.sleep(3000L);
} catch (InterruptedException ignore){}

Java batch programでは、main threadがすぐに終了するため、LogbackのAsyncAppenderのデーモンスレッドが作成され、ログを転送する前にbatchアプリケーションが終了します。 デーモンスレッドに関係なく、生きている一般スレッドがない場合、JVMはすぐに終了します。したがって、上記のようにプログラムの最後に待機するコードを追加し、すべてのログを転送してから終了するようにします。

logback利用してstack traceを出力するには、log.error(e.getMessage(), e);形式を使用します。SLF4J Loggerはメソッドの引数にThrowableのみ受け取るロギングメソッドはサポートしません。

try {
    ...
} catch (Exception e){
    logger.error(e.getMessage(), e);
}

Q. WASで使用する時に安定的に終了するには?

エラーログを転送中の状況でWAS(Tomcatなど)が終了する場合は、次のようなExceptionが発生し、WASが正常に終了しないことがあります。

このような現象を防ぐためには、WAS終了時にLoggerContextインスタンスに対してstop()メソッドを呼び出し、LogNCrashHttpAppendetをcloseすると安定的に終了できます。

Springでは、Log4Jに対してはorg.springframework.web.util.Log4jConfigListenerを提供しますが、Logbackに対しては安定的な終了をサポートするListenerを提供していません。

Log & Crash Logback SDKでは、独自にLogbackShutdownListenerを提供します。web.xmlに次のような設定を追加すると、WAS終了時にエラーログの転送が発生しても安定的に終了できます。

<listener>
    <listener-class>
        com.toast.java.logncrash.logback.LogbackShutdownListener
    </listener-class>
</listener>
TOP