Operational Menu

Operational Menu

The Operational Menu is a simple landing page listing API endpoints for monitoring the IQ Server. These endpoints are bound to the adminConnectors property of the HTTP Configuration. You may navigate to this page directly on the server using the http://localhost:8071 URL.

Warning

The API endpoints exposed on the adminConnectors port are not protected by credentials as some monitoring tools require. This port should never be opened to traffic outside a private subnet as abuse will impact the server's health.

Security Notice

Beginning with recent releases, the admin port (8071) is bound to localhost (127.0.0.1) by default. This restricts access to the Operational Menu and administrative APIs to the server host, preventing unauthorized remote access unless explicitly configured.

Local access works with no additional configuration.

For remote access, use one of the following controlled methods:

To override the bind host setting, use the following environment variable:

export SERVER_ADMIN_CONNECTOR_BIND_HOST=0.0.0.0

Warning: Changing the bind host exposes administrative capabilities and must only be used with strict network access controls.

API Endpoints

Metrics

This API returns the raw metrics from the server in a JSON format. The results can be used with monitoring tools, such as Splunk, to graph the server performance. While Prometheus cannot natively consume JSON metrics, integration is possible through the use of exporters (for example, json_exporter) that transform the JSON output into a Prometheus-compatible format. Including the ?pretty=true property will make the output human-readable but is not required for integration with monitoring tools.

http://localhost:8071/metrics?pretty=true

Ping

This API performs a low-impact port test which produces a simple HTML message of ‘pong’ and a successful HTTP code of 200. Useful for coding and testing for load balancers to make sure that the server is up and available to send/receive traffic. Consider using the /healthcheck endpoint below for high-availability status checks.

curl -I http://localhost:8071/ping

Threads

This API is a troubleshooting tool when details about the java threads are needed.

http://localhost:8071/threads

Health check

This API returns a short set of server status checks in a JSON format. These data points are the preferred method for determining the server's health when testing the server's availability by a load balancer for a highly available cluster or in another failover process. Including the ?pretty=true property will make the output human-readable but is not required for integration with monitoring tools.

Response behavior:

The endpoint returns an HTTP status code along with a JSON response containing individual health indicators.

An HTTP 200 (OK) response indicates that the IQ Server is reachable and able to process requests. It does not guarantee that all system components are healthy.

Each health indicator in the response includes a "healthy" field that represents the status of that specific component.

Sample response:

HTTP/1.1 200 OK

{
  "healthy": true,
  "deadlocks": {
    "healthy": true
  },
  "ds-database": {
    "healthy": false,
    "message": "Database connection unavailable"
  },
  "product-license": {
    "healthy": true
  },
  "work-directory": {
    "healthy": true
  }
}

In this example, the endpoint returns HTTP 200 because the IQ Server is reachable, even though the ds-database health indicator reports "healthy": false.

Interpreting results:

Individual indicators may report "healthy": false even when the overall response returns HTTP 200.

Non-2xx HTTP responses typically indicate a more severe failure, such as the service being unavailable or unable to respond.

Monitoring guidance:

For basic availability checks, such as load balancer probes, verifying an HTTP 200 response may be sufficient.

For full system health monitoring, evaluate the "healthy" fields in the JSON response rather than relying solely on the HTTP status code.

The returned data points are as follows:

http://localhost:8071/healthcheck?pretty=true

CPU Profile & Contention

These APIs output a file used by support when troubleshooting CPU issues.

http://localhost:8071/pprof

http://localhost:8071/pprof?state=blocked

Other Admin APIs

The admin connector exposes additional endpoints used to trigger internal maintenance tasks manually. These tasks should mostly be avoided unless recommended during guidance from the Sonatype Support team. A few are detailed below however most will remain unpublished.

Data Retention and Purging

Manually trigger the data retention task which is scheduled to run nightly.

http://localhost:8071/tasks/purgeObsoleteReports

Triggering Continuous Monitoring

Manually start the nightly continuous monitoring tasks.

http://localhost:8071/tasks/triggerPolicyMonitor

Securing Admin Endpoints

The Operational Menu and related administrative APIs are intended for restricted operational use. These endpoints should only be accessible from trusted hosts and networks.

Default Behavior

The admin port (8071) binds to localhost (127.0.0.1) by default. Only the IQ Server host can reach these endpoints unless additional configuration is applied.

How to Verify

Run the following command from the IQ Server host:

curl -I http://localhost:8071

If the request succeeds locally but not remotely, the secure default binding is active.

Remote Access Options

If remote access is required, use one of the following options:

ssh -L 8071:localhost:8071 user@iq-server-host

Override Bind Host

To override the default bind host:

export SERVER_ADMIN_CONNECTOR_BIND_HOST=0.0.0.0

Important: This override should only be used when strict firewall or network protections are in place.

For more details, see the System Requirements → Admin Port Security section.