Merge pull request #2496 from DataDog/otel-2

OpenTelemetry Traces support

Appraisals

@@ -1225,6 +1225,10 @@ elsif ruby_version?('2.6')
       gem 'rack-test'
     end
 
+    appraise 'opentelemetry' do
+      gem 'opentelemetry-sdk', '~> 1.1'
+    end
+
     [3, 4, 5].each do |n|
       appraise "redis-#{n}" do
         gem 'redis', "~> #{n}"
@@ -1453,6 +1457,10 @@ elsif ruby_version?('2.7')
       gem 'rack-test'
     end
 
+    appraise 'opentelemetry' do
+      gem 'opentelemetry-sdk', '~> 1.1'
+    end
+
     [3, 4, 5].each do |n|
       appraise "redis-#{n}" do
         gem 'redis', "~> #{n}"
@@ -1594,6 +1602,10 @@ elsif ruby_version?('3.0') || ruby_version?('3.1')
     gem 'rack-test'
   end
 
+  appraise 'opentelemetry' do
+    gem 'opentelemetry-sdk', '~> 1.1'
+  end
+
   appraise 'contrib-old' do
     gem 'dalli', '< 3.0.0'
     gem 'elasticsearch', '< 8.0.0' # Dependency elasticsearch-transport renamed to elastic-transport in >= 8.0
@@ -1720,6 +1732,10 @@ elsif ruby_version?('3.2')
     gem 'rack-test'
   end
 
+  appraise 'opentelemetry' do
+    gem 'opentelemetry-sdk', '~> 1.1'
+  end
+
   [3, 4, 5].each do |n|
     appraise "redis-#{n}" do
       gem 'redis', "~> #{n}"

Rakefile

@@ -17,8 +17,8 @@ namespace :spec do
 
   RSpec::Core::RakeTask.new(:main) do |t, args|
     t.pattern = 'spec/**/*_spec.rb'
-    t.exclude_pattern = 'spec/**/{contrib,benchmark,redis,opentracer,auto_instrument}/**/*_spec.rb,'\
-                        ' spec/**/auto_instrument_spec.rb'
+    t.exclude_pattern = 'spec/**/{contrib,benchmark,redis,opentracer,auto_instrument,opentelemetry}/**/*_spec.rb,'\
+                        ' spec/**/{auto_instrument,opentelemetry}_spec.rb'
     t.rspec_opts = args.to_a.join(' ')
   end
   if RUBY_ENGINE == 'ruby' && OS.linux? && Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.2.0')
@@ -37,6 +37,11 @@ namespace :spec do
     t.rspec_opts = args.to_a.join(' ')
   end
 
+  RSpec::Core::RakeTask.new(:opentelemetry) do |t, args|
+    t.pattern = 'spec/datadog/opentelemetry/**/*_spec.rb,spec/datadog/opentelemetry_spec.rb'
+    t.rspec_opts = args.to_a.join(' ')
+  end
+
   RSpec::Core::RakeTask.new(:rails) do |t, args|
     t.pattern = 'spec/datadog/tracing/contrib/rails/**/*_spec.rb'
     t.exclude_pattern = 'spec/datadog/tracing/contrib/rails/**/*{active_job,disable_env,redis_cache,auto_instrument,'\
@@ -273,6 +278,7 @@ task :ci do
   declare '✅ 2.1 / ✅ 2.2 / ✅ 2.3 / ✅ 2.4 / ✅ 2.5 / ✅ 2.6 / ✅ 2.7 / ✅ 3.0 / ✅ 3.1 / ✅ 3.2 / ✅ jruby' => 'bundle exec rake spec:appsec:main'
   declare '✅ 2.1 / ✅ 2.2 / ✅ 2.3 / ✅ 2.4 / ✅ 2.5 / ✅ 2.6 / ✅ 2.7 / ✅ 3.0 / ✅ 3.1 / ✅ 3.2 / ✅ jruby' => 'bundle exec rake spec:contrib'
   declare '✅ 2.1 / ✅ 2.2 / ✅ 2.3 / ✅ 2.4 / ✅ 2.5 / ✅ 2.6 / ✅ 2.7 / ✅ 3.0 / ✅ 3.1 / ✅ 3.2 / ✅ jruby' => 'bundle exec rake spec:opentracer'
+  declare '❌ 2.1 / ❌ 2.2 / ❌ 2.3 / ❌ 2.4 / ❌ 2.5 / ✅ 2.6 / ✅ 2.7 / ✅ 3.0 / ✅ 3.1 / ✅ 3.2 / ❌ jruby' => 'bundle exec appraisal opentelemetry rake spec:opentelemetry'
 
   # Contrib specs
   declare '❌ 2.1 / ✅ 2.2 / ✅ 2.3 / ✅ 2.4 / ✅ 2.5 / ✅ 2.6 / ✅ 2.7 / ✅ 3.0 / ✅ 3.1 / ✅ 3.2 / ✅ jruby' => 'bundle exec appraisal contrib rake spec:action_pack'
@@ -403,6 +409,9 @@ task :ci do
   declare '❌ 2.1 / ✅ 2.2 / ✅ 2.3 / ✅ 2.4 / ✅ 2.5 / ✅ 2.6 / ✅ 2.7 / ❌ 3.0 / ❌ 3.1 / ❌ 3.2 / ❌ jruby' => 'bundle exec appraisal rails5-mysql2 rake spec:appsec:rails'
   declare '❌ 2.1 / ❌ 2.2 / ❌ 2.3 / ❌ 2.4 / ✅ 2.5 / ✅ 2.6 / ✅ 2.7 / ❌ 3.0 / ❌ 3.1 / ❌ 3.2 / ❌ jruby' => 'bundle exec appraisal rails6-mysql2 rake spec:appsec:rails'
   declare '❌ 2.1 / ❌ 2.2 / ❌ 2.3 / ❌ 2.4 / ✅ 2.5 / ✅ 2.6 / ✅ 2.7 / ✅ 3.0 / ✅ 3.1 / ❌ 3.2 / ❌ jruby' => 'bundle exec appraisal rails61-mysql2 rake spec:appsec:rails'
+
+  # Upstream gem test suite with ddtrace enabled
+  declare '❌ 2.1 / ❌ 2.2 / ❌ 2.3 / ❌ 2.4 / ❌ 2.5 / ✅ 2.6 / ✅ 2.7 / ✅ 3.0 / ✅ 3.1 / ✅ 3.2 / ❌ jruby' => 'bundle exec rake upstream:opentelemetry'
 end
 
 namespace :coverage do

docs/GettingStarted.md

@@ -2395,7 +2395,7 @@ Service C:
   Priority:  1
 ```
 
-**Distributed header formats**
+#### Distributed header formats
 
 Tracing supports the following distributed trace formats:
 

docs/OpenTelemetry.md

@@ -0,0 +1,68 @@
+**ATTENTION**:
+
+***OpenTelemetry support is currently "experimental". It may be subject to breaking changes between minor versions, and is not yet recommended for use in production or other sensitive environments.***
+
+If you are interested in using this feature experimentally, please contact the dd-trace-rb maintainers; we would be happy to provide you with more information!
+
+**Supported tracing frameworks**:
+
+| Type          | Documentation                                        | ddtrace version | Gem version support |
+| ------------- | ---------------------------------------------------- | --------------- | ------------------- |
+| OpenTelemetry | https://github.com/open-telemetry/opentelemetry-ruby | 1.9.0+          | >= 1.1.0            |
+
+#### Configuring OpenTelemetry
+
+1. Add the `ddtrace` gem to your Gemfile:
+
+    ```ruby
+    source 'https://rubygems.org'
+    gem 'ddtrace'
+    ```
+
+1. Install the gem with `bundle install`
+1. To your OpenTelemetry configuration file, add the following:
+
+    ```ruby
+    require 'opentelemetry'
+    require 'datadog/opentelemetry'
+    ```
+
+1. Add a configuration block to your application:
+
+    ```ruby
+    Datadog.configure do |c|
+      # Configure the Datadog tracer here.
+      # Activate integrations, change tracer settings, etc...
+      # By default without additional configuration,
+      # no additional integrations will be traced, only
+      # what you have instrumented with OpenTelemetry.
+    end
+    ```
+
+   Using this block you can:
+
+    - [Add additional Datadog configuration settings](#additional-configuration)
+    - [Activate or reconfigure Datadog instrumentation](#integration-instrumentation)
+
+1. OpenTelemetry spans and Datadog APM spans will now be combined into a single trace your application.
+
+   [Integration instrumentations](#integration-instrumentation) and OpenTelemetry [Automatic instrumentations](https://opentelemetry.io/docs/instrumentation/ruby/automatic/) are also supported.
+
+##### Limitations
+
+There are a few limitations to OpenTelemetry Tracing when the APM integration is activated:
+
+| Feature                                                                                                    | Support?    | Explanation                                                                       | Recommendation                                       |   |
+|------------------------------------------------------------------------------------------------------------|-------------|-----------------------------------------------------------------------------------|------------------------------------------------------|---|
+| [Context propagation](https://opentelemetry.io/docs/instrumentation/ruby/manual/#context-propagation)      | Unsupported | Datadog [distributed header format](#distributed-header-formats) is used instead. | N/A                                                  |   |
+| [Span processors](https://opentelemetry.io/docs/reference/specification/trace/sdk/#span-processor)         | Unsupported |                                                                                   | N/A                                                  |   |
+| [Span Exporters](https://opentelemetry.io/docs/reference/specification/trace/sdk/#span-exporter)           | Unsupported |                                                                                   | N/A                                                  |   |
+| `OpenTelemetry.logger`                                                                                     | Special     | `OpenTelemetry.logger` is set to the same object as `Datadog.logger`.             | Configure through [Custom logging](#custom-logging). |   |
+| Trace/span [ID generators](https://opentelemetry.io/docs/reference/specification/trace/sdk/#id-generators) | Special     | ID generation is performed by `ddtrace`.                                          | N/A                                                  |   |
+
+##### Exporting OpenTelemetry-only traces
+
+You can send OpenTelemetry traces directly to the Datadog agent (without `ddtrace`) by using [OTLP](https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-exporter-otlp/latest).
+Check out our documentation on [OTLP ingest in the Datadog Agent](https://docs.datadoghq.com/tracing/setup_overview/open_standards/#otlp-ingest-in-datadog-agent) for details.
+
+Datadog APM spans will not be sent through the OTLP exporter.