Feedback fixes: net.box and vshard (#3491)

p7nov · web-flow · commit 8cb2ff81dc63 · 2023-06-05T15:24:19.000+03:00
Resolves #3399, #2680, #2459, #2405, #2262, #2273, #2483 * Add fetch_schema, reorder functions * Remove console param of net.box.connect * Fix translation or reconnect_after * Remove conn.timeout() from reference * Fix vshard bucket parameters * Fix mertics description and link
diff --git a/doc/book/admin/server_introspection.rst b/doc/book/admin/server_introspection.rst
@@ -107,7 +107,7 @@ To check the boot log, on systems with ``systemd``, say:
     Jan 21 21:17:47 localhost.localdomain tarantoolctl[5969]: /usr/bin/tarantoolctl: Starting instance...
     Jan 21 21:17:47 localhost.localdomain systemd[1]: Started Tarantool Database Server
 
-For more details, use the reports provided by functions in the following submodules:
+For more specific checks, use the reports provided by functions in the following submodules:
 
 * :doc:`/reference/reference_lua/box_cfg` (check and specify all
   configuration parameters for the Tarantool server)
@@ -121,10 +121,10 @@ For more details, use the reports provided by functions in the following submodu
 * :doc:`/reference/reference_lua/box_stat` (introspect Tarantool
   request and network statistics)
 
-You can also try `prometheus <https://github.com/tarantool/metrics/tree/master/metrics/plugins/prometheus>`_,
-a plugin that makes it easy to collect metrics (e.g. memory usage or number
-of requests) from Tarantool applications and databases and expose them via the
-Prometheus protocol.
+Finally, there is the `metrics <https://github.com/tarantool/metrics>`_
+library, which enables collecting metrics (such as memory usage or number
+of requests) from Tarantool applications and expose them via various
+protocols, including Prometheus. Check :ref:`Monitoring <monitoring>` for more details.
 
 **Example**
 
diff --git a/doc/reference/reference_lua/net_box.rst b/doc/reference/reference_lua/net_box.rst
@@ -160,29 +160,21 @@ Below is a list of all ``net.box`` functions.
 
 .. function:: connect(URI [, {option[s]}])
 
-    The names ``connect()`` and ``new()`` are synonyms: ``connect()`` is 
-    preferred; ``new()`` is retained for backward compatibility. For more 
-    information, see the description of ``net_box.new()`` below.
-
-.. _net_box-new:
-
-.. function:: new(URI [, {option[s]}])
-
     Create a new connection. The connection is established on demand, at the
     time of the first request. It can be re-established automatically after a
     disconnect (see ``reconnect_after`` option below).
     The returned ``conn`` object supports methods for making remote requests,
     such as select, update or delete.
-    
+
     :param string URI: the :ref:`URI <index-uri>` of the target for the connection
     :param options: the supported options are shown below:
-    
-        *   ``user/password``: two options to connect to a remote host other than through 
-            :ref:`URI <index-uri>`. For example, instead of ``connect('username:userpassword@localhost:3301')`` 
+
+        *   ``user/password``: two options to connect to a remote host other than through
+            :ref:`URI <index-uri>`. For example, instead of ``connect('username:userpassword@localhost:3301')``
             you can write ``connect('localhost:3301', {user = 'username', password='userpassword'})``.
 
-        *   ``wait_connected``: a connection timeout. By default, the connection is blocked until the connection 
-            is established, but if you specify ``wait_connected=false``, the connection returns immediately. 
+        *   ``wait_connected``: a connection timeout. By default, the connection is blocked until the connection
+            is established, but if you specify ``wait_connected=false``, the connection returns immediately.
             If you specify this timeout, it will wait before returning (``wait_connected=1.5`` makes it wait at most 1.5 seconds).
 
             .. NOTE::
@@ -191,43 +183,44 @@ Below is a list of all ``net.box`` functions.
                  The wait completes once the connection is established or is closed explicitly.
 
 
-        *   ``reconnect_after``: a number of seconds to wait before reconnecting. 
-            The default value, as with the other ``connect`` options, is ``nil``. If ``reconnect_after`` 
-            is greater than zero, then a ``net.box`` instance will attempt to reconnect if a connection 
-            is lost or a connection attempt fails. This makes transient network failures transparent to the application. 
-            Reconnection happens automatically in the background, so requests that initially fail due to connection drops 
-            fail, are transparently retried. The number of retries is unlimited, connection retries are made after 
-            any specified interval (for example, ``reconnect_after=5`` means that reconnect attempts are made every 5 seconds). 
-            When a connection is explicitly closed or when the Lua garbage collector removes it, then reconnect attempts stop. 
-        
+        *   ``reconnect_after``: a number of seconds to wait before reconnecting.
+            The default value, as with the other ``connect`` options, is ``nil``. If ``reconnect_after``
+            is greater than zero, then a ``net.box`` instance will attempt to reconnect if a connection
+            is lost or a connection attempt fails. This makes transient network failures transparent to the application.
+            Reconnection happens automatically in the background, so requests that initially fail due to connection drops
+            fail, are transparently retried. The number of retries is unlimited, connection retries are made after
+            any specified interval (for example, ``reconnect_after=5`` means that reconnect attempts are made every 5 seconds).
+            When a connection is explicitly closed or when the Lua garbage collector removes it, then reconnect attempts stop.
 
-        *   ``call_16``: [since 1.7.2] a new binary protocol command for CALL in ``net.box`` connections by default. 
-            The new CALL is not backward compatible with previous versions. It no longer restricts a function to 
-            returning an array of tuples and allows returning an arbitrary MsgPack/JSON result, 
-            including scalars, nil and void (nothing). The old CALL is left intact for backward compatibility. 
-            It will not be present in the next major release. All programming language drivers will gradually be switched 
-            to the new CALL. To connect to a Tarantool instance that uses the old CALL, specify ``call_16=true``.
 
-        *   ``console``: an option to use different connection support methods (as if instances of different 
-            classes are returned). With ``console = true``, you can use the ``conn`` methods ``close()``, 
-            ``is_connected()``, ``wait_state()``, ``eval()`` (in this case both binary and Lua console 
-            network protocols are supported). 
-            With ``console = false`` (default), you can also use ``conn`` database methods (in this case only the 
-            binary protocol is supported). Deprecation note: ``console = true`` is deprecated, users should use 
-            :ref:`console.connect() <console-connect>` instead.
+        *   ``call_16``: [since 1.7.2] a new binary protocol command for CALL in ``net.box`` connections by default.
+            The new CALL is not backward compatible with previous versions. It no longer restricts a function to
+            returning an array of tuples and allows returning an arbitrary MsgPack/JSON result,
+            including scalars, nil and void (nothing). The old CALL is left intact for backward compatibility.
+            It will not be present in the next major release. All programming language drivers will gradually be switched
+            to the new CALL. To connect to a Tarantool instance that uses the old CALL, specify ``call_16=true``.
 
         *   ``connect_timeout``: a number of seconds to wait before returning "error: Connection timed out".
 
-        *   ``required_protocol_version``: a minimum version of the :ref:`IPROTO protocol <box_protocol-id>` 
-            supported by the server. If the version of the :ref:`IPROTO protocol <box_protocol-id>` supported 
-            by the server is lower than specified, the connection will fail with an error message. 
-            With ``required_protocol_version = 1``, all connections fail where the :ref:`IPROTO protocol <box_protocol-id>` 
-            version is lower than ``1``.  
+        *   ``fetch_schema``: a boolean option that controls fetching schema changes from the server. Default: ``true``.
+            If you don't operate with remote spaces, for example, run only ``call`` or ``eval``, set ``fetch_schema`` to
+            ``false`` to avoid fetching schema changes which is not needed in this case.
+
+            .. important::
+
+                In connections with ``fetch_schema == false``, remote spaces are unavailable
+                and the :ref:`on_schema_reload <net_box-on_schema_reload>` triggers don't work.
 
-        *   ``required_protocol_features``: specified :ref:`IPROTO protocol features <box_protocol-id>` supported by the server. 
-            You can specify one or more ``net.box`` features from the table below. If the server does not 
-            support the specified features, the connection will fail with an error message. 
-            With ``required_protocol_features = {'transactions'}``, all connections fail where the 
+        *   ``required_protocol_version``: a minimum version of the :ref:`IPROTO protocol <box_protocol-id>`
+            supported by the server. If the version of the :ref:`IPROTO protocol <box_protocol-id>` supported
+            by the server is lower than specified, the connection will fail with an error message.
+            With ``required_protocol_version = 1``, all connections fail where the :ref:`IPROTO protocol <box_protocol-id>`
+            version is lower than ``1``.
+
+        *   ``required_protocol_features``: specified :ref:`IPROTO protocol features <box_protocol-id>` supported by the server.
+            You can specify one or more ``net.box`` features from the table below. If the server does not
+            support the specified features, the connection will fail with an error message.
+            With ``required_protocol_features = {'transactions'}``, all connections fail where the
             server has ``transactions: false``.
 
     ..  container:: table
@@ -240,26 +233,26 @@ Below is a list of all ``net.box`` functions.
                -   Use
                -   IPROTO feature ID
                -   IPROTO versions supporting the feature
-           *   -   ``streams``  
+           *   -   ``streams``
                -   Requires streams support on the server
-               -   IPROTO_FEATURE_STREAMS 
+               -   IPROTO_FEATURE_STREAMS
                -   1 and newer
            *   -   ``transactions``
                -   Requires transactions support on the server
-               -   IPROTO_FEATURE_TRANSACTIONS   
+               -   IPROTO_FEATURE_TRANSACTIONS
                -   1 and newer
            *   -   ``error_extension``
                -   Requires support for :ref:`MP_ERROR <msgpack_ext-error>` MsgPack extension on the server
-               -   IPROTO_FEATURE_ERROR_EXTENSION   
+               -   IPROTO_FEATURE_ERROR_EXTENSION
                -   2 and newer
            *   -   ``watchers``
                -   Requires remote :ref:`watchers <conn-watch>` support on the server
-               -   IPROTO_FEATURE_WATCHERS   
-               -   3 and newer      
-            
+               -   IPROTO_FEATURE_WATCHERS
+               -   3 and newer
+
     To learn more about IPROTO features, see :ref:`IPROTO_ID <box_protocol-id>`
     and the :ref:`IPROTO_FEATURES <internals-iproto-keys-features>` key.
- 
+
     :return: conn object
     :rtype:  userdata
 
@@ -268,12 +261,19 @@ Below is a list of all ``net.box`` functions.
     .. code-block:: lua
 
         net_box = require('net.box')
-        
+
         conn = net_box.connect('localhost:3301')
         conn = net_box.connect('127.0.0.1:3302', {wait_connected = false})
         conn = net_box.connect('127.0.0.1:3303', {reconnect_after = 5, call_16 = true})
         conn = net_box.connect('127.0.0.1:3304', {required_protocol_version = 4, required_protocol_features = {'transactions', 'streams'}, })
 
+.. _net_box-new:
+
+.. function:: new(URI [, {option[s]}])
+
+    ``new()`` is a synonym for ``connect()``. It is retained for backward compatibility.
+    For more information, see the description of :ref:`net_box.connect() <net_box-connect>`.
+
 .. _net_box-self:
 
 .. class:: self
@@ -562,13 +562,13 @@ Below is a list of all ``net.box`` functions.
         The method has the same syntax as the :doc:`box.watch() </reference/reference_lua/box_events/broadcast>`
         function, which is used for subscribing to events locally.
 
-        Watchers survive reconnection (see the ``reconnect_after`` connection :ref:`option <net_box-new>`).
+        Watchers survive reconnection (see the ``reconnect_after`` connection :ref:`option <net_box-connect>`).
         All registered watchers are automatically resubscribed when the
         connection is reestablished.
 
         If a remote host supports watchers, the ``watchers`` key will be set in the
         connection ``peer_protocol_features``.
-        For details, check the :ref:`net.box features table <net_box-new>`.
+        For details, check the :ref:`net.box features table <net_box-connect>`.
 
         ..  note::
 
@@ -603,28 +603,6 @@ Below is a list of all ``net.box`` functions.
 
             w:unregister()
 
-    .. _conn-timeout:
-
-    .. method:: timeout(timeout)
-
-        ``timeout(...)`` is a wrapper which sets a timeout for the request that
-        follows it. Since version 1.7.4 this method is deprecated -- it is better
-        to pass a timeout value for a method's ``{options}`` parameter.
-
-        **Example:**
-
-        .. code-block:: lua
-
-            conn:timeout(0.5).space.tester:update({1}, {{'=', 2, 15}})
-
-        Although ``timeout(...)`` is deprecated, all
-        remote calls support its use. Using a wrapper object makes
-        the remote connection API compatible with the local one, removing the need
-        for a separate ``timeout`` argument, which the local version would ignore. Once
-        a request is sent, it cannot be revoked from the remote server even if a
-        timeout expires: the timeout expiration only aborts the wait for the remote
-        server response, not the request itself.
-
     ..  _net_box-is_async:
 
     ..  method:: request(... {is_async=...})
diff --git a/doc/reference/reference_rock/vshard/vshard_router.rst b/doc/reference/reference_rock/vshard/vshard_router.rst
@@ -710,19 +710,19 @@ Router public API
 
     Bucket parameters:
 
-    * ``available_ro``—the number of buckets known to the ``router`` and available for read requests
-    * ``available_rw``—the number of buckets known to the ``router`` and available for read and write requests
-    * ``unavailable``—the number of buckets known to the ``router`` but unavailable for any requests
-    * ``unreachable``—the number of buckets whose replica sets are not known to the ``router``
+    * ``available_ro`` -- the number of buckets known to the ``router`` and available for read requests
+    * ``available_rw`` -- the number of buckets known to the ``router`` and available for read and write requests
+    * ``unreachable`` -- the number of buckets known to the ``router`` but unavailable for any requests
+    * ``unknown`` -- the number of buckets whose replica sets are not known to the ``router``
 
     Service parameters:
 
-    * ``name`` — service name. Possible values: ``discovery``, ``failover``, ``master_search``.
-    * ``status`` — service status. Possible values: ``ok``, ``error``.
-    * ``error`` — error message that appears on the ``error`` status.
-    * ``activity`` — service state. It shows what the service is currently doing
+    * ``name`` -- service name. Possible values: ``discovery``, ``failover``, ``master_search``.
+    * ``status`` -- service status. Possible values: ``ok``, ``error``.
+    * ``error`` -- error message that appears on the ``error`` status.
+    * ``activity`` -- service state. It shows what the service is currently doing
       (for example, ``updating replicas``).
-    * ``status_idx`` — incrementing counter of the status changes.
+    * ``status_idx`` -- incrementing counter of the status changes.
       The ``ok`` status is updated on every successful iteration of the service.
       The ``error`` status is updated only when it is fixed.
 
diff --git a/locale/ru/LC_MESSAGES/reference/reference_lua/net_box.po b/locale/ru/LC_MESSAGES/reference/reference_lua/net_box.po
@@ -355,7 +355,7 @@ msgid ""
 msgstr ""
 "`reconnect_after`: ``net.box`` автоматически подключается повторно в случае "
 "разрыва соединения или провала попытки подключения. В таком случае "
-"неустойчивые сетевые отказы становятся очевидными. Повторное подключение "
+"точечные сетевые проблемы не влияют на работу приложения. Повторное подключение "
 "выполняется автоматически в фоновом режиме, поэтому запросы/обращения, не "
 "выполненные по причине потери соединения, явным образом выполняются "
 "повторно. Количество повторов не ограничено, попытки подключения выполняются"
