- 印刷する
- PDF
Log4j2 SDK v2
- 印刷する
- PDF
Classic/VPC環境で利用できます。
log4j2 SDK v2では、Effective Log Search & Analytics 2.0サービスで提供する log4j2 SDKの使用方法を説明します。
SDKを使用する手順は、次の通りです。
1. 事前準備
2. Dependency追加
3. 基本 Appender設定
4. AsyncAppender設定
5. SDKを使用する
1. 事前準備
log4j2 SDKをインストールするための事前準備事項は、次の通りです。
- NAVERクラウドプラットフォームコンソールで、プロジェクトを作成します。
- 作成したプロジェクト詳細情報画面で txtToken値を確認します。
- log4j2 SDKをダウンロードします。
2. Dependency追加
log4j2 SDK v2をインストールする方法は、次の通りです。
ダウンロードした SDKファイルの圧縮を解凍します。
pom.xmlファイルに以下のように dependencyを追加します。
<systemPath>
に各々 coreモジュール(nelo2-java-sdk-core-1.6.6.jar)と log4j2モジュール(nelo2-java-sdk-log4j2-2.8.5.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-log4j2</artifactId> <version>2.8.5</version> <scope>system</scope> <systemPath>/nelo2-java-sdk-log4j2-2.8.5.jar</systemPath> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-api</artifactId> <version>2.8.2</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-core</artifactId> <version>2.8.2</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-slf4j-impl</artifactId> <version>2.8.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は log4j2の slf4jバインドライブラリである log4j-slf4j-implを含めて提供します。
- slf4jは特性上、同時に1つのバインドのみサポートするので、他の slf4jバインドのためのライブラリを一緒に使用できません。
- 既存の使用中の参照ライブラリと nelo2 log4j2 SDKで参照するライブラリが重複する場合、問題が発生することがあります。この場合、より上位のバージョンを使用してください(推奨)。
3. 基本 Appender設定
基本 Appenderを設定する方法は、次の通りです。
- ファイル名:
log4j2.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_ID</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_ID</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 | 転送プロトコルに従って 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 log4j2 SDKはログを件数ごとに転送する singleモードとセット単位で転送する bulkモードをサポートします。xml appender設定で isBulkEnabled
を true
または false
にし、bulkと singleモードの中から選択できます(デフォルト値: true
(bulkモード))。
プロトコルに応じて以下のパフォーマンス指標をご参照ください。
- 1分間単一スレッドで 1kb sizeのログを転送する場合の throughput
- thrift
- singleモード: 2636.00logs/sec
- bulkモード: 6369.10logs/sec
- http
- singleモード: 583.36logs/sec
- bulkモード: 4618.90logs/sec
- thrift
- 上記のパフォーマンステストに使用した装置のスペックは、次の通りです。
- ログ転送サーバ: 2GHZ、12core cpu、48G mem
- ログ収集サーバ: 2.26GHZ、12core cpu、48G mem
- 負荷に応じて転送パフォーマンスは異なります。
- テストは負荷がない状況で駆動しております。実際に使用中のインスタンスに転送する場合、比較的低いパフォーマンスを見せます。
- インスタンス負荷に応じたパフォーマンスの体験は、bulkモードに比べて singleモードでより大きく表示されます。そのため、デフォルト値である bulkモードを使用してください(推奨)。
- 収集サーバが許可する最大パケットのサイズは30mbです。クライアントサーバのログパターンを検討し、適切な
bulkSize
を設定します(デフォルト値: 1000)。
4. AsyncAppender設定
基本的に使用する Appenderに追加として log4j2でサポートする AsyncAppenderを使用し、実際のログ転送を別途スレッドで行えます。
以下の例を参照し、AsyncAppenderを設定します。
AsyncAppenderの includeLocation
を true
に設定します。そうでない場合、転送時にエラーが発生します。
AsyncAppender設定の詳細情報は、log4j2マニュアルをご参照ください。
例)
<?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_ID</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_ID</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 log4j2 SDKを使用する実際のサンプルコードを参照し、プロジェクトにログを転送します。
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
private static final Logger logger = LoggerFactory.getLogger("nelo");
...
logger.debug("Effective Log Search & Analytics log4j2 SDK Debug Message");
try {
String npe = null;
npe.toString();
} catch(Exception e) {
logger.error("Effective Log Search & Analytics log4j2 SDK Exception", e);
}
Effective Log Search & Analytics 2.0 log4j2 SDKの制限事項は、次の通りです。
- AsyncAppenderの使用時、転送スピードに比べてログの発生スピードが早い場合は、
queueSize
(デフォルト値: 128)を超過して発生したログは転送しません。 - AsyncAppenderと基本 Appenderは、以下の基準に従って選択してください(推奨)。
- 基本 Appender: ログ損失を最小化したい場合
- AsyncAppende: Effective Log Search & Analytics 2.0システムの障害時、アプリケーションのパフォーマンス低下の恐れがある場合
log4j2 SDK v2のトラブルシューティング
log4j2 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
に設定して実行した後、以下のような転送ログが出力されることを確認します。
- 設定ファイル(log4j.xml)で Effective Log Search & Analytics 2.0 NELO appenderの
<!-- define nelo appender -->
<ThriftAppender>
<name>nelo</name>
<collectorUrl>COLLECTOR_HOST</collectorUrl>
<port>COLLECTOR_PORT</port>
<projectName>PROJECT_ID</projectName>
<version>PROJECT_VERSION</version>
<logType>LOG_TYPE</logType>
<logSource>LOG_SOURCE</logSource>
<debug>true</debug>
</ThriftAppender>
[NELO2] Log Append : sent event, return value :
…