jrushford commented on a change in pull request #7478: URL: https://github.com/apache/trafficserver/pull/7478#discussion_r577144616
########## File path: doc/developer-guide/jsonrpc/jsonrpc-handler-development.en.rst ########## @@ -0,0 +1,279 @@ +.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license + agreements. See the NOTICE file distributed with this work for additional information regarding + copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software distributed under the License + is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express + or implied. See the License for the specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. |RPC| replace:: ``JSONRPC 2.0`` + +.. _JSONRPC: https://www.jsonrpc.org/specification +.. _JSON: https://www.json.org/json-en.html +.. _YAML: https://github.com/jbeder/yaml-cpp/wiki/Tutorial + +.. _jsonrpc_development: + +JSONRPC handler implementation +****************************** + +Use this section as a guide for developing new rpc methods inside |TS| and how to expose them through the |RPC| endpoint. +Before we start is worth mentioning some of the architecture of the current implementation. The whole RPC mechanism is divided in Review comment: should "start is worth" be "start, it is worth"? ########## File path: doc/developer-guide/jsonrpc/jsonrpc-architecture.en.rst ########## @@ -0,0 +1,533 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + +.. _JSONRPC: https://www.jsonrpc.org/specification +.. _JSON: https://www.json.org/json-en.html + + +.. |str| replace:: ``string`` +.. |arraynum| replace:: ``array[number]`` +.. |arraystr| replace:: ``array[string]`` +.. |num| replace:: *number* +.. |strnum| replace:: *string|number* +.. |object| replace:: *object* +.. |array| replace:: *array* +.. |optional| replace:: ``optional`` + +.. |arrayrecord| replace:: ``array[record]`` +.. |arrayerror| replace:: ``array[errors]`` + +JSONRPC +******* + +RPC Architecture +================ + + +Protocol +^^^^^^^^ + +The RPC mechanism implements the `JSONRPC`_ protocol. You can refer to this section `jsonrpc-protocol`_ for more information. + +Server +^^^^^^ + +IPC +""" + +The current server implementation runs on an IPC Socket(Unix Domain Socket). This server implements an iterative server style. +The implementation runs on a dedicated ``TSThread`` and as their style express, this performs blocking calls to all the registered handlers. +Configuration for this particular server style can be found in the admin section :ref:`admnin-jsonrpc-configuration`. + + +Using the JSONRPC mechanism +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As a user, currently, :program:`traffic_ctl` exercise this new protocol, please refer to the :ref:`traffic_ctl_jsonrpc` section. Review comment: "exercises" ########## File path: doc/appendices/command-line/traffic_ctl_jsonrpc.en.rst ########## @@ -0,0 +1,506 @@ +.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license + agreements. See the NOTICE file distributed with this work for additional information regarding + copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software distributed under the License + is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express + or implied. See the License for the specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. |RPC| replace:: ``JSONRPC 2.0`` + +.. _JSONRPC: https://www.jsonrpc.org/specification +.. _JSON: https://www.json.org/json-en.html + +.. _traffic_ctl_jsonrpc: + +traffic_ctl +*********** + +Synopsis +======== + +:program:`traffic_ctl` [OPTIONS] SUBCOMMAND [OPTIONS] + + +.. note:: + + :program:`traffic_ctl` now uses a `JSONRPC`_ endpoint instead of ``traffic_manager``. ``traffic_manager`` is not + required. To build this version of :program:`traffic_ctl` ``--enable-jsonrpc-tc`` should be passed when configure the build. + +Description +=========== + +:program:`traffic_ctl` is used to display,manipulate and configure +a running Traffic Server. :program:`traffic_ctl` includes a number +of subcommands that control different aspects of Traffic Server: + + +:program:`traffic_ctl config` + Manipulate and display configuration records +:program:`traffic_ctl metric` + Manipulate performance and status metrics +:program:`traffic_ctl server` + Stop, restart and examine the server +:program:`traffic_ctl storage` + Manipulate cache storage +:program:`traffic_ctl plugin` + Interact with plugins. +:program:`traffic_ctl host` + Manipulate host status. parents for now but will be expanded to origins. +:program:`traffic_ctl rpc` + Interact directly with the |RPC| server in |TS| + + + + +Options +======= + +.. program:: traffic_ctl +.. option:: --debug + + Enable debugging output. + +.. option:: -V, --version + + Print version information and exit. + +.. option:: -f, --format + + Specify the output print style. `legacy` and `pretty` are availables. + `legacy` will honour the old :program:`traffic_ctl` output messages. `pretty` <if available> will print a different output. + Errors from the server will be display if ``pretty`` is specified. + In case of a record request(config, metric) ``--records`` overrides this flag. + + Default: ``legacy`` + +.. option:: -r, --debugrpc + + Display human readable rpc messages. This will display the request and the response from the server. + +.. option:: --records + + Option available only for records request. + +Subcommands +=========== + +.. _traffic-control-command-alarm: + +traffic_ctl alarm +----------------- + +.. warning:: + + Option not available in the |RPC| version. + +.. _traffic-control-command-config: + +traffic_ctl config +------------------ + +.. program:: traffic_ctl config +.. option:: defaults [--records] + + Display the default values for all configuration records. The ``--records`` flag has the same + behavior as :option:`traffic_ctl config get --records`. + +.. program:: traffic_ctl config +.. option:: describe RECORD [RECORD...] + + Display all the known information about a configuration record. This includes the current and + default values, the data type, the record class and syntax checking expression. + + Error output available if ``--format pretty`` is specified. + +.. program:: traffic_ctl config +.. option:: diff [--records] + + Display configuration records that have non-default values. The ``--records`` flag has the same + behavior as :option:`traffic_ctl config get --records`. + +.. program:: traffic_ctl config +.. option:: get [--records] RECORD [RECORD...] + + Display the current value of a configuration record. + + Error output available if ``--format pretty`` is specified. + +.. program:: traffic_ctl config get +.. option:: --records + + If this flag is provided, :option:`traffic_ctl config get` will emit results in + :file:`records.config` format. + +.. program:: traffic_ctl config +.. option:: match [--records] REGEX [REGEX...] + + Display the current values of all configuration variables whose names match the given regular + expression. The ``--records`` flag has the same behavior as :option:`traffic_ctl config get + --records`. + +.. program:: traffic_ctl config +.. option:: reload + + Initiate a Traffic Server configuration reload. Use this command to update the running + configuration after any configuration file modification. If no configuration files have been + modified since the previous configuration load, this command is a no-op. + + The timestamp of the last reconfiguration event (in seconds since epoch) is published in the + `proxy.node.config.reconfigure_time` metric. + +.. program:: traffic_ctl config +.. option:: set RECORD VALUE + + Set the named configuration record to the specified value. Refer to the :file:`records.config` + documentation for a list of the configuration variables you can specify. Note that this is not a + synchronous operation. + +.. program:: traffic_ctl config +.. option:: status + + Display detailed status about the Traffic Server configuration system. This includes version + information, whether the internal configuration store is current and whether any daemon processes + should be restarted. + +.. _traffic-control-command-metric: + +traffic_ctl metric +------------------ +.. program:: traffic_ctl metric +.. option:: get METRIC [METRIC...] + + Display the current value of the specified statistics. + + Error output available if ``--format pretty`` is specified. + +.. program:: traffic_ctl metric +.. option:: match REGEX [REGEX...] + + Display the current values of all statistics whose names match + the given regular expression. + +.. program:: traffic_ctl metric +.. option:: zero METRIC [METRIC...] + + Reset the named statistics to zero. + +.. program:: traffic_ctl metric +.. option:: describe RECORD [RECORD...] + + Display all the known information about a metric record. + +.. program:: traffic_ctl metric +.. option:: describe RECORD [RECORD...] + + Display all the known information about a metric record. + + Error output available if ``--format pretty`` is specified. + +.. _traffic-control-command-server: + +traffic_ctl server +------------------ +.. program:: traffic_ctl server +.. option:: restart + + Option not yet available + +.. program:: traffic_ctl server restart +.. option:: --drain + + This option modifies the behavior of :option:`traffic_ctl server restart` such that + :program:`traffic_server` is not shut down until the number of active client connections drops to + the number given by the :ts:cv:`proxy.config.restart.active_client_threshold` configuration + variable. + +.. program:: traffic_ctl server +.. option:: start + + Option not yet available + +.. program:: traffic_ctl server +.. option:: status + + Option not yet available + +.. program:: traffic_ctl server +.. option:: stop + + Option not yet available + +.. program:: traffic_ctl server +.. option:: backtrace + + Option not yet available + +.. _traffic-control-command-storage: + +traffic_ctl storage +------------------- +.. program:: traffic_ctl storage +.. option:: offline PATH [PATH ...] + + Mark a cache storage device as offline. The storage is identified by :arg:`PATH` which must match + exactly a path specified in :file:`storage.config`. This removes the storage from the cache and + redirects requests that would have used this storage to other storage. This has exactly the same + effect as a disk failure for that storage. This does not persist across restarts of the + :program:`traffic_server` process. + +.. _traffic-control-command-plugin: + +traffic_ctl plugin +------------------- +.. program:: traffic_ctl plugin +.. option:: msg TAG DATA + + Send a message to plugins. All plugins that have hooked the + ``TSLifecycleHookID::TS_LIFECYCLE_MSG_HOOK`` will receive a callback for that hook. + The :arg:`TAG` and :arg:`DATA` will be available to the plugin hook processing. It is expected + that plugins will use :arg:`TAG` to select relevant messages and determine the format of the + :arg:`DATA`. + +.. _traffic-control-command-host: + +traffic_ctl host +---------------- +.. program:: traffic_ctl host + +A stat to track status is created for each host. The name is the host fqdn with a prefix of +"proxy.process.host_status". The value of the stat is a string which is the serialized +representation of the status. This contains the overall status and the status for each reason. The +stats may be viewed using the :program:`traffic_ctl metric` command or through the `stats_over_http` +endpoint. + +.. option:: --time count + + Set the duration of an operation to ``count`` seconds. A value of ``0`` means no duration, the + condition persists until explicitly changed. The default is ``0`` if an operation requires a time + and none is provided by this option. + +.. option:: --reason active | local | manual + + Sets the reason for the operation. + + ``active`` + Set the active health check reason. + + ``local`` + Set the local health check reason. + + ``manual`` + Set the administrative reason. This is the default reason if a reason is needed and not + provided by this option. + + Internally the reason can be ``self_detect`` if + :ts:cv:`proxy.config.http.parent_proxy.self_detect` is set to the value 2 (the default). This is + used to prevent parent selection from creating a loop by selecting itself as the upstream by + marking this reason as "down" in that case. + + .. note:: + + The up / down status values are independent, and a host is consider available if and only if + all of the statuses are "up". + +.. option:: status HOSTNAME [HOSTNAME ...] + + Get the current status of the specified hosts with respect to their use as targets for parent + selection. This returns the same information as the per host stat. + +.. option:: down HOSTNAME [HOSTNAME ...] + + Marks the listed hosts as down so that they will not be chosen as a next hop parent. If + :option:`--time` is included the host is marked down for the specified number of seconds after + which the host will automatically be marked up. A host is not marked up until all reason codes + are cleared by marking up the host for the specified reason code. + + Supports :option:`--time`, :option:`--reason`. + +.. option:: up HOSTNAME [HOSTNAME ...] + + Marks the listed hosts as up so that they will be available for use as a next hop parent. Use + :option:`--reason` to mark the host reason code. The 'self_detect' is an internal reason code + used by parent selection to mark down a parent when it is identified as itself and + + + Supports :option:`--reason`. + +.. _traffic_ctl rpc: + +traffic_ctl rpc +--------------- +.. program:: traffic_ctl rpc + +A mechanism to interact directly with the |TS| |RPC| endpoint. This means that this is not tied to any particular API +but rather to the rpc endpoint, so you can directly send requests and receive responses from the server. + +.. option:: file + + Reads a file or a set of files from the disc, use the content of the files as message(s) to the |RPC| endpoint. All jsonrpc messages + will be validated before sending them. If the file contains invalid json|yaml format the message will not be send, in + case of a set of files, if a particular file is not a proper json/yaml format then that particular file will be skipped. + + Example: + + .. code-block:: bash + + traffic_ctl rpc file jsonrpc_cmd1.json jsonrpc_cmd2.yaml + +.. option:: get-api + + Request the entire admin api. This will retrieve all the registered methods and notifications on the server side. + + Example: + + .. code-block:: bash + + $ traffic_ctl rpc get-api + Methods: + - admin_host_set_status + - admin_server_stop_drain + - admin_server_start_drain + - admin_clear_metrics_records + - admin_clear_all_metrics_records + - admin_plugin_send_basic_msg + - admin_lookup_records + - admin_config_set_records + - admin_storage_get_device_status + - admin_storage_set_device_offline + - admin_config_reload + - show_registered_handlers + Notifications: + - some_registered_notification_handler + + +.. option:: input + + Input mode, traffic_ctl will provide a control input from a stream buffer. Once the content was write the terminal :program:`traffic_ctl` + will wait for the user to press Control-D to send the request to the rpc endpoint. + This feature allow you to directly interact with the jsonrpc endpoint and test your API easily and without the need to know the low level Review comment: "allows" ########## File path: doc/developer-guide/jsonrpc/jsonrpc-architecture.en.rst ########## @@ -0,0 +1,533 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + +.. _JSONRPC: https://www.jsonrpc.org/specification +.. _JSON: https://www.json.org/json-en.html + + +.. |str| replace:: ``string`` +.. |arraynum| replace:: ``array[number]`` +.. |arraystr| replace:: ``array[string]`` +.. |num| replace:: *number* +.. |strnum| replace:: *string|number* +.. |object| replace:: *object* +.. |array| replace:: *array* +.. |optional| replace:: ``optional`` + +.. |arrayrecord| replace:: ``array[record]`` +.. |arrayerror| replace:: ``array[errors]`` + +JSONRPC +******* + +RPC Architecture +================ + + +Protocol +^^^^^^^^ + +The RPC mechanism implements the `JSONRPC`_ protocol. You can refer to this section `jsonrpc-protocol`_ for more information. + +Server +^^^^^^ + +IPC +""" + +The current server implementation runs on an IPC Socket(Unix Domain Socket). This server implements an iterative server style. +The implementation runs on a dedicated ``TSThread`` and as their style express, this performs blocking calls to all the registered handlers. +Configuration for this particular server style can be found in the admin section :ref:`admnin-jsonrpc-configuration`. + + +Using the JSONRPC mechanism +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As a user, currently, :program:`traffic_ctl` exercise this new protocol, please refer to the :ref:`traffic_ctl_jsonrpc` section. + +As a developer, please refer to the :ref:`jsonrpc_development` for a more detailed guide. + + + +JSON Parsing +^^^^^^^^^^^^ + +Our JSONRPC protocol implementation uses lib yamlcpp for parsing incoming and outgoing requests, +this allows the server to accept either JSON or YAML format messages which then will be parsed by the protocol implementation. This seems handy +for user that want to feed |TS| with existing yaml configuration without the need to translate yaml into json. + +.. note:: + + :program:`traffic_ctl` have an option to read files from disc and push them into |TS| through the RPC server. Files should be a + valid `JSONRPC`_ message. Please refer to :ref:`traffic_ctl rpc` for more details. + + +In order to programs communicate with |TS| , This one implements a simple RPC mechanism to expose all the registered API handlers. + +You can check all current API by: + + .. code-block:: bash + + traffic_ctl rpc get-api + +or by using the ``show_registered_handlers`` API method. + + +.. _jsonrpc-protocol: + +JSONRPC 2.0 Protocol +==================== + +JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures +and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, +over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format. + +Overview +======== + +.. note:: + + Although most of the protocol specs are granted, we do have implemented some exceptions. All the modifications we have implemented will Review comment: Change "we do have" to "we have" ########## File path: doc/appendices/command-line/traffic_ctl_jsonrpc.en.rst ########## @@ -0,0 +1,506 @@ +.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license + agreements. See the NOTICE file distributed with this work for additional information regarding + copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software distributed under the License + is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express + or implied. See the License for the specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. |RPC| replace:: ``JSONRPC 2.0`` + +.. _JSONRPC: https://www.jsonrpc.org/specification +.. _JSON: https://www.json.org/json-en.html + +.. _traffic_ctl_jsonrpc: + +traffic_ctl +*********** + +Synopsis +======== + +:program:`traffic_ctl` [OPTIONS] SUBCOMMAND [OPTIONS] + + +.. note:: + + :program:`traffic_ctl` now uses a `JSONRPC`_ endpoint instead of ``traffic_manager``. ``traffic_manager`` is not + required. To build this version of :program:`traffic_ctl` ``--enable-jsonrpc-tc`` should be passed when configure the build. + +Description +=========== + +:program:`traffic_ctl` is used to display,manipulate and configure +a running Traffic Server. :program:`traffic_ctl` includes a number +of subcommands that control different aspects of Traffic Server: + + +:program:`traffic_ctl config` + Manipulate and display configuration records +:program:`traffic_ctl metric` + Manipulate performance and status metrics +:program:`traffic_ctl server` + Stop, restart and examine the server +:program:`traffic_ctl storage` + Manipulate cache storage +:program:`traffic_ctl plugin` + Interact with plugins. +:program:`traffic_ctl host` + Manipulate host status. parents for now but will be expanded to origins. +:program:`traffic_ctl rpc` + Interact directly with the |RPC| server in |TS| + + + + +Options +======= + +.. program:: traffic_ctl +.. option:: --debug + + Enable debugging output. + +.. option:: -V, --version + + Print version information and exit. + +.. option:: -f, --format + + Specify the output print style. `legacy` and `pretty` are availables. + `legacy` will honour the old :program:`traffic_ctl` output messages. `pretty` <if available> will print a different output. + Errors from the server will be display if ``pretty`` is specified. + In case of a record request(config, metric) ``--records`` overrides this flag. + + Default: ``legacy`` + +.. option:: -r, --debugrpc + + Display human readable rpc messages. This will display the request and the response from the server. + +.. option:: --records + + Option available only for records request. + +Subcommands +=========== + +.. _traffic-control-command-alarm: + +traffic_ctl alarm +----------------- + +.. warning:: + + Option not available in the |RPC| version. + +.. _traffic-control-command-config: + +traffic_ctl config +------------------ + +.. program:: traffic_ctl config +.. option:: defaults [--records] + + Display the default values for all configuration records. The ``--records`` flag has the same + behavior as :option:`traffic_ctl config get --records`. + +.. program:: traffic_ctl config +.. option:: describe RECORD [RECORD...] + + Display all the known information about a configuration record. This includes the current and + default values, the data type, the record class and syntax checking expression. + + Error output available if ``--format pretty`` is specified. + +.. program:: traffic_ctl config +.. option:: diff [--records] + + Display configuration records that have non-default values. The ``--records`` flag has the same + behavior as :option:`traffic_ctl config get --records`. + +.. program:: traffic_ctl config +.. option:: get [--records] RECORD [RECORD...] + + Display the current value of a configuration record. + + Error output available if ``--format pretty`` is specified. + +.. program:: traffic_ctl config get +.. option:: --records + + If this flag is provided, :option:`traffic_ctl config get` will emit results in + :file:`records.config` format. + +.. program:: traffic_ctl config +.. option:: match [--records] REGEX [REGEX...] + + Display the current values of all configuration variables whose names match the given regular + expression. The ``--records`` flag has the same behavior as :option:`traffic_ctl config get + --records`. + +.. program:: traffic_ctl config +.. option:: reload + + Initiate a Traffic Server configuration reload. Use this command to update the running + configuration after any configuration file modification. If no configuration files have been + modified since the previous configuration load, this command is a no-op. + + The timestamp of the last reconfiguration event (in seconds since epoch) is published in the + `proxy.node.config.reconfigure_time` metric. + +.. program:: traffic_ctl config +.. option:: set RECORD VALUE + + Set the named configuration record to the specified value. Refer to the :file:`records.config` + documentation for a list of the configuration variables you can specify. Note that this is not a + synchronous operation. + +.. program:: traffic_ctl config +.. option:: status + + Display detailed status about the Traffic Server configuration system. This includes version + information, whether the internal configuration store is current and whether any daemon processes + should be restarted. + +.. _traffic-control-command-metric: + +traffic_ctl metric +------------------ +.. program:: traffic_ctl metric +.. option:: get METRIC [METRIC...] + + Display the current value of the specified statistics. + + Error output available if ``--format pretty`` is specified. + +.. program:: traffic_ctl metric +.. option:: match REGEX [REGEX...] + + Display the current values of all statistics whose names match + the given regular expression. + +.. program:: traffic_ctl metric +.. option:: zero METRIC [METRIC...] + + Reset the named statistics to zero. + +.. program:: traffic_ctl metric +.. option:: describe RECORD [RECORD...] + + Display all the known information about a metric record. + +.. program:: traffic_ctl metric +.. option:: describe RECORD [RECORD...] + + Display all the known information about a metric record. + + Error output available if ``--format pretty`` is specified. + +.. _traffic-control-command-server: + +traffic_ctl server +------------------ +.. program:: traffic_ctl server +.. option:: restart + + Option not yet available + +.. program:: traffic_ctl server restart +.. option:: --drain + + This option modifies the behavior of :option:`traffic_ctl server restart` such that + :program:`traffic_server` is not shut down until the number of active client connections drops to + the number given by the :ts:cv:`proxy.config.restart.active_client_threshold` configuration + variable. + +.. program:: traffic_ctl server +.. option:: start + + Option not yet available + +.. program:: traffic_ctl server +.. option:: status + + Option not yet available + +.. program:: traffic_ctl server +.. option:: stop + + Option not yet available + +.. program:: traffic_ctl server +.. option:: backtrace + + Option not yet available + +.. _traffic-control-command-storage: + +traffic_ctl storage +------------------- +.. program:: traffic_ctl storage +.. option:: offline PATH [PATH ...] + + Mark a cache storage device as offline. The storage is identified by :arg:`PATH` which must match + exactly a path specified in :file:`storage.config`. This removes the storage from the cache and + redirects requests that would have used this storage to other storage. This has exactly the same + effect as a disk failure for that storage. This does not persist across restarts of the + :program:`traffic_server` process. + +.. _traffic-control-command-plugin: + +traffic_ctl plugin +------------------- +.. program:: traffic_ctl plugin +.. option:: msg TAG DATA + + Send a message to plugins. All plugins that have hooked the + ``TSLifecycleHookID::TS_LIFECYCLE_MSG_HOOK`` will receive a callback for that hook. + The :arg:`TAG` and :arg:`DATA` will be available to the plugin hook processing. It is expected + that plugins will use :arg:`TAG` to select relevant messages and determine the format of the + :arg:`DATA`. + +.. _traffic-control-command-host: + +traffic_ctl host +---------------- +.. program:: traffic_ctl host + +A stat to track status is created for each host. The name is the host fqdn with a prefix of +"proxy.process.host_status". The value of the stat is a string which is the serialized +representation of the status. This contains the overall status and the status for each reason. The +stats may be viewed using the :program:`traffic_ctl metric` command or through the `stats_over_http` +endpoint. + +.. option:: --time count + + Set the duration of an operation to ``count`` seconds. A value of ``0`` means no duration, the + condition persists until explicitly changed. The default is ``0`` if an operation requires a time + and none is provided by this option. + +.. option:: --reason active | local | manual + + Sets the reason for the operation. + + ``active`` + Set the active health check reason. + + ``local`` + Set the local health check reason. + + ``manual`` + Set the administrative reason. This is the default reason if a reason is needed and not + provided by this option. + + Internally the reason can be ``self_detect`` if + :ts:cv:`proxy.config.http.parent_proxy.self_detect` is set to the value 2 (the default). This is + used to prevent parent selection from creating a loop by selecting itself as the upstream by + marking this reason as "down" in that case. + + .. note:: + + The up / down status values are independent, and a host is consider available if and only if + all of the statuses are "up". + +.. option:: status HOSTNAME [HOSTNAME ...] + + Get the current status of the specified hosts with respect to their use as targets for parent + selection. This returns the same information as the per host stat. + +.. option:: down HOSTNAME [HOSTNAME ...] + + Marks the listed hosts as down so that they will not be chosen as a next hop parent. If + :option:`--time` is included the host is marked down for the specified number of seconds after + which the host will automatically be marked up. A host is not marked up until all reason codes + are cleared by marking up the host for the specified reason code. + + Supports :option:`--time`, :option:`--reason`. + +.. option:: up HOSTNAME [HOSTNAME ...] + + Marks the listed hosts as up so that they will be available for use as a next hop parent. Use + :option:`--reason` to mark the host reason code. The 'self_detect' is an internal reason code + used by parent selection to mark down a parent when it is identified as itself and + + + Supports :option:`--reason`. + +.. _traffic_ctl rpc: + +traffic_ctl rpc +--------------- +.. program:: traffic_ctl rpc + +A mechanism to interact directly with the |TS| |RPC| endpoint. This means that this is not tied to any particular API +but rather to the rpc endpoint, so you can directly send requests and receive responses from the server. + +.. option:: file + + Reads a file or a set of files from the disc, use the content of the files as message(s) to the |RPC| endpoint. All jsonrpc messages + will be validated before sending them. If the file contains invalid json|yaml format the message will not be send, in + case of a set of files, if a particular file is not a proper json/yaml format then that particular file will be skipped. + + Example: + + .. code-block:: bash + + traffic_ctl rpc file jsonrpc_cmd1.json jsonrpc_cmd2.yaml + +.. option:: get-api + + Request the entire admin api. This will retrieve all the registered methods and notifications on the server side. + + Example: + + .. code-block:: bash + + $ traffic_ctl rpc get-api + Methods: + - admin_host_set_status + - admin_server_stop_drain + - admin_server_start_drain + - admin_clear_metrics_records + - admin_clear_all_metrics_records + - admin_plugin_send_basic_msg + - admin_lookup_records + - admin_config_set_records + - admin_storage_get_device_status + - admin_storage_set_device_offline + - admin_config_reload + - show_registered_handlers + Notifications: + - some_registered_notification_handler + + +.. option:: input + + Input mode, traffic_ctl will provide a control input from a stream buffer. Once the content was write the terminal :program:`traffic_ctl` Review comment: Maybe use "content is written"? ########## File path: mgmt2/config/AddConfigFilesHere.cc ########## @@ -0,0 +1,89 @@ +/** @file + + A brief file description + + @section license License + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + */ + +#include "tscore/ink_platform.h" +#include "tscore/Filenames.h" +//#include "MgmtUtils.h" Review comment: remove the include if not needed. ########## File path: doc/developer-guide/jsonrpc/traffic_ctl-development.en.rst ########## @@ -0,0 +1,214 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. |RPC| replace:: ``JSONRPC 2.0`` + +.. _YAML: https://github.com/jbeder/yaml-cpp/wiki/Tutorial + +.. _developer-guide-traffic_ctl-development: + +Traffic Control Development Guide +********************************* + +Traffic Control interacts with |TS| through the |RPC| endpoint. All interaction is done by following the |RPC| protocol. + +Overall structure +================= + +.. figure:: ../../uml/images/traffic_ctl-class-diagram.svg + + +* The whole point is to separate the command handling from the printing part. +* Printing should be done by an appropriate Printer implementation, this should support several kinds of printing formats. +* For now, everything is printing in the standard output, but a particular printer can be implemented in such way that + the output could be sent to a different destination. +* JSONRPC requests have a base class that hides some of the basic and common parts, like ``id``, and ``version``. When deriving + from this class, the only thing that needs to be override is the ``method`` + + +.. important:: + + CtrlCommand will invoke ``_invoked_func`` when executed, this should be set by the derived class + +* The whole design is that the command will execute the ``_invoked_func`` once invoked. This function ptr should be set by the + appropriated derived class based on the passed parameters. The derived class have the option to override the execute() which + is a ``virtual`` function and does something else. Check ``RecordCommand`` as an example. + + +Command implementation +====================== + +#. Add the right command to the ``ArgParser`` object inside the ``traffic_ctl.cc``. +#. If needed, define a new ``Command`` derived class inside the ``CtrlCommands`` file. if it's not an new command level, and it's a subcommand, + then you should check the existing command to decide where to place it. + + * Implement the member function that will be dealing with the particular command, ie: (config_status()) + + * If a new JsonRPC Message needs to be done, then implement it by deriving from ``CtrlClientRequest`` if a method is needed, or from + ``CtrlClientRequestNotification`` if it's a notification. More info can be found here :ref:`jsonrpc-request` and + :ref:`jsonrpc_development-design`. This can be done inside the ``RPCRequest.h`` file. + + + .. note:: + + Make sure you override the ``std::string get_method() const`` member function with the appropriate api method name. + + +#. If needed define a new ``Printer`` derived class inside the ``CtrlPrinter`` file. + + * If pretty printing format will be supported, then make sure you read the ``_format`` member you get from the ``BasePrinter`` class. + +#. If it's a new command level (like config, metric, etc), make sure you update the ``Command`` creation inside the ``traffic_ctl.cc`` file. + +Implementation Example +====================== + +Let's define a new command for a new specific API with name == ``admin_new_command_1`` with the following json structure: + +.. code-block: json + + { + "id":"0f0780a5-0758-4f51-a177-752facc7c0eb", + "jsonrpc":"2.0", + "method":"admin_new_command_1", + "params":{ + "named_var_1":"Some value here" + } + } + + +.. code-block:: bash + + $ traffic_ctl new-command new-subcommand1 + +#. Update ``traffic_ctl.cc``. I will ignore the details as they are trivial. + +#. Define a new Request. + + So based on the above json, we can model our request as: + + .. code-block:: cpp + + // RPCRequests.h + struct NewCommandJsonRPCRequest : CtrlClientRequest { + using super = CtrlClientRequest; + struct Params { + std::string named_var_1; + }; + NewCommandJsonRPCRequest(Params p) + { + super::params = p; // This will invoke the built-in conversion mechanism in the yamlcpp library. + } + // Important to override this function, as this is the only way that the "method" field will be set. + std::string + get_method() const { + return "admin_new_command_1"; + } + }; + +#. Implement the yamlcpp convert function, Yaml-cpp has a built-in conversion mechanism. You can refer to `YAML`_ for more info. + + .. code-block:: cpp + + // yaml_codecs.h + template <> struct convert<NewCommandJsonRPCRequest::Params> { + static Node + encode(NewCommandJsonRPCRequest::Params const ¶ms) + { + Node node; + node["named_var_1"] = params.named_var_1; + return node; + } + }; + +#. Define a new command. For the sake of simplicity I'll only implement it in the ``.h`` files. + + .. code-block:: cpp + + // CtrlCommands.h & CtrlCommands.cc + struct NewCommand : public CtrlCommand { + NewCommand(ts::Arguments args): CtrlCommand(args) + { + // we are interested in the format. + auto fmt = parse_format(_arguments); + if (args.get("new-subcommand1") { + // we need to create the right printer. + _printer = std::make_sharec<MyNewSubcommandPrinter>(fmt); + // we need to set the _invoked_func that will be called when execute() is called. + _invoked_func = [&]() { handle_new_subcommand1(); }; + } + // if more subcommands are needed, then add them here. + } + + private: + void handle_new_subcommand1() { + NewCommandJsonRPCRequest req{}; + // fill the req if needed. + auto response = invoke_rpc(req); + _printer->write_output(response); + } + }; + +#. Define a new printer to deal with this command. We will assume that the printing will be different for every subcommand. + so we will create our own one. + + + .. code-block:: cpp + + class MyNewSubcommandPrinter : public BasePrinter + { + void write_output(YAML::Node const &result) override { + // result will contain what's coming back from the server. + } + }; + + In case that the format type is important, then we should allow it by accepting the format being passed in the constructor. + And let it set the base one as well. + + .. code-block:: cpp + + MyNewSubcommandPrinter(BasePrinter::Format fmt) : BasePrinter(fmt) {} + + + + The way you print and the destination of the message is up to the developer's needs, either a terminal or some other place. If the response + from the server is a complex object, always can model the response with your own class or structure and use the built-in yamlcpp mechanism Review comment: maybe change to "you can always model the response" ########## File path: doc/developer-guide/jsonrpc/jsonrpc-handler-development.en.rst ########## @@ -0,0 +1,279 @@ +.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license + agreements. See the NOTICE file distributed with this work for additional information regarding + copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software distributed under the License + is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express + or implied. See the License for the specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. |RPC| replace:: ``JSONRPC 2.0`` + +.. _JSONRPC: https://www.jsonrpc.org/specification +.. _JSON: https://www.json.org/json-en.html +.. _YAML: https://github.com/jbeder/yaml-cpp/wiki/Tutorial + +.. _jsonrpc_development: + +JSONRPC handler implementation +****************************** + +Use this section as a guide for developing new rpc methods inside |TS| and how to expose them through the |RPC| endpoint. +Before we start is worth mentioning some of the architecture of the current implementation. The whole RPC mechanism is divided in +few components. + +Json RPC manager +================ + +This class is the entrance point for both, server calls and registered functions. + +.. figure:: ../../uml/images/JsonRPCManager.svg + +Dispatcher class +^^^^^^^^^^^^^^^^^ + +* Class that keeps track of all the registered methods and notifications that can be invoked by the RPC server. This class holds two + hash tables containing methods and notifications which uses the method name as a key. +* This class internally consumes ``RPCRequestInfo`` objects and performs the invocation of the respective calls. +* This class handlers the responses from the registered callbacks and it fills the appropriated ``RPCResponseInfo`` which then is passed + back to the ``JsonRPCManager`` class. + + +JsonRPCManager class +^^^^^^^^^^^^^^^^^^^^ + +* Singleton class that handles the JSONRPC handler registration and JSONRPC handler invocation. +* This class is the main entrance point for the RPC server through ``handle_call(std::string_view req)`` function. +* This class is the main entrance point for handler to be able to register in the RPC logic. ``add_notification_handler`` and ``remove_notification_handler``. + + +Implementing new handlers +========================= + +There a a few basic concepts that needs to be known before implementing a new handler, this is an easy process and the complexity depends on +the nature of the handler that you want to implement. +Dealing with incoming and outgoing parameters is up to the developer, we will touch some ways to deal with this through this guide. + +.. _jsonrpc_development-design: + +Design +^^^^^^ + +As requirement from the ``JsonRPCManager`` in order to be able to register inside the RPC management a function should implement the +following signature: + +Methods: + +.. code-block:: cpp + + ts::Rv<YAML::Node> your_rpc_handler_function_name(std::string_view const &id, YAML::Node const ¶ms); + + + +Notifications: + +.. code-block:: cpp + + void your_rpc_handler_function_name(YAML::Node const ¶ms); + + +* Incoming method request's id will be passed to the handler, this is read only value as the server is expected to respond with the same value. +* ``YAML::Node`` params is expected to be a ``Sequence`` or a ``Map``, as per protocol this cannot be a single value, so do not expect things like: + ``param=123`` or ``param=SomeString``. +* The ``params`` can be empty and contains no data at all. + + +.. note:: + + ``method`` handlers are expected to respond to the requests, while ``notifications``` will not respond with any data nor error. You can find + more information in :ref:`jsonrpc-protocol` or directly in the protocol specs `JSONRPC`_. + + +.. note:: + + If there is no explicit response from the method, the protocol implementation will respond with :ref:`success_response` unless an error + was specified. + + +Error Handling +^^^^^^^^^^^^^^ + + +There are several ways to deal with internal handler errors. Errors are expected to be send back to the client if the API was expressed that way Review comment: "send back" perhaps should be "sent back" ########## File path: mgmt2/config/AddConfigFilesHere.cc ########## @@ -0,0 +1,89 @@ +/** @file + + A brief file description + + @section license License + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + */ + +#include "tscore/ink_platform.h" +#include "tscore/Filenames.h" +//#include "MgmtUtils.h" +#include "records/P_RecCore.h" +#include "tscore/Diags.h" +#include "FileManager.h" +#include "tscore/Errata.h" +// #include <string_view> + +// extern FileManager *configFiles; Review comment: Remove this and the #include <string_view> if not needed. ########## File path: doc/admin-guide/jsonrpc/index.en.rst ########## @@ -0,0 +1,1692 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + + + +.. |RPC| replace:: ``JSONRPC 2.0`` + +.. _JSONRPC: https://www.jsonrpc.org/specification +.. _JSON: https://www.json.org/json-en.html + +.. |str| replace:: ``string`` +.. |arraynum| replace:: ``array[number]`` +.. |arraynumstr| replace:: ``array[number|string]`` +.. |arraystr| replace:: ``array[string]`` +.. |num| replace:: *number* +.. |strnum| replace:: *string|number* +.. |object| replace:: *object* +.. |array| replace:: *array* +.. |optional| replace:: ``optional`` + +.. |arrayrecord| replace:: ``array[record]`` +.. |arrayerror| replace:: ``array[errors]`` + +.. _admin-jsonrpc: + +JSONRPC API +*********** + + + +.. _admin-jsonrpc-description: + +Description +=========== + +|TS| Implements and exposes management calls using a JSONRPC API. This API is base on the following two things: + +* `JSON <https://www.json.org/json-en.html>`_ format. Lightweight data-interchange format. It is easy for humans to read and write. + It is easy for machines to parse and generate. It's basically a collection of name/value pairs. + +* `JSONRPC 2.0 <https://www.jsonrpc.org/specification>`_ protocol. Stateless, light-weight remote procedure call (RPC) protocol. + Primarily this specification defines several data structures and the rules around their processing. + + +In order for programs to communicate with |TS|, the server exposes a ``JSONRRPC 2.0`` API where programs can communicate with it. + + + + +.. _admnin-jsonrpc-configuration: + +Configuration +============= + +The |RPC| server can be configured using the following configuration file. + + +.. note:: + + |TS| will start the |RPC| server without any need for configuration. + + +In case a special configuration is needed, the following describes the structure. + + +File `jsonrpc.yaml` is a YAML format. The default configuration is:: + + + #YAML + rpc: + enabled: true + unix: + lock_path_name: /tmp/conf_jsonrpc.lock + sock_path_name: /tmp/conf_jsonrpc.sock + backlog: 5 + max_retry_on_transient_errors: 64 + + +===================== ========================================================================================= +Field Name Description +===================== ========================================================================================= +``enabled`` Enable/disable toggle for the whole implementation, server will not start if this is false/no +``unix`` Specific definitions as per transport. +===================== ========================================================================================= + + +IPC Socket (``unix``): + +===================================== ========================================================================================= +Field Name Description +===================================== ========================================================================================= +``lock_path_name`` Lock path, including the file name. (changing this may have impacts in :program:`traffic_ctl`) +``sock_path_name`` Sock path, including the file name. This will be used as ``sockaddr_un.sun_path``. (changing this may have impacts in :program:`traffic_ctl`) +``backlog`` Check https://man7.org/linux/man-pages/man2/listen.2.html +``max_retry_on_transient_errors`` Number of times the implementation is allowed to retry when a transient error is encountered. +===================================== ========================================================================================= + + +.. note:: + + As today, there is only 1 communication mechanism supported. IPC Sockets. + + + +.. note:: + + Traffic Control does support this RPC mechanism for communication with |TS| . Please check :program:`traffic_ctl` documentation for + more details. + + +.. _admin-jsonrpc-api: + +API +=== + + +.. _admin-jsonrpc-api-management: + +Administrative API +------------------ + +This section describe how to interact with the administrative RPC API to interact with |TS| + +.. + _This: We should explain how to deal with permission once it's implemented. + + + +.. _Records: + +Records +------- + +When interacting with the admin api, there are a few structures that need to be understood, this section will describe each of them. + + +.. _RecordRequest: + +RPC Record Request +^^^^^^^^^^^^^^^^^^ + +To obtain information regarding a particular record(s) from |TS|, we should use the following fields in an *unnamed* json structure. + + + ====================== ============= ================================================================================================================ + Field Type Description + ====================== ============= ================================================================================================================ + ``record_name`` |str| The name we want to query from |TS|. This is |optional| if ``record_name_regex`` is used. + ``record_name_regex`` |str| The regular expression we want to query from |TS|. This is |optional| if ``record_name`` is used. + ``rec_types`` |arraynumstr| |optional| A list of types that should be used to match against the found record. These types refer to ``RecT``. + Other values (in decimal) than the ones defined by the ``RecT`` ``enum`` will be ignored. If no type is + specified, the server will not match the type against the found record. + ====================== ============= ================================================================================================================ + +.. note:: + + If ``record_name`` and ``record_name_regex`` are both provided, the server will not use any of them. Only one should be provided. + + +Example: + + #. Single record: + + .. code-block:: json + + { + "id":"2947819a-8563-4f21-ba45-bde73210e387", + "jsonrpc":"2.0", + "method":"admin_lookup_records", + "params":[ + { + "record_name":"proxy.config.exec_thread.autoconfig.scale", + "rec_types":[ + 1, + 16 + ] + } + ] + } + + #. Multiple records: + + .. code-block:: json + :emphasize-lines: 5-12 + + { + "id": "ded7018e-0720-11eb-abe2-001fc69cc946", + "jsonrpc": "2.0", + "method": "admin_lookup_records", + "params": [{ + "record_name": "proxy.config.exec_thread.autoconfig.scale" + }, + { + "record_name": "proxy.config.log.rolling_interval_sec", + "rec_types": [1] + } + ] + } + + #. Batch Request + + .. code-block:: json + + [ + { + "id": "ded7018e-0720-11eb-abe2-001fc69cc946", + "jsonrpc": "2.0", + "method": "admin_lookup_records", + "params": [{ + "record_name_regex": "proxy.config.exec_thread.autoconfig.scale", + "rec_types": [1] + }] + }, { + "id": "dam7018e-0720-11eb-abe2-001fc69dd123", + "jsonrpc": "2.0", + "method": "admin_lookup_records", + "params": [{ + "record_name_regex": "proxy.config.log.rolling_interval_sec", + "rec_types": [1] + }] + } + ] + + +.. _RecordResponse: + + +RPC Record Response +^^^^^^^^^^^^^^^^^^^ + +When querying for a record(s), in the majority of the cases the record api will respond with the following json structure. + +=================== ==================== ======================================================================== +Field Type Description +=================== ==================== ======================================================================== +``recordList`` |arrayrecord| A list of record |object|. See `RecordRequestObject`_ +``errorList`` |arrayerror| A list of error |object| . See `RecordErrorObject`_ +=================== ==================== ======================================================================== + + +.. _RecordErrorObject: + +RPC Record Error Object +^^^^^^^^^^^^^^^^^^^^^^^ + +All errors that are found during a record query, will be returned back to the caller in the ``error_list`` field as part of the `RecordResponse`_ object. +The record errors have the following fields. + + +=================== ============= =========================================================================== +Field Type Description +=================== ============= =========================================================================== +``code`` |str| |optional| An error code that should be used to get a description of the error.(Add error codes) +``record_name`` |str| |optional| The associated record name, this may be omitted sometimes. +``message`` |str| |optional| A descriptive message. The server can omit this value. +=================== ============= =========================================================================== + + +Example: + + .. code-block:: json + :linenos: + + { + "code": "2007", + "record_name": "proxy.config.exec_thread.autoconfig.scale" + } + + +Examples: + +#. Request a non existing record among with an invalid type for a record: + + .. code-block:: json + :linenos: + + { + "id": "ded7018e-0720-11eb-abe2-001fc69cc946", + "jsonrpc": "2.0", + "method": "admin_lookup_records", + "params": [ + { + "record_name": "non.existing.record" + }, + { + "record_name": "proxy.process.http.total_client_connections_ipv4", + "rec_types": [1] + } + ] + } + + Line ``7`` requests a non existing record and in line ``11`` we request a type that does not match the record's type. + + .. code-block:: json + :linenos: + + { + "jsonrpc":"2.0", + "result":{ + "errorList":[ + { + "code":"2000", + "record_name":"non.existing.record" + }, + { + "code":"2007", + "record_name":"proxy.process.http.total_client_connections_ipv4" + } + ] + }, + "id":"ded7018e-0720-11eb-abe2-001fc69cc946" + } + + In this case we get the response indicating that the requested fields couldn't be retrieved. See `RecordErrorObject`_ for more details. + +.. _RecordErrorObject-Enum: + + +JSONRPC Record Errors +""""""""""""""""""""" + +The following errors could be generated when requesting record from the server. + +.. class:: RecordError + + .. enumerator:: RECORD_NOT_FOUND = 2000 + + Record not found. + + .. enumerator:: RECORD_NOT_CONFIG = 2001 + + Record is not a configuration type. + + .. enumerator:: RECORD_NOT_METRIC = 2002 + + Record is not a metric type. + + .. enumerator:: INVALID_RECORD_NAME = 2003 + + Invalid Record Name. + + .. enumerator:: VALIDITY_CHECK_ERROR = 2004 + + Validity check failed. + + .. enumerator:: GENERAL_ERROR = 2005 + + Error reading the record. + + .. enumerator:: RECORD_WRITE_ERROR = 2006 + + Generic error while writting the record. ie: RecResetStatRecord() returns REC_ERR_OKAY + + .. enumerator:: REQUESTED_TYPE_MISMATCH = 2007 + + The requested record's type does not match againts the passed type list. + + .. enumerator:: INVALID_INCOMING_DATA = 2008 + + This could be caused by an invalid value in the incoming request which may cause the parser to fail. + + +.. _RecordRequestObject: + +RPC Record Object +^^^^^^^^^^^^^^^^^ + +This is mapped from a ``RecRecord``, when requesting for a record the following information will be populated into a json |object|. +The ``record`` structure has the following members. + + =================== ======== ================================================================== + Record Field Type Description + =================== ======== ================================================================== + ``current_value`` |str| Current value that is held by the record. + ``default_value`` |str| Record's default value. + ``name`` |str| Record's name + ``order`` |str| Record's order + ``overridable`` |str| Records's overridable configuration. + ``raw_stat_block`` |str| Raw Stat Block Id. + ``record_class`` |str| Record type. Mapped from ``RecT`` + ``record_type`` |str| Record's data type. Mapped from RecDataT + ``version`` |str| Record's version. + ``stats_meta`` |object| Stats metadata `stats_meta`_ + ``config_meta`` |object| Config metadata `config_meta`_ + =================== ======== ================================================================== + + * it will be either ``config_meta`` or ``stats_meta`` object, but never both* + + +.. _config_meta: + +Config Metadata + + =================== ======== ================================================================== + Record Field Type Description + =================== ======== ================================================================== + `access_type` |str| Access type. This is mapped from ``TSRecordAccessType``. + `check_expr` |str| Syntax checks regular expressions. + `checktype` |str| Check type, This is mapped from ``RecCheckT``. + `source` |str| Source of the configuration value. Mapped from RecSourceT + `update_status` |str| Update status flag. + `update_type` |str| How the records get updated. Mapped from RecUpdateT + =================== ======== ================================================================== + + + .. _stats_meta: + + Stats Metadata (TBC) + + =================== ======== ================================================================== + Record Field Type Description + =================== ======== ================================================================== + `persist_type` |str| Persistent type. This is mapped from ``RecPersistT`` + =================== ======== ================================================================== + + +Example with config meta: + + .. code-block:: json + :linenos: + + { + "record":{ + "record_name":"proxy.config.diags.debug.tags", + "record_type":"3", + "version":"0", + "raw_stat_block":"0", + "order":"421", + "config_meta":{ + "access_type":"0", + "update_status":"0", + "update_type":"1", + "checktype":"0", + "source":"3", + "check_expr":"null" + }, + "record_class":"1", + "overridable":"false", + "data_type":"STRING", + "current_value":"rpc", + "default_value":"http|dns" + } + } + +Example with stats meta: + + .. code-block:: json + :linenos: + + { + "record": { + "current_value": "0", + "data_type": "COUNTER", + "default_value": "0", + "order": "8", + "overridable": "false", + "raw_stat_block": "10", + "record_class": "2", + "record_name": "proxy.process.http.total_client_connections_ipv6", + "record_type": "4", + "stat_meta": { + "persist_type": "1" + }, + "version": "0" + } + } + +.. _jsonrpc-admin-api: + +API list +-------- + +* `admin_lookup_records`_ + +* `admin_clear_all_metrics_records`_ + +* `admin_config_set_records`_ + +* `admin_config_reload`_ + +* `admin_clear_metrics_records`_ + +* `admin_clear_all_metrics_records`_ + +* `admin_host_set_status`_ + +* `admin_server_stop_drain`_ + +* `admin_server_start_drain`_ + +* `admin_plugin_send_basic_msg`_ + +* `admin_storage_get_device_status`_ + +* `admin_storage_set_device_offline`_ + + +show_registered_handlers + + + +.. _admin-jsonapi-management-records: + + +Records +^^^^^^^ + +.. _admin_lookup_records: + + +admin_lookup_records +^^^^^^^^^^^^^^^^^^^^ + + +Description +^^^^^^^^^^^ + +Obtain record(s) from TS. + + +Parameters +^^^^^^^^^^ + +* ``params``: A list of `RecordRequest`_ objects. + + +Result +^^^^^^ + +A list of `RecordResponse`_ . In case of any error obtaining the requested record, the `RecordErrorObject`_ |object| will be included. + + +Examples +^^^^^^^^ + +Request a configuration record, no errors: + + .. code-block:: json + + { + "id":"b2bb16a5-135a-4c84-b0a7-8d31ebd82542", + "jsonrpc":"2.0", + "method":"admin_lookup_records", + "params":[ + { + "record_name":"proxy.config.log.rolling_interval_sec", + "rec_types":[ + "1", + "16" + ] + } + ] + } + +Response: + + .. code-block:: json + + { + "jsonrpc":"2.0", + "result":{ + "recordList":[ + { + "record":{ + "record_name":"proxy.config.log.rolling_interval_sec", + "record_type":"1", + "version":"0", + "raw_stat_block":"0", + "order":"410", + "config_meta":{ + "access_type":"0", + "update_status":"0", + "update_type":"1", + "checktype":"1", + "source":"3", + "check_expr":"^[0-9]+$" + }, + "record_class":"1", + "overridable":"false", + "data_type":"INT", + "current_value":"86400", + "default_value":"86400" + } + } + ] + }, + "id":"b2bb16a5-135a-4c84-b0a7-8d31ebd82542" + } + + +Request a configuration record, some errors coming back: + + +Request: + + .. code-block:: json + + { + "id": "ded7018e-0720-11eb-abe2-001fc69cc946", + "jsonrpc": "2.0", + "method": "admin_lookup_records", + "params": [ + { + "rec_types": [1], + "record_name": "proxy.config.log.rolling_interval_sec" + }, + { + "record_name": "proxy.config.log.rolling_interv" + } + ] + } + + +Response: + + .. code-block:: json + + { + "jsonrpc":"2.0", + "result":{ + "recordList":[ + { + "record":{ + "record_name":"proxy.config.log.rolling_interval_sec", + "record_type":"1", + "version":"0", + "raw_stat_block":"0", + "order":"410", + "config_meta":{ + "access_type":"0", + "update_status":"0", + "update_type":"1", + "checktype":"1", + "source":"3", + "check_expr":"^[0-9]+$" + }, + "record_class":"1", + "overridable":"false", + "data_type":"INT", + "current_value":"86400", + "default_value":"86400" + } + } + ], + "errorList":[ + { + "code":"2000", + "record_name":"proxy.config.log.rolling_interv" + } + ] + }, + "id":"ded7018e-0720-11eb-abe2-001fc69cc946" + } + + +Request using a `regex` instead of the full name. + +.. note:: + + Regex lookups use ``record_name_regex` and not ``record_name``. Check `RecordRequestObject`_ . + +Examples +^^^^^^^^ + +#. Request a mix(config and stats) of records record using a regex, no errors: + + .. code-block:: json + + { + "id": "ded7018e-0720-11eb-abe2-001fc69cc946", + "jsonrpc": "2.0", + "method": "admin_lookup_records", + "params": [ + { + "rec_types": [1], + "record_name_regex": "proxy.config.exec_thread.autoconfig.sca*" + }, + { + "rec_types": [2], + "record_name_regex": "proxy.process.http.total_client_connections_ipv" + } + ] + } + + + Response: + + .. code-block:: json + + { + "jsonrpc":"2.0", + "result":{ + "recordList":[ + { + "record":{ + "record_name":"proxy.config.exec_thread.autoconfig.scale", + "record_type":"2", + "version":"0", + "raw_stat_block":"0", + "order":"355", + "config_meta":{ + "access_type":"2", + "update_status":"0", + "update_type":"2", + "checktype":"0", + "source":"3", + "check_expr":"null" + }, + "record_class":"1", + "overridable":"false", + "data_type":"FLOAT", + "current_value":"1", + "default_value":"1" + } + }, + { + "record":{ + "record_name":"proxy.process.http.total_client_connections_ipv4", + "record_type":"4", + "version":"0", + "raw_stat_block":"9", + "order":"7", + "stat_meta":{ + "persist_type":"1" + }, + "record_class":"2", + "overridable":"false", + "data_type":"COUNTER", + "current_value":"0", + "default_value":"0" + } + }, + { + "record":{ + "record_name":"proxy.process.http.total_client_connections_ipv6", + "record_type":"4", + "version":"0", + "raw_stat_block":"10", + "order":"8", + "stat_meta":{ + "persist_type":"1" + }, + "record_class":"2", + "overridable":"false", + "data_type":"COUNTER", + "current_value":"0", + "default_value":"0" + } + } + ] + }, + "id":"ded7018e-0720-11eb-abe2-001fc69cc946" + } + + + +#. Request a configuration record using a regex with some errors coming back: + + + Request: + + .. code-block:: json + :linenos: + + { + "id": "ded7018e-0720-11eb-abe2-001fc69cc946", + "jsonrpc": "2.0", + "method": "admin_lookup_records", + "params": [ + { + "rec_types": [1], + "record_name_regex": "proxy.config.exec_thread.autoconfig.sca*" + }, + { + "rec_types": [987], + "record_name_regex": "proxy.process.http.total_client_connections_ipv" + } + ] + } + + + Note the invalid ``rec_type`` at line ``11`` + + Response: + + .. code-block:: json + :linenos: + + { + "jsonrpc":"2.0", + "result":{ + "recordList":[ + { + "record":{ + "record_name":"proxy.config.exec_thread.autoconfig.scale", + "record_type":"2", + "version":"0", + "raw_stat_block":"0", + "order":"355", + "config_meta":{ + "access_type":"2", + "update_status":"0", + "update_type":"2", + "checktype":"0", + "source":"3", + "check_expr":"null" + }, + "record_class":"1", + "overridable":"false", + "data_type":"FLOAT", + "current_value":"1", + "default_value":"1" + } + } + ], + "errorList":[ + { + "code":"2008", + "message":"Invalid request data provided" + } + ] + }, + "id":"ded7018e-0720-11eb-abe2-001fc69cc946" + } + + + + We get a valid record that was found base on the passed criteria, ``proxy.config.exec_thread.autoconfig.sca*`` and the ``rec_type`` *1*. Review comment: maybe "was found based on"? ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
