feat: Redis Semantic Stability

instrumentation/redis/Appraisals

@@ -1,16 +1,26 @@
 # frozen_string_literal: true
 
-if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('4')
-  appraise 'redis-4.x' do
-    gem 'redis-client', '~> 0.22'
-    gem 'redis', '~> 4.8'
+# To facilitate database semantic convention stability migration, we are using
+# appraisal to test the different semantic convention modes along with different
+# gem versions. For more information on the semantic convention modes, see:
+# https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/
+
+semconv_stability = %w[old stable dup]
+
+semconv_stability.each do |stability|
+  # redis-4.x requires redis-client which has Ruby version constraints
+  if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('4')
+    appraise "redis-4.x-#{stability}" do
+      gem 'redis-client', '~> 0.22'
+      gem 'redis', '~> 4.8'
+    end
   end
-end
 
-appraise 'redis-5.x' do
-  gem 'redis', '~> 5.0'
-end
+  appraise "redis-5.x-#{stability}" do
+    gem 'redis', '~> 5.0'
+  end
 
-appraise 'redis-latest' do
-  gem 'redis'
+  appraise "redis-latest-#{stability}" do
+    gem 'redis'
+  end
 end

instrumentation/redis/README.md

@@ -70,6 +70,22 @@ The `opentelemetry-instrumentation-redis` gem source is [on github][repo-github]
 
 The OpenTelemetry Ruby gems are maintained by the OpenTelemetry Ruby special interest group (SIG). You can get involved by joining us on our [GitHub Discussions][discussions-url], [Slack Channel][slack-channel] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
 
+## Database semantic convention stability
+
+In the OpenTelemetry ecosystem, database semantic conventions have now reached a stable state. However, the initial Redis instrumentation was introduced before this stability was achieved, which resulted in database attributes being based on an older version of the semantic conventions.
+
+To facilitate the migration to stable semantic conventions, you can use the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable. This variable allows you to opt-in to the new stable conventions, ensuring compatibility and future-proofing your instrumentation.
+
+When setting the value for `OTEL_SEMCONV_STABILITY_OPT_IN`, you can specify which conventions you wish to adopt:
+
+- `database` - Emits the stable database and networking conventions and ceases emitting the old conventions previously emitted by the instrumentation.
+- `database/dup` - Emits both the old and stable database and networking conventions, enabling a phased rollout of the stable semantic conventions.
+- Default behavior (in the absence of either value) is to continue emitting the old database and networking conventions the instrumentation previously emitted.
+
+During the transition from old to stable conventions, Redis instrumentation code comes in three patch versions: `dup`, `old`, and `stable`. These versions are identical except for the attributes they send. Any changes to Redis instrumentation should consider all three patches.
+
+For additional information on migration, please refer to our [documentation](https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/).
+
 ## License
 
 Apache 2.0 license. See [LICENSE][license-github] for more information.

instrumentation/redis/lib/opentelemetry/instrumentation/redis/instrumentation.rb

@@ -11,8 +11,9 @@ module Redis
       # instrumentation
       class Instrumentation < OpenTelemetry::Instrumentation::Base
         install do |_config|
-          require_dependencies
-          patch_client
+          patch_type = determine_semconv
+          send(:"require_dependencies_#{patch_type}")
+          send(:"patch_client_#{patch_type}")
         end
 
         present do
@@ -25,14 +26,47 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
 
         private
 
-        def require_dependencies
-          require_relative 'patches/redis_v4_client' if defined?(::Redis) && ::Redis::VERSION < '5'
-          require_relative 'middlewares/redis_client' if defined?(::RedisClient)
+        def determine_semconv
+          stability_opt_in = ENV.fetch('OTEL_SEMCONV_STABILITY_OPT_IN', '')
+          values = stability_opt_in.split(',').map(&:strip)
+
+          if values.include?('database/dup')
+            'dup'
+          elsif values.include?('database')
+            'stable'
+          else
+            'old'
+          end
+        end
+
+        def require_dependencies_old
+          require_relative 'patches/old/redis_v4_client' if defined?(::Redis) && ::Redis::VERSION < '5'
+          require_relative 'middlewares/old/redis_client' if defined?(::RedisClient)
+        end
+
+        def require_dependencies_stable
+          require_relative 'patches/stable/redis_v4_client' if defined?(::Redis) && ::Redis::VERSION < '5'
+          require_relative 'middlewares/stable/redis_client' if defined?(::RedisClient)
+        end
+
+        def require_dependencies_dup
+          require_relative 'patches/dup/redis_v4_client' if defined?(::Redis) && ::Redis::VERSION < '5'
+          require_relative 'middlewares/dup/redis_client' if defined?(::RedisClient)
+        end
+
+        def patch_client_old
+          ::RedisClient.register(Middlewares::Old::RedisClientInstrumentation) if defined?(::RedisClient)
+          ::Redis::Client.prepend(Patches::Old::RedisV4Client) if defined?(::Redis) && ::Redis::VERSION < '5'
+        end
+
+        def patch_client_stable
+          ::RedisClient.register(Middlewares::Stable::RedisClientInstrumentation) if defined?(::RedisClient)
+          ::Redis::Client.prepend(Patches::Stable::RedisV4Client) if defined?(::Redis) && ::Redis::VERSION < '5'
         end
 
-        def patch_client
-          ::RedisClient.register(Middlewares::RedisClientInstrumentation) if defined?(::RedisClient)
-          ::Redis::Client.prepend(Patches::RedisV4Client) if defined?(::Redis) && ::Redis::VERSION < '5'
+        def patch_client_dup
+          ::RedisClient.register(Middlewares::Dup::RedisClientInstrumentation) if defined?(::RedisClient)
+          ::Redis::Client.prepend(Patches::Dup::RedisV4Client) if defined?(::Redis) && ::Redis::VERSION < '5'
         end
       end
     end

instrumentation/redis/lib/opentelemetry/instrumentation/redis/middlewares/dup/redis_client.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module Redis
+      module Middlewares
+        module Dup
+          # Adapter for redis-client instrumentation interface
+          module RedisClientInstrumentation
+            MAX_STATEMENT_LENGTH = 500
+            private_constant :MAX_STATEMENT_LENGTH
+
+            def call(command, redis_config)
+              return super unless instrumentation.config[:trace_root_spans] || OpenTelemetry::Trace.current_span.context.valid?
+
+              op_name = command[0].to_s.upcase
+              attributes = span_attributes(redis_config)
+              attributes['db.operation.name'] = op_name
+
+              unless instrumentation.config[:db_statement] == :omit
+                serialized = serialize_commands([command])
+                # Both old and new attributes
+                attributes['db.statement'] = serialized
+                attributes['db.query.text'] = serialized
+              end
+
+              instrumentation.tracer.in_span(op_name, attributes: attributes, kind: :client) do |span|
+                super
+              rescue StandardError => e
+                set_error_attributes(span, e)
+                raise
+              end
+            end
+
+            def call_pipelined(commands, redis_config)
+              return super unless instrumentation.config[:trace_root_spans] || OpenTelemetry::Trace.current_span.context.valid?
+
+              attributes = span_attributes(redis_config)
+              attributes['db.operation.name'] = 'PIPELINE'
+              attributes['db.operation.batch.size'] = commands.size
+
+              unless instrumentation.config[:db_statement] == :omit
+                serialized = serialize_commands(commands)
+                # Both old and new attributes
+                attributes['db.statement'] = serialized
+                attributes['db.query.text'] = serialized
+              end
+
+              instrumentation.tracer.in_span('PIPELINE', attributes: attributes, kind: :client) do |span|
+                super
+              rescue StandardError => e
+                set_error_attributes(span, e)
+                raise
+              end
+            end
+
+            private
+
+            def span_attributes(redis_config)
+              port = redis_config.port
+
+              # Old conventions
+              attributes = {
+                'db.system' => 'redis',
+                'net.peer.name' => redis_config.host,
+                'net.peer.port' => port
+              }
+
+              # New stable conventions
+              attributes['db.system.name'] = 'redis'
+              attributes['server.address'] = redis_config.host
+              attributes['server.port'] = port if port
+
+              unless redis_config.db.zero?
+                # Old convention
+                attributes['db.redis.database_index'] = redis_config.db
+                # New stable convention (db.namespace as string)
+                attributes['db.namespace'] = redis_config.db.to_s
+              end
+              attributes['peer.service'] = instrumentation.config[:peer_service] if instrumentation.config[:peer_service]
+              attributes.merge!(OpenTelemetry::Instrumentation::Redis.attributes)
+              attributes
+            end
+
+            def set_error_attributes(span, error)
+              error_type = extract_error_type(error)
+              span.set_attribute('error.type', error_type)
+              span.set_attribute('db.response.status_code', error_type) if redis_error?(error)
+              span.record_exception(error)
+              span.status = OpenTelemetry::Trace::Status.error(error.message)
+            end
+
+            def extract_error_type(error)
+              # Redis errors start with an error prefix like ERR, WRONGTYPE, CLUSTERDOWN
+              # Extract this prefix for db.response.status_code and error.type
+              if redis_error?(error) && error.message
+                prefix = error.message.split.first
+                return prefix if prefix && prefix == prefix.upcase && prefix.match?(/\A[A-Z]+\z/)
+              end
+              error.class.name
+            end
+
+            def redis_error?(error)
+              error.is_a?(::RedisClient::CommandError)
+            end
+
+            def serialize_commands(commands)
+              obfuscate = instrumentation.config[:db_statement] == :obfuscate
+
+              serialized_commands = commands.map do |command|
+                # If we receive an authentication request command we want to obfuscate it
+                if obfuscate || command[0].match?(/\A(AUTH|HELLO)\z/i)
+                  command[0].to_s.upcase + (' ?' * (command.size - 1))
+                else
+                  command_copy = command.dup
+                  command_copy[0] = command_copy[0].to_s.upcase
+                  command_copy.join(' ')
+                end
+              end.join("\n")
+              serialized_commands = OpenTelemetry::Common::Utilities.truncate(serialized_commands, MAX_STATEMENT_LENGTH)
+              OpenTelemetry::Common::Utilities.utf8_encode(serialized_commands, binary: true)
+            end
+
+            def instrumentation
+              Redis::Instrumentation.instance
+            end
+          end
+        end
+      end
+    end
+  end
+end

instrumentation/redis/lib/opentelemetry/instrumentation/redis/middlewares/old/redis_client.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module Redis
+      module Middlewares
+        module Old
+          # Adapter for redis-client instrumentation interface
+          module RedisClientInstrumentation
+            MAX_STATEMENT_LENGTH = 500
+            private_constant :MAX_STATEMENT_LENGTH
+
+            def call(command, redis_config)
+              return super unless instrumentation.config[:trace_root_spans] || OpenTelemetry::Trace.current_span.context.valid?
+
+              attributes = span_attributes(redis_config)
+
+              attributes['db.statement'] = serialize_commands([command]) unless instrumentation.config[:db_statement] == :omit
+
+              span_name = command[0].to_s.upcase
+              instrumentation.tracer.in_span(span_name, attributes: attributes, kind: :client) do
+                super
+              end
+            end
+
+            def call_pipelined(commands, redis_config)
+              return super unless instrumentation.config[:trace_root_spans] || OpenTelemetry::Trace.current_span.context.valid?
+
+              attributes = span_attributes(redis_config)
+
+              attributes['db.statement'] = serialize_commands(commands) unless instrumentation.config[:db_statement] == :omit
+
+              instrumentation.tracer.in_span('PIPELINED', attributes: attributes, kind: :client) do
+                super
+              end
+            end
+
+            private
+
+            def span_attributes(redis_config)
+              attributes = {
+                'db.system' => 'redis',
+                'net.peer.name' => redis_config.host,
+                'net.peer.port' => redis_config.port
+              }
+
+              attributes['db.redis.database_index'] = redis_config.db unless redis_config.db.zero?
+              attributes['peer.service'] = instrumentation.config[:peer_service] if instrumentation.config[:peer_service]
+              attributes.merge!(OpenTelemetry::Instrumentation::Redis.attributes)
+              attributes
+            end
+
+            def serialize_commands(commands)
+              obfuscate = instrumentation.config[:db_statement] == :obfuscate
+
+              serialized_commands = commands.map do |command|
+                # If we receive an authentication request command we want to obfuscate it
+                if obfuscate || command[0].match?(/\A(AUTH|HELLO)\z/i)
+                  command[0].to_s.upcase + (' ?' * (command.size - 1))
+                else
+                  command_copy = command.dup
+                  command_copy[0] = command_copy[0].to_s.upcase
+                  command_copy.join(' ')
+                end
+              end.join("\n")
+              serialized_commands = OpenTelemetry::Common::Utilities.truncate(serialized_commands, MAX_STATEMENT_LENGTH)
+              OpenTelemetry::Common::Utilities.utf8_encode(serialized_commands, binary: true)
+            end
+
+            def instrumentation
+              Redis::Instrumentation.instance
+            end
+          end
+        end
+      end
+    end
+  end
+end