---
title: "Log4j2 SDK v2"
slug: "elsa2-sdk-log4j2"
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-log4j2"
---

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

# Log4j2 SDK v2

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

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

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

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

## 1. 사전 준비

log4j2 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. log4j2 SDK를 [다운로드](/docs/elsa2-sdk-download)해 주십시오.

## 2. Dependency 추가

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

          참고

          

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

- slf4j는 특성상 동시에 하나의 바인딩만 지원하므로, 다른 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_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>
```

각 설정 옵션에 대한 설명은 다음과 같습니다.

| 설정 옵션 | 설명 |
| --- | --- |
| `Appender` | 전송 프로토콜에 따라 Appender의 클래스명을 선택 - Thrift Appender: `ThriftAppender` - Http Appender: `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`: 에러 메시지의 처음부터 공백 문자까지만 사용 - <예시> 에러 메시지가 `다운로드에러 다운로드가 실패했습니다.`인 경우, '다운로드에러'만 사용 - `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 log4j2 SDK는 로그 전송을 건당으로 보내는 single 모드와 묶음 단위로 전송하는 bulk 모드를 지원합니다. xml appender 설정에서 `isBulkEnabled`를 `true` 또는 `false`로 하여 bulk 또는 single 모드를 선택할 수 있습니다(기본값: `true`(bulk 모드)). 프로토콜에 따라 다음 성능 지표를 참고해 주십시오.

- 1분간 단일 스레드에서 1kb size의 로그를 전송할 시의 throughput
  - thrift
    - single 모드: 2636.00 logs/sec
    - bulk 모드: 6369.10 logs/sec
  - http
    - single 모드: 583.36 logs/sec
    - bulk 모드: 4618.90 logs/sec

          참고

          

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

## 4. AsyncAppender 설정

기본적으로 사용하는 Appender에 추가로 log4j2에서 지원하는 AsyncAppender를 사용하여 실제 로그 전송 작업을 별도의 스레드에서 수행할 수 있습니다.

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

          주의

          

AsyncAppender의 `includeLocation`를 `true`로 설정해 주십시오. 그렇지 않으면 전송 시에 에러가 발생합니다.

          참고

          

AsyncAppender 설정에 대한 상세 정보는 [log4j2 매뉴얼](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 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 서버로 로그를 전송했지만, 이를 웹에서 확인할 수 없는 경우

전송한 로그를 웹에서 확인할 수 없는 경우 다음과 같이 조치해 주십시오.

1. 로그를 Effective Log Search & Analytics 2.0 수집 서버로 전송 후, 결과 메시지에 오류가 없는 경우에는 `projectName`이 정확한지 확인해 주십시오.
2. 실제 오류 데이터가 전송되는지 확인해 주십시오.
  - 설정 파일(log4j.xml)에서 Effective Log Search & Analytics 2.0 NELO appender의 `debug` 속성을 `true`로 설정하고 실행한 후 다음와 같은 전송 로그가 출력되는지 확인해 주십시오.

```
  <!-- define nelo appender -->
  <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>
      <debug>true</debug>
  </ThriftAppender>

  [NELO2] Log Append : sent event, return value :
  …
```