Management Interface¶
App Suite Proxy comes with an additional management interface which allows administrators and third party systems to get access to runtime environment. The interface is implemented as REST API and listens on a configurable port. For convenience a commandline tool is also provided.
HTTP REST Endpoint¶
Click here to open the OpenAPI reference.
Following topics are currently covered:
Prometheus Metrics
Microprofile Health Check
Configuration Reload
To enable management endpoint on startup set configuration property proxy.admin.port.enabled
to
true
. For a complete reference to all possible configuration properties and their defaults see section Settings.
Hint
To get an overview of all exposed endpoints open root entry at http://<server>:<port>
Endpoint Settings¶
Note
All properties can be found in application.properties
. If a property is missing, not set or the value is not in range the default value will be used.
- proxy.admin.port.enabled
Enables Management Endpoint
Default:
false
Reloadable:
false
EnvVar:
PROXY_ADMIN_PORT_ENABLED
- proxy.admin.port
The Management Endpoint Port. Supported port range 8081-9999
Default:
8888
Reloadable:
false
EnvVar:
PROXY_ADMIN_PORT
- proxy.admin.http.errorresponse.enabled
Get a detailed error message in case of any HTTP Error (4xx, 5xx). This property can be changed on runtime.
Default:
false
Reloadable:
true
EnvVar:
PROXY_ADMIN_HTTP_ERRORRESPONSE_ENABLED
- proxy.health.default.procedures.enabled
Register default health check procedures. See Developers Guide for prerequisites.
Default:
false
Reloadable:
false
EnvVar:
PROXY_HEALTH_DEFAULT_PROCEDURES_ENABLED
- proxy.health.default.package
Classes within this package will be registered on server startup. See Developers Guide for prerequisites.
Default:
io.ox.proxy.health.impl.checks
Reloadable:
false
EnvVar:
PROXY_HEALTH_DEFAULT_PACKAGE
- proxy.health.jvm.threadcount.max
Health Check Threads- After exceeding this value the health check change to DOWN. Supported range 1 - Integer.MAX_VALUE. This property can be changed on runtime.
Default:
50
Reloadable:
true
EnvVar:
PROXY_HEALTH_JVM_THREADCOUNT_MAX
- proxy.health.jvm.heapmemory.maxpercentage
Health Check Memory - After exceeding this value the health check change to DOWN. 0.01 -> 1%, 0.99 -> 99% of max heap. Supported range 0.01 - 0.99. This property can be changed on runtime.
Default:
0.9
Reloadable:
true
EnvVar:
PROXY_HEALTH_JVM_HEAPMEMORY_MAXPERCENTAGE
- proxy.health.http
Health Check HTTP - If Endpoint is not available health check change to DOWN. If no value is present health check will be skipped. This property can be changed on runtime.
Default:
<empty>
Reloadable:
true
EnvVar:
PROXY_HEALTH_HTTP
- proxy.admin.openapi.enabled
Creates an additional Open API Endpoint when enabled. Endpoint is then available under
{{baseUrl}}/openapi
,{{baseUrl}}/openapi.json
,{{baseUrl}}/openapi.yaml
. Must be set before Server Startup.Default:
false
Reloadable:
false
EnvVar:
PROXY_ADMIN_OPENAPI_ENABLED
- proxy.admin.properties.sanitizekeys
Property names containing one the given keys will be sanitized when exposing via HTTP API. The values of well known properties will be sanitized even if this parameter is not set. Those values are
.password,.secret,.key.,.token,.credentials
. By setting this property keys will be added as additional keys to the list. Does not support regular expressionsDefault:
false
Reloadable:
false
- proxy.admin.properties.filter
Use positive filter where only property names matches the given value will be exposed via HTTP API. Leave this blank will disable the filter and lead to exposing all properties. Filter does not support regular expressions
Default: `` ``
Reloadable:
true
Sample¶
A sample configuration may look like this:
##################################################
##Management Tooling
##################################################
proxy.admin.port.enabled=true
proxy.admin.port=
proxy.admin.http.errorresponse.enabled=
proxy.admin.openapi.enabled=
###################################################
##Microprofile - Health Checks
###################################################
proxy.health.default.procedures.enabled=true
proxy.health.default.package=io.ox.proxy.health.impl.checks
proxy.health.jvm.threadcount.max=
proxy.health.jvm.heapmemory.maxpercentage=
proxy.health.http=
Note
This configuration will start the management listener on port 8888 and register all default health checks. Empty parameters will fall back to their default.
Microprofile Health Check¶
App Suite Proxy comes with an implementation of Microprofile Health API.
Some basic health checks are available by default and will be registered when enabled (see Settings). According to the API specification these health checks will be exposed to /health
/health/live
/health/ready
.
Payload from http://<server>:<port>/health
looks like the following example:
{
"status": "DOWN",
"checks": [
{
"name": "threads",
"state": "UP",
"data": {
"max thread count": 50,
"daemon thread count": 7,
"monitor deadlocked thread count": 0,
"thread count": 13,
"deadlocked thread count": 0,
"started thread count": 13,
"peak thread count": 13
}
},
{
"name": "http-check",
"state": "DOWN",
"data": {
"error": "java.net.ConnectException: Connection refused (Connection refused)",
"URI": "http://localhost:9999/ping"
}
},
{
"name": "heap-memory",
"state": "UP",
"data": {
"max %": "0.9",
"max": 3817865216,
"used": 69881976
}
}
],
"service": {
"name": "App Suite Proxy",
"version": "dev",
"date": "2019-10-31T11:58:18,745+0100",
"timeZone": "Europe/Berlin",
"locale": "de_DE",
"charset": "UTF-8"
}
}
Prometheus Metrics¶
Monitoring Metrics from server runtime will be exposed under /metrics
. The format follows the Prometheus Format specification .
Payload from http://<server>:<port>/metrics
looks like the following example:
# HELP zuul_filter_concurrency_current Current amount of concurrent requests for a filter
# TYPE zuul_filter_concurrency_current gauge
zuul_filter_concurrency_current{id="InitOidcSso.end",} 0.0
zuul_filter_concurrency_current{id="HttpRedirectFilter.end",} 0.0
zuul_filter_concurrency_current{id="GZipResponseCustomFilter.out",} 0.0
zuul_filter_concurrency_current{id="ProxyPassFilter.in",} 0.0
zuul_filter_concurrency_current{id="HttpSimpleResponseFilter.end",} 0.0
zuul_filter_concurrency_current{id="HeaderHandlingFilter.in",} 0.0
zuul_filter_concurrency_current{id="ZuulResponseFilter.out",} 0.0
Open API¶
Management Endpoint comes with an integrated Open API documentation which can be created while server startup, see section Settings. Once enabled the documentation is available at /openapi
, /openapi.yaml
and /openapi.json
. /metrics
. Use this endpoint to import the payload in a tool of your choise e.g. Postman, or use /application.wadl
to help with client generation.
Payload from /openapi
looks like the following example:
openapi: 3.0.1
info:
title: Appsuite-Proxy Management API
description: Description
termsOfService: http://swagger.io/terms/
contact:
email: devs@open-xchange.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: dev
paths:
/healthcheck:
get:
operationId: doHealthCheck
responses:
default:
description: default response
content:
'*/*': {}
/health:
get:
tags:
- Health Checks
summary: Health Check
description: Health Check according to microprofile Health API
operationId: getHealthResponse
responses:
default:
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorModel'
"200":
description: All Health Checks are UP
"503":
description: At least one Health Check failed with state DOWN
"500":
description: Health Check call could not be processed in backend. If property
enable API response errors is set to true see payload for futher details.
CLI¶
Appsuite Proxy comes with a command line tool which basically gives access to Proxy`s management API Endpoints. The command line tool can be installed as additional docker image or locally using gradle a task.
For more information see project`s readme. Once you have installed command line tool run appsuite-proxy --help
to get a list with possible actions
root@2a1f20a3b3d7:/usr/local/bin# appsuite-proxy
Usage: appsuite-proxy [OPTIONS] COMMAND [ARGS]...
Command line tool can be used to perform management tasks from shell which
basically invoke Appsuite Proxy`s REST API Endpoints.
Options:
--baseurl TEXT Base URL to HTTP API [default: (http://127.0.0.1:8888)]
--debug Show debug output in case of any errors [default: (False)]
--version The CLI version
-h, --help Show this message and exit.
Commands:
config Actions calling Appsuite Proxy`s configuration endpoint
health Actions calling Appsuite Proxy`s health endpoint
metrics Actions calling Appsuite Proxy`s metrics endpoint
Run 'appsuite-proxy COMMAND --help' for more information
CLI Docker Image¶
Alternatively you can use appsuite-proxy-cli docker image which includes the clt. To use it you need just to run the image, e.g. docker run ImageId
. This will show you the help text and you can just add options or commands on your next docker run call, e.g. docker run ImageId config get
.