---
title: "Logback SDK v2"
slug: "elsa2-sdk-logback"
tags: ["elsa2", "Log4j", "log4j2", "logback", "sdk", "로그 전송"]
updated: 2026-09-17T09:28:51Z
published: 2026-09-17T09:28:51Z
canonical: "guide.ncloud-docs.com/elsa2-sdk-logback"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Logback SDK v2

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

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

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

[1. 事前準備](/docs/ja/elsa2-sdk-logback#1%EC%82%AC%EC%A0%84%EC%A4%80%EB%B9%84) [2. Dependency追加](/docs/ja/elsa2-sdk-logback#2Dependency%EC%B6%94%EA%B0%80) [3. デフォルト Appender設定](/docs/ja/elsa2-sdk-logback#3%EA%B8%B0%EB%B3%B8Appender%EC%84%A4%EC%A0%95) [4. AsyncAppender設定](/docs/ja/elsa2-sdk-logback#4AsyncAppender%EC%84%A4%EC%A0%95) [5. SDKを使用する](/docs/ja/elsa2-sdk-logback#5SDK%EC%82%AC%EC%9A%A9)

## 1. 事前準備

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

1. NAVERクラウドプラットフォームコンソールで、[プロジェクトを作成](/docs/ja/elsa2-project)します。
2. 作成した[プロジェクト詳細情報画面](/docs/ja/elsa2-project#%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8%EC%83%81%EC%84%B8%EC%A0%95%EB%B3%B4%ED%99%95%EC%9D%B8)で txtToken値を確認します。
3. logback SDKを[ダウンロード](/docs/ja/elsa2-sdk-download)します。

## 2. Dependency追加

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

1. ダウンロードした SDKファイルの圧縮を解凍します。
2. pom.xmlファイルに以下のように dependencyを追加します。

```
 <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>
```
  - `&lt;systemPath&gt;`に各々 coreモジュール(nelo2-java-sdk-core-1.6.6.jar)と logbackモジュール(nelo2-java-sdk-logback-1.6.6.jar)のパス追加

              参考

              

この 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`

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_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>
```
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_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`: エラーメッセージの先頭からスペース文字まで使用 - 例) エラーメッセージが `&#xB2E4;&#xC6B4;&#xB85C;&#xB4DC;&#xC5D0;&#xB7EC; &#xB2E4;&#xC6B4;&#xB85C;&#xB4DC;&#xAC00; &#xC2E4;&#xD328;&#xD588;&#xC2B5;&#xB2C8;&#xB2E4;.`の場合、「ダウンロードエラー」のみ使用 - `mdc`: SLF4J MDCに設定した `errorCode`値を使用 - 例) `MDC.put(&quot;errorCode&quot;, &quot;Login&quot;)`に設定した場合、`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は `(&#xB85C;&#xADF8; &#xC0AC;&#xC774;&#xC988; + 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マニュアル](https://logging.apache.org/log4j/2.x/manual/appenders.html)をご参照ください。

例)

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

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

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_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 :
  …
```