Odyssey console¶

Odyssey supports administration console, that are configuraed like 'local' storage.

This console allows to connect to Odyssey with psql like usual and performs some 'admin' operations or retrieve some metrics/statistics.

Configuration¶

You will need to create a local storage and rule for accessing the console. Odyssey configuration to create an ability for console connections can look like:

storage "local" {
    type "local"
}

database "console" {
    user "console" {
        authentication "none"
        role "admin"
        pool "session"
        storage "local"
    }
}

After that you can connect and execute commands in console with any postgresql client:

psql -h localhost -p 6432 -U console -d console -c "show clients"

psql -h localhost -p 6432 -U console -d console -c "show servers"

psql -h localhost -p 6432 -U console -d console -c "pause"

kill_client¶

Drop connection with specified client.

kill_client c123dfsdfg2

reload¶

Reload Odyssey configuration. Can be used to set some Odyssey parameters without restarting Odyssey.

reload

alter system¶

This command saves global configuration changes, like ALTER SYSTEM in PostgreSQL. It requires the admin role.

alter system set workers = 4
alter system set log_debug to yes
alter system set availability_zone = 'eu-1'
alter system set log_debug = default
alter system reset log_debug
alter system reset all

Odyssey writes changes to <config>.autoconf next to the main configuration file. For /etc/odyssey/odyssey.conf, this is /etc/odyssey/odyssey.conf.autoconf. At startup and on reload, Odyssey reads the autoconf file after the main configuration, so its values take precedence.

alter system saves the value without changing the running configuration. Run reload to apply it. Parameters that reload cannot change require a restart; show config marks them with changeable set to no.

For these parameters, alter system returns a NOTICE. reset all does not return these notices, so check show config to see whether you need to restart Odyssey after resetting all parameters.

odyssey=# alter system set workers = 4;
NOTICE:  parameter "workers" cannot be changed without restarting odyssey
HINT:  The value is saved in the autoconf file and takes effect after restart.
ALTER SYSTEM

Odyssey comments out previous values and keeps them in the file as a history of changes:

# Do not edit this file manually!
# It is overwritten by ALTER SYSTEM.
# log_debug yes
log_debug no

reset comments out the parameter's saved value, so the value from the main configuration applies again. reset all does this for every parameter.

Notes:

You can change the global parameters listed by show config. Sections such as database, storage or listen are not supported.
Odyssey checks each value before saving it. Booleans must be yes or no, integers must be plain numbers, and strings cannot contain line breaks. It then loads the complete configuration with the candidate autoconf file and runs the same checks as reload. If the configuration would prevent Odyssey from starting, the command fails and logs the reason. A rejected command leaves the existing file unchanged.
Odyssey replaces the file atomically to avoid leaving a partial file after a crash. The file is limited to 1 MB. When it reaches that limit, remove old commented lines by hand before running alter system again.
The autoconf file cannot contain include directives.

help¶

Writes available commands to execute in console.

help

show ...¶

show clients¶

Writes list of currently connected clients.

show clients

show servers¶

Writes list of currently connected servers.

show servers

show server_prep_stmts¶

Writes list of currently allocated prepared statements.

show server_prep_stmts

show pools¶

Write information about currently allocated pools for every database.user

show pools

show pools_extended¶

Write even more information about currently allocated pools for every database.user

show pools_extended

Returns every show pools column, then bytes_received, bytes_sent, tcp_conn_count, cl_queue, and a query_<q>/transaction_<q> pair per configured quantile.

The client counters distinguish three different client states, which is easy to get wrong:

Column	Meaning
`cl_active`	Clients currently attached to a backend connection
`cl_waiting`	Clients holding a route but not attached to a backend, i.e. idle between transactions. This is not a sign of pool pressure
`cl_queue`	Clients blocked waiting for a backend connection to become free. A non-zero value means the pool is exhausted
`maxwait`	Whole seconds the longest-queued client has been waiting so far, `0` when nothing is queued
`maxwait_us`	Sub-second remainder of `maxwait`, in microseconds

A client that starts to queue moves out of cl_waiting into cl_queue, so cl_waiting can drop exactly when the pool becomes saturated. Use cl_queue and maxwait to detect pool exhaustion.

show storages¶

Write information about current storages that are used to connect to PostgreSQL

show storages

show version¶

Write Odyssey version

show version

show listen¶

Show list of currently listened addresses

show listen

show is_paused¶

Show if Odyssey is paused or not

show is_paused

show errors¶

Show statistics about currently appeared errors

show errors

show lists¶

Show counts of the objects Odyssey is tracking: pools, clients in each state, servers and DNS cache entries

show lists

show instance¶

Show the state of the running Odyssey process itself, as opposed to the objects it is currently routing

show instance

Field	Description
`config_load_failed`	`1` if the last config load failed, so the process kept its previous configuration and a restart would not come up on the file currently on disk. `0` otherwise

show databases¶

Show info about databases

show databases

show host utilization¶

Show info about host resources utilization, in percentages

console=> show host_utilization;
  cpu  |  mem  
-------+-------
 13.37 | 15.77

show config¶

Reports the global configuration of the running process.

show config

console=> show config;
             key             | value | default | changeable
-----------------------------+-------+---------+------------
 workers                     | 4     | 1       | no
 log_query                   | yes   | no      | yes
 ...

Column	Meaning
`key`	parameter name, as accepted by the configuration parser
`value`	value the running process is using right now
`default`	built-in value used when the parameter is absent from the configuration file
`changeable`	whether `RELOAD` applies a new value without a restart

Reading odyssey.conf tells you what was asked for, not what is in effect. RELOAD applies only part of the global configuration; the rest keeps the value the process started with, and no error is reported. The changeable column tells the two apart, so comparing value against the file is enough to spot a parameter that needs a restart.

Notes:

default is the built-in initial value. A few parameters are derived from others when left unset - client_max_routing, for instance, becomes workers * 64 - so value can differ from default even though the configuration file does not mention the parameter.
Values longer than 255 characters are truncated in the output.
Per-route settings are not reported here, see show rules. Listen sockets are reported by show listen, storages by show storages.

pause¶

Pause Odyssey execution. This will drop any session connections and pause statement executions for transaction pools.

Can be used to reduce damage if you need to perform some operation on Postgres

pause

resume¶

Resume Odyssey statements execution.

resume