Log4j2 SDK v2
    • 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를 설치하기 위한 사전 준비 사항은 다음과 같습니다.

    1. 네이버 클라우드 플랫폼의 콘솔에서 프로젝트를 생성해 주십시오.
    2. 생성한 프로젝트의 상세 정보 화면에서 txtToken 값을 확인해 주십시오.
    3. log4j2 SDK를 다운로드해 주십시오.

    2. Dependency 추가

    log4j2 SDK v2를 설치하는 방법은 다음과 같습니다.

    1. 다운로드한 SDK 파일의 압축을 풀어 주십시오.
    2. 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는 특성상 동시에 하나의 바인딩만 지원하므로, 다른 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의 클래스명을 선택
    • 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
    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가 선언되어 있고, 그 중 하나의 debug 값이 true일 경우, 모든 appender에서 콘솔에 디버그 로그 출력
    timeout전송 시 사용되는 socket의 타임아웃(기본값: 5000 ms(5초))
    keepAlive전송 시 사용되는 socket의 keepAlive 타임아웃(기본값: 60000 ms(1분), 최댓값: 180000 ms(3분))
    isBulkEnabledbulk 모드 사용 여부 설정(기본값: true)
    • 설정값이 false일 경우, 로그를 건당 전송(single 모드)
    bulkSizebulk 모드 사용 시, 하나의 bulk 요청에 전송될 최대 로그의 수(기본값: 1000, 최댓값: 100000)
    bulkIntervalbulk 모드를 사용 시, bulk 요청을 호출하게 될 주기(기본값: 1000 ms(1초), 최댓값: 10000 ms(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입니다. 하나의 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 설정에서 isBulkEnabledtrue 또는 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의 includeLocationtrue로 설정해 주십시오. 그렇지 않으면 전송 시에 에러가 발생합니다.

    참고

    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 서버로 로그를 전송했지만, 이를 웹에서 확인할 수 없는 경우

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

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

    이 문서가 도움이 되었습니까?

    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.