6. 애플리케이션 그룹관리

이 장에서 하는 일

애플리케이션 그룹과 서버 그룹을 API 로 관리합니다. 애플리케이션 그룹은 인스턴스를 서비스 단위로 묶는 단위이며, 콘솔의 화면 대부분이 이 단위로 데이터를 보여 줍니다. 서버 그룹은 SYS 에이전트 서버를 묶는 단위입니다 — 서버 그룹 절을 보세요.

언제 쓰나 — 배포 자동화에서 새 서비스를 올릴 때 그룹도 함께 만들어 두는 식으로 씁니다. 그룹 이름은 에이전트 설정의 application.name 과 맞춰야 인스턴스가 그 그룹에 들어갑니다.

애플리케이션 그룹

조회

등록된 애플리케이션 그룹과 각 그룹에 속한 호스트·인스턴스를 받아 옵니다.

항목	설명
URL	`/monitoring/api/metrics/APP?exclusion=false`
URL 요청 예시	`/monitoring/api/metrics/APP?exclusion=false`
HTTP METHOD	`GET`
Content-Type	`application/json; charset=UTF-8`
Body
Response	아래 참고

응답 예시

{
  "applications": [
    {
      "name": "ALL",
      "uuid": "87DC0B05-AB5C-4667-9493-CB08D8619E84",
      "builtIn": false,
      "enable": true,
      "firstDate": 1527052065813,
      "lastDate": 1534469380921,
      "hosts": [ … ]
    }
  ]
}

firstDate · lastDate 는 이 그룹에서 데이터가 처음·마지막으로 들어온 시각(Unix Epoch 밀리초)입니다. builtIn 이 true 면 제품이 만든 그룹이라 이름을 바꾸거나 지울 수 없습니다.

등록

새 그룹을 만듭니다. 에이전트 설정의 application.name 과 이름을 맞춰야 그 인스턴스가 이 그룹에 들어옵니다.

항목	설명
URL	`/monitoring/api/customgroup/group`
URL 요청 예시	`/monitoring/api/customgroup/group`
HTTP METHOD	`PUT`
Content-Type	`application/json; charset=UTF-8`
Body	`{groupId: "EAP_GROUPS1", uuid: "89A43B84-7D49-466C-A172-8F28AAA29ED9"}`
Response	`{"status": 200}`

수정 및 인스턴스 정규식 등록

그룹 이름을 바꾸거나, 인스턴스를 정규식으로 묶습니다. 이름 규칙이 정해진 환경에서는 정규식 하나로 새 인스턴스가 자동으로 들어옵니다.

항목	설명
URL	`/monitoring/api/customgroup/uuid/${UUID}`
URL 요청 예시	`/monitoring/api/customgroup/uuid/89A43B84-7D49-466C-A172-8F28AAA29ED9`
HTTP METHOD	`PUT`
Content-Type	`application/json; charset=UTF-8`
Body	`{ uuid: "89A43B84-7D49-466C-A172-8F28AAA29ED9", groupId: "EAP_GROUPS", regexp: "^eap71-.*"}`
Response	`{"status": 200}`

삭제

그룹을 지웁니다. 수집된 데이터는 지워지지 않고 그룹 묶음만 사라집니다.

항목	설명
URL	`/monitoring/api/customgroup/uuid/${UUID}`
URL 요청 예시	`/monitoring/api/customgroup/uuid/89A43B84-7D49-466C-A172-8F28AAA29ED9`
HTTP METHOD	`DELETE`
Content-Type	`application/json; charset=UTF-8`
Body
Response	`{"status": 200}`

서버 그룹

서버 그룹을 API 로 조회·관리합니다. 서버 그룹은 SYS 에이전트가 수집하는 서버를 호스트 이름·IP 패턴이나 직접 지정으로 묶은 단위로, 애플리케이션 그룹과는 따로 관리합니다. 콘솔의 접근 관리 ▸ 서버 그룹 화면과 TV 월보드의 서버 보기가 이 API 를 씁니다.

조회(GET)와 미리 보기는 로그인한 사용자 누구나 부를 수 있습니다. 관리자가 아니면 그 사용자 그룹 권한으로 볼 수 없는 서버가 결과에서 빠집니다(그룹 자체는 빠지지 않습니다).
등록·수정·삭제는 관리자만 할 수 있습니다. 관리자가 아니면 403 과 함께 "시스템 그룹은 관리자만 바꿀 수 있습니다." 가 돌아옵니다.
입력이 잘못되면 400 이고, 고칠 내용이 reason 에 문장으로 실립니다(예: "CIDR 은 아직 지원하지 않습니다. '192.168.23.*' 처럼 적어 주세요.").
성공 응답은 {"status": 200, "result": …} 형태입니다.

그룹 필드

필드	설명
`uuid`	그룹 식별자. 등록할 때 서버가 만듭니다
`groupId`	그룹 이름. 최대 40자, 대소문자 구분 없이 겹칠 수 없습니다
`matchField`	패턴을 맞출 대상. `hostname`(기본) 또는 `ip`
`patternType`	패턴 문법. `glob`(기본, 예: `worker*`) 또는 `regex`(정규식)
`patternSource`	패턴 원문. 비워 두면 직접 지정 그룹이 되고 `members` 로 서버를 정합니다. `/` 가 들어간 값(CIDR)은 받지 않습니다
`regexp`	저장할 때 서버가 `patternSource` 로 만든 정규식(읽기 전용). `glob` 은 전체 일치(`^…$`), `regex` 는 쓴 그대로(부분 일치)
`members`	직접 지정 그룹의 서버 목록. `{ "ip": "…", "hostname": "…" }` 의 배열
`sortNumber`	표시 순서

참고 glob 에서 * 는 빈 문자열과도 일치하고 패턴 전체가 이름 전체와 일치해야 합니다. regex 는 부분 일치이므로 전체 일치가 필요하면 ^…$ 를 직접 씁니다.

그룹 목록 조회

항목	설명
URL	`/monitoring/api/systemgroup/groups`
URL 요청 예시	`/monitoring/api/systemgroup/groups`
HTTP METHOD	`GET`
Content-Type	`application/json; charset=UTF-8`
Body
Response	`result` 에 그룹 배열. 그룹이 없으면 빈 배열

그룹 하나 조회

항목	설명
URL	`/monitoring/api/systemgroup/uuid/${UUID}`
URL 요청 예시	`/monitoring/api/systemgroup/uuid/89A43B84-7D49-466C-A172-8F28AAA29ED9`
HTTP METHOD	`GET`
Content-Type	`application/json; charset=UTF-8`
Body
Response	`result` 에 그룹 하나. 없는 `uuid` 면 `404`

해석 결과 조회

모든 그룹을 지금 등록된 서버에 맞춰 풀어 본 결과를 한 번에 받습니다.

항목	설명
URL	`/monitoring/api/systemgroup/resolved`
URL 요청 예시	`/monitoring/api/systemgroup/resolved`
HTTP METHOD	`GET`
Content-Type	`application/json; charset=UTF-8`
Body
Response	아래 필드 참고

`result` 필드	설명
`groups`	그룹별 결과 배열. 그룹 필드(`uuid`·`groupId`·`matchField`·`patternType`·`patternSource`·`sortNumber`)와 `matchMode`(`pattern` / `manual`), 지금 이 그룹에 든 서버 `hosts`, 직접 지정했지만 지금 에이전트가 없는 서버 `missing`
`noGroup`	어느 그룹에도 들지 않은 서버
`missing`	그룹별 `missing` 을 모은 것
`hostCount`	지금 등록된 SYS 서버 수(그룹 소속과 무관, 한 서버가 여러 그룹에 들어도 한 번만 셈)

패턴 미리 보기

저장하지 않고, 패턴에 지금 일치하는 서버를 봅니다.

항목	설명
URL	`/monitoring/api/systemgroup/preview`
URL 요청 예시	`/monitoring/api/systemgroup/preview`
HTTP METHOD	`POST`
Content-Type	`application/json; charset=UTF-8`
Body	`{ "matchField": "hostname", "patternType": "glob", "patternSource": "worker*" }`
Response	`result` 에 `regexp`(변환된 정규식), `count`(일치한 서버 수), `hosts`(일치한 서버 목록). 패턴이 비었거나 잘못되면 `400`

등록 (관리자)

항목	설명
URL	`/monitoring/api/systemgroup/group`
URL 요청 예시	`/monitoring/api/systemgroup/group`
HTTP METHOD	`POST`
Content-Type	`application/json; charset=UTF-8`
Body	패턴 그룹: `{ "groupId": "worker 노드", "matchField": "hostname", "patternType": "glob", "patternSource": "worker*" }` 직접 지정 그룹: `{ "groupId": "DB 서버", "matchField": "hostname", "patternSource": "", "members": [ { "ip": "10.0.0.21", "hostname": "db01" } ] }`
Response	`result` 에 저장된 그룹(`uuid` 포함). 검증 실패 `400`, 관리자 아님 `403`

수정 (관리자)

경로의 uuid 가 가리키는 그룹을 고칩니다. 본문의 uuid 는 쓰지 않습니다.

항목	설명
URL	`/monitoring/api/systemgroup/update/${UUID}`
URL 요청 예시	`/monitoring/api/systemgroup/update/89A43B84-7D49-466C-A172-8F28AAA29ED9`
HTTP METHOD	`POST`
Content-Type	`application/json; charset=UTF-8`
Body	등록과 같은 형식
Response	`result` 에 고친 그룹. 검증 실패·없는 그룹 `400`, 관리자 아님 `403`

삭제 (관리자)

그룹 정의만 지웁니다. 서버와 수집된 데이터는 그대로입니다.

항목	설명
URL	`/monitoring/api/systemgroup/remove/${UUID}`
URL 요청 예시	`/monitoring/api/systemgroup/remove/89A43B84-7D49-466C-A172-8F28AAA29ED9`
HTTP METHOD	`POST`
Content-Type	`application/json; charset=UTF-8`
Body
Response	`{"status": 200}`. 없는 그룹 `400`, 관리자 아님 `403`

이 장에서 하는 일​

애플리케이션 그룹​

조회​

등록​

수정 및 인스턴스 정규식 등록​

삭제​

서버 그룹​

그룹 필드​

그룹 목록 조회​

그룹 하나 조회​

해석 결과 조회​

패턴 미리 보기​

등록 (관리자)​

수정 (관리자)​

삭제 (관리자)​