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

> ## 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.

# Log4j SDK v2

Classic/VPC 환경에서 이용 가능합니다.

log4j SDK v2에서는 Effective Log Search & Analytics 2.0 서비스가 제공하는 log4j SDK의 사용 방법을 설명합니다.

SDK를 사용하는 순서는 다음와 같습니다.

[1. 사전 준비](/docs/elsa2-sdk-log4j#1%EC%82%AC%EC%A0%84%EC%A4%80%EB%B9%84) [2. Dependency 추가](/docs/elsa2-sdk-log4j#2Dependency%EC%B6%94%EA%B0%80) [3. 기본 Appender 설정](/docs/elsa2-sdk-log4j#3%EA%B8%B0%EB%B3%B8Appender%EC%84%A4%EC%A0%95) [4. AsyncAppender 설정](/docs/elsa2-sdk-log4j#4AsyncAppender%EC%84%A4%EC%A0%95) [5. SDK 사용](/docs/elsa2-sdk-log4j#5SDK%EC%82%AC%EC%9A%A9)

## 1. 사전 준비

log4j SDK를 설치하기 위한 사전 준비 사항은 다음과 같습니다.

1. 네이버 클라우드 플랫폼의 콘솔에서 [프로젝트를 생성](/docs/elsa2-project)해 주십시오.
2. 생성한 [프로젝트의 상세 정보 화면](/docs/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. log4j SDK를 [다운로드](/docs/elsa2-sdk-download)해 주십시오.

## 2. Dependency 추가

log4j 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-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>
```
  - `&lt;systemPath&gt;`에 각각 core 모듈(nelo2-java-sdk-core-1.6.6.jar)과 log4j 모듈(nelo2-java-sdk-log4j-1.6.6.jar)의 경로 추가

          참고

          

이 SDK는 log4j의 slf4j 바인딩 라이브러리인 slf4j-log4j12을 포함하여 제공하고 있습니다.

- slf4j는 특성상 동시에 하나의 바인딩만 지원하므로, 다른 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가 선언되어 있고, 그 중 하나의 `debug` 값이 `true`일 경우, 모든 appender에서 콘솔에 디버그 로그 출력 |
| `timeout` | 전송 시 사용되는 socket의 타임아웃(기본값: 5000 ms(5초)) |
| `keepAlive` | 전송 시 사용되는 socket의 keepAlive 타임아웃(기본값: 60000 ms(1분), 최댓값: 180000 ms(3분)) |
| `isBulkEnabled` | bulk 모드 사용 여부 설정(기본값: `true`) - 설정값이 `false`일 경우, 로그를 건당 전송(single 모드) |
| `bulkSize` | bulk 모드 사용 시, 하나의 bulk 요청에 전송될 최대 로그의 수(기본값: 1000, 최댓값: 100000) |
| `bulkInterval` | bulk 모드를 사용 시, bulk 요청을 호출하게 될 주기(기본값: 1000 ms(1초), 최댓값: 10000 ms(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입니다. 하나의 Effective Log Search & Analytics 2.0 로그는 `projectName` 등 여러 필드를 포함하고 있기 때문에, 로그 바디가 매우 짧은 경우에도 1 kb정도의 메모리를 차지합니다. 따라서 기본 설정인 경우, Nelo2 bulk는 `(로그 사이즈 + 1 kb)x1000`만큼의 메모리를 차지합니다.
- 자바 프로세스를 기동할 때, 최대 힙을 `-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.54 logs/sec
    - bulk 모드: 6642.97 logs/sec
  - http
    - single 모드: 592.97 logs/sec
    - bulk 모드: 4665.26 logs/sec

          참고

          

- 위 성능 테스트에 사용한 장비의 스펙은 다음과 같습니다.
  - 로그 전송 서버: 2 GHZ, 12core cpu, 48G mem, 가산 IDC 위치
  - 로그 수집 서버: 2.26 GHZ, 12core cpu, 48G mem, 가산 IDC 위치
- 부하에 따라 전송 성능은 다를 수 있습니다.
  - 테스트는 부하가 없는 상황에서 구동하였으며, 실제 사용 중인 인스턴스로 전송 시에는 비교적 낮은 성능을 보입니다.
  - 인스턴스 부하에 따른 성능 체감은 bulk 모드에 비해 single 모드에서 더 크게 나타납니다. 따라서 기본값인 bulk 모드를 사용해 주십시오(권장).
  - 수집 서버가 허용하는 최대 패킷의 사이즈는 30 mb입니다. 클라이언트 서버의 로그 패턴을 고려하여 적절한 `bulkSize`를 설정해 주십시오(기본값: 1000).

## 4. AsyncAppender 설정

기본 Appenderlog4j에서 지원되는 AsyncAppender를 이용하여 기본 Appender와 같은 방식의 결과를 얻을 수 있습니다.

다음의 예시를 참고하여 AsyncAppender를 설정해 주십시오.

          주의

          

AsyncAppender 사용 시에는 다음 설정값에 주의해 주십시오.

- `bufferSize`는 기본값이 `128`이지만, 몇몇 애플리케이션에서는 충분하지 않을 수 있습니다.
- `locationInfo`는 기본값이 `false`로, 이 경우 AsyncAppender는 로그의 발생 위치 정보를 무시합니다.

          참고

          

AsyncAppender 설정에 대한 상세 정보는 [log4j 매뉴얼](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/AsyncAppender.html)을 참고해 주십시오.

<예시>

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