feat: draft - MySQL2 Semantic Stability

instrumentation/mysql2/Appraisals

@@ -1,5 +1,14 @@
 # frozen_string_literal: true
 
-appraise 'mysql2-latest' do
-  gem 'mysql2'
+# 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|
+  appraise "mysql2-latest-#{stability}" do
+    gem 'mysql2'
+  end
 end

instrumentation/mysql2/README.md

@@ -63,6 +63,22 @@ The `opentelemetry-instrumentation-mysql2` 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 MYSQL2 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, MYSQL2 instrumentation code comes in three patch versions: `dup`, `old`, and `stable`. These versions are identical except for the attributes they send. Any changes to MYSQL2 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
 
 The `opentelemetry-instrumentation-mysql2` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.

instrumentation/mysql2/Rakefile

@@ -11,6 +11,14 @@ require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 
+# Set OTEL_SEMCONV_STABILITY_OPT_IN based on appraisal name
+gemfile = ENV.fetch('BUNDLE_GEMFILE', '')
+if gemfile.include?('stable')
+  ENV['OTEL_SEMCONV_STABILITY_OPT_IN'] = 'database'
+elsif gemfile.include?('dup')
+  ENV['OTEL_SEMCONV_STABILITY_OPT_IN'] = 'database/dup'
+end
+
 Rake::TestTask.new :test do |t|
   t.libs << 'test'
   t.libs << 'lib'

instrumentation/mysql2/lib/opentelemetry/instrumentation/mysql2/instrumentation.rb

@@ -26,16 +26,47 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
         option :obfuscation_limit, default: 2000, validate: :integer
         option :propagator, default: 'none', validate: %w[none tracecontext vitess]
 
-        attr_reader :propagator
+        attr_reader :propagator, :semconv
 
         private
 
+        def determine_semconv
+          opt_in = ENV.fetch('OTEL_SEMCONV_STABILITY_OPT_IN', nil)
+          return :old if opt_in.nil?
+
+          opt_in_values = opt_in.split(',').map(&:strip)
+
+          if opt_in_values.include?('database/dup')
+            :dup
+          elsif opt_in_values.include?('database')
+            :stable
+          else
+            :old
+          end
+        end
+
         def require_dependencies
-          require_relative 'patches/client'
+          @semconv = determine_semconv
+
+          case @semconv
+          when :old
+            require_relative 'patches/old/client'
+          when :stable
+            require_relative 'patches/stable/client'
+          when :dup
+            require_relative 'patches/dup/client'
+          end
         end
 
         def patch_client
-          ::Mysql2::Client.prepend(Patches::Client)
+          case @semconv
+          when :old
+            ::Mysql2::Client.prepend(Patches::Old::Client)
+          when :stable
+            ::Mysql2::Client.prepend(Patches::Stable::Client)
+          when :dup
+            ::Mysql2::Client.prepend(Patches::Dup::Client)
+          end
         end
 
         def configure_propagator(config)

instrumentation/mysql2/lib/opentelemetry/instrumentation/mysql2/patches/dup/client.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry-helpers-mysql'
+require 'opentelemetry-helpers-sql-processor'
+
+module OpenTelemetry
+  module Instrumentation
+    module Mysql2
+      module Patches
+        module Dup
+          # Module to prepend to Mysql2::Client for instrumentation
+          # Emits both old and stable semantic convention attributes
+          module Client
+            def query(sql, options = {})
+              tracer.in_span(
+                _otel_span_name(sql),
+                attributes: _otel_span_attributes(sql),
+                kind: :client
+              ) do |span, context|
+                if propagator && sql.frozen?
+                  sql = +sql
+                  propagator.inject(sql, context: context)
+                  sql.freeze
+                elsif propagator
+                  propagator.inject(sql, context: context)
+                end
+
+                super(sql, options)
+              rescue StandardError => e
+                set_error_attributes(span, e)
+                raise
+              end
+            end
+
+            def prepare(sql)
+              tracer.in_span(
+                _otel_span_name(sql),
+                attributes: _otel_span_attributes(sql),
+                kind: :client
+              ) do |span, context|
+                if propagator && sql.frozen?
+                  sql = +sql
+                  propagator.inject(sql, context: context)
+                  sql.freeze
+                elsif propagator
+                  propagator.inject(sql, context: context)
+                end
+
+                super(sql)
+              rescue StandardError => e
+                set_error_attributes(span, e)
+                raise
+              end
+            end
+
+            private
+
+            def _otel_span_name(sql)
+              OpenTelemetry::Helpers::MySQL.database_span_name(
+                sql,
+                OpenTelemetry::Instrumentation::Mysql2.attributes[SemanticConventions::Trace::DB_OPERATION] ||
+                  OpenTelemetry::Instrumentation::Mysql2.attributes['db.operation.name'],
+                _otel_database_name,
+                config
+              )
+            end
+
+            def _otel_span_attributes(sql)
+              attributes = _otel_client_attributes
+              case config[:db_statement]
+              when :include
+                # Both old and stable
+                attributes[SemanticConventions::Trace::DB_STATEMENT] = sql
+                attributes['db.query.text'] = sql
+              when :obfuscate
+                obfuscated = OpenTelemetry::Helpers::SqlProcessor.obfuscate_sql(
+                  sql, obfuscation_limit: config[:obfuscation_limit], adapter: :mysql
+                )
+                # Both old and stable
+                attributes[SemanticConventions::Trace::DB_STATEMENT] = obfuscated
+                attributes['db.query.text'] = obfuscated
+              end
+
+              attributes.merge!(OpenTelemetry::Instrumentation::Mysql2.attributes)
+              attributes.compact!
+              attributes
+            end
+
+            def _otel_database_name
+              # https://github.com/brianmario/mysql2/blob/ca08712c6c8ea672df658bb25b931fea22555f27/lib/mysql2/client.rb#L78
+              (query_options[:database] || query_options[:dbname] || query_options[:db])&.to_s
+            end
+
+            def _otel_client_attributes
+              # The client specific attributes can be found via the query_options instance variable
+              # exposed on the mysql2 Client
+              # https://github.com/brianmario/mysql2/blob/ca08712c6c8ea672df658bb25b931fea22555f27/lib/mysql2/client.rb#L25-L26
+              host = (query_options[:host] || query_options[:hostname]).to_s
+              port = query_options[:port]
+
+              attributes = {
+                # Old attributes
+                SemanticConventions::Trace::DB_SYSTEM => 'mysql',
+                SemanticConventions::Trace::NET_PEER_NAME => host,
+                SemanticConventions::Trace::NET_PEER_PORT => port.to_s,
+                # Stable attributes
+                'db.system.name' => 'mysql',
+                'server.address' => host
+              }
+
+              # Always include server.port when present (important for sampling)
+              attributes['server.port'] = port.to_i if port
+
+              # Both old and stable database name
+              attributes[SemanticConventions::Trace::DB_NAME] = _otel_database_name
+              attributes['db.namespace'] = _otel_database_name
+
+              attributes[SemanticConventions::Trace::PEER_SERVICE] = config[:peer_service]
+              attributes
+            end
+
+            def set_error_attributes(span, error)
+              span.set_attribute('error.type', error.class.name)
+              span.set_attribute('db.response.status_code', error.error_number.to_s) if error.respond_to?(:error_number) && error.error_number
+            end
+
+            def tracer
+              Mysql2::Instrumentation.instance.tracer
+            end
+
+            def config
+              Mysql2::Instrumentation.instance.config
+            end
+
+            def propagator
+              Mysql2::Instrumentation.instance.propagator
+            end
+          end
+        end
+      end
+    end
+  end
+end