Skip to content

Commit e511197

Browse files
gunlee01gunlee01
committed
documentation
1 parent 5d8ae36 commit e511197

File tree

4 files changed

+300
-5
lines changed

4 files changed

+300
-5
lines changed

‎scouter.document/main/Setup.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
# Setup
22
![English](https://img.shields.io/badge/language-English-orange.svg) [![Korean](https://img.shields.io/badge/language-Korean-blue.svg)](Setup_kr.md)
33

4-
Scouter do not require any installation except java.
4+
- Outgoing Links
5+
- Blogging
6+
- [Scouter series #1 - Installation](https://translate.google.co.kr/translate?hl=ko&sl=ko&tl=en&u=https%3A%2F%2Fgunsdevlog.blogspot.kr%2F2017%2F07%2Fscouter-apm-1.html)
57

68
***
79

@@ -12,7 +14,7 @@ Scouter do not require any installation except java.
1214
* JDK 1.8+ (scouter web api)
1315

1416
### 1.2. Collector Server Installation
15-
1. download lateset version of scouter-yyyyMMdd.tar.gz.
17+
1. download the latest version of scouter-yyyyMMdd.tar.gz.
1618
- [Release Page](https://github.com/scouter-project/scouter/releases)
1719
2. Extract the file.(You can see the dircetory ./scouter/server)
1820
3. execute start script.
@@ -78,6 +80,8 @@ cd ./scouter/agent.host
7880

7981
All options and default values are available from the scouter client's **Host > Configure** menu.
8082
83+
***
84+
8185
## 3. Tomcat Agent
8286
### 3.1. Prerequisite
8387
* JDK 1.5+(Required), 1.6+(Recommended)
@@ -115,7 +119,7 @@ net_collector_tcp_port=6100
115119
# Scouter Name(Default : tomcat1)
116120
obj_name=myFirstTomcat1
117121
```
118-
All options and default values are available from the scuoter client's **Object > Configure** menu.
122+
All options and default values are available from the scouter client's **Object > Configure** menu.
119123

120124
***
121125

@@ -132,3 +136,9 @@ All options and default values are available from the scuoter client's **Object
132136
5. Fill the authentication info(default : admin/admin) and press OK button
133137
(First, the scouter server must be running.)
134138
6. The real-time chart will be shown.
139+
140+
***
141+
142+
## 5. Web API (설치 및 설정)
143+
144+
* [Web API Guide](../tech/Web-API-Guide.md)

‎scouter.document/main/Setup_kr.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
# Setup
22
[![English](https://img.shields.io/badge/language-English-orange.svg)](Setup.md) ![Korean](https://img.shields.io/badge/language-Korean-blue.svg)
33

4+
- 외부 링크
5+
- 블로그
6+
- [Scouter 소소한 시리즈 #1 - 설치](http://gunsdevlog.blogspot.kr/2017/07/scouter-apm-1.html)
7+
48
***
59

610
## 1. Collector Server 설치
@@ -74,6 +78,8 @@ cd ./scouter/agent.host
7478
```
7579
전체 옵션 및 default 값은 scouter client의 Host > Configure 메뉴에서 확인이 가능하다.
7680
81+
***
82+
7783
## 3. Tomcat Agent
7884
### 3.1. Prerequisite
7985
* JDK 1.5+(Required), 1.6+(Recommended)
@@ -127,3 +133,9 @@ obj_name=myFirstTomcat1
127133
5. Fill the authentication info(default : admin/admin) and press OK button
128134
(먼저 scouter server가 실행되어 있어야 함.)
129135
6. The real-time chart will be shown.
136+
137+
***
138+
139+
## 5. Web API (Installation and usage)
140+
141+
* [Web API Guide](../tech/Web-API-Guide_kr.md)

‎scouter.document/tech/Web-API-Guide.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# Scouter Web API Guide
22
![English](https://img.shields.io/badge/language-English-orange.svg) [![Korean](https://img.shields.io/badge/language-Korean-blue.svg)](Web-API-Guide_kr.md)
33

4-
## Run API Server
4+
## Run Scouter API server
55

66
### Embedded Mode Run - Run with scouter collector server
7-
- set configurations below (Collector configuration)
7+
- set configurations below (Collector configuration - need to restart collector server)
88
- `net_http_server_enabled` : set `true`
99
- `net_http_api_enabled` : set `true`
1010
- `net_http_port` : default value `6180`

‎scouter.document/tech/Web-API-Guide_kr.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# Scouter Web API Guide
2+
[![English](https://img.shields.io/badge/language-English-orange.svg)](Web-API-Guide.md) [![Korean](https://img.shields.io/badge/language-Korean-blue.svg)](Web-API-Guide_kr.md)
3+
4+
## Scouter API Server 실행
5+
6+
### Embedded Mode로 실행 - 수집서버(Collector)에서 실행
7+
- 수집서버에 아래 옵션을 설정하면 수집서버와 같이 실행된다.(재기동 필요)
8+
- `net_http_server_enabled` : set `true`
9+
- `net_http_api_enabled` : set `true`
10+
- `net_http_port` : default value `6180`
11+
- `net_http_api_allow_ips` : default value `localhost,127.0.0.1,0:0:0:0:0:0:0:1,::1`;
12+
13+
### StandAlone Mode로 실행
14+
- Web API는 Servlet을 통해 서비스 되면 HTTP 프로토콜이나 JSON 파싱 등 부가적인 작업이 필요하기 때문에 기본 수집서버에 비해 자원 사용량이 높다.
15+
따라서 모니터링하는 시스템의 규모가 크다면 API 서버를 분리하여 실행할 필요가 있다.
16+
- standAlone webapp 실행 (Scouter Full 패키지에 포함되어 있음)
17+
```bash
18+
cd scouter.webapp
19+
./startup.sh
20+
```
21+
- scouter web app 설정 (실행전에 설정 필요)
22+
- ```net_collector_ip_port_id_pws``` : default value `127.0.0.1:6100:admin:admin`
23+
- format : `{host}:{port}:{id}:{pw},{host}:{port}:{id}:{pw}`
24+
- ```net_http_port``` : default value `6188`
25+
- `net_http_api_allow_ips` : default value `localhost,127.0.0.1,0:0:0:0:0:0:0:1,::1`;
26+
27+
### Testing
28+
- access the url : http://{http-server-ip}:{port}/scouter/v1/info/server
29+
- expected response
30+
```javascript
31+
{
32+
"status": 200,
33+
"requestId": "#xxxx",
34+
"resultCode": 0,
35+
"message": "success",
36+
"result": [
37+
{
38+
"id": -1234512345,
39+
"name": "MyCollectorName",
40+
"connected": true,
41+
"serverTime": 1507878605943
42+
}
43+
]
44+
}
45+
```
46+
47+
## Configuration
48+
```java
49+
@ConfigDesc("Collector connection infos - eg) host:6100:id:pw,host2:6100:id2:pw2")
50+
@ConfigValueType(ValueType.COMMA_SEPARATED_VALUE)
51+
public String net_collector_ip_port_id_pws = "127.0.0.1:6100:admin:admin";
52+
53+
@ConfigDesc("size of webapp connection pool to collector")
54+
public int net_webapp_tcp_client_pool_size = 12;
55+
@ConfigDesc("timeout of web app connection pool to collector(It depends on net_tcp_client_so_timeout_ms)")
56+
public int net_webapp_tcp_client_pool_timeout = 15000;
57+
58+
@ConfigDesc("Enable api access control by client ip")
59+
public boolean net_http_api_auth_ip_enabled = true;
60+
@ConfigDesc("If get api caller's ip from http header.")
61+
public String net_http_api_auth_ip_header_key;
62+
63+
@ConfigDesc("Enable api access control by JSESSIONID of Cookie")
64+
public boolean net_http_api_auth_session_enabled = true;
65+
@ConfigDesc("api http session timeout")
66+
public int net_http_api_session_timeout = 3600*24;
67+
68+
@ConfigDesc("api access allow ip addresses")
69+
@ConfigValueType(ValueType.COMMA_SEPARATED_VALUE)
70+
public String net_http_api_allow_ips = "localhost,127.0.0.1,0:0:0:0:0:0:0:1,::1";
71+
72+
@ConfigDesc("HTTP service port")
73+
public int net_http_port = NetConstants.WEBAPP_HTTP_PORT;
74+
75+
@ConfigDesc("Log directory")
76+
public String log_dir = "./logs";
77+
@ConfigDesc("Keeping period of log")
78+
public int log_keep_days = 30;
79+
```
80+
81+
## APIs
82+
- **Context root : /scouter**
83+
- if the api url is ```/v1/info/server``` then ```/scouter/v1/info/server```
84+
85+
#### - `GET /v1/info/server`
86+
- get connected collector server info.
87+
- Auth : None
88+
89+
#### - `GET /v1/object`
90+
- get monitoring object list
91+
- **Auth** : required - register api client's ip to ```net_http_api_allow_ips``` configuration.
92+
- **Query params**
93+
- `serverId` : If the webapp connect to single collector then it's optional.(optional if single server)
94+
95+
#### - `GET /v1/counter/realTime/{counters}/ofType/{objType}`
96+
- get real time counter value by object type
97+
- **Auth** : required
98+
- **Path params**
99+
- `counters` : counter names comma separated (required)
100+
- refer to [counter names](https://github.com/scouter-project/scouter/blob/master/scouter.common/src/main/resources/scouter/lang/counters/counters.xml)
101+
- eg) Cpu,Mem,PageIn
102+
- `objType` : object type (required)
103+
- **Query params**
104+
- `serverId` : If the webapp connect to single collector then it's optional.(optional if single server)
105+
106+
#### - `GET /v1/counter/realTime/{counters}/ofObject/{objHash}`
107+
- get real time counter value by object
108+
- **Auth** : required
109+
- **Path params**
110+
- `counters` : (required)
111+
- `objHash` : object id (required)
112+
- **Query params**
113+
- `serverId` : (optional if single server)
114+
115+
#### - `GET /v1/counter/stat/{counters}/ofType/{objType}`
116+
- get 5min counter statistics by object type
117+
- **Auth** : required
118+
- **Path params**
119+
- `counters` : (required)
120+
- `objType` : (required)
121+
- **Query params**
122+
- `startYmd` : yyyymmdd (required)
123+
- `endYmd` : yyyymmdd (required)
124+
- `serverId` : (optional if single server)
125+
126+
#### - `GET /v1/summary/{summaryCategory}/ofType/{objType}`
127+
- get summary of given category
128+
- **Auth** : required
129+
- **Path params**
130+
- `summaryCategory` : service, sql, apiCall, ip, userAgent, error, alert (required)
131+
- `objType` : (required)
132+
- **Query params**
133+
- `startYmdHm` : yyyymmddhhmi (exclusive required with startTimeMillis)
134+
- `endYmdHm` : yyyymmddhhmi (exclusive required with endTimeMillis)
135+
- `startTimeMillis` : timestamp(long) - yyyymmddhhmi (exclusive required with startYmdHm)
136+
- `endTimeMillis` : timestamp(long) - yyyymmddhhmi (exclusive required with endYmdHm)
137+
- `serverId` : (optional if single server)
138+
139+
#### - `GET /v1/summary/{summaryCategory}/ofObject/{objHash}`
140+
- get summary of given category
141+
- **Auth** : required
142+
- **Path params**
143+
- `summaryCategory` : service, sql, apiCall, ip, userAgent, error, alert (required)
144+
- `objHash` : object id (required)
145+
- **Query params**
146+
- `startYmdHm` : yyyymmddhhmi (exclusive required with startTimeMillis)
147+
- `endYmdHm` : yyyymmddhhmi (exclusive required with endTimeMillis)
148+
- `startTimeMillis` : timestamp(long) - yyyymmddhhmi (exclusive required with startYmdHm)
149+
- `endTimeMillis` : timestamp(long) - yyyymmddhhmi (exclusive required with endYmdHm)
150+
- `serverId` : (optional if single server)
151+
152+
#### - `GET /v1/xlog-data/{yyyymmdd}`
153+
- get xlog data within the time range
154+
- **Auth** : required
155+
- **Path params**
156+
- `yyyymmdd` : date to search xlogs
157+
- **Query params**
158+
- `startTimeMillis` : start time as milliseconds(long) (required)
159+
- `endTimeMillis` : end time as milliseconds(long) (required)
160+
- `objHashes` : object hashes by comma separator also allowed with bracket. eg) 10011,10012 or [10011,10012]
161+
- `pageCount` : count to retrieve in one time. (max limit is 30,000, default 10,000)
162+
- `lastTxid` : available from previous response for paging support.
163+
- `lastXLogTime` : available from previous response for paging support.
164+
- `serverId` : (optional if single server)
165+
166+
#### - `GET /v1/xlog-data/{yyyymmdd}/{txid}`
167+
- get xlog data within the time range
168+
- **Auth** : required
169+
- **Path params**
170+
- `yyyymmdd` : date to search xlogs
171+
- `txid` : XLog's txid (long)
172+
- **Query params**
173+
- `serverId` : (optional if single server)
174+
175+
#### - `GET /v1/realTime/{offset1}/{offset2}`
176+
- get current xlog data created after the last searched.
177+
- **Auth** : required
178+
- **Path params**
179+
- `offset1` : the last xlog (loop) offset previously retrieved (initial value is 0)
180+
- `offset2` : the last xlog offset previously retrieved (initial value is 0)
181+
- **Query params**
182+
- `objHashes` : object hashes by comma separator also allowed with bracket. eg) 10011,10012 or [10011,10012]
183+
- `serverId` : (optional if single server)
184+
185+
#### - `GET /v1/profile-data/{yyyymmdd}/{txid}`
186+
- get profile data(decoded) from txid
187+
- **Auth** : required
188+
- **Path params**
189+
- `yyyymmdd` : date to search xlogs
190+
- `txid` : XLog's txid (long)
191+
- **Query params**
192+
- `serverId` : (optional if single server)
193+
194+
#### - `GET /v1/activeService/stepCount/ofType/{objType}`
195+
- current active service count 3-stepped by response time.
196+
- **Auth** : required
197+
- **Path params**
198+
- `objType` : (required)
199+
- **Query params**
200+
- `serverId` : (optional if single server)
201+
202+
#### - `GET /v1/activeService/ofType/{objType}`
203+
- get active service list of given objType
204+
- **Auth** : required
205+
- **Path params**
206+
- `objType` : (required)
207+
- **Query params**
208+
- `serverId` : (optional if single server)
209+
210+
#### - `GET /v1/activeService/ofObject/{objHash}`
211+
- get active service list of given objHash
212+
- **Auth** : required
213+
- **Path params**
214+
- `objHash` : (required)
215+
- **Query params**
216+
- `serverId` : (optional if single server)
217+
218+
#### - `GET /v1/activeService/thread/{threadId}/ofObject/{objHash}`
219+
- get thread detail of the object's threadId
220+
- **Auth** : required
221+
- **Path params**
222+
- `objHash` : (required)
223+
- `threadId` : thread id gotten from active service list (required)
224+
- **Query params**
225+
- `txidName` : This value is for valuable service related information. (like service name & a sql that currently running)
226+
- `txid` : This value has higher priority than txidName.(txidName is String type from Hexa32.toString32(txid) / txid is long type)
227+
- `serverId` : (optional if single server)
228+
229+
#### - `GET /v1/alert/realTime/{offset1}/{offset2}`
230+
- retrieve current alerts unread that is produced newly after the last offsets.
231+
- **Auth** : required
232+
- **Path params**
233+
- `offset1` : (required)
234+
- `offset2` : (required)
235+
- **Query params**
236+
- `objType` : (required)
237+
- `serverId` : (optional if single server)
238+
239+
#### - `GET /v1/dictionary/{yyyymmdd}`
240+
- get text values from dictionary keys requested
241+
- **Auth** : required
242+
- **Path params**
243+
- `yyyymmdd` : (required)
244+
- **Query params**
245+
- `texts` : group of text types & text hashes (required)
246+
- eg) texts=[service:10001,service:10002,obj:20001,sql:55555] (bracket is optional)
247+
248+
#### - `GET /v1/visitor/realTime/ofType/{objType}`
249+
- retrieve today visitor count by objType
250+
- **Auth** : required
251+
- **Path params**
252+
- `objType` : (required)
253+
- **Query params**
254+
- `serverId` : (optional if single server)
255+
256+
#### - `GET /v1/visitor/realTime`
257+
- retrieve today visitor count by objects
258+
- **Auth** : required
259+
- **Query params**
260+
- `objHashes` : object hashes by comma separator also allowed with bracket. eg) 10011,10012 or [10011,10012]
261+
- `serverId` : (optional if single server)
262+
263+
#### - `GET /v1/object/host/realTime/top/ofObject/{objHash}`
264+
- retrieve all OS processes cpu, memory usage of the given object
265+
- **Auth** : required
266+
- **Path params**
267+
- `objHash` : (required)
268+
- **Query params**
269+
- `serverId` : (optional if single server)
270+
271+
272+
273+

0 commit comments

Comments
 (0)