INTRO

SCOUTER PAPER 프로젝트는 오픈 소스 APM인 SCOUTER WEB API를 활용하여, 성능 데이터를 웹을 통해 확인할 수 있도록 제공하는 대시보드 소프트웨어입니다.
많은 사람들과 기업에서 사용하는 APM인 SCOUTER 클라이언트가 성능과 사용성면에서 매우 훌륭하지만, 플랫폼의 특성으로인한 접근성의 한계가 존재하여, 이를 보완하는 보조 도구의 역할로 사용될 수 있도록 하기 위해 다양한 디바이스에서 접근 가능한 형태의 웹 클라이언트를 만들어 배포하며 시작되었습니다.
PAPER 2.0 부터는 Telegraf 데이터를 지원하고 전체 시스템 성능 상황을 한눈에 파악할 수 있는 토폴로지 뷰를 탑재하면서, 어플리케이션과 인프라 소프트웨어를 아우르는 통합 모니터링 대시보드로 발전하고 있습니다.
SCOUTER PAPER는 아파치 라이선스 2.0을 따르는 오픈 소스 소프트웨어입니다. 해당 라이선스의 배포시 의무사항을 준수하는 방식으로 상업/비상업적인 용도로 자유롭게 사용, 수정 및 재배포가 가능합니다.

DOWNLOAD

INSTALL

SCOUTER PAPER는 일반적인 HTML을 사용하는 것과 동일하게 사용할 수 있습니다. 즉 별도의 설치가 필요 없으며, 로컬에서 웹 브라우저를 통해 접근하여 사용하거나, 웹 서버에 올려서 사용할 수 있습니다. 다만 SCOUTER PAPER를 사용하기 위해서는 SCOUTER APM 서버가 구성되어 있어야하므로, 이미 구성된 SCOUTER 서버를 활용하는 것이 가장 간편한 사용 방법이라고 할 수 있습니다. 아래와 같은 방법으로 간단하게 SCOUTER WEB API에 SCOUTER PAPER를 업로드하여 바로 사용할 수 있습니다.

scouter └ webapp └ conf └ extweb <-- 폴더 하위에 SCOUTER PAPER 파일을 복사합니다. └ lib └ logs

위와 같이 extweb 폴더에 SCOUTER PAPER 파일을 업로드하였다면, http://서버주소:6188/extweb 혹은 http://서버주소:6188/extweb/index.html로 접근하면 아래와 같이 SCOUTER PAPER를 사용할 수 있습니다. (포트 번호는 설정에 따라 달라질 수 있습니다.)

setting
<SCOUTER PAPER>

SETTING

SCOUTER PAPER는 SCOUTER 웹 API가 필수적으로 구성되어 있어야 합니다. 또한 SCOUTER PAPER의 접속과 인증 관련 옵션은 필연적으로 SCOUTER 웹 API 서버의 옵션에 맞도록 세팅되어야 올바르게 동작합니다. 따라서 SCOUTER 웹 API의 구성과 옵션에 관해 간략하게 함께 다룹니다. SCOUTER의 설치와 웹 API 서버를 구성하는 자세한 방법은 SCOUTER와 SCOUTER 웹 API 가이드를 확인해주세요.

지원하는 SCOUTER 버전

SCOUTER PAPER 1.X는 SCOUTER 1.8.4.1 이상의 버전이 필요하며, SCOUTER PAPER 2.X는 SCOUTER 2.0 이상의 버전이 필요합니다. 텔레그라프와의 연동으로 모니터링 영역이 대폭 넓어진 SCOUTER 2.0 이상을 사용하시는 것을 권장드립니다.

SCOUTER 웹 API 서버 활성화

설치된 SCOUTER가 1.8.0 이상의 버전이라면, SCOUTER 컬렉터 서버에 포함된 웹 API 서버를 아래 설정을 통하여 컬렉터 서버 구동시 함께 웹 API 서버를 활성화 할 수 있습니다. 만약 콜렉터 서버와 웹 API 서버를 분리하여 구성하고 싶다면, SCOUTER 배포 버전에 포함된 별도의 웹 API 서버를 통해 구성할 수 도 있습니다.

SCOUTER 컬렉터 서버에 포함된 웹 API를 활성화하기 위해서는 설정 파일에 아래 내용이 기본적으로 추가되어야 합니다.

conf/scouter.conf
net_http_server_enabled=true net_http_api_enabled=true net_http_port=6180

정상적으로 웹 API가 활성화되었는지, 웹 브라우저를 통해 HTTP 요청을 수행하여 확인할 수 있습니다. 아래 PORT는 위 설정의 net_http_port 번호를 입력해야 합니다.

웹 API 동작 여부 확인
http://{SERVER-ADDRESS}:{PORT}/scouter/v1/info/server

정상적으로 JSON 형식의 문자열이 수신된다면, 웹 API 서버에 접속할 수 있는 환경이 구성된 것입니다.

SCOUTER 웹 API 서버 인증 관련 설정

SCOUTER 웹 API 서버는 인증 관련 설정 방법에 따라 아래와 같은 인증 방법을 지원합니다. 아래 인증 방법은 꼭 하나만이 설정되는 것이 아니며, 설정의 특성에 따라 조합하여 설정될 수 있습니다. 아무런 설정을 하지 않았다면, 모든 HTTP 요청이 허용되는 상태로 열려있습니다. 방화벽 등으로 보호 받는 네트워크 환경이 아니라면, 하나 이상의 인증 설정을 하는 것을 권장합니다.

인증 옵션 내용 기타
별도의 설정 없음 모든 HTTP 요청을 허용
IP 기반 인증 설정된 IP의 요청만을 허용
ID / PASSWORD 기반 인증 인증된 사용자의 요청만을 허용 쿠키 또는 토큰(BEARER)

SCOUTER PAPER는 결국 SCOUTER 웹 API 서버에 HTTP 요청을 통해 성능 정보를 서버로부터 가져와서 화면에 보여주므로, 위 인증 방식에 따라 SETTINGS 페이지에 세팅을 해야 올바르게 인증을 처리하여 데이터를 수신할 수 있습니다. 아래 내용을 통해서 각 SCOUTER 웹 API의 인증 옵션과 해당 인증 옵션에 해당하는 SCOUTER PAPER 옵션을 확인할 수 있습니다.

SCOUTER 웹 API 서버 인증 관련 설정 (별도의 설정 없음)

별도의 인증 설정이 없는 경우, 모든 요청을 허용하므로, SCOUTER PAPER 또한 [SCOUTER PAPER > SETTINGS > AUTHENTIFICATION CONFIGURATION]에 어떤 값이 선택되어 있어도 정상적으로 데이터를 수신할 수 있습니다.

SCOUTER 웹 API 서버 인증 관련 설정 (IP 기반 인증)

conf/scouter.conf
... net_http_api_auth_ip_enabled=true net_http_api_allow_ips={IP-1},{IP-2} ...

IP 기반으로 인증을 하도록 설정하기 위해서는 위와 같이 설정 파일에 추가하고, 허용할 IP 목록을 net_http_api_allow_ips에 추가합니다. 즉, SCOUTER PAPER를 통해 접속할 사용자의 IP를 추가하여, 해당 IP 사용자만 SCOUTER PAPER를 통해 접속 할 수 있도록 설정 할 수 있습니다.

IP 기반으로 인증만 설정된 경우, SCOUTER PAPER는 [SCOUTER PAPER > SETTINGS > AUTHENTIFICATION CONFIGURATION]에 어떤 값이 선택되어 있어도 IP 목록에만 포함되어 있다면 정상적으로 데이터를 수신할 수 있습니다.

SCOUTER 웹 API 서버 인증 관련 설정 (ID / PASSWORD 기반 인증 + 쿠키)

conf/scouter.conf
... net_http_api_auth_session_enabled=true net_http_api_cors_allow_credentials=true ...

ID/PASSWORD 기반으로 사용자를 인증하고, 이 후 인증된 키 값을 송/수신하는 매커니즘에 따라 쿠키 방식과 토큰 방식으로 나눌 수 있습니다. 만약 쿠키 방식으로 인증 정보를 관리하기 위해서는 위와 같이 설정 내용을 추가합니다.

만약 SCOUTER PAPER를 SCOUTER 웹 API에 올려서 사용한다면, 즉 SAME ORIGIN에서 요청이 이루어지는 상황이라면, net_http_api_cors_allow_credentials는 설정에서 제외해도 상관없습니다.

쿠키를 인증 매커니즘으로 사용하는 경우, [SCOUTER PAPER > SETTINGS > AUTHENTIFICATION CONFIGURATION]에 반드시 cookie가 선택되어야 합니다.

SCOUTER 웹 API 서버 인증 관련 설정 (ID / PASSWORD 기반 인증 + 토큰)

conf/scouter.conf
... net_http_api_auth_bearer_token_enabled=true ...

ID/PASSWORD 기반으로 사용자를 인증하고, 인증 토큰을 요청 헤더를 통해 전송하는 방식으로 인증을 하려면 위와 같이 설정 내용을 추가합니다.

토큰 방식을 인증 매커니즘으로 사용하는 경우, [SCOUTER PAPER > SETTINGS > AUTHENTIFICATION CONFIGURATION]에 반드시 token(bearer)가 선택되어야 합니다.

Telegraf 연동

SCOUTER의 Collector가 Telegraf Server 역할을 할 수 있게 되었으며 Telegraf inputs를 통해 수집된 성능 정보는 PAPER를 통해 모니터링 할 수 있습니다.

Telegraf를 연동하기 위해서는 SCOUTER 2.0 이상을 사용하여야 하며, 상세한 설정은 SCOUTER의 도움말을 참고하시기 바랍니다.

SCOUTER Telegraf Server feature 바로가기

SCOUTER PAPAER SETTINGS

SCOUTER PAPER는 상단의 SETTINGS 메뉴를 통해서 설정 정보를 관리할 수 있습니다. 단 설정 정보는 브라우저 스토리지를 통해 관리되므로, 접속 환경이나 브라우저가 변경되는 경우 설정 정보가 유지되지 않습니다.

setting
<SETTINGS>

SCOUTER WEB API SERVER INFO

'PAPER'에서 접속할 SCOUTER 웹 API 서버 정보를 등록합니다. 등록된 서버 정보를 OBJECT 선택 팝업 상단에서 콤보 박스로 출력되며, 서버를 바꾸면서 여러 SCOUTER 서버의 성능 데이터를 모니터링 할 수 있습니다.

POLLING & RANGE

SCOUTER PAPER가 실시간 데이터를 조회하는 간격, ALERT 데이터를 조회하는 간격, 과거 데이터 조회 구간을 설정할 수 있습니다. SHORT HISTORY / LONG HISTORY로 나눌 수 있으며, 각 구간에서 최대 조회 가능 범위와 시간 범위 선택 컨트롤의 단위를 설정 할 수 있습니다. SHORT HISTORY / LONG HISTORY 구간의 차이점은 매트릭 데이터의 다운 샘플링 기준이 달라지며, XLOG와 같은 대량의 RAW 데이터를 가지는 성능 매트릭은 LONG HISTORY 구간에서는 조회되지 않는 차이점이 있습니다.

ALERT

새로운 ALERT 정보를 수신한 경우, 브라우저 알림을 통해 ALERT을 출력할지를 선택할 수 있습니다.

GRAPH

라인 그래프 관련 설정을 할 수 있습니다. 라인 그래프의 색상 인스턴스별로 구분할지, 매트릭 별로 구분할지 선택할 수 있으며, 라인 그래프를 표현하는 선의 굴기, 곡선 함수, 채움 여부 등을 설정 할 수 있습니다.

THEME

'PAPER'의 테마를 선택할 수 있습니다.

FONTS CONFIGURATION

'PAPER'의 각 구성 요소들의 폰트를 설정 할 수 있습니다.

DATA FORMAT CONFIGURATION

SCOUTER에서 표현되는 날짜와 숫자의 표현 형식을 설정합니다.

숫자 형식에 입력 가능한 값은 http://numeraljs.com/ 페이지를 참고하시기 바랍니다.

날짜 형식에 입력 가능한 값은 https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md 페이지를 참고하시기 바랍니다.

XLOG CONFIGURATION

XLOG 차트에 그려지는 XLOG의 샘플링 값과 모양을 설정합니다. XLOG는 종류에 따라서 NORMAL, ASYNC, ERROR로 구분됩니다. 일반적으로 서블릿 기반의 WAS를 모니터링 한다면, 일반적인 HTTP 요청을 NORMAL XLOG, 비동기 방식으로 처리되는 경우 ASYNC XLOG, 요청 처리 중 에러가 발생한 경우 ERROR XLOG로 그려지게 됩니다. 3가지 유형의 XLOG의 크기 및 색상과 점들의 배치를 통해 그려지는 모양을 설정할 수 있습니다.

데이터의 양이 많을 경우에는 XLOG 차트를 그리는 속도가 늦어질 수 있는데, 이러한 경우 SAMPLING 옵션을 조절하는 것도 고려할 수 있습니다. 기본적으로 100%는 모든 데이터를 XLOG 차트에 그리며, 50%로 설정한 경우 수신된 XLOG 데이터 중에서 50%만 차트에 그리게 됩니다.

GUIDE

SCOUTER PAPER를 이용하여 모니터링 대상을 선택하고, 레이아웃을 구성하는 방법에 대해 설명하며, 전체적인 기능에 대해 함께 소개합니다.

setting

로그인

[SETTINGS > AUTHENTIFICATION TYPE]이 none이 아닐 경우, 우측 상단에 LOGIN 메뉴가 활성화됩니다. 사용자 ID와 PASSWORD를 입력하여 SCOUTER 웹 API에 로그인합니다.

setting

모니터링 대상 선택

모니터링을 시작하기 위해서는 먼저 성능 정보를 확인할 인스턴스를 선택해야 합니다. 우측 상단의 [OBJECTS] 버튼을 클릭하면, 인스턴스 선택을 위한 팝업이 출력됩니다. 해당 팝업 상단에 SETTINGS에 추가했던 SCOUTER 서버 콤보 박스가 있으며, 해당 콤보 박스를 변경할때마다, 해당 SCOUTER 서버에 등록된 모니터링 대상이 변경됩니다.

팝업에서 좌측의 SERVER를 클릭하여 선택하면, 해당 서버에 포함된 인스턴스 목록이 출력됩니다. 인스턴스 명칭으로 필터링하거나, 목록을 클릭을 통해 토글(toggle)하여 모니터링을 시작할 대상을 선택할 수 있습니다. 선택을 모두 완료한 후 APPLY 버튼을 클릭하여 선택을 완료합니다. 또한 자주 사용하는 모니터링 대상들이거나, 용도따라 구분된 모니터링 목록들을 그룹으로 관리하고 싶은 경우, 우측 하단의 [SAVE AS PRESET] 버튼을 클릭하여, 현재 선택된 대상 정보를 저장할 수 있습니다.

setting

PRESET 관리

현재 선택한 모니터링 대상을 자주 사용하는 경우, 이를 PRESET으로 저장하여, 관리할 수 있습니다. [OBJECTS] [우측의 화살표 버튼]을 클릭하여, PRESET을 불러오거나, 삭제할 수 있습니다.

setting

PAPERS

모니터링 대상이 선택되면 성능을 모니터링하는 주요 화면인 PAPER로 이동합니다. 상단 컨트롤 부분을 이용하여, 화면의 중앙 영역에 모니터링 관련 대시보드를 구성합니다. 가운데 빈 영역에 PAPER를 추가하고, PAPER에 모니터링하고자하는 매트릭을 드래그 & 드랍하여 모니터링을 모니터링 차트를 구성할 수 있습니다.

setting

PAPER CONTROLS

상단의 컨트롤 영역을 통해 레이아웃을 구성하고, 과거 데이터를 조회할 수 있습니다. 먼저 좌측의 R 버튼의 경우, 현재의 성능 데이터를 주기적으로 가져올지, 혹은 과거 데이터를 조회할지를 선택하는 버튼입니다.

R 버튼 우측의 + 버튼을 클릭하면 화면에 빈 PAPER가 추가됩니다. PAPER는 레이아웃을 관리하는 컴포넌트이며, PAPER에는 매트릭을 드래그해야 모니터링 데이터가 출력되는 하나의 대시보드 구성요소를 만들 수 있습니다.

METRICS 우측의 컨트롤들이 PAPER에 드랍 가능한 하나의 성능 매트릭을 의미합니다. 모니터링할 매트릭을 PAPER에 드래그 & 드롭하면, 드롭한 PAPER 영역에 드랍한 매트릭의 성능 데이터가 그래프로 출력됩니다.

가장 우측의 휴지통 모양의 아이콘을 클릭하면, 화면의 모든 PAPER를 삭제하여 초기화합니다.

화면에 추가된 PAPER는 우측 상단에 설정 버튼과 닫기 버튼을 가지고 있습니다. 각 매트릭별로 추가적인 옵션이 있는 경우, 설정 버튼을 클릭하여 옵션을 변경할 수 있습니다. 닫기 버튼은 해당 PAPER를 화면에서 삭제합니다.

화면에 추가된 PAPER의 우측 하단에 마우스를 올리면, PAPER의 크기를 자유롭게 조절할 수 있습니다. PAPER의 크기는 화면 해상도에 따라 4단계로 구분되어 적용됩니다. 각 해상도별로 적용된 크기는 로컬 스토리지에 기록되어, 각 해상도로 다시 변경되었을때 적용된 크기와 레이아웃으로 자동으로 적용됩니다. 또한 PAPER를 드래그하여 위치를 이동할 수 있습니다.

setting

매트릭 종류

각 매트릭은 단독으로 표현 가능한 매트릭과 중첩 가능한 매트릭으로 나눌 수 있습니다. 좌측 첫번째 붉은 영역이 단독으로만 표현 가능한 매트릭이며, 우측의 노란 영역의 중첩 가능한 매트릭을 의미합니다. 중첩 가능한 매트릭들은 하나의 PAPER에 여러 매트릭을 중첩하여, 데이터를 함께 모니터링 할 수 있습니다.

단독 매트릭과 중첩 가능 매트릭은 상호 배타적인 성격을 가지고 있습니다. 즉, 단독 매트릭이 있는 PAPER에 중첩 가능 매트릭을 드랍하는 경우, 기존의 매트릭이 사라지고 중첩 가능한 매트릭이 표시됩니다.

setting

METRIC OPTION

각 매트릭 별로 추가적으로 제공하는 옵션들이 있는 경우, PAPER 우측 상단의 설정 버튼을 클릭하여, 옵션을 조절할 수 있습니다.

setting

레이아웃 관리

PAPER와 METRIC이 결합된 정보와 PAPER의 크기와 위치 정보 전체 레이아웃이라고 정의합니다. 이러한 레이아웃 정보를 우측 상단의 LAYOUT 버튼을 클릭하여, 관리할 수 있습니다. 기본적으로 제공되는 레이아웃 샘플이 있으며, 하단의 버튼을 이용하여 레이아웃 저장하고, 삭제하고, 저장된 레이아웃을 불러 올 수 있습니다.

모니터링 대상에 따라서 구성해야 차트가 다르거나, 상황에 따라서 봐야하는 대시보드가 다른 경우, 레이아웃 관리를 통해 쉽게 저장하고, 불러 올 수 있습니다.

setting

모니터링 및 XLOG 선택

XLOG 차트는 트랜잭션을 하나의 점프로 표현하는 XLOG 차트를 제공합니다. 이러한 XLOG 대시보드를 활용하여, 트랜잭션이 처리되는 패턴, 에러 발생 여부, 현재 트랜잭션의 처리 상태 등을 직관적으로 파악할 수 있습니다.

또한 그래프의 패턴 중 보다 세밀하게 프로파일을 확인해야 하는 영역을 드래그 트랜잭션의 상세한 프로파일 데이터를 확인할 수 있습니다.

setting

XLOG 필터링

트랜잭션의 처리 시간, 에러 발생 여부, 트랜잭션 ID, URL 등 다양한 조건을 통해서 XLOG 차트를 필터링 할 수 있습니다. 필터링 중인지의 여부는 필터링되어 있는 경우에는 차트 우측 상단에 필터링 버튼을 통해 확인 할 수 있습니다.

setting

프로파일 조회

팝업을 통해 드래그로 선택된 영역의 XLOG가 목록으로 나타납니다. 목록에서 하나의 XLOG를 선택하면, 선택된 XLOG의 상세 프로파일이 오른쪽 영역에 나타납니다. 프로파일의 상단의 컨트롤을 통해서 프로파일 관련 옵션을 조절하면서 프로파일을 확인할 수 있습니다.

setting

ALERT 확인

새로운 ALERT이 발생하며, 우측 상단이 경고 알림 부분에 배지로 ALERT이 수신되었음을 알립니다. ALERT 아이콘을 클릭하여, 발생한 ALERT 정보를 확인 할 수 있으며, 목록의 시계 모양을 클릭하면, 해당 ALERT이 발생한 과거 시각의 데이터를 바로 조회합니다.

setting

과거 데이터 조회

현재 데이터를 실시간으로 확인하거나, 과거 데이터를 조회 할 수 있습니다. 과거 데이터 조회 범위는 먼저 조회 범위의 시작 일시를 입력하고, 시작 시점부터 얼마간의 시간을 조회할지 범위를 선택하는 방식으로 구성되어있습니다.

어플리케이션 간의 평균 응답 시간, TPS, 에러 발생율 정보와 함께, 연결 선의 애니메이션과 색상을 통해 데이터의 흐름과 에러 발생 여부를 쉽게 파악 할 수 있습니다.

setting

토폴로지

현재 선택된 인스턴스들을 논리적 집합으로 모아서, 네트워크 그래프 형태로 사용자의 어플리케이션간의 연결 관계 및 처리 요약 정보, 외부 시스템간의 연결 관계 등을 직관적으로 파악할 수 있습니다.

PAPER에서 토폴로지 뷰를 사용하기 위해서는 SCOUTER 2.0 이상을 사용하여야 하며 java agent의 counter_interaction_enabled 옵션이 true 로 설정되어야 합니다.