INTRO

오픈 소스 소프트웨어

스카우터 페이퍼는 아파치 라이선스 2.0을 따르는 오픈 소스 소프트웨어입니다. 해당 라이선스의 배포시 의무사항을 준수하는 방식으로 상업/비상업적인 용도로 자유롭게 사용, 수정 및 재배포가 가능합니다.

반응형 웹

스카우터 페이퍼는 오픈소스 성능 모니터링 도구인 스카우터의 성능 데이터를 웹 브라우저를 통해 모니터링 하기 위한 웹 클라이언트 프로그램입니다. 스카우터 페이퍼를 통해 언제, 어디에서든 다양한 디바이스를 통해 스카우터의 성능 정보를 쉽게 확인할 수 있습니다. 스카우터 페이퍼는 반응형 웹 방식으로 제작되어, 모바일, 태블릿, PC 등의 다양한 디바이스를 통해 접속이 가능합니다.

setting

사용자 정의 차트

스카우터 페이퍼는 스카우터에서 제공하는 다양한 성능 매트릭을 조합하여, 어플리케이션과 사용자의 특성에 따른 최적화된 성능 정보를 하나의 그래프를 통해 확인할 수 있습니다. 이를 통해 다양한 매트릭의 상호 연관성을 쉽게 파악할 수 있습니다. 또한 어플리케이션의 특성에 따라 필요한 그래프 조합을 구성하여, 어플리케이션에 따른 최적화된 성능 대시보드의 구성이 가능합니다.

최적화된 레이아웃의 구성

스카우터 페이퍼는 화면 해상도(>1200, 1200, 1000, 800)에 따라 총 4단계의 레이아웃을 구성할 수 있습니다. 각각의 해상도에 사용자가 최적의 레이아웃을 설정할 수 있으며, 이렇게 설정된 정보는 클라이언트 스토리지에 저장되어 유지되며, 해상도가 변경되는 것에 따라 설정된 레이아웃이 즉시 반영됩니다. 또한 레이아웃 관리 기능을 통해서 사용자가 정의한 레이아웃과 차트를 저장하고, 관리하여 다양한 레이아웃을 쉽게 사용할 수 있습니다.

다양한 사용자 설정 기능

스카우터 서버의 인증 설정에 따르는 인증 방법을 비롯하여, 폰트, 성능 데이터 폴링(polling) 주기, 날짜와 숫자 등의 포멧, XLOG의 점 그래픽 등을 설정하여 사용자 환경에 맞는 클라이언트 환경을 구성할 수 있습니다.

이슈 등록

사용하면서 발생하는 이슈는 아래 URL을 통해서 등록해주세요. 수정 및 기능 개선 Contribution은 언제나 환영입니다.

https://github.com/mindplates/scouter-paper/issues

BUILD

스카우터 페이퍼 다운로드

스카우터 페이퍼의 최신 버전은 아래 URL을 통해 다운로드 할 수 있습니다. 스카우터 페이퍼는 별도의 설치가 필요 없이 압축을 해제하여 바로 사용할 수 있습니다.

https://github.com/mindplates/scouter-paper/releases

스카우터 페이퍼 빌드

스카우터 페이퍼는 리액트 기반으로 만들어졌으며, CREATE REACT APP을 이용하여 환경을 구성하였습니다. 소스 코드를 다운로드 받은 후 일반적으로 아래와 같이 간단하게 빌드할 수 있습니다. 빌드를 위해 NPM이 설치되어 있어야 합니다. 빌드 파일은 프로젝트 build 폴더에 생성됩니다.

아래 URL 혹은 Clone한 프로젝트를 체크아웃합니다
https://github.com/mindplates/scouter-paper.git
의존성 패키지를 설치합니다.
npm install
실행 파일을 생성합니다.
npm run build

INSTALL

스카우터 페이퍼는 별도의 설치가 필요 없이 웹 브라우저를 통해 index.html을 실행하는 것으로 바로 사용할 수 있습니다. 다만 이렇게 접속할 경우, 해당 파일을 원격에서 접속 할 수 없기 때문에, 편리하게 사용하기 위해서는 웹 서버에 파일을 업로드하여 사용하는 것을 추천합니다. 사용하는 어떤 웹 서버에라도 올려서 쉽게 구성할 수 있지만, 스카우터 페이퍼는 결국 스카우터 웹 API에 종속적인 웹 클라이언트 프로그램이며, 스카우터 웹 API과 연동하여 호출되므로, 가장 이상적인 상황은 스카우터 웹 API 서버에 함께 배포하는 것이 CORS 문제 등을 쉽게 회피할 수 있는 가장 손쉬운 방법입니다.

BUILD 단계에서 다운로드하거나 생성된 실행 파일을 스카우터 프로젝트의 scouter.webapp 서브 프로젝트 하위의 scouter.webapp/src/main/resources/webroot 하위에 복사한 후 스카우터 프로젝트를 빌드합니다. 이 후 빌드된 스카우터 웹 API 서버를 실행하면, 바로 스카우터 페이퍼에 접속하여 사용할 수 있습니다.

scouter └ scouter.webapp └ conf └ extweb └ scripts └ src └ main └ java └ resources └ scouter └ webroot └ check.html └ asset-manifest.json └ favicon.ico └ help └ index.html └ manifest.json └ service-worker.js

SETTING

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

지원하는 스카우터 버전

스카우터 1.8.0 버전 이상부터 스카우터 웹 API가 추가되었으나, 스카우터 페이퍼는 스카우터 1.8.4.1 버전의 API를 이용하여 만들어졌습니다. 최소 1.8.4.1 이상의 버전을 사용하는 것을 권장합니다.

스카우터 웹 API 서버 활성화

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

스카우터 컬렉터 서버에 포함된 웹 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 서버에 접속할 수 있는 환경이 구성된 것입니다.

스카우터 웹 API 서버 인증 관련 설정

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

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

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

스카우터 웹 API 서버 인증 관련 설정 (별도의 설정 없음)

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

스카우터 웹 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에 추가합니다. 즉, 스카우터 페이퍼를 통해 접속할 사용자의 IP를 추가하여, 해당 IP 사용자만 스카우터 페이퍼를 통해 접속 할 수 있도록 설정 할 수 있습니다.

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

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

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

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

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

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

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

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

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

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

SCOUTER PAPAER SETTINGS

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

setting
<SETTINGS>

SCOUTER SERVER INFO

스카우터 웹 API 서버와의 통신을 위한 정보를 설정합니다. 설정 정보 중 AUTHENTIFICAITON TYPE은 '스카우터 웹 API 서버 인증 관련 설정' 부분을 확인해주세요.

POLLING INTERVAL

스카우터 페이퍼는 폴링(POLLING) 방식으로 스카우터 웹 API 서버로부터 성능 데이터를 조회합니다. INTERVAL 값을 통해서 폴링 주기를 설정할 수 있습니다. 서버의 상황에 따라서 폴링 주기보다 데이터를 표현하는 시간이 많이 걸리는 경우가 있는데, 이러한 현상을 개선하기 위한 방법 중 하나로 폴링 주기를 변경하는 것을 고려할 수 있습니다.

FONTS CONFIGURATION

스카우터 페이퍼의 각 구성 요소들의 폰트를 설정 할 수 있습니다.

DATA FORMAT CONFIGURATION

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

숫자 형식에 입력 가능한 값은 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%만 차트에 그리게 됩니다.

QUICK GUIDE

스카우터 페이퍼를 이용하여 모니터링을 시작하는 방법에 대해 설명합니다.

setting

로그인

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

setting

모니터링 대상 선택

모니터링을 시작하기 위해서는 먼저 성능 정보를 확인할 인스턴스를 선택해야 합니다. 우측 상단의 [INSTANCE] 버튼을 클릭하면, 인스턴스 선택을 위한 팝업이 출력됩니다. 해당 팝업에서 좌측의 SERVER를 클릭하여 선택하면, 해당 서버에 포함된 인스턴스 목록이 출력됩니다. 인스턴스 목록을 클릭을 통해 토글(toggle)하여 모니터링 인스턴스를 선택할 수 있습니다. 선택을 모두 완료한 후 APPLY 버튼을 클릭하여 선택을 완료합니다.

setting

PAPERS

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

setting

PAPER CONTROLS

상단의 컨트롤 영역을 통해 레이아웃을 구성할 수 있습니다. 먼저 가장 좌측의 + 버튼을 클릭하면 화면에 빈 PAPER가 생성됩니다. PAPER에는 매트릭을 드래그해야 모니터링 데이터가 출력됩니다.

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

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

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

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

PAPER의 아무곳을 클릭하여 움직이면, PAPER의 위치를 변경할 수 있습니다.

setting

METRIC OPTION

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

setting

매트릭 종류

각 매트릭은 단독으로 표현 가능한 매트릭과 중첩 가능한 매트릭으로 나눌 수 있습니다. 좌측 첫번째 붉은 영역이 단독으로 표현 가능한 영역이며, 우측의 영문으로 제공되는 컨트롤들은 중첩 가능한 매트릭을 의미합니다. 중첩 가능한 매트릭은 하나의 PAPER에 여러 매트릭이 추가될 수 있습니다.

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

setting

레이아웃 관리

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

setting

모니터링 및 XLOG 선택

구성된 레이아웃으로 모니터링 정보를 확인 할 수 있습니다. 이 중 XLOG의 상세 프로파일을 조회하기 위해서는 XLOG 차트에서 조회하고자하는 영역을 드래그하여 선택합니다.

setting

프로파일 조회

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