dalli 4.2.0 → 4.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7966ac393d9c0f41d61b244c6a5832fbcab5705ed4daa4189b6e1ffc92db600f
-  data.tar.gz: da320eac7a8d553f33fe81315750297f97edb75c6da79197ef1f974d47ac8081
+  metadata.gz: 533bed149f02ca2960fa436d776b920cce0c95b841296c678a247141f8f7f239
+  data.tar.gz: cd3ca6a066d005fd177726b3c29ab460cba9d8ddc9937c1809053bf22b20e387
 SHA512:
-  metadata.gz: 5d29cfbe8d2ee6e2993e8a292238f2762ac1de29b8d8623f0a521f810edf866ffd9d631905d5b7cb939d44216fb7e8d6edabf4c09ba388162fef97a772254352
-  data.tar.gz: ef1c636e6aab12a630ddb7e4d7081c29b0e257203b97f78ccde207170802d1c3619db7057093d4140fcc9cbc23f979bf6f60be4a64011bde983062a724ea59fc
+  metadata.gz: cc927b7e0f8906d326ede287b9d0fb9b3c1fb216b271350bc1e02cd4531b86d365e286da73cb8be9082646d747a494ccc0cdd81d0f9f053cf2439dd58bc40157
+  data.tar.gz: ce17e49264f9cf1550f709eb6d67a3f0f2f7fefaecfab04bf2c3f4356b7636ff95e2d6f76a44abcd8f0efae79ab8bbf21c5ba7d59a802735626af73e7bf0d777

data/CHANGELOG.md

@@ -1,6 +1,21 @@
 Dalli Changelog
 =====================
 
+4.2.1
+==========
+
+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.2.0
 ==========
 

data/lib/dalli/client.rb

@@ -50,6 +50,10 @@ module Dalli
     #                   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)
@@ -134,8 +138,8 @@ module Dalli
       key = key.to_s
       key = @key_manager.validate_key(key)
 
-      Instrumentation.trace('get_with_metadata', { 'db.operation' => 'get_with_metadata' }) do
-        server = ring.server_for_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
@@ -237,7 +241,8 @@ module Dalli
       key = key.to_s
       key = @key_manager.validate_key(key)
 
-      Instrumentation.trace('fetch_with_lock', { 'db.operation' => 'fetch_with_lock' }) do
+      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
@@ -318,10 +323,7 @@ module Dalli
     def set_multi(hash, ttl = nil, req_options = nil)
       return if hash.empty?
 
-      Instrumentation.trace('set_multi', {
-                              'db.operation' => 'set_multi',
-                              'db.memcached.key_count' => hash.size
-                            }) do
+      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
@@ -378,10 +380,7 @@ module Dalli
     def delete_multi(keys)
       return if keys.empty?
 
-      Instrumentation.trace('delete_multi', {
-                              'db.operation' => 'delete_multi',
-                              'db.memcached.key_count' => keys.size
-                            }) do
+      Instrumentation.trace('delete_multi', multi_trace_attrs('delete_multi', keys.size, keys)) do
         pipelined_deleter.process(keys)
       end
     end
@@ -548,7 +547,30 @@ module Dalli
     end
 
     def get_multi_attributes(keys)
-      { 'db.operation' => 'get_multi', 'db.memcached.key_count' => keys.size }
+      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)
@@ -616,10 +638,7 @@ module Dalli
       key = @key_manager.validate_key(key)
 
       server = ring.server_for_key(key)
-      Instrumentation.trace(op.to_s, {
-                              'db.operation' => op.to_s,
-                              'server.address' => server.name
-                            }) do
+      Instrumentation.trace(op.to_s, trace_attrs(op.to_s, key, server)) do
         server.request(op, key, *args)
       end
     rescue NetworkError => e

data/lib/dalli/instrumentation.rb

@@ -8,25 +8,36 @@ module Dalli
   # When OpenTelemetry is loaded, Dalli automatically creates spans for cache operations.
   # When OpenTelemetry is not available, all tracing methods are no-ops with zero overhead.
   #
+  # Dalli 4.2.1 uses the stable OTel semantic conventions for database spans.
+  #
   # == Span Attributes
   #
   # All spans include the following default attributes:
-  # - +db.system+ - Always "memcached"
+  # - +db.system.name+ - Always "memcached"
   #
   # Single-key operations (+get+, +set+, +delete+, +incr+, +decr+, etc.) add:
-  # - +db.operation+ - The operation name (e.g., "get", "set")
-  # - +server.address+ - The memcached server handling the request (e.g., "localhost:11211")
+  # - +db.operation.name+ - The operation name (e.g., "get", "set")
+  # - +server.address+ - The server hostname (e.g., "localhost")
+  # - +server.port+ - The server port as an integer (e.g., 11211); omitted for Unix sockets
   #
   # Multi-key operations (+get_multi+) add:
-  # - +db.operation+ - "get_multi"
+  # - +db.operation.name+ - "get_multi"
   # - +db.memcached.key_count+ - Number of keys requested
   # - +db.memcached.hit_count+ - Number of keys found in cache
   # - +db.memcached.miss_count+ - Number of keys not found
   #
   # Bulk write operations (+set_multi+, +delete_multi+) add:
-  # - +db.operation+ - The operation name
+  # - +db.operation.name+ - The operation name
   # - +db.memcached.key_count+ - Number of keys in the operation
   #
+  # == Optional Attributes
+  #
+  # - +db.query.text+ - The operation and key(s), controlled by the +:otel_db_statement+ client option:
+  #   - +:include+ - Full text (e.g., "get mykey")
+  #   - +:obfuscate+ - Obfuscated (e.g., "get ?")
+  #   - +nil+ (default) - Attribute omitted
+  # - +peer.service+ - Logical service name, set via the +:otel_peer_service+ client option
+  #
   # == Error Handling
   #
   # When an exception occurs during a traced operation:
@@ -40,8 +51,8 @@ module Dalli
   ##
   module Instrumentation
     # Default attributes included on all memcached spans.
-    # @return [Hash] frozen hash with 'db.system' => 'memcached'
-    DEFAULT_ATTRIBUTES = { 'db.system' => 'memcached' }.freeze
+    # @return [Hash] frozen hash with 'db.system.name' => 'memcached'
+    DEFAULT_ATTRIBUTES = { 'db.system.name' => 'memcached' }.freeze
 
     class << self
       # Returns the OpenTelemetry tracer if available, nil otherwise.
@@ -75,15 +86,16 @@ module Dalli
       # @param name [String] the span name (e.g., 'get', 'set', 'delete')
       # @param attributes [Hash] span attributes to merge with defaults.
       #   Common attributes include:
-      #   - 'db.operation' - the operation name
-      #   - 'server.address' - the target server
+      #   - 'db.operation.name' - the operation name
+      #   - 'server.address' - the server hostname
+      #   - 'server.port' - the server port (integer)
       #   - 'db.memcached.key_count' - number of keys (for multi operations)
       # @yield the cache operation to trace
       # @return [Object] the result of the block
       # @raise [StandardError] re-raises any exception from the block
       #
       # @example Tracing a set operation
-      #   trace('set', { 'db.operation' => 'set', 'server.address' => 'localhost:11211' }) do
+      #   trace('set', { 'db.operation.name' => 'set', 'server.address' => 'localhost', 'server.port' => 11211 }) do
       #     server.set(key, value, ttl)
       #   end
       #
@@ -114,7 +126,7 @@ module Dalli
       # @raise [StandardError] re-raises any exception from the block
       #
       # @example Recording hit/miss metrics after get_multi
-      #   trace_with_result('get_multi', { 'db.operation' => 'get_multi' }) do |span|
+      #   trace_with_result('get_multi', { 'db.operation.name' => 'get_multi' }) do |span|
       #     results = fetch_from_cache(keys)
       #     if span
       #       span.set_attribute('db.memcached.hit_count', results.size)

data/lib/dalli/socket.rb

@@ -107,7 +107,7 @@ module Dalli
         # aliases TCPSocket#initialize method to #original_resolv_initialize.
         # https://github.com/ruby/resolv-replace/blob/v0.1.1/lib/resolv-replace.rb#L21
         if RUBY_VERSION >= '3.0' &&
-           !::TCPSocket.private_instance_methods.include?(:original_resolv_initialize)
+           !::TCPSocket.private_method_defined?(:original_resolv_initialize)
           sock = new(host, port, connect_timeout: options[:socket_timeout])
           yield(sock)
         else

data/lib/dalli/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Dalli
-  VERSION = '4.2.0'
+  VERSION = '4.2.1'
 
   MIN_SUPPORTED_MEMCACHED_VERSION = '1.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dalli
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 4.2.1
 platform: ruby
 authors:
 - Peter M. Goldstein
@@ -93,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 4.0.6
 specification_version: 4
 summary: High performance memcached client for Ruby
 test_files: []