Log4j SDK v2

Prev Next

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

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

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

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

1. 事前準備

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

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

2. Dependency追加

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

  1. ダウンロードした SDKファイルの圧縮を解凍します。
  2. pom.xmlファイルに以下のように dependencyを追加します。
    • <systemPath>にそれぞれの coreモジュール(nelo2-java-sdk-core-1.6.6.jar)と log4jモジュール(nelo2-java-sdk-log4j-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-log4j</groupId>
         <artifactId>nelo2-java-sdk-log4j</artifactId>
         <version>1.6.6</version>
         <scope>system</scope>
         <systemPath>/nelo2-java-sdk-log4j-1.6.6.jar</systemPath>
     </dependency>
     <dependency>
         <groupId>log4j</groupId>
         <artifactId>log4j</artifactId>
         <version>1.2.17</version>
     </dependency>
     <dependency>
         <groupId>org.slf4j</groupId>
         <artifactId>slf4j-log4j12</artifactId>
         <version>1.7.2</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は log4jの slf4jバインドライブラリである slf4j-log4j12を含めて提供します。

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

3. デフォルト Appender設定

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

  • ファイル名: log4j.xml
  1. configurationは、以下のように入力します。
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration PUBLIC "" "log4j.dtd">
<log4j:configuration xmlns:log4j='http://jakarta.apache.org/log4j/'>
    <!-- // define appenders // -->
    <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
        <param name="Threshold" value="DEBUG"/>
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%m%n"/>
        </layout>
    </appender>
    <!-- // define loggers // -->
    <logger name="com" additivity="false">
        <level value="INFO"/>
        <appender-ref ref="STDOUT"/>
    </logger>
    <!-- // define root // -->
    <root>
        <level value="WARN"/>
        <appender-ref ref="STDOUT"/>
    </root>
</log4j:configuration>
  1. 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.log4j.ThriftAppender
  • Http Appender: com.naver.nelo2.log4j.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: エラーメッセージの先頭からスペース文字まで使用
    • 例) エラーメッセージが 다운로드에러 다운로드가 실패했습니다.の場合、「ダウンロードエラー」のみ使用
  • action: URLの Path情報(Lucy intercepterが適用されている必要がある)
    • 例) URLが http://xxx.com/board/list?id=100の場合、Pathは「/board/list」
  • 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 log4j SDKはログを件数ごとに転送する singleモードとセット単位で転送する bulkモードをサポートします。xml appender設定で isBulkEnabledを true または falseにし、bulkと singleモードの中から選択できます(デフォルト値: true(bulkモード))。
プロトコルに応じて以下のパフォーマンス指標をご参照ください。

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

4. AsyncAppender設定

デフォルト Appenderlog4jでサポートする AsyncAppenderを利用し、デフォルト Appenderと同じ方式の結果が得られます。

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

注意

AsyncAppenderの使用時には、以下の設定値にご注意ください。

  • bufferSizeのデフォルト値は 128ですが、いくつかのアプリケーションでは十分でないことがあります。
  • locationInfoのデフォルト値は falseであり、この場合 AsyncAppenderはログの発生場所情報を無視します。
参考

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

例)

<appender name="nelo-async" class="org.apache.log4j.AsyncAppender">
    <param name="Threshold" value="ERROR"/>
    <param name="blocking" value="false"/>
    <param name="locationInfo" value="true"/>
    <param name="bufferSize" value="2048"/>
    <appender-ref ref="nelo"/>
</appender>

デフォルトで使用する ThriftAppenderに追加として Nelo2AsyncAppenderを使用し、実際のログ転送を別途スレッドで実行するには、以下の例を参照して設定します。

例)

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration PUBLIC "" "log4j.dtd">
<log4j:configuration xmlns:log4j='http://jakarta.apache.org/log4j/'>
    <!-- // define appenders // -->
    <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
        <param name="Threshold" value="DEBUG"/>
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%m%n"/>
        </layout>
    </appender>
    <!-- define nelo appender -->
    <appender name="nelo" class="com.naver.nelo2.log4j.ThriftAppender">
        <param name="Threshold" value="ERROR"/>
        <param name="projectName" value="프로젝트 키"/>
        <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>
    <!-- define nelo-async appender -->
    <appender name="nelo-async"
              class="org.apache.log4j.AsyncAppender">
        <param name="Threshold" value="ERROR"/>
        <param name="blocking" value="false"/>
        <param name="locationInfo" value="true"/>
        <param name="bufferSize" value="2048"/>
        <appender-ref ref="nelo"/>
    </appender>
    <!-- // define loggers // -->
    <logger name="com" additivity="false">
        <level value="ERROR"/>
        <appender-ref ref="STDOUT"/>
        <appender-ref ref="nelo-async"/>
    </logger>
    <!-- // define root // -->
    <root>
        <level value="WARN"/>
        <appender-ref ref="STDOUT"/>
        <appender-ref ref="nelo-async"/>
    </root>
</log4j:configuration>

5. SDKを使用する

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

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

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

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

  • log4j 2.0バージョンで上記のガイドの内容を公式的にサポートしません。
  • AsyncAppenderの使用時、転送スピードに比べてログの発生スピードが早い場合は、queueSize(デフォルト値: 128)を超過して発生したログは転送しません。
  • AsyncAppenderとデフォルト Appenderは、以下の基準に従って選択してください(推奨)。
    • デフォルト Appender: ログ損失を最小化したい場合
    • AsyncAppende: Effective Log Search & Analytics 2.0サービスシステムの障害時、アプリケーションのパフォーマンス低下の恐れがある場合

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

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

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

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

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

[NELO2] Log Append : sent event, return value :
…
事業者登録番号: 129-86-31394 通信販売業申告番号:第2009-京畿城南-0510号
代表取締役: キム・ユウォン アドレス: 13561 京畿道 城南市 盆唐区 仏亭路6 グリーンファクトリー, 17~26F お客様センターの代表電話: 1544-5876
© NAVER Cloud Corp. All Rights Reserved.