JAVA APM Scouter 활용 - 3부 스카우터 얼럿 플러그인 커스터마이징

1부 APM 선정과 스카우터의 지표소개

2부 스카우터 기능 활용 및 페이퍼 플러그인

3부 스카우터 얼럿 플러그인 커스터마이징

스카우터에서는 성능 모니터링 중 생긴 특정 상황에 대해 얼럿 기능이 들어가 있다.

스카우터 클라이언트의 얼럿항목에서 확인 및 조회가 가능하다.

하지만 항상 보고 있을수는 없는 상황에서, 얼럿을 스카우터 외부에서 받기를 원한다면 어떻게 해야 할까.

스카우터의 커스텀 플러그인으로 해결이 가능하다.

이런 상황에 맞추어 사용자가 직접 플러그인을 개발해서 넣을수 있도록 내부 API를 가지고 있고, 

이를 활용할 수 있는 커스텀 플러그인 구조를 가지고 있다.

우선 스카우터의 플러그인에 대해 알아보도록 하겠다.

스카우터의 플러그인

스카우터의 서버 플러그인은 크게 2가지 종류이다.

스크립트 형식으로 된 스크립팅 플러그인과 java의 jar 파일 형식으로 된 빌트인 플러그인이다.

스크립팅 플러그인은 파일에 java 문법으로 이루어진 스크립트를 넣어서 적용할 수 있다.

빌트인 플러그인의 경우 jar 파일로 이루어진 자바 프로젝트이다.

정해진 형식에 맞게 프로젝트를 만들고 내부 로직은 자유롭게 개발해서 사용할 수 있다.

이번 글에서는 2가지 방식 중 빌트인 플러그인 방식에 대해서 알아보려고 한다.

2가지 방식의 스카우터 플러그인 외에 에이전트에 적용하는 플러그인도 있다. 더 자세한 정보는 아래 링크에서 확인 가능하다.

https://github.com/scouter-project/scouter/blob/master/scouter.document/main/Plugin-Guide_kr.md

처음 접하는 입장에서 플러그인을 처음부터 만드는것은 쉽지 않다.

그래서 스카우터를 사용하는 능력자들께서 손수 만드신 플러그인들을 공유하고 있다.

https://github.com/scouter-project 이곳에서 scouter-plugin 으로 시작하는 프로젝트 들이다.

확인해보고 필요한 것이 있다면 학습해보는 것도 좋을것이다.

빌트인 플러그인 적용방법

1. 플러그인 프로젝트를 jar 파일로 만든다(빌드 방법은 아래에서 다룬다.)
2. ./server/lib 폴더 아래에 jar 파일을 넣어준다.
3. 스카우터 수집기 서버를 재기동 한다. (./server.startup.sh)

얼럿 플러그인

얼럿을 외부로 보내기 위한 플러그인은 매체에 따라 구분된다. email, slack, line, telegram, teamup(?) 등이 있다.

매체가 다른 플러그인이지만, 대부분 로직은 비슷하고 발송 단계의 로직만 다르기 때문에 원하는 발송 매체가 있다면 커스터마이징도 가능하다.

이번 글에서는 다양한 발송 매체 중에 슬랙을 이용하는 플러그인을 가지고 설명하려고 한다.

해당 플러그인의 깃헙 주소는 아래와 같다.

https://github.com/scouter-project/scouter-plugin-server-alert-slack

이 얼럿 플러그인으로 받을수 있는 알림은 아래와 같다.

• CPU of Agent (warning / fatal)
• Memory of Agent (warning / fatal)
• Disk of Agent (warning / fatal)
• connected new Agent
• disconnected Agent
• reconnect Agent

얼럿 플러그인 적용하기

1.  플러그인 빌드

적용하기 위해서는 얼럿 플러그인 프로젝트의 jar 파일이 필요하다.

클론을 받고, jar 파일로 빌드하자(macos 기준..)

git clone https://github.com/scouter-project/scouter-plugin-server-alert-slack.git
cd scouter-plugin-server-alert-slack/
mvn package

문제없이 빌드가 완료되었다면,

target 디렉토리에 scouter-plugin-server-alert-slack-1.0.1-SNAPSHOT.jar 라는 파일이 생성되어 있을 것이다.

이 파일을 스카우터 수집기 서버 디렉토리 아래 lib 폴더에 복사한다. (스카우터를 설치한 디렉토리에서 ./server/lib 이다)

2. 플러그인 설정

스카우터 수집기 서버의 설정 파일을 수정해야 한다.

별도의 변경이 없다면 경로는 아래와 같다.

./server/conf/scouter.conf

얼럿 플러그인을 사용하기 위해 필요한 설정값은 아래와 같다.

내용을 참고해서 환경에 맞게 내용을 추가해 준다.

ext_plugin_slack_send_alert : 발송기능을 사용할지 여부. true/false

ext_plugin_slack_debug : 메시지를 로깅 할지 여부. true/false

ext_plugin_slack_level : 로깅 레벨. (0=info, 1=warn, 2=error, 3=fatal)

ext_plugin_slack_webhook_url : 슬랙 웹훅 url

ext_plugin_slack_channel : 채널명 (ex. #test1) 혹은 사용자명(ex. @user_id)

ext_plugin_slack_botName : 알림을 보낼 봇 이름

ext_plugin_slack_icon_emoji : 봇 아이콘

ext_plugin_slack_xlog_enabled : xlog 얼럿 활성화 여부 true/false

ext_plugin_elapsed_time_threshold : 응답시간의 임계치. 이 값 보다 큰 응답시간에 반응한다

ext_plugin_gc_time_threshold : gc 시간 임계치. 이 값보다 큰 gc 시간이 걸리면 반응한다

ext_plugin_thread_count_threshold : 쓰레드 갯수 임계치. 쓰레드 갯수가 임계치 보다 커지면 반응한다.

적용해 사용하고 있는 설정은 아래와 같다.

# External Interface (Slack)
ext_plugin_slack_send_alert=true
ext_plugin_slack_debug=true
ext_plugin_slack_level=0
ext_plugin_slack_webhook_url=http://mydonain.com/hooks/1234CCSReKgN23wiw/dtCGozaNPAA41234yiCnhnpcNQCA7BSrkjqmFmsy3nMuKk95
ext_plugin_slack_channel=#alert_channel
ext_plugin_slack_botName=scouter
ext_plugin_slack_icon_emoji=:computer:
ext_plugin_slack_icon_url=https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQnQFLCYQ-rg_iJFXBzazZjUqMXTHPmTQ-AVU_JymsxleUHI1Oe
ext_plugin_slack_xlog_enabled=true
ext_plugin_elapsed_time_threshold=3000
ext_plugin_gc_time_threshold=5000
ext_plugin_thread_count_threshold=300

3. 적용하기

서버를 재기동 하면 적용된다.

./server/startup.sh

플러그인 커스터마이징

얼럿 플러그인을 사용하면서, 기능상 변경이 필요한 상황이 종종 찾아왔다.

예를들어,

스카우터에서 모니터링 하고 있는 서비스 중, 일부 서비스의 요청은 기본 응답시간이 1분이 넘어갈 정도로 오래 걸리게 만들어져 있었다.

응답시간 임계치 보다 크다보니 이 요청이 호출 될 때마다 응답시간 초과로 얼럿이 오게 되었다.

스카우터 전체 응답시간 임계치를 늘리면 기존에 10ms 이내로 처리되는 요청들의 응답이 느려질 때 얼럿을 받지 못하게 되어서 문제가 되었다.

이런식으로 얼럿 조건이 특수한 상황에 맞게 설정 되어야 할 때, 소스를 직접 수정하여 해결 할 수 있다.

대부분의 로직은 SlackPlugin.java 에 있다.

https://github.com/scouter-project/scouter-plugin-server-alert-slack/blob/master/src/main/java/scouter/plugin/server/alert/slack/SlackPlugin.java

이 클래스의 메소드는 아래와 같은 용도를 가진다.

• alert : 얼럿 발송
• object : 에이전트 연결/연결끊김/재연결 얼럿 처리
• xlog : xlog 에 에러로 표시된 건에 대한 얼럿 처리
• counter : gc 타임 임계치 값에 대한 얼럿 처리

나의 경우 xlog 에서 응답시간 임계 초과 때 오는 얼럿을 서비스 마다 따로 설정하고 싶었다.

xlog 메소드 쪽에  분기를 추가해서 처리했다. 로직을 만들 때 사용한 내용은 아래와 같다.

• elapsedThreshold 변수에는 아까 설정한 ext_plugin_elapsed_time_threshold 값이 들어있다. 기본 3초이다.
• XlogPack 객체로 이루어진 pack 변수에는 xlog의 각 요청을 정보가 들어있다.
• pack 변수에는 http 요청에 대한 엔드포인트 URL 정보와  지연된 응답시간 정보가 있다.

기존 코드의 264라인 근처에 수정을 하였다.

아래는 특정 엔드포인트에 대해서만 지연 응답시간 기준을 60초로 설정하는  분기를 추가한 코드이다.

try {
      int elapsedThreshold = conf.getInt("ext_plugin_elapsed_time_threshold", 0);
      if (elapsedThreshold != 0 && pack.elapsed > elapsedThreshold) {
         String serviceName = TextRD.getString(DateUtil.yyyymmdd(pack.endTime), TextTypes.SERVICE, pack.service);
         if (
                 AgentManager.getAgentName(pack.objHash).equals("/192.168.123.111/endpoint1")
                 || AgentManager.getAgentName(pack.objHash).equals("/192.168.123.111/endpoint2")
               && pack.elapsed < 60000) {
           //얼럿을 보내지 않음.
         } else {
            AlertPack ap = new AlertPack();
            ap.level = AlertLevel.WARN;
            ap.objHash = pack.objHash;
            ap.title = "Elapsed time exceed a threshold.";
            ap.message = "[" + AgentManager.getAgentName(pack.objHash) + "] "
                  + pack.service + "(" + serviceName + ") "
                  + "elapsed time(" + pack.elapsed + " ms) exceed a threshold.";
            ap.time = System.currentTimeMillis();
            ap.objType = AgentManager.getAgent(pack.objHash).objType;
            alert(ap);
         }
      }

수정을 마치게 되면 위에 설명한 방식으로 빌드를 다시 하고,

스카우터 수집기 서버 lib 폴더에 jar 파일을 덮어쓴 뒤 재기동 하면 바로 적용이 된다.

스카우터에서는 플러그인 개발을 위해 내부 API를 잘 정리하여 공유하고 있다.

https://github.com/scouter-project/scouter/blob/master/scouter.document/main/JavaAgent-Plugin-Scripting_kr.md

자신만의 로직이 필요한 상황이라면 내부 API 문서를 참고하여 기존의 플러그인에 수정을 해서 필요에 맞게 사용할 수 있다.

혹은 새로운 플러그인을 새로 만들 수 있을것이다. 결과가 좋다면 커뮤니티에 공유해서 좋은 피드백도 받을 수도 있지 않을까 한다.