Logback SDK v2
    • PDF

    Logback SDK v2

    • PDF

    記事の要約

    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をインストールするための事前準備事項は、次の通りです。

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

    2. Dependency追加

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

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

    2. 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.groovylogback-test.xmllogback.xml 順に設定ファイルを検索します。
      • ここでは logback.xml 文書を基準に説明します。
    • ファイル名: logback.xml
    1. 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>
      
    2. 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のクラス名を選択
    • Thrift Appender: com.naver.nelo2.logback.ThriftAppender
    • Http Appender: com.naver.nelo2.logback.HttpAppender
    projectNameプロジェクト ID
    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
    enableSDKの使用有無(デフォルト値 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 を使用
    debugEffective Log Search & Analytics 2.0のデバッグ情報を表示(デフォルト値: false)
    • このオプションは全域的に適用され、truefalseに優先。複数の appender宣言されていて、その中から1つの debug 値が trueの場合、すべての appenderでコンソールにデバッグログを出力
    timeout転送時に使用する socketのタイムアウト(デフォルト値: 5000ms(5秒))
    keepAlive転送時に使用する socketの keepAliveタイムアウト(デフォルト値: 60000ms(1分)、最大値: 180000ms(3分))
    isBulkEnabledbulkモードの使用有無を設定(デフォルト値: true)
    • 設定値が falseの場合、ログを件数ごとに転送(singleモード)
    bulkSizebulkモードの使用時に、1つの bulkリクエストに転送するログの最大数(デフォルト値: 1000、最大値: 100000)
    bulkIntervalbulkモードを使用する場合、bulkリクエストを呼び出すことになる周期(デフォルト値: 1000ms(1秒)、最大値: 10000ms(10秒))
    alwaysIncludeLocationLocation フィールドをすべてのログに追加するかどうかを設定(デフォルト値: true)
    • false 設定時: ログレベル(logLevel)が ERRORであるログの Locationフィールドを確認した後に設定
    • true 設定時: すべてのログに対して Location フィールドを確認した後に設定。falseに比べてロギングパフォーマンスに悪い影響を与えることがある
    mdcConversionRuleMDC keyリネームルールの設定
    • 形式: key1:newKey1;key2:newkey2;...
    • 例) time:date;fullname:name(MDC keyの timedateと、fullnamenameとリネームする場合)
    注意

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

    • 提供する 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設定で isBulkEnabledtrue または 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の includeLocationtrueに設定します。そうでない場合、転送時にエラーが発生します。

    参考

    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_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 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サーバにログを転送したが、これをウェブで確認できない場合

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

    1. ログを Effective Log Search & Analytics 2.0収集サーバに転送した後、結果メッセージにエラーがない場合は projectNameが正しいか確認します。
    2. 実際にエラーデータが転送されることを確認します。
      • 設定ファイル(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_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 :
      …
    

    この記事は役に立ちましたか?

    What's Next
    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.