dalli 3.2.8 → 4.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7d8b3dd9e76a224d876f901dc44c3cf8016326209df3efc7fe522053a4a3c22
-  data.tar.gz: 0ced058a6a170cadd4b74268de5417c4a1e700baf5767fc8f260db9477e2b735
+  metadata.gz: 57b78e30ee409a2d742fc47ee57ccdd482fe9c75f369366ae315b7ef8b649934
+  data.tar.gz: b8cad66f3cba53bbcb84b18f406eed60f22209c10dd4a312063a1e13189185ca
 SHA512:
-  metadata.gz: 3e316a4d60c3327cecec46a0a34c52536130199124035c375bf1933676d85fbf09e99a985ae44faf4e27b0fb1f8b8faef1656a812e6bdfc387406c5e18874461
-  data.tar.gz: bce3e0e41c280e99889bea6835c1b2f701cbcb5e4f398203ae2b4d6ebc05cdc505ee5955365715f8e00441d69701ceac84de37a98eac8581d003d1ab411a33e9
+  metadata.gz: 18b26e3c4aa30e5f8b4195d95307afca6c9240dd1154a36966d40d52047e638758850ec06e2a40fd1bd8e69fe150dee7409b1f4a565f0a80e397aaf115315463
+  data.tar.gz: b6db69ecbc1e6d34587d8ec29b861f6a71c863b36229d3c642e3d0e646ba6234e3bac04225d64ff174d12f35b728663e82e1d2b5f7e93dc9ac3e1ff33fd58db3

data/CHANGELOG.md

@@ -1,9 +1,177 @@
 Dalli Changelog
 =====================
 
-Unreleased
+4.3.3
 ==========
 
+Performance:
+
+- Reduce object allocations in pipelined get response processing (#1072)
+  - Offset-based `ResponseBuffer`: track a read offset instead of slicing a new string after every parsed response; compact only when the consumed portion exceeds 4KB and more than half the buffer
+  - Inline response processor parsing: avoid intermediate array allocations from `split`-based header parsing in both binary and meta protocols
+  - Block-based `pipeline_next_responses`: yield `(key, value, cas)` directly when a block is given, avoiding per-call Hash allocation
+  - `PipelinedGetter`: replace Hash-based socket-to-server mapping with linear scan (faster for typical 1-5 server counts); use `Process.clock_gettime(CLOCK_MONOTONIC)` instead of `Time.now`
+- Add cross-version benchmark script (`bin/compare_versions`) for reproducible performance comparisons across Dalli versions
+
+Bug Fixes:
+
+- Skip OTel integration tests when meta protocol is unavailable (#1072)
+
+4.3.2
+==========
+
+OpenTelemetry:
+
+- Migrate to stable OTel semantic conventions
+  - `db.system` renamed to `db.system.name`
+  - `db.operation` renamed to `db.operation.name`
+  - `server.address` now contains hostname only; `server.port` is a separate integer attribute
+  - `get_with_metadata` and `fetch_with_lock` now include `server.address`/`server.port`
+- Add `db.query.text` span attribute with configurable modes
+  - `:otel_db_statement` option: `:include`, `:obfuscate`, or `nil` (default: omitted)
+- Add `peer.service` span attribute
+  - `:otel_peer_service` option for logical service naming
+
+4.3.1
+==========
+
+Bug Fixes:
+
+- Fix socket compatibility with gems that monkey-patch TCPSocket (#996, #1012)
+  - Gems like `socksify` and `resolv-replace` modify `TCPSocket#initialize`, breaking Ruby 3.0+'s `connect_timeout:` keyword argument
+  - Detection now uses parameter signature checking instead of gem-specific method detection
+  - Falls back to `Timeout.timeout` when monkey-patching is detected
+  - Detection result is cached for performance
+
+- Fix network retry bug with `socket_max_failures: 0` (#1065)
+  - Previously, setting `socket_max_failures: 0` could still cause retries due to error handling
+  - Introduced `RetryableNetworkError` subclass to distinguish retryable vs non-retryable errors
+  - `down!` now raises non-retryable `NetworkError`, `reconnect!` raises `RetryableNetworkError`
+  - Thanks to Graham Cooper (Shopify) for this fix
+
+- Fix "character class has duplicated range" Ruby warning (#1067)
+  - Fixed regex in `KeyManager::VALID_NAMESPACE_SEPARATORS` that caused warnings on newer Ruby versions
+  - Thanks to Hartley McGuire for this fix
+
+Improvements:
+
+- Add StrictWarnings test helper to catch Ruby warnings early (#1067)
+
+- Use bulk attribute setter for OpenTelemetry spans (#1068)
+  - Reduces lock acquisitions when setting span attributes
+  - Thanks to Robert Laurin (Shopify) for this optimization
+
+- Fix double recording of exceptions on OpenTelemetry spans (#1069)
+  - OpenTelemetry's `in_span` method already records exceptions and sets error status automatically
+  - Removed redundant explicit exception recording that caused exceptions to appear twice in traces
+  - Thanks to Robert Laurin (Shopify) for this fix
+
+4.3.0
+==========
+
+New Features:
+
+- Add `namespace_separator` option to customize the separator between namespace and key (#1019)
+  - Default is `:` for backward compatibility
+  - Must be a single non-alphanumeric character (e.g., `:`, `/`, `|`, `.`)
+  - Example: `Dalli::Client.new(servers, namespace: 'myapp', namespace_separator: '/')`
+
+Bug Fixes:
+
+- Fix architecture-dependent struct timeval packing for socket timeouts (#1034)
+  - Detects correct pack format for time_t and suseconds_t on each platform
+  - Fixes timeout issues on architectures with 64-bit time_t
+
+- Fix get_multi hanging with large key counts (#776, #941)
+  - Add interleaved read/write for pipelined gets to prevent socket buffer deadlock
+  - For batches over 10,000 keys per server, requests are now sent in chunks
+
+- **Breaking:** Enforce string-only values in raw mode (#1022)
+  - `set(key, nil, raw: true)` now raises `MarshalError` instead of storing `""`
+  - `set(key, 123, raw: true)` now raises `MarshalError` instead of storing `"123"`
+  - This matches the behavior of client-level `raw: true` mode
+  - To store counters, use string values: `set('counter', '0', raw: true)`
+
+CI:
+
+- Add TruffleRuby to CI test matrix (#988)
+
+4.2.0
+==========
+
+Performance:
+
+- Buffered I/O: Use `socket.sync = false` with explicit flush to reduce syscalls for pipelined operations
+- get_multi optimizations: Use Set for O(1) server tracking lookups
+- Raw mode optimization: Skip bitflags request in meta protocol when in raw mode (saves 2 bytes per request)
+
+New Features:
+
+- OpenTelemetry tracing support: Automatically instruments operations when OpenTelemetry SDK is present
+  - Zero overhead when OpenTelemetry is not loaded
+  - Traces `get`, `set`, `delete`, `get_multi`, `set_multi`, `delete_multi`, `get_with_metadata`, and `fetch_with_lock`
+  - Spans include `db.system: memcached` and `db.operation` attributes
+  - Single-key operations include `server.address` attribute
+  - Multi-key operations include `db.memcached.key_count` attribute
+  - `get_multi` spans include `db.memcached.hit_count` and `db.memcached.miss_count` for cache efficiency metrics
+  - Exceptions are automatically recorded on spans with error status
+
+4.1.0
+==========
+
+New Features:
+
+- Add `set_multi` for efficient bulk set operations using pipelined requests
+- Add `delete_multi` for efficient bulk delete operations using pipelined requests
+- Add `fetch_with_lock` for thundering herd protection using meta protocol's vivify/recache flags (requires memcached 1.6+)
+- Add thundering herd protection support to meta protocol (requires memcached 1.6+):
+  - `N` (vivify) flag for creating stubs on cache miss
+  - `R` (recache) flag for winning recache race when TTL is below threshold
+  - Response flags `W` (won recache), `X` (stale), `Z` (lost race)
+  - `delete_stale` method for marking items as stale instead of deleting
+- Add `get_with_metadata` for advanced cache operations with metadata retrieval (requires memcached 1.6+):
+  - Returns hash with `:value`, `:cas`, `:won_recache`, `:stale`, `:lost_recache`
+  - Optional `:return_hit_status` returns `:hit_before` (true/false for previous access)
+  - Optional `:return_last_access` returns `:last_access` (seconds since last access)
+  - Optional `:skip_lru_bump` prevents LRU update on access
+  - Optional `:vivify_ttl` and `:recache_ttl` for thundering herd protection
+
+Deprecations:
+
+- Binary protocol is deprecated and will be removed in Dalli 5.0. Use `protocol: :meta` instead (requires memcached 1.6+)
+- SASL authentication is deprecated and will be removed in Dalli 5.0. Consider using network-level security or memcached's TLS support
+
+4.0.1
+==========
+
+- Add `:raw` client option to skip serialization entirely, returning raw byte strings
+- Handle `OpenSSL::SSL::SSLError` in connection manager
+
+4.0.0
+==========
+
+BREAKING CHANGES:
+
+- Require Ruby 3.1+ (dropped support for Ruby 2.6, 2.7, and 3.0)
+- Removed `Dalli::Server` deprecated alias - use `Dalli::Protocol::Binary` instead
+- Removed `:compression` option - use `:compress` instead
+- Removed `close_on_fork` method - use `reconnect_on_fork` instead
+
+Other changes:
+
+- Add security warning when using default Marshal serializer (silence with `silence_marshal_warning: true`)
+- Add defense-in-depth input validation for stats command arguments
+- Add `string_fastpath` option to skip serialization for simple strings (byroot)
+- Meta protocol set performance improvement (danmayer)
+- Fix connection_pool 3.0 compatibility for Rack session store
+- Fix session recovery after deletion (stengineering0)
+- Fix cannot read response data included terminator `\r\n` when use meta protocol (matsubara0507)
+- Support SERVER_ERROR response from Memcached as per the [memcached spec](https://github.com/memcached/memcached/blob/e43364402195c8e822bb8f88755a60ab8bbed62a/doc/protocol.txt#L172) (grcooper)
+- Update Socket timeout handling to use Socket#timeout= when available (nickamorim)
+- Serializer: reraise all .load errors as UnmarshalError (olleolleolle)
+- Reconnect gracefully when a fork is detected instead of crashing (PatrickTulskie)
+- Update CI to test against memcached 1.6.40
+
 3.2.8
 ==========
 

data/Gemfile

@@ -5,9 +5,18 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
+  gem 'benchmark'
+  gem 'cgi'
   gem 'connection_pool'
-  gem 'minitest', '~> 5'
-  gem 'rack', '~> 2.0', '>= 2.2.0'
+  gem 'debug' unless RUBY_PLATFORM == 'java'
+  if RUBY_VERSION >= '3.2'
+    gem 'minitest', '~> 6'
+    gem 'minitest-mock'
+  else
+    gem 'minitest', '~> 5'
+  end
+  gem 'rack', '~> 3'
+  gem 'rack-session'
   gem 'rake', '~> 13.0'
   gem 'rubocop'
   gem 'rubocop-minitest'
@@ -18,4 +27,8 @@ end
 
 group :test do
   gem 'ruby-prof', platform: :mri
+
+  # For socket compatibility testing (these gems monkey-patch TCPSocket)
+  gem 'resolv-replace', require: false
+  gem 'socksify', require: false
 end

data/README.md

@@ -11,9 +11,101 @@ Dalli supports:
 * Thread-safe operation (either through use of a connection pool, or by using the Dalli client in threadsafe mode)
 * SSL/TLS connections to memcached
 * SASL authentication
+* OpenTelemetry distributed tracing (automatic when SDK is present)
 
 The name is a variant of Salvador Dali for his famous painting [The Persistence of Memory](http://en.wikipedia.org/wiki/The_Persistence_of_Memory).
 
+## Requirements
+
+* Ruby 3.1 or later
+* memcached 1.4 or later (1.6+ recommended for meta protocol support)
+
+## Protocol Options
+
+Dalli supports two protocols for communicating with memcached:
+
+* `:binary` (default) - Works with all memcached versions, supports SASL authentication
+* `:meta` - Requires memcached 1.6+, better performance for some operations, no authentication support
+
+```ruby
+Dalli::Client.new('localhost:11211', protocol: :meta)
+```
+
+## Configuration Options
+
+### Namespace
+
+Use namespaces to partition your cache and avoid key collisions between different applications or environments:
+
+```ruby
+# All keys will be prefixed with "myapp:"
+Dalli::Client.new('localhost:11211', namespace: 'myapp')
+
+# Dynamic namespace using a Proc (evaluated on each operation)
+Dalli::Client.new('localhost:11211', namespace: -> { "tenant:#{Thread.current[:tenant_id]}" })
+```
+
+### Namespace Separator
+
+By default, the namespace and key are joined with a colon (`:`). You can customize this with the `namespace_separator` option:
+
+```ruby
+# Keys will be prefixed with "myapp/" instead of "myapp:"
+Dalli::Client.new('localhost:11211', namespace: 'myapp', namespace_separator: '/')
+```
+
+The separator must be a single non-alphanumeric character. Valid examples: `:`, `/`, `|`, `.`, `-`, `_`, `#`
+
+## Security Note
+
+By default, Dalli uses Ruby's Marshal for serialization. Deserializing untrusted data with Marshal can lead to remote code execution. If you cache user-controlled data, consider using a safer serializer:
+
+```ruby
+Dalli::Client.new('localhost:11211', serializer: JSON)
+```
+
+See the [4.0-Upgrade.md](4.0-Upgrade.md) guide for more information.
+
+## OpenTelemetry Tracing
+
+Dalli automatically instruments operations with [OpenTelemetry](https://opentelemetry.io/) when the SDK is present. No configuration is required - just add the OpenTelemetry gems to your application:
+
+```ruby
+# Gemfile
+gem 'opentelemetry-sdk'
+gem 'opentelemetry-exporter-otlp' # or your preferred exporter
+```
+
+When OpenTelemetry is loaded, Dalli creates spans for:
+- Single key operations: `get`, `set`, `delete`, `add`, `replace`, `incr`, `decr`, etc.
+- Multi-key operations: `get_multi`, `set_multi`, `delete_multi`
+- Advanced operations: `get_with_metadata`, `fetch_with_lock`
+
+### Span Attributes
+
+All spans include:
+- `db.system`: `memcached`
+- `db.operation`: The operation name (e.g., `get`, `set_multi`)
+
+Single-key operations also include:
+- `server.address`: The memcached server that handled the request (e.g., `localhost:11211`)
+
+Multi-key operations include cache efficiency metrics:
+- `db.memcached.key_count`: Number of keys in the request
+- `db.memcached.hit_count`: Number of keys found (for `get_multi`)
+- `db.memcached.miss_count`: Number of keys not found (for `get_multi`)
+
+### Error Handling
+
+Exceptions are automatically recorded on spans with error status. When an operation fails:
+1. The exception is recorded on the span via `span.record_exception(e)`
+2. The span status is set to error with the exception message
+3. The exception is re-raised to the caller
+
+### Zero Overhead
+
+When OpenTelemetry is not present, there is zero overhead - the tracing code checks once at startup and bypasses all instrumentation logic entirely when the SDK is not loaded.
+
 ![Persistence of Memory](https://upload.wikimedia.org/wikipedia/en/d/dd/The_Persistence_of_Memory.jpg)
 
 

data/lib/dalli/client.rb

@@ -41,16 +41,26 @@ module Dalli
     # - :compressor - defaults to Dalli::Compressor, a Zlib-based implementation
     # - :cache_nils - defaults to false, if true Dalli will not treat cached nil values as 'not found' for
     #                 #fetch operations.
+    # - :raw        - If set, disables serialization and compression entirely at the client level.
+    #                 Only String values are supported. This is useful when the caller handles its own
+    #                 serialization (e.g., Rails' ActiveSupport::Cache). Note: this is different from
+    #                 the per-request :raw option which converts values to strings but still uses the
+    #                 serialization pipeline.
     # - :digest_class - defaults to Digest::MD5, allows you to pass in an object that responds to the hexdigest method,
     #                   useful for injecting a FIPS compliant hash object.
     # - :protocol - one of either :binary or :meta, defaulting to :binary.  This sets the protocol that Dalli uses
     #               to communicate with memcached.
+    # - :otel_db_statement - controls the +db.query.text+ span attribute when OpenTelemetry is loaded.
+    #                        +:include+ logs the full operation and key(s), +:obfuscate+ replaces keys with "?",
+    #                        +nil+ (default) omits the attribute entirely.
+    # - :otel_peer_service - when set, adds a +peer.service+ span attribute with this value for logical service naming.
     #
     def initialize(servers = nil, options = {})
       @normalized_servers = ::Dalli::ServersArgNormalizer.normalize_servers(servers)
       @options = normalize_options(options)
       @key_manager = ::Dalli::KeyManager.new(@options)
       @ring = nil
+      emit_deprecation_warnings
     end
 
     #
@@ -91,24 +101,70 @@ module Dalli
       yield value, cas
     end
 
+    ##
+    # Get value with extended metadata using the meta protocol.
+    #
+    # IMPORTANT: This method requires memcached 1.6+ and the meta protocol (protocol: :meta).
+    # It will raise an error if used with the binary protocol.
+    #
+    # @param key [String] the cache key
+    # @param options [Hash] options controlling what metadata to return
+    #   - :return_cas [Boolean] return the CAS value (default: true)
+    #   - :return_hit_status [Boolean] return whether item was previously accessed
+    #   - :return_last_access [Boolean] return seconds since last access
+    #   - :skip_lru_bump [Boolean] don't bump LRU or update access stats
+    #
+    # @return [Hash] containing:
+    #   - :value - the cached value (or nil on miss)
+    #   - :cas - the CAS value
+    #   - :hit_before - true/false if previously accessed (only if return_hit_status: true)
+    #   - :last_access - seconds since last access (only if return_last_access: true)
+    #
+    # @example Get with hit status
+    #   result = client.get_with_metadata('key', return_hit_status: true)
+    #   # => { value: "data", cas: 123, hit_before: true }
+    #
+    # @example Get with all metadata without affecting LRU
+    #   result = client.get_with_metadata('key',
+    #     return_hit_status: true,
+    #     return_last_access: true,
+    #     skip_lru_bump: true
+    #   )
+    #   # => { value: "data", cas: 123, hit_before: true, last_access: 42 }
+    #
+    def get_with_metadata(key, options = {})
+      raise_unless_meta_protocol!
+
+      key = key.to_s
+      key = @key_manager.validate_key(key)
+
+      server = ring.server_for_key(key)
+      Instrumentation.trace('get_with_metadata', trace_attrs('get_with_metadata', key, server)) do
+        server.request(:meta_get, key, options)
+      end
+    rescue NetworkError => e
+      Dalli.logger.debug { e.inspect }
+      Dalli.logger.debug { 'retrying get_with_metadata with new server' }
+      retry
+    end
+
     ##
     # Fetch multiple keys efficiently.
     # If a block is given, yields key/value pairs one at a time.
     # Otherwise returns a hash of { 'key' => 'value', 'key2' => 'value1' }
+    # rubocop:disable Style/ExplicitBlockArgument
     def get_multi(*keys)
       keys.flatten!
       keys.compact!
-
       return {} if keys.empty?
 
       if block_given?
-        pipelined_getter.process(keys) { |k, data| yield k, data.first }
+        get_multi_yielding(keys) { |k, v| yield k, v }
       else
-        {}.tap do |hash|
-          pipelined_getter.process(keys) { |k, data| hash[k] = data.first }
-        end
+        get_multi_hash(keys)
       end
     end
+    # rubocop:enable Style/ExplicitBlockArgument
 
     ##
     # Fetch multiple keys efficiently, including available metadata such as CAS.
@@ -144,6 +200,57 @@ module Dalli
       new_val
     end
 
+    ##
+    # Fetch the value with thundering herd protection using the meta protocol's
+    # N (vivify) and R (recache) flags.
+    #
+    # This method prevents multiple clients from simultaneously regenerating the same
+    # cache entry (the "thundering herd" problem). Only one client wins the right to
+    # regenerate; other clients receive the stale value (if available) or wait.
+    #
+    # IMPORTANT: This method requires memcached 1.6+ and the meta protocol (protocol: :meta).
+    # It will raise an error if used with the binary protocol.
+    #
+    # @param key [String] the cache key
+    # @param ttl [Integer] time-to-live for the cached value in seconds
+    # @param lock_ttl [Integer] how long the lock/stub lives (default: 30 seconds)
+    #   This is the maximum time other clients will return stale data while
+    #   waiting for regeneration. Should be longer than your expected regeneration time.
+    # @param recache_threshold [Integer, nil] if set, win the recache race when the
+    #   item's remaining TTL is below this threshold. Useful for proactive recaching.
+    # @param req_options [Hash] options passed to set operations (e.g., raw: true)
+    #
+    # @yield Block to regenerate the value (only called if this client won the race)
+    # @return [Object] the cached value (may be stale if another client is regenerating)
+    #
+    # @example Basic usage
+    #   client.fetch_with_lock('expensive_key', ttl: 300, lock_ttl: 30) do
+    #     expensive_database_query
+    #   end
+    #
+    # @example With proactive recaching (recache before expiry)
+    #   client.fetch_with_lock('key', ttl: 300, lock_ttl: 30, recache_threshold: 60) do
+    #     expensive_operation
+    #   end
+    #
+    def fetch_with_lock(key, ttl: nil, lock_ttl: 30, recache_threshold: nil, req_options: nil, &block)
+      raise ArgumentError, 'Block is required for fetch_with_lock' unless block_given?
+
+      raise_unless_meta_protocol!
+
+      key = key.to_s
+      key = @key_manager.validate_key(key)
+
+      server = ring.server_for_key(key)
+      Instrumentation.trace('fetch_with_lock', trace_attrs('fetch_with_lock', key, server)) do
+        fetch_with_lock_request(key, ttl, lock_ttl, recache_threshold, req_options, &block)
+      end
+    rescue NetworkError => e
+      Dalli.logger.debug { e.inspect }
+      Dalli.logger.debug { 'retrying fetch_with_lock with new server' }
+      retry
+    end
+
     ##
     # compare and swap values using optimistic locking.
     # Fetch the existing value for key.
@@ -155,8 +262,8 @@ module Dalli
     # - nil if the key did not exist.
     # - false if the value was changed by someone else.
     # - true if the value was successfully updated.
-    def cas(key, ttl = nil, req_options = nil, &block)
-      cas_core(key, false, ttl, req_options, &block)
+    def cas(key, ttl = nil, req_options = nil, &)
+      cas_core(key, false, ttl, req_options, &)
     end
 
     ##
@@ -166,8 +273,8 @@ module Dalli
     # Returns:
     # - false if the value was changed by someone else.
     # - true if the value was successfully updated.
-    def cas!(key, ttl = nil, req_options = nil, &block)
-      cas_core(key, true, ttl, req_options, &block)
+    def cas!(key, ttl = nil, req_options = nil, &)
+      cas_core(key, true, ttl, req_options, &)
     end
 
     ##
@@ -201,6 +308,26 @@ module Dalli
       set_cas(key, value, 0, ttl, req_options)
     end
 
+    ##
+    # Set multiple keys and values efficiently using pipelining.
+    # This method is more efficient than calling set() in a loop because
+    # it batches requests by server and uses quiet mode.
+    #
+    # @param hash [Hash] key-value pairs to set
+    # @param ttl [Integer] time-to-live in seconds (optional, uses default if not provided)
+    # @param req_options [Hash] options passed to each set operation
+    # @return [void]
+    #
+    # Example:
+    #   client.set_multi({ 'key1' => 'value1', 'key2' => 'value2' }, 300)
+    def set_multi(hash, ttl = nil, req_options = nil)
+      return if hash.empty?
+
+      Instrumentation.trace('set_multi', multi_trace_attrs('set_multi', hash.size, hash.keys)) do
+        pipelined_setter.process(hash, ttl_or_default(ttl), req_options)
+      end
+    end
+
     ##
     # Set the key-value pair, verifying existing CAS.
     # Returns the resulting CAS value if succeeded, and falsy otherwise.
@@ -240,6 +367,24 @@ module Dalli
       delete_cas(key, 0)
     end
 
+    ##
+    # Delete multiple keys efficiently using pipelining.
+    # This method is more efficient than calling delete() in a loop because
+    # it batches requests by server and uses quiet mode.
+    #
+    # @param keys [Array<String>] keys to delete
+    # @return [void]
+    #
+    # Example:
+    #   client.delete_multi(['key1', 'key2', 'key3'])
+    def delete_multi(keys)
+      return if keys.empty?
+
+      Instrumentation.trace('delete_multi', multi_trace_attrs('delete_multi', keys.size, keys)) do
+        pipelined_deleter.process(keys)
+      end
+    end
+
     ##
     # Append value to the value already stored on the server for 'key'.
     # Appending only works for values stored with :raw => true.
@@ -369,6 +514,65 @@ module Dalli
 
     private
 
+    # Records hit/miss metrics on a span for cache observability.
+    # @param span [OpenTelemetry::Trace::Span, nil] the span to record on
+    # @param key_count [Integer] total keys requested
+    # @param hit_count [Integer] keys found in cache
+    def record_hit_miss_metrics(span, key_count, hit_count)
+      return unless span
+
+      span.add_attributes('db.memcached.hit_count' => hit_count,
+                          'db.memcached.miss_count' => key_count - hit_count)
+    end
+
+    def get_multi_yielding(keys)
+      Instrumentation.trace_with_result('get_multi', get_multi_attributes(keys)) do |span|
+        hit_count = 0
+        pipelined_getter.process(keys) do |k, data|
+          hit_count += 1
+          yield k, data.first
+        end
+        record_hit_miss_metrics(span, keys.size, hit_count)
+        nil
+      end
+    end
+
+    def get_multi_hash(keys)
+      Instrumentation.trace_with_result('get_multi', get_multi_attributes(keys)) do |span|
+        {}.tap do |hash|
+          pipelined_getter.process(keys) { |k, data| hash[k] = data.first }
+          record_hit_miss_metrics(span, keys.size, hash.size)
+        end
+      end
+    end
+
+    def get_multi_attributes(keys)
+      multi_trace_attrs('get_multi', keys.size, keys)
+    end
+
+    def trace_attrs(operation, key, server)
+      attrs = { 'db.operation.name' => operation, 'server.address' => server.hostname }
+      attrs['server.port'] = server.port if server.socket_type == :tcp
+      attrs['peer.service'] = @options[:otel_peer_service] if @options[:otel_peer_service]
+      add_query_text(attrs, operation, key)
+    end
+
+    def multi_trace_attrs(operation, key_count, keys)
+      attrs = { 'db.operation.name' => operation, 'db.memcached.key_count' => key_count }
+      attrs['peer.service'] = @options[:otel_peer_service] if @options[:otel_peer_service]
+      add_query_text(attrs, operation, keys)
+    end
+
+    def add_query_text(attrs, operation, key_or_keys)
+      case @options[:otel_db_statement]
+      when :include
+        attrs['db.query.text'] = "#{operation} #{Array(key_or_keys).join(' ')}"
+      when :obfuscate
+        attrs['db.query.text'] = "#{operation} ?"
+      end
+      attrs
+    end
+
     def check_positive!(amt)
       raise ArgumentError, "Positive values only: #{amt}" if amt.negative?
     end
@@ -381,6 +585,17 @@ module Dalli
       perform(:set, key, newvalue, ttl_or_default(ttl), cas, req_options)
     end
 
+    def fetch_with_lock_request(key, ttl, lock_ttl, recache_threshold, req_options)
+      server = ring.server_for_key(key)
+      result = server.request(:meta_get, key, { vivify_ttl: lock_ttl, recache_ttl: recache_threshold })
+
+      return result[:value] unless result[:won_recache]
+
+      new_val = yield
+      set(key, new_val, ttl_or_default(ttl), req_options)
+      new_val
+    end
+
     ##
     # Uses the argument TTL or the client-wide default.  Ensures
     # that the value is an integer
@@ -423,8 +638,10 @@ module Dalli
       key = @key_manager.validate_key(key)
 
       server = ring.server_for_key(key)
-      server.request(op, key, *args)
-    rescue NetworkError => e
+      Instrumentation.trace(op.to_s, trace_attrs(op.to_s, key, server)) do
+        server.request(op, key, *args)
+      end
+    rescue RetryableNetworkError => e
       Dalli.logger.debug { e.inspect }
       Dalli.logger.debug { 'retrying request with new server' }
       retry
@@ -440,5 +657,23 @@ module Dalli
     def pipelined_getter
       PipelinedGetter.new(ring, @key_manager)
     end
+
+    def pipelined_setter
+      PipelinedSetter.new(ring, @key_manager)
+    end
+
+    def pipelined_deleter
+      PipelinedDeleter.new(ring, @key_manager)
+    end
+
+    def raise_unless_meta_protocol!
+      return if protocol_implementation == Dalli::Protocol::Meta
+
+      raise Dalli::DalliError,
+            'This operation requires the meta protocol (memcached 1.6+). ' \
+            'Use protocol: :meta when creating the client.'
+    end
+
+    include ProtocolDeprecations
   end
 end