feat: Trilogy semantic convention stability

helpers/mysql/lib/opentelemetry/helpers/mysql.rb

@@ -2,7 +2,8 @@
 
 # Copyright The OpenTelemetry Authors
 #
-# SPDX-License-Identifier: Apache-2.0module OpenTelemetry
+# SPDX-License-Identifier: Apache-2.0
+
 require 'opentelemetry-common'
 
 module OpenTelemetry
@@ -66,6 +67,31 @@ def database_span_name(sql, operation, database_name, config)
         end || 'mysql'
       end
 
+      # Span naming following stable database semantic conventions.
+      # Per spec: {db.query.summary} -> {db.operation.name} {target} -> {target} -> {db.system.name}
+      # We don't have db.query.summary, so we use:
+      # {db.operation.name} {db.namespace} -> {db.namespace} -> mysql
+      #
+      # Note: Per spec, db.operation.name SHOULD NOT be extracted from db.query.text.
+      # The operation should only be used if explicitly provided by the application
+      # (e.g., via with_attributes).
+      #
+      # @param operation [String] The database operation (db.operation.name), if provided by the application.
+      # @param database_name [String] The name of the database (db.namespace).
+      # @return [String] The span name.
+      # @api private
+      def stable_database_span_name(operation, database_name)
+        if operation && database_name
+          "#{operation} #{database_name}"
+        elsif database_name
+          database_name
+        elsif operation
+          operation
+        else
+          'mysql'
+        end
+      end
+
       # @api private
       def extract_statement_type(sql)
         return unless sql

helpers/mysql/test/helpers/mysql_test.rb

@@ -55,6 +55,51 @@
     end
   end
 
+  describe '.stable_database_span_name' do
+    let(:operation) { 'SELECT' }
+    let(:database_name) { 'mydb' }
+    let(:stable_span_name) { OpenTelemetry::Helpers::MySQL.stable_database_span_name(operation, database_name) }
+
+    describe 'when operation and database_name are present' do
+      it 'returns "{operation} {database_name}"' do
+        assert_equal('SELECT mydb', stable_span_name)
+      end
+    end
+
+    describe 'when only database_name is present' do
+      let(:operation) { nil }
+
+      it 'returns database_name' do
+        assert_equal('mydb', stable_span_name)
+      end
+    end
+
+    describe 'when only operation is present' do
+      let(:database_name) { nil }
+
+      it 'returns operation' do
+        assert_equal('SELECT', stable_span_name)
+      end
+    end
+
+    describe 'when both operation and database_name are nil' do
+      let(:operation) { nil }
+      let(:database_name) { nil }
+
+      it 'returns mysql as fallback' do
+        assert_equal('mysql', stable_span_name)
+      end
+    end
+
+    describe 'preserves operation case as provided' do
+      it 'does not normalize case' do
+        assert_equal('select mydb', OpenTelemetry::Helpers::MySQL.stable_database_span_name('select', 'mydb'))
+        assert_equal('SELECT mydb', OpenTelemetry::Helpers::MySQL.stable_database_span_name('SELECT', 'mydb'))
+        assert_equal('Select mydb', OpenTelemetry::Helpers::MySQL.stable_database_span_name('Select', 'mydb'))
+      end
+    end
+  end
+
   describe '.db_operation_and_name' do
     let(:operation) { 'operation' }
     let(:database_name) { 'database_name' }

instrumentation/trilogy/.rubocop.yml

@@ -1 +1,6 @@
 inherit_from: ../../.rubocop.yml
+
+Metrics/ModuleLength:
+  Exclude:
+    - "lib/opentelemetry/instrumentation/trilogy/patches/stable/client.rb"
+    - "lib/opentelemetry/instrumentation/trilogy/patches/dup/client.rb"

instrumentation/trilogy/Appraisals

@@ -4,10 +4,19 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-appraise 'trilogy-2.9' do
-  gem 'trilogy', '~> 2.9.0'
-end
+# 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 |mode|
+  appraise "trilogy-2-#{mode}" do
+    gem 'trilogy', '~> 2.9'
+  end
 
-appraise 'trilogy-latest' do
-  gem 'trilogy'
+  appraise "trilogy-latest-#{mode}" do
+    gem 'trilogy'
+  end
 end

instrumentation/trilogy/README.md

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

instrumentation/trilogy/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/trilogy/lib/opentelemetry/instrumentation/trilogy/instrumentation.rb

@@ -30,16 +30,47 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
         option :propagator, default: 'none', validate: %w[none tracecontext vitess]
         option :record_exception, default: true, validate: :boolean
 
-        attr_reader :propagator
+        attr_reader :propagator, :semconv
 
         private
 
         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
-          ::Trilogy.prepend(Patches::Client)
+          case @semconv
+          when :old
+            ::Trilogy.prepend(Patches::Old::Client)
+          when :stable
+            ::Trilogy.prepend(Patches::Stable::Client)
+          when :dup
+            ::Trilogy.prepend(Patches::Dup::Client)
+          end
+        end
+
+        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 configure_propagator(config)