Skip to content

6. Application Group Management

What This Chapter Does​

It manages application groups and server groups through the API. An application group is the unit that bundles instances by service, and most of the console's screens show data at this unit. A server group bundles SYS agent servers -- see the Server Groups section.

When to use it -- in deployment automation, to create the group at the same time a new service goes up. The group name has to match application.name in the agent configuration for the instance to land in that group.

Application Groups​

Query​

Fetches the registered application groups and the hosts and instances in each.

ItemDescription
URL/monitoring/api/metrics/APP?exclusion=false
Example request URL/monitoring/api/metrics/APP?exclusion=false
HTTP METHODGET
Content-Typeapplication/json; charset=UTF-8
Body
ResponseSee below

Example response

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

firstDate and lastDate are when data first and last arrived for this group (Unix epoch milliseconds). When builtIn is true, the group was created by the product and cannot be renamed or deleted.

Create​

Creates a new group. The name has to match application.name in the agent configuration for that instance to land in this group.

ItemDescription
URL/monitoring/api/customgroup/group
Example request URL/monitoring/api/customgroup/group
HTTP METHODPUT
Content-Typeapplication/json; charset=UTF-8
Body{groupId: "EAP_GROUPS1", uuid: "89A43B84-7D49-466C-A172-8F28AAA29ED9"}
Response{"status": 200}

Update and Registering an Instance Regular Expression​

Renames the group, or bundles instances with a regular expression. Where a naming rule is fixed, one regular expression brings new instances in automatically.

ItemDescription
URL/monitoring/api/customgroup/uuid/${UUID}
Example request URL/monitoring/api/customgroup/uuid/89A43B84-7D49-466C-A172-8F28AAA29ED9
HTTP METHODPUT
Content-Typeapplication/json; charset=UTF-8
Body{ uuid: "89A43B84-7D49-466C-A172-8F28AAA29ED9", groupId: "EAP_GROUPS", regexp: "^eap71-.*"}
Response{"status": 200}

Delete​

Deletes the group. The collected data is not deleted -- only the grouping disappears.

ItemDescription
URL/monitoring/api/customgroup/uuid/${UUID}
Example request URL/monitoring/api/customgroup/uuid/89A43B84-7D49-466C-A172-8F28AAA29ED9
HTTP METHODDELETE
Content-Typeapplication/json; charset=UTF-8
Body
Response{"status": 200}

Server Groups​

It queries and manages server groups through the API. A server group bundles the servers collected by SYS agents, by host name or IP pattern or by direct choice, and is managed apart from application groups. The console's Access Management ▸ Server Groups screen and the TV wallboard's server view use this API.

  • Queries (GET) and preview can be called by any logged-in user. For a user who is not an administrator, servers outside that user group's permissions are left out of the results (the groups themselves are not).
  • Create, update, and delete are for administrators only. A non-administrator gets 403 with the message "시스템 그룹은 관리자만 바꿀 수 있습니다." (only administrators can change system groups).
  • Invalid input returns 400, with what to fix as a sentence in reason (for example, the message that CIDR is not supported yet and a value like 192.168.23.* should be used). The messages are in Korean.
  • A successful response has the form {"status": 200, "result": …}.

Group Fields​

FieldDescription
uuidThe group identifier. The server creates it on registration
groupIdThe group name. Up to 40 characters, unique regardless of case
matchFieldWhat the pattern is matched against. hostname (default) or ip
patternTypeThe pattern syntax. glob (default, for example worker*) or regex (a regular expression)
patternSourceThe pattern as written. Leaving it empty makes a directly chosen group, whose servers are set by members. A value containing / (CIDR) is not accepted
regexpThe regular expression the server built from patternSource on save (read-only). glob matches the whole value (^…$); regex is used as written (partial match)
membersThe server list of a directly chosen group. An array of { "ip": "…", "hostname": "…" }
sortNumberThe display order

Note In glob, * also matches the empty string, and the pattern must match the whole name. regex is a partial match, so write ^…$ yourself when a whole match is needed.

Querying the Group List​

ItemDescription
URL/monitoring/api/systemgroup/groups
Example request URL/monitoring/api/systemgroup/groups
HTTP METHODGET
Content-Typeapplication/json; charset=UTF-8
Body
ResponseAn array of groups in result. An empty array when there are no groups

Querying One Group​

ItemDescription
URL/monitoring/api/systemgroup/uuid/${UUID}
Example request URL/monitoring/api/systemgroup/uuid/89A43B84-7D49-466C-A172-8F28AAA29ED9
HTTP METHODGET
Content-Typeapplication/json; charset=UTF-8
Body
ResponseOne group in result. 404 for an unknown uuid

Querying the Resolved Result​

Receives, in one call, every group resolved against the servers registered now.

ItemDescription
URL/monitoring/api/systemgroup/resolved
Example request URL/monitoring/api/systemgroup/resolved
HTTP METHODGET
Content-Typeapplication/json; charset=UTF-8
Body
ResponseSee the fields below
result fieldDescription
groupsThe per-group results. The group fields (uuid, groupId, matchField, patternType, patternSource, sortNumber) plus matchMode (pattern / manual), the servers now in the group hosts, and the directly chosen servers that have no agent now missing
noGroupThe servers that belong to no group
missingAll the per-group missing entries together
hostCountThe number of SYS servers registered now (regardless of groups; a server in several groups is counted once)

Previewing a Pattern​

Shows the servers that match a pattern now, without saving.

ItemDescription
URL/monitoring/api/systemgroup/preview
Example request URL/monitoring/api/systemgroup/preview
HTTP METHODPOST
Content-Typeapplication/json; charset=UTF-8
Body{ "matchField": "hostname", "patternType": "glob", "patternSource": "worker*" }
ResponseIn result: regexp (the converted regular expression), count (the number of matching servers), hosts (the matching servers). 400 if the pattern is empty or invalid

Create (Administrator)​

ItemDescription
URL/monitoring/api/systemgroup/group
Example request URL/monitoring/api/systemgroup/group
HTTP METHODPOST
Content-Typeapplication/json; charset=UTF-8
BodyA pattern group: { "groupId": "worker nodes", "matchField": "hostname", "patternType": "glob", "patternSource": "worker*" }
A directly chosen group: { "groupId": "DB servers", "matchField": "hostname", "patternSource": "", "members": [ { "ip": "10.0.0.21", "hostname": "db01" } ] }
ResponseThe saved group (with uuid) in result. 400 on validation failure, 403 for a non-administrator

Update (Administrator)​

Updates the group the uuid in the path points to. A uuid in the body is not used.

ItemDescription
URL/monitoring/api/systemgroup/update/${UUID}
Example request URL/monitoring/api/systemgroup/update/89A43B84-7D49-466C-A172-8F28AAA29ED9
HTTP METHODPOST
Content-Typeapplication/json; charset=UTF-8
BodyThe same format as Create
ResponseThe updated group in result. 400 on validation failure or an unknown group, 403 for a non-administrator

Delete (Administrator)​

Deletes only the group definition. The servers and the collected data stay as they are.

ItemDescription
URL/monitoring/api/systemgroup/remove/${UUID}
Example request URL/monitoring/api/systemgroup/remove/89A43B84-7D49-466C-A172-8F28AAA29ED9
HTTP METHODPOST
Content-Typeapplication/json; charset=UTF-8
Body
Response{"status": 200}. 400 for an unknown group, 403 for a non-administrator