Add active_root_span to Tracer

docs/GettingStarted.md

@@ -229,7 +229,7 @@ def finish(name, id, payload)
   end
 end
 ```
-#####Enriching traces from nested methods
+##### Enriching traces from nested methods
 
 You can tag additional information to current active span from any method. Note however that if the method is called and there is no span currently active `active_span` will be nil.
 
@@ -240,6 +240,15 @@ current_span = Datadog.tracer.active_span
 current_span.set_tag('my_tag', 'my_value') unless current_span.nil?
 ```
 
+You can also get the root span of the current active trace using the `active_root_span` method. This method will return `nil` if there is no active trace.
+
+```ruby
+# e.g. adding tag to active root span
+
+current_root_span = Datadog.tracer.active_root_span
+current_root_span.set_tag('my_tag', 'my_value') unless current_root_span.nil?
+```
+
 ## Integration instrumentation
 
 Many popular libraries and frameworks are supported out-of-the-box, which can be auto-instrumented. Although they are not activated automatically, they can be easily activated and configured by using the `Datadog.configure` API:

lib/ddtrace/context.rb

@@ -63,6 +63,12 @@ def current_span
       end
     end
 
+    def current_root_span
+      @mutex.synchronize do
+        return @current_root_span
+      end
+    end
+
     # Add a span to the context trace list, keeping it as the last active span.
     def add_span(span)
       @mutex.synchronize do
@@ -77,6 +83,7 @@ def add_span(span)
           return
         end
         set_current_span(span)
+        @current_root_span = span if @trace.empty?
         @trace << span
         span.context = self
       end
@@ -158,6 +165,7 @@ def reset(options = {})
       @sampling_priority = options.fetch(:sampling_priority, nil)
       @finished_spans = 0
       @current_span = nil
+      @current_root_span = nil
     end
 
     def set_current_span(span)

lib/ddtrace/tracer.rb

@@ -346,6 +346,11 @@ def active_span
       call_context.current_span
     end
 
+    # Return the current active root span or +nil+.
+    def active_root_span
+      call_context.current_root_span
+    end
+
     # Send the trace to the writer to enqueue the spans list in the agent
     # sending queue.
     def write(trace)

spec/ddtrace/context_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+require 'ddtrace'
+
+RSpec.describe Datadog::Context do
+  subject(:context) { described_class.new(options) }
+  let(:options) { {} }
+  let(:tracer) { ::Datadog::Tracer.new(writer: FauxWriter.new) }
+
+  describe '#current_root_span' do
+    subject(:current_root_span) { context.current_root_span }
+
+    it { is_expected.to be nil }
+
+    context 'after a span is added' do
+      let(:span) { Datadog::Span.new(tracer, 'span.one', context: context) }
+      before(:each) { context.add_span(span) }
+
+      it { is_expected.to be span }
+
+      context 'and is reset' do
+        before(:each) { context.send(:reset) }
+        it { is_expected.to be nil }
+      end
+
+      context 'followed by a second' do
+        let(:span_two) { Datadog::Span.new(tracer, 'span.two', context: context) }
+        before(:each) { context.add_span(span_two) }
+        it { is_expected.to be span }
+      end
+    end
+  end
+end

spec/ddtrace/tracer_spec.rb

@@ -72,4 +72,14 @@
       end
     end
   end
+
+  describe '#active_root_span' do
+    subject(:active_root_span) { tracer.active_root_span }
+    let(:span) { instance_double(Datadog::Span) }
+
+    it do
+      expect(tracer.call_context).to receive(:current_root_span).and_return(span)
+      is_expected.to be(span)
+    end
+  end
 end