Operation#

This page provides instructions for managing Starburst Gateway and connected clusters.

Query History UI#

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

Admin UI#

Use the admin page to configure Starburst Gateway backends. You can also add new backends and modify existing backend configurations.

Graceful shutdown#

Starburst Gateway supports graceful shutdown of clusters. You can still receive query states using the query ID after you deactivate a cluster.

To gracefully shut down a cluster without losing queries, use the following steps:

  1. Deactivate the backend to prevent the assignment of new queries.

  2. Monitor the backend cluster until all queued queries finish.

  3. Terminate the coordinator and worker Java processes.

To gracefully shut down a single worker process, refer to the graceful shutdown documentation for more details.

Query routing options#

Starburst Gateway provides the following routing options.

Default routing#

The default router randomly selects a backend to route queries.

Load-based routing#

To route queries to the backend with the fewest queries running or queued from a particular user, use QueryCountBasedRouter. Add the module name to your configuration file:

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

The router uses cluster statistics including queued and running queries. Set the interval for collecting statistics using the following configuration property:

monitor:
  taskDelaySeconds: 10

The default interval is 60.

Monitoring#

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

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

Health endpoints#

Starburst Gateway provides two API endpoints to indicate server status.

  • /trino-gateway/livez always returns status code 200 when the server is running and responsive. The endpoint may not respond if Starburst Gateway is overloaded or unresponsive.

  • /trino-gateway/readyz returns status code 200 when the server completes initialization and is ready to serve requests. This means that the database is connected and the first round of health checks is complete. If the server is not ready, the endpoint returns status code 503.