Operation#

The following aspects apply to managing Starburst Gateway and the connected clusters.

Query History UI - check query plans etc.#

Starburst Gateway records history of recent queries and displays links to check query details page in respective cluster.

Admin UI - add and modify backend information#

The admin page is used to configure the gateway to multiple backends. Existing backend information can also be modified using the same.

Graceful shutdown#

Starburst Gateway supports graceful shutdown of clusters. Even when a cluster is deactivated, any submitted query states can still be retrieved based on the Query ID.

To graceful shutdown a cluster without query losses, the steps are:

  1. Set the backend to deactivate state, this prevents any new incoming queries from getting assigned to the backend.

  2. Poll the backend coordinator URL until the queued query count and the running query count both hit 0.

  3. Terminate the Coordinator & Worker Java process.

To gracefully shutdown a single worker process, refer to the Trino documentation </admin/graceful-shutdown.html> for more details.

Query routing options#

  • The default router selects the backend randomly to route the queries.

  • If you want to route the queries to the least loaded backend for a user i.e. backend with the least number of queries running or queued from a particular user, then use QueryCountBasedRouter, it can be configured by adding the module name to config file’s modules section like below

modules:
  - io.trino.gateway.ha.module.QueryCountBasedRouterProvider

  • The router works on the stats it receives from the clusters about the load i.e number queries queued and running on a cluster at regular intervals which can be configured like below. The default interval is 1 min

monitor:
  taskDelaySeconds: 10

Monitoring#

Starburst Gateway provides a metrics endpoint that uses the OpenMetrics format at /metrics. Use it to monitor Starburst Gateway instances with Prometheus and other compatible systems with the following Prometheus configuration:

scrape_configs:
- job_name: trino_gateway
  static_configs:
    - targets:
        - gateway1.example.com:8080

Starburst Gateway health endpoints#

Starburst Gateway provides two API endpoints to indicate the current status of the server:

  • /trino-gateway/livez always returns status code 200, indicating the server is alive. However, it might not respond if the Starburst Gateway is too busy, stuck, or taking a long time for garbage collection.

  • /trino-gateway/readyz returns status code 200, indicating the server has completed initialization and is ready to serve requests. This means the initial connection to the database and the first round of health check on Starburst clusters are completed. Otherwise, status code 503 is returned.