tarantool-client 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c88acf7dfc96a8094a2c1562b7d98c86ae22670dc1cc853f69b8324df14bada
-  data.tar.gz: c46e62c20535c8733329f6ec9db242d5a1ab9b5bd0cf0b0205c330ac80961538
+  metadata.gz: 312e13dccce60b22bb3e74005e914cadcbf6dbbf096d378759a2697e6c0a1e8c
+  data.tar.gz: f0fd02d53f7bbb97ee347f7b81b1e9a9f83476a5af871042036b025c9cbb8060
 SHA512:
-  metadata.gz: 44fe72a002d29b8565fa35dcc812dfeaebcc6e8eb67a7993a275deab03136f628f235ffb345eb3df1a31ef41f9e5cedd144b27aa1a9ef53d46e54c931a3a7cf9
-  data.tar.gz: 424b07a9cd9d143c153303f07aa5986270ea0f2b1fc3acbe1c88230dff7f99d135824ad3a27676adff696cf8d5850e4b18c8486bd087d7f72aeff41d0c149027
+  metadata.gz: 81512742b3dfc97f726a1af22d2bbfd578cd083cc2dd75f3cbe3c4004bde4e1e73ee21ba03675581b7586d590c2624e6287bc8040ee281e3b3fe85ef8c093f4e
+  data.tar.gz: 8e4390ef152eab60197e2a5822a132266b12c4eb567801017a2dd0308426109823230b86df6700b1e220f9353f9de892cbe634acaa4d89578ff84c99167ead89

data/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## 0.1.0 (unreleased)
+## 0.3.0 (2026-10-17)
+
+- `select(fetch_position: true)` returns a `Page` with the server-side position of the last tuple; `after:` takes that position (String) as well as a tuple.
+- Graceful shutdown: the client subscribes to `box.shutdown`; on the event it stops sending, a `Pool` member leaves the rotation, requests in flight finish, and the connection is closed by the client before the server stops (`shutdown.tarantool` event, `disconnect.tarantool` with the reason `server ... is shutting down`).
+
+## 0.2.0 (2026-10-17)
+
+- `as: :hash` and `as: :row` on `select`, `insert`, `replace`, `update` and `delete` return tuples as Hashes by the space format (`Client::Row` keeps the raw tuple too); `SpaceInfo#to_hash` and `#to_tuple` do the conversion.
+- `insert`, `replace` and `upsert` accept a Hash; missing fields go out as nil, an unknown key raises `ArgumentError`.
+- The format comes from the schema the request runs against; a schema change makes the server reject the request and the retry rebuilds it by the new format. A numeric space id unknown to the cache costs one reload too, like a name.
+- A Hash key unknown to the cached format costs one schema reload; a field still missing after it raises `UnknownFieldError` (an `ArgumentError`). Inside a transaction there is no reload.
+- An unknown numeric space id paired with a named index now raises `SchemaError` with "space 'N' not found" instead of "index '...' not found in space N".
+- `delete_by`: delete every tuple matching a key on any TREE index, including non-unique ones, in keyset batches; not atomic outside a transaction, the error carries `#deleted`.
+- `instrumenter:` option on `Client` and `Pool`: `request.tarantool` for every call and transaction step, plus `disconnect`, `reconnect`, `reconnect_failed`, `fork` and `role_change` events. Payloads carry no keys, tuples, arguments, bindings or credentials; exceptions use ActiveSupport's `exception` and `exception_object` keys.
+- `logger:` option: a debug line per request, lifecycle lines, and background warnings that used to go to stderr.
+
+## 0.1.0 (2026-10-16)
 
 First release.
 

data/README.md

@@ -42,6 +42,8 @@ URIs: `tcp://user:password@host:port`, `host:port`, `unix:/path/to/socket`. Keyw
 | `reconnect_delay` | `0.1` | base delay of the exponential backoff |
 | `reconnect_max_delay` | `5` | cap of the backoff delay |
 | `max_frame_size` | `67108864` (64 MB) | maximum allowed response frame size in bytes; larger frames raise `ProtocolError` and break the connection |
+| `instrumenter` | `nil` | receives request and lifecycle events; see [Instrumentation](#instrumentation) |
+| `logger` | `nil` | `Logger`-compatible; one debug line per request, lifecycle lines, background warnings |
 
 Tarantool Community Edition has no TLS support. Authentication uses chap-sha1; the password is never sent in clear. `client.inspect` leaves the password out, and `Configuration#inspect`, `#to_s` and `pp` replace it with `[FILTERED]`. `Configuration#to_h` keeps it, so `Tarantool::Client.new(**client.config.to_h)` connects with the same credentials; don't log it.
 
@@ -70,6 +72,33 @@ page = client.select(:users, [18], index: :age, iterator: :ge, limit: 50)
 next_page = client.select(:users, [18], index: :age, iterator: :ge, limit: 50, after: page.last)
 ```
 
+With `fetch_position: true` the server hands back a position instead, so the caller carries an opaque String rather than the last tuple (`IPROTO_FETCH_POSITION`, `IPROTO_POSITION`, `IPROTO_AFTER_POSITION`; 2.11+). `select` then returns a `Client::Page`: `tuples` (converted by `as:` as usual, also reachable through `each`), and `position`, nil once a page comes back empty. A position is tied to the index and iterator of the select that produced it; don't parse it or reuse it with another index. `after:` accepts a position (String) or a tuple (Array).
+
+```ruby
+page = client.select(:users, [18], index: :age, iterator: :ge, limit: 50, fetch_position: true)
+until page.empty?
+  page.each { |user| ... }
+  page = client.select(:users, [18], index: :age, iterator: :ge, limit: 50, fetch_position: true, after: page.position)
+end
+```
+
+`delete_by` deletes every tuple a select finds, including by a non-unique index, which IPROTO `DELETE` can't do. It selects `batch_size` tuples at a time (default 1000), continues past the last one with `after:`, deletes each by primary key, and returns the number deleted. TREE indexes only, like `after:`. Multikey and functional indexes are not supported either: tuple-based `after` raises `ServerError` there, before deleting anything.
+
+```ruby
+client.delete_by(:users, [18], index: :age)                                   # => 42
+client.delete_by(:users, [18], index: :age, iterator: :lt, batch_size: 500, timeout: 30)
+```
+
+Outside a transaction `delete_by` is **not atomic**: the batches are separate requests, and if one fails the tuples deleted so far stay deleted. The raised error is the original one (`TimeoutError`, `ConnectionError`, `ServerError`, ...) with `#deleted` set to the number of deletes confirmed before the failure (a delete cut off by a timeout or a lost connection may still have run, so treat it as a lower bound); `deleted` is filled only by `delete_by` and is `nil` on every other error. Tuples inserted while it runs are deleted if they land ahead of the cursor; tuples inserted **behind the cursor are not deleted**. `timeout:` bounds the whole operation; without it each request gets `request_timeout`.
+
+Inside a transaction it is atomic — a failure rolls back every delete:
+
+```ruby
+client.transaction { |tx| tx.delete_by(:users, [18], index: :age) }
+```
+
+This needs `memtx_use_mvcc_engine = true` on the server, like any transaction on memtx.
+
 `space_info` returns the format and indexes from the same schema cache; an unknown name costs one reload. Inside a transaction it reads the schema the transaction started with; on a `Pool` it accepts `mode:`.
 
 ```ruby
@@ -79,6 +108,17 @@ info.primary_index.parts.map(&:name) # => ["id"]
 info.indexes['age'].unique           # => false
 ```
 
+`as: :hash` returns tuples as Hashes keyed by field name; fields beyond the format are keyed by their 0-based position. `as: :row` returns `Client::Row` with the raw `tuple` and its `attributes`. `insert`, `replace` and `upsert` take a Hash too: Symbol or String names, missing fields go out as nil, an unknown name raises `ArgumentError`. A key may also be an Integer position past the format, up to 1024 positions beyond it; a negative position or one further out also raises `ArgumentError`. The format comes from the same schema the request carries the version of, so an alter in between makes the server reject the request and the client rebuilds it by the new format. This works the same in transactions and on a `Pool`.
+
+```ruby
+client.insert(:users, { id: 42, email: 'a@b.c', age: 0 })
+client.select(:users, [42], as: :hash) # => [{ id: 42, email: "a@b.c", age: 0 }]
+row = client.select(:users, [42], as: :row).first
+row.tuple                              # => [42, "a@b.c", 0]
+row.attributes                         # => { id: 42, email: "a@b.c", age: 0 }
+info.to_hash([42, 'a@b.c', 0])         # => { id: 42, email: "a@b.c", age: 0 }
+```
+
 ## Lua
 
 ```ruby
@@ -158,6 +198,12 @@ pool.close
 
 Roles come from `box.status` (`is_ro`), so a switchover is picked up as soon as the instances report it. Requests are spread round-robin among matching instances. If none matches, the call raises `NoAvailableInstanceError`. `Pool.new` raises it only if no address answers; addresses that are down keep being retried in the background. That retrying covers start-up only: once connected, a member relies on its client's reconnect, so with a finite `reconnect_attempts` a member that gives up stays out of rotation. `Pool#close` may wait for an in-progress background connect attempt, up to `connect_timeout` + `request_timeout`. Options are passed to each client. A prepared statement from `pool.prepare` stays bound to the instance that prepared it.
 
+## Graceful shutdown
+
+Tarantool 2.10+ announces `SIGTERM` through the `box.shutdown` event and waits, up to `box.ctl.set_on_shutdown_timeout` (3 s by default), for the connections subscribed to it to close. Every `Client` subscribes. When the event arrives the client stops sending: `connected?` turns false, a `Pool` member leaves the rotation at once, and new requests on a bare `Client` wait for the next connection as they do while reconnecting. Requests already in flight get their replies; once none is left, or after `request_timeout`, the client closes the connection itself with the reason `server <address> is shutting down` and the usual reconnect follows. A transaction open on that connection fails on its next request, as after any loss. Nothing is retried elsewhere.
+
+Watching `box.shutdown` yourself works as before; the client's own subscription is never unwatched.
+
 ## Forking servers
 
 `Client` and `Pool` are fork-safe. The first request in a child process after `fork` reinitializes the connection transparently — a new socket is opened, background threads are restarted, and watchers are resubscribed. The parent's connection is unaffected.
@@ -166,6 +212,43 @@ Streams (interactive transactions) cannot cross a fork boundary. Using a stream
 
 No configuration is needed; the detection is a single PID comparison on every request.
 
+## Instrumentation
+
+```ruby
+client = Tarantool::Client.new(uri, instrumenter: ActiveSupport::Notifications, logger: Rails.logger)
+```
+
+`instrumenter:` takes any object with `instrument(name, payload) { }`, so `ActiveSupport::Notifications` works as is. `logger:` takes any `Logger`-compatible object. `Pool` accepts both and passes them to every member. Without either, no payload is built and nothing is timed; the request path only goes through a few extra method calls. `benchmark/request_overhead.rb` measures this.
+
+Every call emits `request.tarantool`, transactions included (`begin`, each operation, `commit` or `rollback`). A retry after a schema change is part of the same event. `delete_by` emits one `request.tarantool` per select or delete batch; there is no separate event for it. A key appears only when it has a value:
+
+| Key | Value |
+|---|---|
+| `request` | absent when a space, index or field name failed to resolve, so the request was never built; otherwise `:select`, `:insert`, `:replace`, `:update`, `:upsert`, `:delete`, `:call`, `:eval`, `:execute`, `:prepare`, `:ping`, `:begin`, `:commit`, `:rollback` |
+| `space`, `index` | as passed (name or id); `index` only for select, update, delete, and only once the request is built |
+| `function` | function name of a call |
+| `sql` / `statement_id` | SQL text, or the id of a prepared statement |
+| `address` | `host:port` or socket path of the instance |
+| `schema_reloaded` | `true` when the call reloaded the schema |
+| `exception`, `exception_object` | `[class name, message]` and the exception, as ActiveSupport sets them |
+
+Keys, tuples, update operations, call and eval arguments, SQL bindings, the eval expression and credentials are never included. The exception message and the SQL text can still carry data: a duplicate-key `ServerError` quotes the tuple, and `sql` is the statement as passed.
+
+Lifecycle events have the instance `address` too. Subscribers should be fast: `disconnect.tarantool` is emitted on the reconnect thread before it backs off and retries, and `Client#close` waits for that thread to finish.
+
+| Event | Payload | Log level |
+|---|---|---|
+| `disconnect.tarantool` | `reason` | warn |
+| `reconnect.tarantool` | `attempts` | info |
+| `reconnect_failed.tarantool` | `attempts` (when known), `exception`, `exception_object` | error |
+| `fork.tarantool` | | info |
+| `role_change.tarantool` | `read_only` (pool members) | info |
+| `shutdown.tarantool` | `pending` (requests in flight when the server announced its shutdown) | info |
+
+`role_change.tarantool` fires only when the role actually changes, not on the first report after connecting.
+
+The logger writes requests at debug, one line each: `tarantool select space=users index=email 1.24ms 127.0.0.1:3301`. A failed request's line shows the exception class and, when it has one, its code, e.g. `error=Tarantool::ServerError(3)`, never the message. Background warnings (a failing callback hook, a pool member that gave up) go to the logger as well, or to stderr without one.
+
 ## Errors
 
 ```
@@ -181,9 +264,13 @@ Tarantool::Error
 └── NoAvailableInstanceError
 ```
 
+`#deleted` is set only on errors raised by `delete_by` (see Data); it is `nil` otherwise.
+
 The error classes are flat under `Tarantool::`, e.g. `Tarantool::ServerError`, not `Tarantool::Client::ServerError`.
 tarantool-crud and tarantool-model errors also descend from `Tarantool::Error`.
 
+`Tarantool::UnknownFieldError` (an `ArgumentError`, not under `Tarantool::Error`) is raised for a Hash tuple key naming a field missing from the format.
+
 `box.error` objects inside returned data decode into `Tarantool::Client::BoxError`.
 
 ## Development
@@ -197,6 +284,12 @@ INTEGRATION=1 TARANTOOL_URI=tcp://app:secret@localhost:3301 bundle exec rspec
 bundle exec rubocop
 ```
 
+Instrumentation overhead against the container on 3301:
+
+```sh
+bundle exec ruby -Ilib benchmark/request_overhead.rb
+```
+
 Reconnect and pool specs restart their own pair of instances:
 
 ```sh
@@ -208,10 +301,12 @@ bundle exec rspec --tag failover
 
 Using podman instead of docker: prefix the `bundle exec rspec --tag failover` command above with `CONTAINER_CLI=podman`; the reconnect spec uses it to restart containers (default `docker`).
 
+Don't create multikey indexes on these containers: with `memtx_use_mvcc_engine = true`, inserting into a space with a multikey index segfaults Tarantool 2.11, and 3.x refuses to create the index.
+
 ## Public API
 
 `Tarantool::Client`, `Tarantool::Client::Pool`, `Tarantool::Client::Stream` (yielded by `transaction`),
-`Watcher` (returned by `watch`), `SqlResult`, `PreparedStatement`, `SpaceInfo`, `IndexInfo`, `Configuration`
+`Watcher` (returned by `watch`), `SqlResult`, `PreparedStatement`, `SpaceInfo`, `IndexInfo`, `Row`, `Page`, `Configuration`
 (returned by `client.config`), `Tarantool::Client::UUID`, `Interval`, `BoxError`, and the error classes above.
 
 Everything else, including anything tagged `@api private` in its source comment, is an implementation detail

data/lib/tarantool/client/batch_delete.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Deletes every tuple a select over a TREE index finds: keyset pages via `after`, then one delete per tuple
+    # by primary key. Drives only the public operations of its target, so it runs the same on Client and Stream.
+    # @api private
+    class BatchDelete
+      # Internal signal that the overall deadline ran out; `call` turns it into the public delete_by message.
+      class DeadlineExceeded < StandardError; end
+      private_constant :DeadlineExceeded
+
+      def initialize(target, space, key, index:, iterator:, batch_size:, timeout:)
+        validate_batch_size(batch_size)
+
+        @target = target
+        @space = space
+        @key = key
+        @index = index
+        @iterator = iterator
+        @batch_size = batch_size
+        @timeout = timeout
+        @deadline = Transport::Deadline.after(timeout)
+        @deleted = 0
+      end
+
+      def call
+        delete_pages(primary_fieldnos)
+      rescue DeadlineExceeded
+        raise deadline_timeout_error, cause: nil
+      rescue TimeoutError => e
+        raise deadline_timeout_error if @deadline
+
+        e.deleted = @deleted
+        raise
+      rescue Error => e
+        e.deleted = @deleted
+        raise
+      end
+
+      private
+
+      def validate_batch_size(batch_size)
+        return if batch_size.is_a?(Integer) && batch_size.positive?
+
+        raise ArgumentError, "batch_size must be a positive Integer, got #{batch_size.inspect}"
+      end
+
+      def delete_pages(fieldnos)
+        cursor = nil
+
+        loop do
+          batch = fetch(cursor)
+          delete_all(batch, fieldnos)
+          return @deleted if batch.size < @batch_size
+
+          cursor = batch.last
+        end
+      end
+
+      def primary_fieldnos
+        parts = @target.space_info(@space, timeout: remaining).primary_index.parts
+        raise ArgumentError, 'delete_by cannot build a primary key from a JSON path part' if parts.any?(&:path)
+
+        parts.map(&:fieldno)
+      end
+
+      def fetch(cursor)
+        @target.select(@space, @key, index: @index, iterator: @iterator, limit: @batch_size, after: cursor,
+                                     timeout: remaining)
+      end
+
+      def delete_all(batch, fieldnos)
+        batch.each do |tuple|
+          @deleted += 1 if @target.delete(@space, tuple.values_at(*fieldnos), timeout: remaining)
+        end
+      end
+
+      def deadline_timeout_error
+        error = TimeoutError.new("delete_by did not finish within #{@timeout}s")
+        error.deleted = @deleted
+
+        error
+      end
+
+      # nil leaves each request on the connection's request_timeout.
+      def remaining
+        return unless @deadline
+
+        left = Transport::Deadline.remaining(@deadline)
+        raise DeadlineExceeded if left.zero?
+
+        left
+      end
+    end
+  end
+end

data/lib/tarantool/client/configuration.rb

@@ -8,7 +8,7 @@ module Tarantool
     Configuration = Data.define(
       :host, :port, :path, :user, :password, :connect_timeout, :request_timeout,
       :reconnect, :reconnect_attempts, :reconnect_delay, :reconnect_max_delay,
-      :max_frame_size
+      :max_frame_size, :instrumenter, :logger
     ) do
       def self.build(uri = nil, **options)
         new(**defaults, **parse_uri(uri), **options)
@@ -18,7 +18,7 @@ module Tarantool
         {
           host: 'localhost', port: 3301, path: nil, user: nil, password: nil, connect_timeout: 3, request_timeout: 10,
           reconnect: true, reconnect_attempts: Float::INFINITY, reconnect_delay: 0.1, reconnect_max_delay: 5,
-          max_frame_size: 64 * 1024 * 1024
+          max_frame_size: 64 * 1024 * 1024, instrumenter: nil, logger: nil
         }
       end
 
@@ -59,13 +59,30 @@ module Tarantool
       end
 
       def inspect
-        fields = to_h.merge(password: password && '[FILTERED]').map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
+        fields = to_h.map { |key, value| "#{key}=#{inspect_field(key, value)}" }.join(', ')
 
         "#<data #{self.class.name} #{fields}>"
       end
       alias_method :to_s, :inspect
 
       def pretty_print(printer) = printer.text(inspect)
+
+      private
+
+      def inspect_field(key, value)
+        case key
+        when :password then (value && '[FILTERED]').inspect
+        when :instrumenter, :logger then inspect_object(value)
+        else value.inspect
+        end
+      end
+
+      def inspect_object(value)
+        return 'nil' unless value
+
+        klass = value.is_a?(Module) ? value : value.class
+        klass.name ? "#<#{klass.name}>" : klass.inspect
+      end
     end
   end
 end

data/lib/tarantool/client/diagnostics.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Warnings from background threads: to the configured logger, else to stderr.
+    # @api private
+    module Diagnostics
+      module_function
+
+      # Called from rescue blocks of background threads, which must outlive a broken logger.
+      def warn(logger, message)
+        return Kernel.warn(message) unless logger
+
+        logger.warn(message)
+      rescue StandardError
+        Kernel.warn(message)
+      end
+    end
+  end
+end

data/lib/tarantool/client/errors.rb

@@ -2,7 +2,11 @@
 
 module Tarantool
   # Base class for every error raised by tarantool-ruby gems.
-  class Error < StandardError; end
+  class Error < StandardError
+    # Rows delete_by confirmed deleted before it failed (a lower bound); nil for errors raised by any other operation.
+    # Writer is @api private, for BatchDelete only.
+    attr_accessor :deleted
+  end
 
   # Socket-level failure: refused, lost or broken connection.
   class ConnectionError < Error; end
@@ -29,6 +33,9 @@ module Tarantool
   # Space or index name cannot be resolved.
   class SchemaError < Error; end
 
+  # A Hash tuple names a field missing from the space format.
+  class UnknownFieldError < ArgumentError; end
+
   # Transaction misuse or a transaction that can no longer proceed.
   class TransactionError < Error; end
 

data/lib/tarantool/client/fork_safety.rb

@@ -17,6 +17,7 @@ module Tarantool
       def reopen_after_fork
         close_inherited_link
         open_link
+        @instrumentation&.notify('fork.tarantool')
       end
 
       # Joining a thread that died with an exception re-raises it; nothing from the parent may stop the reopen.
@@ -26,16 +27,24 @@ module Tarantool
         nil
       end
 
-      # Watcher registrations outlive a fork; on_ready resubscribes them on the new link.
+      # Watcher registrations outlive a fork; on_ready resubscribes them on the new link, the shutdown
+      # subscription among them.
       def open_link
-        @link = Transport::Link.new(@config, **link_hooks)
+        @link = Transport::Link.new(@config, instrumentation: @instrumentation, **link_hooks)
         @watchers&.restart_after_fork(@link)
+        first = @watchers.nil?
         @watchers ||= Watchers.new(@link, timeout: @config.request_timeout)
         @link.event_handler = @watchers.method(:dispatch)
         @schema_cache = SchemaCache.new
         @stream_ids = Transport::StreamIds.new
         @link.connect
         @pid = Process.pid
+        subscribe_to_shutdown if first
+      end
+
+      # box.shutdown is true once the server starts stopping; the value on subscribing is nil before that.
+      def subscribe_to_shutdown
+        @watchers.add('box.shutdown', ->(_key, value) { @link.drain if value })
       end
     end
   end

data/lib/tarantool/client/instrumentation/log_instrumenter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    class Instrumentation
+      # A logger as an instrumenter, around the user's instrumenter if there is one. The request line is built
+      # only when the logger takes debug.
+      # @api private
+      class LogInstrumenter
+        def initialize(logger, instrumenter)
+          @logger = logger
+          @instrumenter = instrumenter
+        end
+
+        def instrument(name, payload, &)
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          @instrumenter ? @instrumenter.instrument(name, payload, &) : yield
+        ensure
+          log(name, payload, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
+        end
+
+        private
+
+        def log(name, payload, duration)
+          level = LogLines.level(name)
+
+          @logger.public_send(level) { LogLines.line(name, payload, duration) } if level
+        rescue StandardError => e
+          Kernel.warn("tarantool logger failed: #{e.class}: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/client/instrumentation/log_lines.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    class Instrumentation
+      # Log level and line of each event the client emits.
+      # @api private
+      module LogLines
+        LEVELS = {
+          'request.tarantool' => :debug, 'disconnect.tarantool' => :warn, 'reconnect.tarantool' => :info,
+          'reconnect_failed.tarantool' => :error, 'fork.tarantool' => :info, 'role_change.tarantool' => :info,
+          'shutdown.tarantool' => :info
+        }.freeze
+
+        LINES = {
+          'request.tarantool' => ->(payload, duration) { request(payload, duration) },
+          'disconnect.tarantool' => lambda do |payload, _duration|
+            "tarantool disconnected from #{payload[:address]}: #{payload[:reason]}"
+          end,
+          'reconnect.tarantool' => lambda do |payload, _duration|
+            "tarantool reconnected to #{payload[:address]} after #{attempts(payload[:attempts])}"
+          end,
+          'reconnect_failed.tarantool' => lambda do |payload, _duration|
+            "tarantool gave up reconnecting to #{payload[:address]}: #{error(payload)}"
+          end,
+          'fork.tarantool' => lambda do |payload, _duration|
+            "tarantool reopened connection to #{payload[:address]} after fork"
+          end,
+          'role_change.tarantool' => lambda do |payload, _duration|
+            "tarantool #{payload[:address]} is now #{payload[:read_only] ? 'read-only' : 'writable'}"
+          end,
+          'shutdown.tarantool' => lambda do |payload, _duration|
+            "tarantool #{payload[:address]} is shutting down, #{requests(payload[:pending])} in flight"
+          end
+        }.freeze
+
+        module_function
+
+        def level(name) = LEVELS[name]
+
+        def line(name, payload, duration) = LINES[name]&.call(payload, duration)
+
+        def request(payload, duration)
+          parts = [request_name(payload)]
+          %i[space index function].each { |key| parts << "#{key}=#{payload[key]}" if payload.key?(key) }
+          parts << format('%.2fms', duration * 1000) << payload[:address]
+          parts << "error=#{request_error(payload)}" if payload.key?(:exception)
+          parts << 'schema_reloaded' if payload[:schema_reloaded]
+
+          parts.join(' ')
+        end
+
+        def request_name(payload) = payload[:request] ? "tarantool #{payload[:request]}" : 'tarantool'
+
+        def attempts(count) = count == 1 ? '1 attempt' : "#{count} attempts"
+        def requests(count) = count == 1 ? '1 request' : "#{count} requests"
+        def error(payload) = payload[:exception].join(': ')
+
+        # The message may quote data (ER_TUPLE_FOUND repeats the tuple), so the request line keeps only the
+        # class and, when the exception has one, its code.
+        def request_error(payload)
+          exception = payload[:exception_object]
+          klass = exception ? exception.class.name : payload[:exception].first
+          code = exception.respond_to?(:code) ? exception.code : nil
+
+          code ? "#{klass}(#{code})" : klass
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/client/instrumentation/request_payload.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    class Instrumentation
+      # Request event fields taken from a request. Keys, tuples, arguments and bindings stay out: they may hold
+      # personal data.
+      # @api private
+      module RequestPayload
+        NAMES = {
+          Protocol::Requests::Ping => :ping, Protocol::Requests::Select => :select,
+          Protocol::Requests::Insert => :insert, Protocol::Requests::Replace => :replace,
+          Protocol::Requests::Update => :update, Protocol::Requests::Upsert => :upsert,
+          Protocol::Requests::Delete => :delete, Protocol::Requests::Call => :call,
+          Protocol::Requests::Eval => :eval, Protocol::Requests::Execute => :execute,
+          Protocol::Requests::Prepare => :prepare, Protocol::Requests::Begin => :begin,
+          Protocol::Requests::Commit => :commit, Protocol::Requests::Rollback => :rollback
+        }.freeze
+
+        module_function
+
+        def build(request) = describe({}, request)
+
+        # Space operations pass the resolved index in; only requests that have one keep it.
+        def describe(payload, request, index = nil)
+          payload[:request] = NAMES.fetch(request.class)
+          payload[:index] = index if request.respond_to?(:index_id)
+          case request
+          when Protocol::Requests::Call then payload[:function] = request.function_name
+          when Protocol::Requests::Execute, Protocol::Requests::Prepare then add_statement(payload, request.statement)
+          end
+
+          payload
+        end
+
+        def add_statement(payload, statement)
+          payload[statement.is_a?(Integer) ? :statement_id : :sql] = statement
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/client/instrumentation.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Emits request and lifecycle events to the configured instrumenter, with the logger wrapped around it.
+    # Exception keys follow ActiveSupport::Notifications, which writes the same values again, so a payload looks
+    # the same whatever the instrumenter.
+    # @api private
+    class Instrumentation
+      REQUEST = 'request.tarantool'
+
+      def self.build(config)
+        instrumenter = config.instrumenter
+        instrumenter = LogInstrumenter.new(config.logger, instrumenter) if config.logger
+
+        new(instrumenter, config) if instrumenter
+      end
+
+      def self.exception_keys(exception)
+        { exception: [exception.class.name, exception.message], exception_object: exception }
+      end
+
+      def initialize(instrumenter, config)
+        @instrumenter = instrumenter
+        @address = config.address
+        @logger = config.logger
+      end
+
+      # The block's value is kept here: a duck-typed instrumenter need not return it.
+      def request(payload)
+        payload[:address] = @address
+        result = nil
+        @instrumenter.instrument(REQUEST, payload) do
+          result = yield
+        rescue Exception => e
+          payload.merge!(self.class.exception_keys(e))
+          raise
+        end
+
+        result
+      end
+
+      # Lifecycle events come from background threads, which a failing instrumenter must not stop.
+      def notify(name, payload = {})
+        @instrumenter.instrument(name, payload.merge(address: @address)) { nil }
+      rescue StandardError => e
+        Diagnostics.warn(@logger, "tarantool #{name} instrumentation failed: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/tarantool/client/instrumented.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Request events around the requests of Client and Stream. Includers implement
+    # transmit(request, timeout:, schema_version:, on_push:) and
+    # transmit_on_space(space, index, timeout:, format:, payload:, &), and set @instrumentation,
+    # nil when nothing is configured.
+    # @api private
+    module Instrumented
+      private
+
+      def perform(request, timeout: nil, schema_version: nil, on_push: nil)
+        instrumented(request) { transmit(request, timeout:, schema_version:, on_push:) }
+      end
+
+      def perform_on_space(space, index, timeout: nil, format: false, &)
+        return transmit_on_space(space, index, timeout:, format:, &) unless @instrumentation
+
+        perform_on_space_instrumented(space, index, timeout, format, &)
+      end
+
+      def instrumented(request, &)
+        return yield unless @instrumentation
+
+        @instrumentation.request(Instrumentation::RequestPayload.build(request), &)
+      end
+
+      # The request is built only once names resolve to ids, so its type and index join the payload then.
+      def perform_on_space_instrumented(space, index, timeout, format, &)
+        payload = { space: }
+        @instrumentation.request(payload) do
+          transmit_on_space(space, index, timeout:, format:, payload:) do |*resolved|
+            yield(*resolved).tap { |request| Instrumentation::RequestPayload.describe(payload, request, index) }
+          end
+        end
+      end
+
+      def mark_schema_reloaded(payload) = payload&.store(:schema_reloaded, true)
+    end
+  end
+end