diff --git a/Documentation/Reference/MaxCtrl.md b/Documentation/Reference/MaxCtrl.md index 36dd41e6d..7e72f4ef7 100644 --- a/Documentation/Reference/MaxCtrl.md +++ b/Documentation/Reference/MaxCtrl.md @@ -94,48 +94,116 @@ Commands: List all servers in MaxScale. + + Field | Description + ----- | ----------- + Server | Server name + Address | Address where the server listens + Port | The port on which the server listens + Connections | Current connection count + State | Server state + GTID | Current value of @@gtid_current_pos + ### list services `Usage: list services` List all services and the servers they use. + + Field | Description + ----- | ----------- + Service | Service name + Router | Router used by the service + Connections | Current connection count + Total Connections | Total connection count + Servers | Servers that the service uses + ### list listeners `Usage: list listeners ` List listeners for a service. + + Field | Description + ----- | ----------- + Name | Listener name + Port | The port where the listener listens + Host | The address or socket where the listener listens + State | Listener state + ### list monitors `Usage: list monitors` List all monitors in MaxScale. + + Field | Description + ----- | ----------- + Monitor | Monitor name + State | Monitor state + Servers | The servers that this monitor monitors + ### list sessions `Usage: list sessions` List all client sessions. + + Field | Description + ----- | ----------- + Id | Session ID + User | Username + Host | Client host address + Connected | Time when the session started + Idle | How long the session has been idle, in seconds + Service | The service where the session connected + ### list filters `Usage: list filters` List all filters in MaxScale. + + Field | Description + ----- | ----------- + Filter | Filter name + Service | Services that use the filter + Module | The module that the filter uses + ### list modules `Usage: list modules` List all currently loaded modules. + + Field | Description + ----- | ----------- + Module | Module name + Type | Module type + Version | Module version + ### list threads `Usage: list threads` List all worker threads. + + Field | Description + ----- | ----------- + Id | Thread ID + Current FDs | Current number of managed file descriptors + Total FDs | Total number of managed file descriptors + Load (1s) | Load percentage over the last second + Load (1m) | Load percentage over the last minute + Load (1h) | Load percentage over the last hour + ### list users `Usage: list users` @@ -143,12 +211,25 @@ List all worker threads. List network the users that can be used to connect to the MaxScale REST API as well as enabled local accounts. + + Field | Description + ----- | ----------- + Name | User name + Type | User type + Privileges | User privileges + ### list commands `Usage: list commands` List all available module commands. + + Field | Description + ----- | ----------- + Module | Module name + Commands | Available commands + ## show ``` @@ -172,6 +253,8 @@ Commands: threads Show all threads logging Show MaxScale logging information commands Show module commands of a module + qc_cache Show query classifier cache + dbusers Show database users of the service ``` @@ -179,9 +262,24 @@ Commands: `Usage: show server ` -Show detailed information about a server. The `Parameters` field contains the -currently configured parameters for this server. See `help alter server` for -more details about altering server parameters. +Show detailed information about a server. The `Parameters` field contains the currently configured parameters for this server. See `help alter server` for more details about altering server parameters. + + + Field | Description + ----- | ----------- + Server | Server name + Address | Address where the server listens + Port | The port on which the server listens + State | Server state + Last Event | The type of the latest event + Triggered At | Time when the latest event was triggered at + Services | Services that use this server + Monitors | Monitors that monitor this server + Master ID | The server ID of the master + Node ID | The node ID of this server + Slave Server IDs | List of slave server IDs + Statistics | Server statistics + Parameters | Server parameters ### show servers @@ -189,13 +287,41 @@ more details about altering server parameters. Show detailed information about all servers. + + Field | Description + ----- | ----------- + Server | Server name + Address | Address where the server listens + Port | The port on which the server listens + State | Server state + Last Event | The type of the latest event + Triggered At | Time when the latest event was triggered at + Services | Services that use this server + Monitors | Monitors that monitor this server + Master ID | The server ID of the master + Node ID | The node ID of this server + Slave Server IDs | List of slave server IDs + Statistics | Server statistics + Parameters | Server parameters + ### show service `Usage: show service ` -Show detailed information about a service. The `Parameters` field contains the -currently configured parameters for this service. See `help alter service` for -more details about altering service parameters. +Show detailed information about a service. The `Parameters` field contains the currently configured parameters for this service. See `help alter service` for more details about altering service parameters. + + + Field | Description + ----- | ----------- + Service | Service name + Router | Router that the service uses + State | Service state + Started At | When the service was started + Current Connections | Current connection count + Total Connections | Total connection count + Servers | Servers that the service uses + Parameters | Service parameter + Router Diagnostics | Diagnostics provided by the router module ### show services @@ -203,13 +329,33 @@ more details about altering service parameters. Show detailed information about all services. + + Field | Description + ----- | ----------- + Service | Service name + Router | Router that the service uses + State | Service state + Started At | When the service was started + Current Connections | Current connection count + Total Connections | Total connection count + Servers | Servers that the service uses + Parameters | Service parameter + Router Diagnostics | Diagnostics provided by the router module + ### show monitor `Usage: show monitor ` -Show detailed information about a monitor. The `Parameters` field contains the -currently configured parameters for this monitor. See `help alter monitor` for -more details about altering monitor parameters. +Show detailed information about a monitor. The `Parameters` field contains the currently configured parameters for this monitor. See `help alter monitor` for more details about altering monitor parameters. + + + Field | Description + ----- | ----------- + Monitor | Monitor name + State | Monitor state + Servers | The servers that this monitor monitors + Parameters | Monitor parameters + Monitor Diagnostics | Diagnostics provided by the monitor module ### show monitors @@ -217,23 +363,58 @@ more details about altering monitor parameters. Show detailed information about all monitors. + + Field | Description + ----- | ----------- + Monitor | Monitor name + State | Monitor state + Servers | The servers that this monitor monitors + Parameters | Monitor parameters + Monitor Diagnostics | Diagnostics provided by the monitor module + ### show session `Usage: show session ` -Show detailed information about a single session. The list of sessions can be -retrieved with the `list sessions` command. The is the session ID of a -particular session. +Show detailed information about a single session. The list of sessions can be retrieved with the `list sessions` command. The is the session ID of a particular session. -The `Connections` field lists the servers to which the session is connected and -the `Connection IDs` field lists the IDs for those connections. +The `Connections` field lists the servers to which the session is connected and the `Connection IDs` field lists the IDs for those connections. + + + Field | Description + ----- | ----------- + Id | Session ID + Service | The service where the session connected + State | Session state + User | Username + Host | Client host address + Connected | Time when the session started + Idle | How long the session has been idle, in seconds + Connections | Ordered list of backend connections + Connection IDs | Thread IDs for the backend connections + Queries | Query history + Log | Per-session log messages ### show sessions `Usage: show sessions` -Show detailed information about all sessions. See `help show session` for more -details. +Show detailed information about all sessions. See `help show session` for more details. + + + Field | Description + ----- | ----------- + Id | Session ID + Service | The service where the session connected + State | Session state + User | Username + Host | Client host address + Connected | Time when the session started + Idle | How long the session has been idle, in seconds + Connections | Ordered list of backend connections + Connection IDs | Thread IDs for the backend connections + Queries | Query history + Log | Per-session log messages ### show filter @@ -241,18 +422,44 @@ details. The list of services that use this filter is show in the `Services` field. + + Field | Description + ----- | ----------- + Filter | Filter name + Module | The module that the filter uses + Services | Services that use the filter + Parameters | Filter parameters + ### show filters `Usage: show filters` Show detailed information of all filters. + + Field | Description + ----- | ----------- + Filter | Filter name + Module | The module that the filter uses + Services | Services that use the filter + Parameters | Filter parameters + ### show module `Usage: show module ` -This command shows all available parameters as well as detailed version -information of a loaded module. +This command shows all available parameters as well as detailed version information of a loaded module. + + + Field | Description + ----- | ----------- + Module | Module name + Type | Module type + Version | Module version + Maturity | Module maturity + Description | Short description about the module + Parameters | All the parameters that the module accepts + Commands | Commands that the module provides ### show modules @@ -260,36 +467,130 @@ information of a loaded module. Displays detailed information about all modules. + + Field | Description + ----- | ----------- + Module | Module name + Type | Module type + Version | Module version + Maturity | Module maturity + Description | Short description about the module + Parameters | All the parameters that the module accepts + Commands | Commands that the module provides + ### show maxscale `Usage: show maxscale` See `help alter maxscale` for more details about altering MaxScale parameters. + + Field | Description + ----- | ----------- + Version | MaxScale version + Commit | MaxScale commit ID + Started At | Time when MaxScale was started + Activated At | Time when MaxScale left passive mode + Uptime | Time MaxScale has been running + Parameters | Global MaxScale parameters + ### show thread `Usage: show thread ` Show detailed information about a worker thread. + + Field | Description + ----- | ----------- + Id | Thread ID + Accepts | Number of TCP accepts done by this thread + Reads | Number of EPOLLIN events + Writes | Number of EPOLLOUT events + Hangups | Number of EPOLLHUP and EPOLLRDUP events + Errors | Number of EPOLLERR events + Avg event queue length | Average number of events returned by one epoll_wait call + Max event queue length | Maximum number of events returned by one epoll_wait call + Max exec time | The longest time spent processing events returned by a epoll_wait call + Max queue time | The longest time an event had to wait before it was processed + Current FDs | Current number of managed file descriptors + Total FDs | Total number of managed file descriptors + Load (1s) | Load percentage over the last second + Load (1m) | Load percentage over the last minute + Load (1h) | Load percentage over the last hour + QC cache size | Query classifier size + QC cache inserts | Number of times a new query was added into the query classification cache + QC cache hits | How many times a query classification was found in the query classification cache + QC cache misses | How many times a query classification was not found in the query classification cache + QC cache evictions | How many times a query classification result was evicted from the query classification cache + ### show threads `Usage: show threads` Show detailed information about all worker threads. + + Field | Description + ----- | ----------- + Id | Thread ID + Accepts | Number of TCP accepts done by this thread + Reads | Number of EPOLLIN events + Writes | Number of EPOLLOUT events + Hangups | Number of EPOLLHUP and EPOLLRDUP events + Errors | Number of EPOLLERR events + Avg event queue length | Average number of events returned by one epoll_wait call + Max event queue length | Maximum number of events returned by one epoll_wait call + Max exec time | The longest time spent processing events returned by a epoll_wait call + Max queue time | The longest time an event had to wait before it was processed + Current FDs | Current number of managed file descriptors + Total FDs | Total number of managed file descriptors + Load (1s) | Load percentage over the last second + Load (1m) | Load percentage over the last minute + Load (1h) | Load percentage over the last hour + QC cache size | Query classifier size + QC cache inserts | Number of times a new query was added into the query classification cache + QC cache hits | How many times a query classification was found in the query classification cache + QC cache misses | How many times a query classification was not found in the query classification cache + QC cache evictions | How many times a query classification result was evicted from the query classification cache + ### show logging `Usage: show logging` See `help alter logging` for more details about altering logging parameters. + + Field | Description + ----- | ----------- + Current Log File | The current log file MaxScale is logging into + Enabled Log Levels | List of log levels enabled in MaxScale + Parameters | Logging parameters + ### show commands `Usage: show commands ` -This command shows the parameters the command expects with the parameter -descriptions. +This command shows the parameters the command expects with the parameter descriptions. + + + Field | Description + ----- | ----------- + Command | Command name + Parameters | Parameters the command supports + Descriptions | Parameter descriptions + +### show qc_cache + +`Usage: show qc_cache` + +Show contents (statement and hits) of query classifier cache. + +### show dbusers + +`Usage: show dbusers ` + +Show information about the database users of the service ## set @@ -413,52 +714,24 @@ The Linux user accounts are used by the MaxAdmin UNIX Domain Socket interface Usage: create Commands: - server Create a new server + server [port] Create a new server monitor [params...] Create a new monitor service Create a new service filter [params...] Create a new filter listener Create a new listener user Create a new network user -Common create options: - --protocol Protocol module name [string] - --authenticator Authenticator module name [string] - --authenticator-options Option string for the authenticator [string] - --tls-key Path to TLS key [string] - --tls-cert Path to TLS certificate [string] - --tls-ca-cert Path to TLS CA certificate [string] - --tls-version TLS version to use [string] - --tls-cert-verify-depth TLS certificate verification depth [string] - -Create server options: - --services Link the created server to these services [array] - --monitors Link the created server to these monitors [array] - -Create monitor options: - --servers Link the created service to these servers [array] - --monitor-user Username for the monitor user [string] - --monitor-password Password for the monitor user [string] - -Create service options: - --servers Link the created service to these servers [array] - --filters Link the created service to these filters [array] - -Create listener options: - --interface Interface to listen on [string] [default: "::"] - -Create user options: - --type Type of user to create - [string] [choices: "admin", "basic"] [default: "basic"] - ``` ### create server -`Usage: create server ` +`Usage: create server [port]` The created server will not be used by any services or monitors unless the --services or --monitors options are given. The list of servers a service or a -monitor uses can be altered with the `link` and `unlink` commands. +monitor uses can be altered with the `link` and `unlink` commands. If the + argument is an absolute path, the server will use a local UNIX +domain socket connection. In this case the [port] argument is ignored. ### create monitor @@ -680,31 +953,60 @@ MaxScale. Usage: alter Commands: - server Alter server parameters - monitor Alter monitor parameters - service Alter service parameters - service-filters [filters...] Alter filters of a service - logging Alter logging parameters - maxscale Alter MaxScale parameters - user Alter admin user passwords + server Alter server parameters + [params...] + monitor Alter monitor parameters + [params...] + service Alter service parameters + [params...] + service-filters [filters...] Alter filters of a service + logging [params...] Alter logging parameters + maxscale [params...] Alter MaxScale parameters + user Alter admin user passwords ``` ### alter server -`Usage: alter server ` +`Usage: alter server ...` -To display the server parameters, execute `show server ` +To display the server parameters, execute `show server `. + +### alter [params...] + +`Usage: alter ` + +Multiple values can be updated at a time by providing the parameter name +followed by the new value. For example, the following command would change both +the `address` and the `port` parameter of a server: + + alter server server1 address 127.0.0.1 port 3306 + +All alter commands except `alter user` and `alter service-filters` support +multiple parameters. ### alter monitor -`Usage: alter monitor ` +`Usage: alter monitor ...` To display the monitor parameters, execute `show monitor ` +### alter [params...] + +`Usage: alter ` + +Multiple values can be updated at a time by providing the parameter name +followed by the new value. For example, the following command would change both +the `address` and the `port` parameter of a server: + + alter server server1 address 127.0.0.1 port 3306 + +All alter commands except `alter user` and `alter service-filters` support +multiple parameters. + ### alter service -`Usage: alter service ` +`Usage: alter service ...` To display the service parameters, execute `show service `. Some routers support runtime configuration changes to all parameters. Currently all @@ -727,6 +1029,19 @@ service parameters can be altered at runtime: "retain_last_statements" ] +### alter [params...] + +`Usage: alter ` + +Multiple values can be updated at a time by providing the parameter name +followed by the new value. For example, the following command would change both +the `address` and the `port` parameter of a server: + + alter server server1 address 127.0.0.1 port 3306 + +All alter commands except `alter user` and `alter service-filters` support +multiple parameters. + ### alter service-filters `Usage: alter service-filters [filters...]` @@ -742,13 +1057,13 @@ the `filters=A|B|C` parameter was defined for the service. ### alter logging -`Usage: alter logging ` +`Usage: alter logging ...` To display the logging parameters, execute `show logging` ### alter maxscale -`Usage: alter maxscale ` +`Usage: alter maxscale ...` To display the MaxScale parameters, execute `show maxscale`. The following list of parameters can be altered at runtime: diff --git a/maxctrl/lib/common.js b/maxctrl/lib/common.js index c56a3fa6d..e2d044ab2 100644 --- a/maxctrl/lib/common.js +++ b/maxctrl/lib/common.js @@ -425,8 +425,8 @@ module.exports = function() { this.fieldDescriptions = function(fields) { var t = new Table({chars: { - 'top' : '', 'top-mid': '', 'top-left': '', 'top-right': '', 'left': ' ', 'right': '', - 'left-mid': '' , 'mid': '' , 'mid-mid': '', 'right-mid': '' , 'middle': '', + 'top' : ' ', 'top-mid': '', 'top-left': '', 'top-right': '', 'left': ' ', 'right': '', + 'left-mid': '' , 'mid': '' , 'mid-mid': '', 'right-mid': '' , 'middle': '|', 'bottom' : '', 'bottom-mid': '', 'bottom-left': '', 'bottom-right': '', }}) diff --git a/maxctrl/lib/show.js b/maxctrl/lib/show.js index 997625aee..d4268cb75 100644 --- a/maxctrl/lib/show.js +++ b/maxctrl/lib/show.js @@ -448,6 +448,42 @@ const show_commands_fields = [ } ] +const qc_cache_fields = [ + { + name: 'Statement', + path: 'id', + description: 'The canonical form of the SQL statement' + }, + { + name: 'Hits', + path: 'attributes.hits', + description: 'Number of times cache entry has been used' + }, + { + name: 'Type', + path: 'attributes.classification.type_mask', + description: 'Query type' + } +] + +const show_dbusers_fields = [ + { + name: 'Users', + path: 'attributes.authenticator_diagnostics[]', + description: 'The list of users' + }, + { + name: 'Listener', + path: 'id', + description: 'Listener name' + }, + { + name: 'Authenticator', + path: 'attributes.parameters.authenticator', + description: 'The authenticator used by the listener' + } +] + exports.command = 'show ' exports.desc = 'Show objects' exports.handler = function() {} @@ -458,6 +494,7 @@ exports.builder = function(yargs) { 'field contains the currently configured parameters for this ' + 'server. See `help alter server` for more details about altering ' + 'server parameters.' + fieldDescriptions(server_fields)) + .wrap(null) .usage('Usage: show server ') }, function(argv) { maxctrl(argv, function(host) { @@ -467,6 +504,7 @@ exports.builder = function(yargs) { .command('servers', 'Show all servers', function(yargs) { return yargs.epilog('Show detailed information about all servers.' + fieldDescriptions(server_fields)) + .wrap(null) .usage('Usage: show servers') }, function(argv) { maxctrl(argv, function(host) { @@ -478,6 +516,7 @@ exports.builder = function(yargs) { 'field contains the currently configured parameters for this ' + 'service. See `help alter service` for more details about altering ' + 'service parameters.' + fieldDescriptions(service_fields)) + .wrap(null) .usage('Usage: show service ') }, function(argv) { maxctrl(argv, function(host) { @@ -487,6 +526,7 @@ exports.builder = function(yargs) { .command('services', 'Show all services', function(yargs) { return yargs.epilog('Show detailed information about all services.' + fieldDescriptions(service_fields)) + .wrap(null) .usage('Usage: show services') }, function(argv) { maxctrl(argv, function(host) { @@ -498,6 +538,7 @@ exports.builder = function(yargs) { 'field contains the currently configured parameters for this ' + 'monitor. See `help alter monitor` for more details about altering ' + 'monitor parameters.' + fieldDescriptions(monitor_fields)) + .wrap(null) .usage('Usage: show monitor ') }, function(argv) { maxctrl(argv, function(host) { @@ -507,6 +548,7 @@ exports.builder = function(yargs) { .command('monitors', 'Show all monitors', function(yargs) { return yargs.epilog('Show detailed information about all monitors.' + fieldDescriptions(monitor_fields)) + .wrap(null) .usage('Usage: show monitors') }, function(argv) { maxctrl(argv, function(host) { @@ -522,6 +564,7 @@ exports.builder = function(yargs) { 'the session is connected and the `Connection IDs` ' + 'field lists the IDs for those connections.' + fieldDescriptions(session_fields)) + .wrap(null) .usage('Usage: show session ') .group([rDnsOption.shortname], 'Options:') .option(rDnsOption.shortname, rDnsOption.definition) @@ -538,6 +581,7 @@ exports.builder = function(yargs) { return yargs.epilog('Show detailed information about all sessions. ' + 'See `help show session` for more details.' + fieldDescriptions(session_fields)) + .wrap(null) .usage('Usage: show sessions') .group([rDnsOption.shortname], 'Options:') .option(rDnsOption.shortname, rDnsOption.definition) @@ -552,7 +596,8 @@ exports.builder = function(yargs) { }) .command('filter ', 'Show filter', function(yargs) { return yargs.epilog('The list of services that use this filter is show in the `Services` field.' + - fieldDescriptions(filter_fields)) + fieldDescriptions(filter_fields)) + .wrap(null) .usage('Usage: show filter ') }, function(argv) { maxctrl(argv, function(host) { @@ -562,6 +607,7 @@ exports.builder = function(yargs) { .command('filters', 'Show all filters', function(yargs) { return yargs.epilog('Show detailed information of all filters.' + fieldDescriptions(filter_fields)) + .wrap(null) .usage('Usage: show filters') }, function(argv) { maxctrl(argv, function(host) { @@ -571,7 +617,8 @@ exports.builder = function(yargs) { .command('module ', 'Show loaded module', function(yargs) { return yargs.epilog('This command shows all available parameters as well as ' + 'detailed version information of a loaded module.' + - fieldDescriptions(module_fields)) + fieldDescriptions(module_fields)) + .wrap(null) .usage('Usage: show module ') }, function(argv) { maxctrl(argv, function(host) { @@ -580,7 +627,8 @@ exports.builder = function(yargs) { }) .command('modules', 'Show all loaded modules', function(yargs) { return yargs.epilog('Displays detailed information about all modules.' + - fieldDescriptions(module_fields)) + fieldDescriptions(module_fields)) + .wrap(null) .usage('Usage: show modules') }, function(argv) { maxctrl(argv, function(host) { @@ -590,6 +638,7 @@ exports.builder = function(yargs) { .command('maxscale', 'Show MaxScale information', function(yargs) { return yargs.epilog('See `help alter maxscale` for more details about altering ' + 'MaxScale parameters.' + fieldDescriptions(show_maxscale_fields)) + .wrap(null) .usage('Usage: show maxscale') }, function(argv) { maxctrl(argv, function(host) { @@ -598,7 +647,8 @@ exports.builder = function(yargs) { }) .command('thread ', 'Show thread', function(yargs) { return yargs.epilog('Show detailed information about a worker thread.' + - fieldDescriptions(thread_fields)) + fieldDescriptions(thread_fields)) + .wrap(null) .usage('Usage: show thread ') }, function(argv) { maxctrl(argv, function(host) { @@ -607,7 +657,8 @@ exports.builder = function(yargs) { }) .command('threads', 'Show all threads', function(yargs) { return yargs.epilog('Show detailed information about all worker threads.' + - fieldDescriptions(thread_fields)) + fieldDescriptions(thread_fields)) + .wrap(null) .usage('Usage: show threads') }, function(argv) { maxctrl(argv, function(host) { @@ -617,6 +668,7 @@ exports.builder = function(yargs) { .command('logging', 'Show MaxScale logging information', function(yargs) { return yargs.epilog('See `help alter logging` for more details about altering ' + 'logging parameters.' + fieldDescriptions(show_logging_fields)) + .wrap(null) .usage('Usage: show logging') }, function(argv) { maxctrl(argv, function(host) { @@ -626,6 +678,7 @@ exports.builder = function(yargs) { .command('commands ', 'Show module commands of a module', function(yargs) { return yargs.epilog('This command shows the parameters the command expects with ' + 'the parameter descriptions.' + fieldDescriptions(show_commands_fields)) + .wrap(null) .usage('Usage: show commands ') }, function(argv) { maxctrl(argv, function(host) { @@ -635,29 +688,23 @@ exports.builder = function(yargs) { }) .command('qc_cache', 'Show query classifier cache', function(yargs) { return yargs.epilog('Show contents (statement and hits) of query classifier cache.') + .wrap(null) .usage('Usage: show qc_cache') }, function(argv) { maxctrl(argv, function(host) { - return getCollection(host, 'maxscale/query_classifier/cache', [ - {'Statement': 'id'}, - {'Hits': 'attributes.hits'}, - {'Type': 'attributes.classification.type_mask' } - ]) + return getCollection(host, 'maxscale/query_classifier/cache', qc_cache_fields) }) }) .command('dbusers ', 'Show database users of the service', function(yargs) { return yargs.epilog('Show information about the database users of the service') + .wrap(null) .usage('Usage: show dbusers ') }, function(argv) { maxctrl(argv, function(host) { - return getSubCollection(host, 'services/' + argv.service, 'attributes.listeners[]', [ - {'Users': 'attributes.authenticator_diagnostics[]'}, - {'Listener': 'id'}, - {'Authenticator': 'attributes.parameters.authenticator'} - ]) + return getSubCollection(host, 'services/' + argv.service, 'attributes.listeners[]', show_dbusers_fields) }) }) - + .wrap(null) .usage('Usage: show ') .help() .command('*', 'the default command', {}, function(argv) {