Higson Studio and Higson Runtime REST expose Spring Boot Actuator endpoints for health checks and metrics. Starting with version 4.3.7, metrics are available in the Prometheus format and every actuator endpoint other than health requires authentication.

Endpoints#

Paths are relative to the application address. Higson Studio in the official Docker image listens on port 38080, Higson Runtime REST on port 8081. When Runtime REST runs with a context path (SERVER_SERVLET_CONTEXT_PATH), add it in front of /actuator.

Authentication:

• Higson Studio accepts any valid token, sent as Authorization: Bearer <token>.
• Higson Runtime REST uses its configured security type (see Authentication in Runtime REST): a Runtime REST token in JWT mode, user credentials in basic and Active Directory mode.

Requests without valid credentials get 401 Unauthorized.

Health checks#

The health endpoint is available without authentication and returns only the overall status, for example {"status":"UP"}. Component details (database, disk space) are not shown to anonymous callers.

Use /actuator/health for Docker HEALTHCHECK, load balancers and Kubernetes probes:

1
2
3
4

livenessProbe:
  httpGet:
    path: /higson/api/actuator/health   # Runtime REST: /actuator/health
    port: 38080                         # Runtime REST: 8081

Kubernetes liveness and readiness probes are also available in both applications: /actuator/health/liveness and /actuator/health/readiness (in Higson Studio prefixed with /higson/api). They are public like the health endpoint.

Prometheus metrics#

The prometheus endpoint returns the metrics collected by Micrometer, among others:

These are technical metrics of the application. Higson does not publish business metrics (for example the number of evaluated decision tables) through this endpoint.

Creating a token for the scraper#

Higson Runtime REST (JWT mode). In Higson Studio go to Tools → Licenses and tokens and add a token of type Runtime REST Token with a long expiry date. In basic or Active Directory mode use the credentials of a dedicated technical user instead.

Higson Studio.

1. Create a technical user dedicated to monitoring. It does not need administrative rights.
2. In Higson Studio go to Tools → Licenses and tokens, add a token of type Studio Integration Token for that user and set its expiry date.
3. Store the token in a file that Prometheus can read (for example a Kubernetes Secret).

Studio integration tokens are accepted on actuator endpoints because /actuator/** is included in the default value of higson.studio.security.token.verification.studio-token-secured-paths. If you override this property, keep /actuator/** in the list, otherwise the scraper gets 401 Unauthorized.

Plan the token rotation before the expiry date: when a token expires, scraping fails with 401 Unauthorized.

Prometheus configuration#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

scrape_configs:
  - job_name: higson-runtime-rest
    metrics_path: /actuator/prometheus
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/secrets/higson-runtime-rest.token
    static_configs:
      - targets: ['runtime-rest.example.com:8081']

  - job_name: higson-studio
    metrics_path: /higson/api/actuator/prometheus
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/secrets/higson-studio.token
    static_configs:
      - targets: ['studio.example.com:38080']

For Runtime REST in basic or Active Directory mode replace the authorization section with:

1
2
3

    basic_auth:
      username: monitoring
      password_file: /etc/prometheus/secrets/higson-runtime-rest.password

With the Prometheus Operator use a ServiceMonitor and keep the token in a Secret:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: higson-runtime-rest
spec:
  selector:
    matchLabels:
      app: higson-runtime-rest
  endpoints:
    - port: http
      path: /actuator/prometheus
      interval: 30s
      authorization:
        type: Bearer
        credentials:
          name: higson-monitoring
          key: runtime-rest-token

Checking the configuration#

1
2
3
4
5
6

# without a token: 401
curl -i http://runtime-rest.example.com:8081/actuator/prometheus

# with a token: 200 and metrics in the text format
curl -s -H "Authorization: Bearer $(cat higson-runtime-rest.token)" \
     http://runtime-rest.example.com:8081/actuator/prometheus | grep jvm_memory_used_bytes

In Prometheus the target should be reported as UP on the Status → Targets page.

Example queries#

Ready-made Grafana dashboards for Micrometer metrics, such as JVM (Micrometer), can be used as a starting point.

Changing the exposed endpoints#

The list of endpoints is controlled by the standard Spring Boot property. The default value in Higson Studio is:

management.endpoints.web.exposure.include=health, info, prometheus

and in Higson Runtime REST:

management.endpoints.web.exposure.include=health, prometheus

To disable metrics, remove prometheus from the list. Every endpoint added to the list requires authentication (only health is public). Endpoints such as logfile, env or loggers give access to logs and configuration and allow changing the logging level, so enable them only when needed.

Security#

• Keep the actuator endpoints reachable only from the internal network: on an Ingress or load balancer publish only the application paths and /actuator/health if it is needed outside.
• Use a dedicated technical user for monitoring and do not share its token with other integrations.
• Before version 4.3.7 all actuator endpoints of Higson Studio were available without authentication. After the upgrade, monitoring tools that read endpoints other than health need a token.