- 印刷する
- PDF
Log4j SDK v2
- 印刷する
- PDF
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をインストールするための事前準備事項は、次の通りです。
- NAVERクラウドプラットフォームコンソールで、プロジェクトを作成します。
- 作成したプロジェクト詳細情報画面で txtToken値を確認します。
- log4j SDKをダウンロードします。
2. Dependency追加
log4j SDK v2をインストールする方法は、次の通りです。
ダウンロードした SDKファイルの圧縮を解凍します。
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
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>
appender
は、以下のような形式で入力します。
<!-- define nelo appender -->
<appender name="nelo" class="com.naver.nelo2.log4j.ThriftAppender">
<param name="Threshold" value="ERROR"/>
<param name="projectName" value="%YOUR_PROJECT_ID%"/>
<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のクラス名を選択
|
projectName | プロジェクト ID |
version | プロジェクトバージョン(英数字、-、_、.のみ許可し、先頭は英数字/_にすること) |
collectorUrl | ログ収集サーバの URL
|
port | 収集サーバポート
|
enable | SDKの使用有無(デフォルト値 true ) |
logType | ログタイプ(logType)の設定 |
logSource | ログソース(logSource)の設定 |
errorCodeType | エラーコードのタイプ
|
debug | Effective Log Search & Analytics 2.0のデバッグ情報を表示(デフォルト値: false )
|
timeout | 転送時に使用する socketのタイムアウト(デフォルト値: 5000ms(5秒)) |
keepAlive | 転送時に使用する socketの keepAliveタイムアウト(デフォルト値: 60000ms(1分)、最大値: 180000ms(3分)) |
isBulkEnabled | bulkモードの使用有無を設定(デフォルト値: true )
|
bulkSize | bulkモードの使用時に、1つの bulkリクエストに転送するログの最大数(デフォルト値: 1000、最大値: 100000) |
bulkInterval | bulkモードを使用する場合、bulkリクエストを呼び出すことになる周期(デフォルト値: 1000ms(1秒)、最大値: 10000ms(10秒)) |
alwaysIncludeLocation | Location フィールドをすべてのログに追加するかどうかを設定(デフォルト値: true )
|
mdcConversionRule | MDC keyリネームルールの設定
|
メモリ使用量に関して、以下をご注意ください。
- 提供する 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
- thrift
- 上記のパフォーマンステストに使用した装置のスペックは、次の通りです。
- ログ転送サーバ: 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="プロジェクト ID"/>
<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サーバにログを転送したが、これをウェブで確認できない場合
転送したログをウェブで確認できない場合、以下のように対応します。
- ログを Effective Log Search & Analytics 2.0収集サーバに転送した後、結果メッセージにエラーがない場合は
projectName
が正しいか確認します。 - 実際にエラーデータが転送されることを確認します。
- 設定ファイル(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_ID%"/> <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 : …
- 設定ファイル(log4j.xml)で Effective Log Search & Analytics 2.0 NELO appenderの