Logback SDK v2

Classic/VPC環境で利用できます。

logback SDK v2では、Effective Log Search & Analytics 2.0サービスで提供する logback SDK使用方法を説明します。

SDKを使用する手順は、次の通りです。

1. 事前準備
 2. Dependency追加
 3. デフォルト Appender設定
 4. AsyncAppender設定
 5. SDKを使用する

1. 事前準備

logback SDKをインストールするための事前準備事項は、次の通りです。

NAVERクラウドプラットフォームコンソールで、プロジェクトを作成します。
作成したプロジェクト詳細情報画面で txtToken値を確認します。
logback SDKをダウンロードします。

2. Dependency追加

logback SDK v2をインストールする方法は、次の通りです。

ダウンロードした SDKファイルの圧縮を解凍します。

pom.xmlファイルに以下のように dependencyを追加します。

<systemPath>に各々 coreモジュール(nelo2-java-sdk-core-1.6.6.jar)と logbackモジュール(nelo2-java-sdk-logback-1.6.6.jar)のパス追加

 <dependencies>
         <dependency>
             <groupId>nelo2-java-sdk-core</groupId>
             <artifactId>nelo2-java-sdk-core</artifactId>
             <version>1.6.6</version>
             <scope>system</scope>
             <systemPath>/nelo2-java-sdk-core-1.6.6.jar</systemPath>
         </dependency>
         <dependency>
             <groupId>nelo2-java-sdk</groupId>
             <artifactId>nelo2-java-sdk-logback</artifactId>
             <version>1.6.6</version>
             <scope>system</scope>
             <systemPath>/nelo2-java-sdk-logback-1.6.6.jar</systemPath>
         </dependency>
         <dependency>
             <groupId>ch.qos.logback</groupId>
             <artifactId>logback-classic</artifactId>
             <version>1.1.7</version>
         </dependency>
         <dependency>
             <groupId>org.apache.thrift</groupId>
             <artifactId>libthrift</artifactId>
             <version>0.9.3</version>
         </dependency>
         <dependency>
             <groupId>org.apache.httpcomponents</groupId>
             <artifactId>httpclient</artifactId>
             <version>4.2.6</version>
         </dependency>
         <dependency>
             <groupId>com.fasterxml.jackson.core</groupId>
             <artifactId>jackson-databind</artifactId>
             <version>2.3.1</version>
         </dependency>
 </dependencies>

参考

この SDKは logbackの slf4jバインドライブラリである logback-classicを含めて提供します。

slf4jは特性上、同時に1つのバインドのみサポートするため、他の slf4jバインドのためのライブラリを一緒に使用できません。
既存の使用中の参照ライブラリと nelo2 logback SDKで参照するライブラリが重複する場合、問題が発生することがあります。この場合、より上位のバージョンを使用してください(推奨)。

3. デフォルト Appender設定

デフォルト Appenderを設定する方法は、次の通りです。

logbackは logback.groovy → logback-test.xml → logback.xml 順に設定ファイルを検索します。
- ここでは logback.xml 文書を基準に説明します。
ファイル名: logback.xml

configurationは、以下の例のように入力します。

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" shutDownHook="disable">
    <Appenders>
        <Console name="console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
        </Console>
        <ThriftAppender>
            <name>nelo</name>
            <collectorUrl>COLLECTOR_HOST</collectorUrl>
            <port>COLLECTOR_PORT</port>
            <projectName>PROJECT_KEY</projectName>
            <version>PROJECT_VERSION</version>
            <logType>LOG_TYPE</logType>
            <logSource>LOG_SOURCE</logSource>
        </ThriftAppender>
        <HttpAppender>
            <name>http</name>
            <collectorUrl>COLLECTOR_HOST</collectorUrl>
            <port>COLLECTOR_PORT</port>
            <projectName>PROJECT_KEY</projectName>
            <version>PROJECT_VERSION</version>
            <logType>LOG_TYPE</logType>
            <logSource>LOG_SOURCE</logSource>
        </HttpAppender>
    </Appenders>
    <Loggers>
        <Logger name="nelo" level="error" additivity="false">
            <AppenderRef ref="nelo"/>
            <AppenderRef ref="console"/>
        </Logger>
        <Root level="warn">
            <AppenderRef ref="nelo"/>
            <AppenderRef ref="console"/>
        </Root>
    </Loggers>
</Configuration>

appenderは、以下の例のように入力します。

<!-- define nelo appender -->
<appender name="nelo" class="com.naver.nelo2.log4j.ThriftAppender">
    <param name="Threshold" value="ERROR"/>
    <param name="projectName" value="%YOUR_PROJECT_KEY%"/>
    <param name="collectorUrl" value="elsa-v2-col.ncloud.com"/>
    <param name="port" value="10006"/>
    <param name="timeout" value="1200"/>
    <param name="enable" value="true"/>
    <param name="errorCodeType" value="default"/>
</appender>

各設定オプションの説明は、次の通りです。

設定オプション	説明
`Appender`	転送プロトコルに応じて Appenderのクラス名を選択 Thrift Appender: `com.naver.nelo2.logback.ThriftAppender` Http Appender: `com.naver.nelo2.logback.HttpAppender`
`projectName`	プロジェクトキー
`version`	プロジェクトバージョン(英数字、-、_、.のみ許可し、先頭は英数字/_にすること)
`collectorUrl`	ログ収集サーバの URL Thrift Appender: `elsa-v2-col.ncloud.com` Http Appender: `http://elsa-v2-col.ncloud.com/_store`
`port`	収集サーバポート Thrift Appender: `10006` Http Appender: `80`
`enable`	SDKの使用有無(デフォルト値 `true`)
`logType`	ログタイプ(logType)の設定
`logSource`	ログソース(logSource)の設定
`errorCodeType`	エラーコードタイプ `default`: log4jの基本情報のうち、Exception情報を使用 Exception情報が渡されていない場合(log.error(message)の形式でログが記録される場合)は、全体のエラーメッセージをエラーコードとして使用する例) NullPointerExceptionが発生した場合: `NullPointerException` `message`: エラーメッセージの先頭からスペース文字まで使用例) エラーメッセージが `다운로드에러 다운로드가 실패했습니다.`の場合、「ダウンロードエラー」のみ使用 `mdc`: SLF4J MDCに設定した `errorCode`値を使用例) `MDC.put("errorCode", "Login")`に設定した場合、`Login`を使用
`debug`	Effective Log Search & Analytics 2.0のデバッグ情報を表示(デフォルト値: `false`) このオプションは全域的に適用され、`true`が `false`より優先。複数の appender宣言されていて、その中から1つの `debug` 値が `true`の場合、すべての appenderでコンソールにデバッグログを出力
`timeout`	転送時に使用する socketのタイムアウト(デフォルト値: 5000ms(5秒))
`keepAlive`	転送時に使用する socketの keepAliveタイムアウト(デフォルト値: 60000ms(1分)、最大値: 180000ms(3分))
`isBulkEnabled`	bulkモードの使用有無を設定(デフォルト値: `true`) 設定値が `false`の場合、ログを件数ごとに転送(singleモード)
`bulkSize`	bulkモードの使用時に、1つの bulkリクエストに転送するログの最大数(デフォルト値: 1000、最大値: 100000)
`bulkInterval`	bulkモードを使用する場合、bulkリクエストを呼び出すことになる周期(デフォルト値: 1000ms(1秒)、最大値: 10000ms(10秒))
`alwaysIncludeLocation`	`Location` フィールドをすべてのログに追加するかどうかを設定(デフォルト値: `true`) `false` 設定時: ログレベル(logLevel)が `ERROR`であるログの `Location`フィールドを確認した後に設定 `true` 設定時: すべてのログに対して `Location`フィールドを確認した後に設定。`false`に比べてロギングパフォーマンスに悪い影響を与えることがある
`mdcConversionRule`	MDC keyリネームルールの設定形式: `key1:newKey1;key2:newkey2;...` 例) `time:date;fullname:name`(MDC keyの `time`を `date`と、`fullname`を `name`とリネームする場合)

注意

メモリ使用量に関して、以下をご注意ください。

提供する SDKは bulk転送モードをデフォルトで使用し、bulkSizeのデフォルト値は1000です。1つの Effective Log Search & Analytics 2.0ログは projectName などの複数のフィールドを含めているので、ログボディが非常に短い場合にも1kb程度のメモリに含まれます。基本設定の場合、Nelo2 bulkは (로그 사이즈 + 1 kb)x1000だけのメモリに含まれます。
Javaプロセスを起動する場合、最大ヒープを -Xmx オプションとして指定できます。この時、付加的なメモリ使用量も検討してください。
bulkSize オプションをより大きく指定する場合は、特にご注意ください。

bulkと singleモード

NELO2 logback SDKはログを件数ごとに転送する singleモードとセット単位で転送する bulkモードをサポートします。xml appender設定で isBulkEnabledを true または falseにし、bulkと singleモードの中から選択できます(デフォルト値: true(bulkモード))。
プロトコルに応じて以下のパフォーマンス指標をご参照ください。

1分間単一スレッドで 1kb sizeのログを転送する場合の throughput
- thrift
  - singleモード: 2587.93logs/sec
  - bulkモード: 6492.99logs/sec
- http
  - singleモード: 595.86logs/sec
  - bulkモード: 4617.98logs/sec

参考

上記のパフォーマンステストに使用した装置のスペックは、次の通りです。
- ログ転送サーバ: 2GHZ、12core cpu、48G mem
- ログ収集サーバ: 2.26GHZ、12core cpu、48G mem
負荷に応じて転送パフォーマンスは異なります。
- テストは負荷がない状況で実行され、実際に使用中のインスタンスに送信する際には比較的低いパフォーマンスを示します。
- インスタンス負荷に応じたパフォーマンスの体験は、bulkモードに比べて singleモードでより大きく表示されます。そのため、デフォルト値である bulkモードを使用してください(推奨)。
- 収集サーバが許可する最大パケットのサイズは30mbです。クライアントサーバのログパターンを検討し、適切な bulkSizeを設定します(デフォルト値: 1000)。

4. AsyncAppender設定

デフォルトで使用する Appenderに追加として logbackでサポートする AsyncAppenderを使用し、実際のログ転送を別途スレッドで行えます。

以下の例を参照し、AsyncAppenderを設定します。

注意

AsyncAppenderの includeLocationを trueに設定します。そうでない場合、転送時にエラーが発生します。

参考

AsyncAppender設定の詳細情報は、logbackマニュアルをご参照ください。

例)

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" shutDownHook="disable">
    <Appenders>
        <Console name="console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
        </Console>
        <ThriftAppender>
            <name>nelo</name>
            <collectorUrl>COLLECTOR_HOST</collectorUrl>
            <port>COLLECTOR_PORT</port>
            <projectName>PROJECT_KEY</projectName>
            <version>PROJECT_VERSION</version>
            <logType>LOG_TYPE</logType>
            <logSource>LOG_SOURCE</logSource>
        </ThriftAppender>
        <HttpAppender>
            <name>http</name>
            <collectorUrl>COLLECTOR_HOST</collectorUrl>
            <port>COLLECTOR_PORT</port>
            <projectName>PROJECT_KEY</projectName>
            <version>PROJECT_VERSION</version>
            <logType>LOG_TYPE</logType>
            <logSource>LOG_SOURCE</logSource>
        </HttpAppender>
        <Async name="async">
            <AppenderRef ref="nelo"/>
            <includeLocation>true</includeLocation>
        </Async>
    </Appenders>
    <Loggers>
        <Logger name="nelo" level="error" additivity="false">
            <AppenderRef ref="async"/>
            <AppenderRef ref="console"/>
        </Logger>
        <Root level="warn">
            <AppenderRef ref="nelo"/>
            <AppenderRef ref="console"/>
        </Root>
    </Loggers>
</Configuration>

5. SDKを使用する

以下の Effective Log Search & Analytics 2.0 logback SDKを使用する実際のサンプルコードを参照し、プロジェクトにログを転送します。

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

private static final Logger logger = LoggerFactory.getLogger("nelo");
...
    logger.debug("Effective Log Search & Analytics logback SDK Debug Message");
    try {
        String npe = null;
        npe.toString();
    } catch(Exception e) {
        logger.error("Effective Log Search & Analytics logback SDK Exception", e);
    }

参考

Effective Log Search & Analytics 2.0 logback SDKの制限事項は、次の通りです。

AsyncAppenderの使用時、転送スピードに比べてログの発生スピードが早い場合は、queueSize(デフォルト値: 128)を超過して発生したログは転送しません。
includeCallerData デフォルト値が falseの場合、AsyncAppenderはログの発生場所情報を無視することになります。
AsyncAppenderとデフォルト Appenderは、以下の基準に従って選択してください(推奨)。
- デフォルト Appender: ログ損失を最小化したい場合
- AsyncAppende: Effective Log Search & Analytics 2.0サービスシステムの障害時、アプリケーションのパフォーマンス低下の恐れがある場合

logback SDK v2のトラブルシューティング

logback SDK v2に関して発生し得る問題と解決方法を確認します。

Effective Log Search & Analytics 2.0サーバにログを転送したが、これをウェブで確認できない場合

転送したログをウェブで確認できない場合、以下のように対応します。

ログを Effective Log Search & Analytics 2.0収集サーバに転送した後、結果メッセージにエラーがない場合は projectNameが正しいか確認します。
実際にエラーデータが転送されることを確認します。
- 設定ファイル(logback.xml)で Effective Log Search & Analytics 2.0 NELO appenderの debug プロパティを trueに設定して実行した後、以下のような転送ログが出力されることを確認します。

  <!-- NELO2 Logback Appender -->
  <appender name="nelo-logback" class="com.naver.nelo2.logback.ThriftAppender">
      <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
          <level>ERROR</level>
      </filter>
      <param name="projectName" value="%YOUR_PROJECT_KEY%"/>
      <param name="collectorUrl" value="elsa-v2-col.ncloud.com"/>
      <param name="port" value="10006"/>
      <param name="timeout" value="1200" />
      <param name="enable" value="true" />
      <param name="errorCodeType" value="default" />
      <param name="debug" value="true" />
  </appender>

  [NELO2] Log Append : sent event, return value :
  …