Add README and consider database migration env vars

Author: hannahramadan

instrumentation/http/README.md

@@ -64,3 +64,19 @@ The `opentelemetry-instrumentation-http` gem is distributed under the Apache 2.0
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
 [slack-channel]: https://cloud-native.slack.com/archives/C01NWKKMKMY
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions
+
+## HTTP semantic convention stability
+
+In the OpenTelemetry ecosystem, HTTP semantic conventions have now reached a stable state. However, the initial HTTP instrumentation was introduced before this stability was achieved, which resulted in HTTP 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:
+
+- `http` - Emits the stable HTTP and networking conventions and ceases emitting the old conventions previously emitted by the instrumentation.
+- `http/dup` - Emits both the old and stable HTTP 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 HTTP and networking conventions the instrumentation previously emitted.
+
+During the transition from old to stable conventions, HTTP instrumentation code comes in three patch versions: `dup`, `old`, and `stable`. These versions are identical except for the attributes they send. Any changes to HTTP instrumentation should consider all three patches.
+
+For additional information on migration, please refer to our [documentation](https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/).

instrumentation/http/lib/opentelemetry/instrumentation/http/instrumentation.rb

@@ -22,10 +22,12 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
         option :span_name_formatter, default: nil, validate: :callable
 
         def determine_semconv
-          case ENV.fetch('OTEL_SEMCONV_STABILITY_OPT_IN', nil)
-          when 'http/dup'
+          stability_opt_in = ENV.fetch('OTEL_SEMCONV_STABILITY_OPT_IN', nil)
+          values = stability_opt_in&.split(',')
+
+          if values.include?('http/dup')
             'dup'
-          when 'http'
+          elsif values.include?('http')
             'stable'
           else
             'old'

instrumentation/http/test/instrumentation/http/patches/dup/client_test.rb

@@ -23,7 +23,7 @@
   before do
     skip unless ENV['BUNDLE_GEMFILE'].include?('dup')
 
-    ENV['OTEL_SEMCONV_STABILITY_OPT_IN'] = 'http/dup'
+    ENV['OTEL_SEMCONV_STABILITY_OPT_IN'] = 'http/dup, database'
     exporter.reset
     @orig_propagation = OpenTelemetry.propagation
     propagator = OpenTelemetry::Trace::Propagation::TraceContext.text_map_propagator

instrumentation/http/test/instrumentation/http/patches/dup/connection_test.rb

@@ -17,7 +17,7 @@
   before do
     skip unless ENV['BUNDLE_GEMFILE'].include?('dup')
 
-    ENV['OTEL_SEMCONV_STABILITY_OPT_IN'] = 'http/dup'
+    ENV['OTEL_SEMCONV_STABILITY_OPT_IN'] = 'http/dup, database'
     exporter.reset
     instrumentation.install({})
   end