From 523deefe7a278dcff34234e1fd25940dd5605578 Mon Sep 17 00:00:00 2001 From: Vishal Jadhav Date: Fri, 19 Jul 2024 16:53:46 -0400 Subject: [PATCH] Add router development docs * Add doc for the current routers and steps to add a new one * Add to nav in Contribute section Co-authored-by: Manfred Moser --- docs/routers.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 82 insertions(+) create mode 100644 docs/routers.md diff --git a/docs/routers.md b/docs/routers.md new file mode 100644 index 000000000..ea6c542ad --- /dev/null +++ b/docs/routers.md @@ -0,0 +1,81 @@ +# Routers + +Trino Gateway offers two entry-level router options, providing users with a +straightforward and easy-to-use starting point for their routing needs. The +routers make the decision based on the clusters load reported in +[ClusterStats](https://github.com/trinodb/trino-gateway/blob/main/gateway-ha/src/main/java/io/trino/gateway/ha/clustermonitor/ClusterStats.java). + +## StochasticRoutingManager + +This primary routing mechanism employs a straightforward, decentralized +approach, dispatching incoming queries in a random manner without utilizing +advanced optimization techniques. + +## QueryCountBasedRouterProvider + +This routing mechanism utilizes near real-time, user-level cluster load +statistics. It uses running queries count and query queue lengths to determine +the most suitable cluster for each individual user. With is information it +directs queries to the least loaded cluster for that user, optimizing the +likelihood of successful execution. + +## Adding a routing mechanism + +To enhance Trino Gateway's capabilities, you can create and contribute new and +advanced router modules with intelligent routing features. To integrate a new +router, you need to create a provider module that can be configured via the +configuration file. This allows for seamless addition of new routers without +disrupting existing functionality. + +### Add router Provider module + +Use the following steps to incorporate a new routing mechanism with advanced +capabilities: + +- Derive a class from `RouterBaseModule` +- The module must instantiate the router and hold a reference to it. +- Add the module name to the `modules` section of the configuration file to load + the provider module and make the new router available. +- For example, `QueryCountBasedRouterProvider` and refer to the config file in + the following sections. + +### Add router class + +Use the following steps to create a new router: + +- Derive a class from `StochasticRoutingManager` to create the router that + does the actual work. +- Override the methods `provideAdhocBackend` and `provideBackendForRoutingGroup` + and implement the new smarter logic +- The router listens to the list of `ClusterStats` via the`updateBackEndStats` + method. +- This method is called on regular intervals defined in the config + parameter `monitor=>taskDelaySeconds`. +- Each element in the list corresponds to each backend cluster. +- Only the stats from the healthy cluster are reported, unhealthy clusters are + not included in the list. If you have three cluster backends and one is + unhealthy, then the parameter `List stats` has only two + elements. +- To get the cluster stats set the parameter + `clusterStatsConfiguration=>monitorType` to `UI_API` or `JDBC` which in turn + needs the setup of `backendState` section in the config file. + +### Configuration file reference + +```yaml +backendState: + username: + password: + ssl: + +clusterStatsConfiguration: + monitorType: UI_API + +monitor: + taskDelaySeconds: 10 + +modules: + - io.trino.gateway.ha.module.QueryCountBasedRouterProvider +``` + + diff --git a/mkdocs.yml b/mkdocs.yml index 9accd430c..de08ea470 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -87,4 +87,5 @@ nav: - Migration to Airlift: migration-to-airlift.md - Contribute: - Code: development.md + - Routers: routers.md - Documentation: docs.md