SYSLOG 인코딩 형식 변경 가이드

How To
1

본 문서는 시스로그 수집 시 발생하는 한글 인코딩 깨짐 현상의 원인과 해결 방법을 정리한 가이드입니다.

실제 고객사에서 EUC-KR 등 비 UTF-8 인코딩으로 시스로그를 송신하는 장비를 연동할 때 자주 마주치는 이슈이므로, 동일한 문제를 겪는 분들께 실질적인 도움이 되기를 바랍니다.

내용 중 수정이 필요한 부분이나 추가 의견이 있으시면 언제든 피드백 부탁드립니다.

개요

  • 로그프레소 시스로그 수집기는 기본 인코딩이 UTF-8입니다.

  • 송신 측 장비가 EUC-KR, CP949 등 다른 인코딩으로 메시지를 전송하면 한글이 ???, ��, 깨진 문자 형태로 저장됩니다.

  • 송신 장비별로 인코딩이 상이한 환경에서는 원격 IP 단위로 인코딩을 개별 지정하여 문제를 해결할 수 있습니다.

  • 다중 노드 구성이라면 모든 노드에서 동일하게 설정하여 환경값을 일치시키는 것을 권장드립니다. 특정 노드에만 매핑이 등록되어 있으면 해당 노드를 거치지 않은 트래픽은 인코딩이 깨진 상태로 적재될 수 있습니다.

적용 대상

  • 로그프레소 시스로그 서버(syslog 수집 바인딩)를 운영 중인 환경

  • 송신 장비(방화벽, 네트워크 장비, 레거시 서버 등)가 EUC-KR/CP949로 메시지를 보내는 경우

  • 수집된 시스로그 테이블에서 한글이 깨진 상태로 적재되어 있는 경우

배경

  • 시스로그 프로토콜(RFC 3164/5424)은 메시지 본문의 문자 인코딩을 규약으로 강제하지 않습니다.

  • 송신 장비 OS·솔루션에 따라 EUC-KR, CP949, UTF-8 등 다양한 인코딩이 혼재합니다.

  • 수신 측이 일괄적으로 UTF-8로 디코딩하면 비 UTF-8 송신 장비의 한글 메시지가 깨지게 됩니다.

사전 확인

  • 인코딩 매핑을 적용하기 전에, syslog.servers 명령어로 현재 운영 중인 시스로그 바인딩 목록과 기본 인코딩 상태를 먼저 확인합니다.

  • 대괄호([ ]) 안의 값이 시스로그 바인딩 이름(server name)입니다. syslog.addCharsetMapping의 첫 번째 인자로 사용합니다.

  • charset=UTF-8 (override: N)에서 override 값은 현재 바인딩에 등록된 IP별 인코딩 매핑의 개수를 의미합니다. 매핑 적용 전후 비교에 활용할 수 있습니다.

  • syslog.servers를 비롯한 시스로그 바인딩 명령(syslog.open, syslog.close 등) 전반에 대한 자세한 내용은 시스로그 수집 안내 글을 참고 부탁드립니다

    logpresso> syslog.servers
Syslog Servers
----------------
[logpresso_udp_1514] 0.0.0.0:1514 (udp), charset=UTF-8 (override: 0), capacity=20000, rx_buf_size=0, receiver_cpu_id=-1, queue_count=1, buffer_file_path=./, buffer_file_size=10737418240, start from=2026-04-28 10:19:07, received=1
[logpresso] 0.0.0.0:514 (udp), charset=UTF-8 (override: 0), capacity=20000, rx_buf_size=0, receiver_cpu_id=-1, queue_count=1, buffer_file_path=./, buffer_file_size=10737418240, start from=2026-03-23 13:45:05, received=43

해결 방법

  • 원격 IP별로 클라이언트 인코딩을 지정하면 해당 IP에서 수신되는 패킷에 한해 지정된 인코딩으로 해석됩니다.

  • syslog.addCharsetMapping 명령어를 사용합니다.

명령어 사양

  • 인자 없이 명령어를 입력하면 아래와 같은 도움말 출력으로 사용법을 확인할 수 있습니다.

    • server name: 인코딩을 적용할 시스로그 바인딩(서버) 이름

    • ip: 인코딩을 다르게 해석할 송신 장비의 클라이언트 IP

    • charset: 적용할 문자셋(예: euc-kr, cp949)

    logpresso> syslog.addCharsetMapping
Description

add ip charset override

Arguments

1. server name: syslog server name (required)
2. ip: client ip address (required)
3. charset: syslog charset (required)

적용 예시

  • logpresso 라는 시스로그 바인딩에 대해, 100.100.100.100 에서 수신되는 패킷을 euc-kr 로 해석하도록 지정합니다.

    logpresso> syslog.addCharsetMapping logpresso 100.100.100.100 euc-kr

  • 명령 적용 후에는 즉시 반영되며 수집기 재시작은 필요하지 않습니다.

  • 동일한 바인딩에 대해 송신 IP가 여러 개라면 각 IP마다 위 명령을 반복 실행해 주시기 바랍니다.

확인

  1. syslog.charsetMappings [server name] 명령으로 해당 바인딩에 등록된 IP별 인코딩 매핑이 의도대로 들어갔는지 확인합니다.

       logpresso> syslog.charsetMappings logpresso
   Charset Mappings
   ------------------
   100.100.100.100 => EUC-KR