WebtoB Admin API

WebtoB는 시스템 동작 중 각종 상태 정보 확인, 제어 등의 관리 기능을 제공합니다. 예를 들어 제공되는 서비스들 중 특정 서비스에 대하여 현재 처리 상태 정보(서비스 처리 건수, 평균 처리 시간, 요청 대기 건수 등)를 확인할 수 있습니다.

WebtoB는 이와 같은 기능들을 Rest API를 이용한 Admin API를 통해 제공합니다. /server/admin 설정에서 포트를 지정하여 해당 포트를 통해 API 통신을 수행합니다.

config에서 admin 설정은 다음과 같이 수행합니다. 아래와 같이 설정하면 이후 9090 포트에 대해 Admin API 통신이 가능합니다.

"server":{
    "admin": {
        "port": 9090
    }
}

다음은 Admin API가 제공하는 API에 대한 설명입니다.

API 이름 설명

config

환경 설정 내용을 조회합니다.

client-info

접속 웹 브라우저를 확인합니다.

svg-info

서버 정보를 확인합니다.

stat-info

프로세스, 스레드 및 서비스 상태에 대한 통계를 조회합니다.

cache-list

HTTP 응답 캐시에 저장된 응답들의 정보를 출력합니다.

 

WebtoB Admin API의 주요 특징을 다음과 같습니다.

  • 모든 API는 POST 메소드로 통신합니다.

  • HTH별로 동작하는 API의 경우 HTH가 일정 시간동안 응답이 없다면 타임아웃 이후 "busy_hth"에 표시됩니다. 예를 들어 /client-info API에 대해 HTH-1, HTH-2가 타임아웃동안 응답하지 않는 경우 해당 정보가 다음과 같이 "busy_hth"에 표현됩니다.

    {
    "result": {
        "HTH-0": [
            {
                ...
            }
        ]
    },
    "busy_hth": [
        "HTH-1",
        "HTH-2"
    ]
}

  • API가 올바르게 동작한 경우 HTTP 응답 코드 200을 반환하고, 그렇지 않은 경우에는 상황에 따라 적절한 응답 코드를 반환합니다.

    공통적으로 발생하는 에러 응답 코드는 다음과 같습니다.

    응답 코드 설명

    400

    HTTP 본문에 대한 JSON 스키마 검증에 실패

    401

    사용자 인증에 실패

    403

    대상 API에 대한 동작 권한이 없음

    404

    대상 API가 없음

    405

    올바르지 않은 메소드로 요청

    500

    API 동작 중 에러가 발생 (API별로 발생하는 상황과 메시지가 다름)

  • 응답 코드가 200이 아닌 경우 공통적으로 다음과 같은 방식으로 구성됩니다.

    {
    "error_code": string,
    "error_message": string
}

    예를 들어 응답 코드가 404인 경우는 다음과 같이 발생할 수 있습니다.

    {
    "error_code": "APIERR_COMMON_0003",
    "error_message": "No such API"
}

환경 정보

/config

현재 동작 중인 시스템의 환경 정보를 조회합니다. 이 과정에서는 설정 파일에서 지정한 값뿐만 아니라 기본적으로 적용되는 값까지 확인할 수 있습니다.

  • 사용법

    {
    "path": string
}
    옵션 설명

    path

    config의 JSON 경로를 설정합니다. 경로를 생략하거나 /로 설정하면 현재 설정된 모든 config를 가져옵니다. 경로는 항상 /로 시작해야 합니다.

  • 예시

    다음은 NODE 절 환경 설정을 "/config" Admin API로 확인한 예시입니다. NODE 절의 설정 항목에 대한 자세한 설명은 NODE 절 설정 항목을 참고합니다.

    [Request]
{
    "path": "/node"
}

[Response]
{
    "result": {
        "cacheEntry": 128,
        "cacheKey": "HOST_URI",
        "cacheMaxFileSize": 8192,
        "connectionPoolSize": 8192,
        "gracefulShutdownTimeout": 30,
        "hthCount": 1,
        "hthSchedule": "RR",
        "maxCacheMemorySize": 100,
        "name": "webtob_node",
        "webtobDir": "$WEBTOBDIR",
        "workerThreads": 1
    }
}

동작 상태 정보

/client-info

현재 접속된 클라이언트(주로 웹 브라우저)의 환경 정보를 조회합니다. 현재 상태(status), 접속 IP 주소, 처리 건수(count)와 같은 정보를 확인할 수 있습니다.

  • 사용법

    {
    "virtual_host": string,
    "hth_number": integer
}
    옵션 설명

    (empty)

    서버에 연결된 모든 클라이언트의 정보를 조회합니다.

    virtual_host

    지정한 가상 호스트에 연결된 클라이언트의 정보를 조회합니다.

    hth_number

    지정한 HTH에 연결된 클라이언트의 정보를 조회합니다. 지정하지 않으면 모든 HTH에 대해 조회합니다.

  • 예시

    다음은 HTH 3번에서 vhost1 가상 호스트에 연결된 클라이언트 정보를 "/client-info" Admin API로 확인한 예시입니다.

    [Request]
{
    "virtual_host": "vhost1",
    "hth_number": 3
}

[Response]
{
    "result": {
        "HTH-3": [
            {
                "count": 0,
                "idle": 24,
                "local_ipaddr:port": "192.168.15.167:8080",
                "no": 1,
                "remote_ipaddr:port": "192.168.15.168:48006",
                "ssl": false,
                "status": "READY"
            },
            {
                "count": 2,
                "idle": 24,
                "local_ipaddr:port": "192.168.15.167:8080",
                "no": 0,
                "remote_ipaddr:port": "192.168.15.168:48005",
                "ssl": false,
                "status": "READY"
            }
        ]
    }
}

    다음은 출력 항목에 대한 설명입니다.

    출력 항목 설명

    count

    해당 클라이언트가 전송한 요청 수

    idle

    해당 클라이언트가 어떠한 데이터도 주고받지 않고 있는 상태로 지속된 시간

    local_ipaddr:port,

    remote_ipaddr:port

    서버와 클라이언트 IP:PORT

    no

    WebtoB 내부적으로 관리하는 커넥션 번호

    ssl

    해당 클라이언트가 SSL로 연결되어 있는지 여부

    status

    서버 내부의 클라이언트 상태

    • READY: 클라이언트로부터 요청을 받는 중

    • RUNNING: 클라이언트의 요청이 서버에서 처리 중

/svg-info

현재 동작 중인 각 서버 그룹의 정보를 조회합니다.

  • 사용법

    {
    "jeus" : array(string),
    "rproxy" : array(string)
}
    옵션 설명

    jeus

    JEUS 서버 그룹 이름을 설정합니다. "*"을 포함하면 모든 서버에 대한 정보를 확인할 수 있습니다.

    rproxy

    역방향 프록시 그룹 이름을 설정합니다. "*"을 포함하면 모든 서버에 대한 정보를 확인할 수 있습니다.

  • 예시

    다음은 모든 JEUS 서버 그룹과 rproxy1이라는 이름의 역방향 프록시 그룹 정보를 "/svg-info" Admin API로 확인한 예시입니다.

    [Request]
{
    "jeus" : [*],
    "rproxy" : ["rproxy1"]
}

[Response]
"result": [
    {
        "HTH-0": {
            "jeus": [
                {
                    "aqcnt": 0,
                    "count": 0,
                    "cqcnt": 0,
                    "qpcnt": 0,
                    "reqs": 0,
                    "rscnt": 0,
                    "status": "NRDY",
                    "svgname": "MyGroup2"
                },
                {
                    "aqcnt": 0,
                    "count": 0,
                    "cqcnt": 0,
                    "qpcnt": 0,
                    "reqs": 0,
                    "rscnt": 0,
                    "status": "NRDY",
                    "svgname": "MyGroup1"
                }
            ],
            "rproxy": [
                {
                    "aqcnt": 0,
                    "count": 0,
                    "cqcnt": 0,
                    "qpcnt": 0,
                    "reqs": 0,
                    "rscnt": 0,
                    "status": "RDY",
                    "svgname": "rproxy1"
                }
            ]
        }
    }
]

    다음은 출력 항목에 대한 설명입니다.

    출력 항목 설명

    aqcnt

    현재까지 큐에 대기했던 요청 수(cqcnt의 cumulative 값)

    count

    요청 처리 수

    cqcnt

    현재 큐에서 대기 중인 요청 수

    qpcnt

    큐에 대기 중이던 요청이 timeout 또는 qp 명령 등으로 인해 큐에서 제거된 요청 수

    reqs

    해당 서버에 보내진 요청 수

    rscnt

    해당 서버의 비정상 종료로 인한 재시작 횟수

    status

    서버 내부의 클라이언트 상태

    • RDY: 서버가 요청을 처리할 수 있으며, WebtoB와 연결된 서버 프로세스들이 존재함

    • NRDY: 요청을 처리할 수 없으며, WebtoB와 연결된 서버 프로세스가 존재하지 않음

    • BLK: 서버가 관리자 명령에 따라 일시 정지된 상태이며, 이로 인해 요청을 처리할 수 없음

    svgname

    환경 설정의 서버 그룹 이름

/stat-info

실질적인 시스템 동작 상태를 나타내며, 동작 중인 서버 프로세스와 서비스에 대한 정보를 조회합니다.

서버별로 처리한 서비스 개수, 커넥션 개수 등과 같은 동적인 정보를 확인할 수 있습니다.

  • 사용법

    {
    "hth_number" : integer,
    "target":{
        "jeus": array(string),
        "rproxy" : array(string),
        "htmls": boolean
    }
}
    옵션 설명

    hth_number

    통계를 확인할 HTH를 지정합니다.

    target/jeus

    JSV 서버들의 통계 정보를 출력합니다. "*"을 포함하면 모든 서버에 대한 정보를 확인할 수 있습니다.

    target/rproxy

    역방향 프록시의 각 서버별 상태를 출력합니다. "*"을 포함하면 모든 서버에 대한 정보를 확인할 수 있습니다.

    target/htmls

    HTMLS의 통계 정보 출력 여부입니다.

    target에서 최소한 1개 이상의 항목은 지정해야 합니다.

  • 예시

    다음은 MyGroup1이라는 JEUS 서버, rproxy1이라는 이름의 역방향 프록시 그룹 내 서버, HTMLS 서버 정보를 "/stat-info" Admin API로 확인한 예시입니다.

    [Request]
{
    "hth_number" : 1,
    "target":{
        "jeus": ["MyGroup1"],
        "rproxy" : ["rproxy1"],
        "htmls": true
    }
}

[Response]
{
    "result": {
        "HTH-0": {
            "jeus": [
                {
                    "average_processed_time": 0,
                    "connections": 50,
                    "request_count": 0,
                    "response_count": 0,
                    "server": "amV1c19kb21haW4vc2VydmVyMQ==",
                    "server_group": "MyGroup1",
                    "sticky_routed_count": 0
                }
            ],
            "rproxy": [
                {
                    "average_processed_time": 0,
                    "connections": 0,
                    "request_count": 0,
                    "response_count": 0,
                    "server": "192.168.15.167:8090",
                    "server_group": "rproxy1",
                    "sticky_routed_count": 0
                },
                {
                    "average_processed_time": 0,
                    "connections": 0,
                    "request_count": 0,
                    "response_count": 0,
                    "server": "192.168.15.167:8088",
                    "server_group": "rproxy1",
                    "sticky_routed_count": 0
                }
            ],
            "htmls": {
                "average_processed_time": 0.000309519,
                "request_count": 5,
                "response_count": 5,
                "server": "HTMLS"
            }
        }
    }
}

    다음은 출력 항목에 대한 설명입니다.

    출력 항목 설명

    average_processed_time

    요청당 평균 처리 시간(초)

    connections

    해당 서버에 연결된 커넥션 개수

    request_count

    해당 프로세스로 보내진 요청 수

    response_count

    해당 프로세스가 처리한 요청 수

    server

    서버 그룹에 속한 서버 이름

    • JEUS: jenginedid

    • 역방향 프록시: 대상 서버 주소

    • HTMLS: HTMLS (고정)

    server_group

    서버 그룹 이름

    sticky_routed_count

    클라이언트로부터 받은 스티키(Sticky) ID를 기준으로 해당 서버에 라우팅한 횟수

캐시 정보 관리

/cache-list

현재 WebtoB의 HTTP 응답 캐시에 저장된 응답 정보를 출력합니다.

  • 사용법

    {
    "hth_number": integer
}
    옵션 설명

    "hth_number"

    캐시 정보를 조회할 HTH를 설정합니다. 지정하지 않으면 모든 HTH의 정보를 조회합니다.

  • 예시

    다음은 HTH 0번에 대한 캐시 정보를 "/cache-list" Admin API로 확인한 예시입니다. 요청 경로 외의 부분은 서버 내부 디버그 용도로만 사용됩니다.

    [Request]
{
    "hth_number": 0
}


[Response]
"result": {
    "HTH-0": {
        "cache_map": [
            {
                "expire_time": "2023-10-25 16:35:18",
                "key": "192.168.15.167:8080/index.html",
                "size": 4312
            },
            {
                "expire_time": "2023-10-25 16:34:52",
                "key": "192.168.15.167:8080/favicon.ico",
                "size": 4507
            },
            {
                "expire_time": "2023-10-25 16:34:52",
                "key": "192.168.15.167:8080/4.html",
                "size": 219
            }
        ],
        "cache_map_size": 3,
        "memory_usage": 9038
    }
}

    다음은 출력 항목에 대한 설명입니다.

    출력 항목 설명

    cache_map

    캐시에서 관리하는 키(URI)와 관련 정보들을 반환

    cache_map/expire_time

    해당 아이템이 만료되는 시각

    cache_map/key

    해당 아이템의 URI

    cache_map/size

    해당 캐시 아이템의 전체 크기

    cache_map_size

    캐시에서 관리 중인 캐시 아이템 건수

    memory_usage

    캐시 아이템 콘텐츠에 대해 실제 사용 중인 메모리 총량 (단위: byte)