Datadog::Correlation usage improvements

docs/GettingStarted.md

@@ -1608,9 +1608,35 @@ Datadog::Pipeline.before_flush(
 
 ### Trace correlation
 
-In many cases, such as logging, it may be useful to correlate trace IDs to other events or data streams, for easier cross referencing. The tracer can produce a correlation identifier for the currently active trace via `active_correlation_ids`, which can be used to decorate these other data sources.
+In many cases, such as logging, it may be useful to correlate trace IDs to other events or data streams, for easier cross referencing. The tracer can produce a correlation identifier for the currently active trace via `active_correlation`, which can be used to decorate these other data sources.
 
-An example of this for the purpose of logging:
+```ruby
+# When a trace is active...
+Datadog.tracer.trace('correlation.example') do
+  # Returns #<Datadog::Correlation::Identifier>
+  correlation = Datadog.tracer.active_correlation
+  correlation.trace_id # => 5963550561812073440
+  correlation.span_id # => 2232727802607726424
+end
+
+# When a trace isn't active...
+correlation = Datadog.tracer.active_correlation
+# Returns #<Datadog::Correlation::Identifier>
+correlation = Datadog.tracer.active_correlation
+correlation.trace_id # => 0
+correlation.span_id # => 0
+```
+
+#### For logging
+
+To add correlation IDs to your logger, simply add a log formatter which retrieve the correlation IDs via `Datadog.tracer.active_correlation`, then add them to the message.
+
+To properly correlate with Datadog logging, be sure the following is present:
+
+ - `dd.trace_id=<trace_id>`: Where `<trace_id>` is `Datadog.tracer.active_correlation.trace_id`. `0` if no trace active.
+ - `dd.span_id=<span_id>`: Where `<span_id>` is `Datadog.tracer.active_correlation.span_id`. `0` if no trace active.
+
+An example of this in practice:
 
 ```ruby
 require 'ddtrace'
@@ -1620,25 +1646,9 @@ logger = Logger.new(STDOUT)
 logger.progname = 'my_app'
 logger.formatter  = proc do |severity, datetime, progname, msg|
   # Returns Datadog::Correlation::Identifier
-  ids = Datadog.tracer.active_correlation_ids
+  ids = Datadog.tracer.active_correlation
   "[#{datetime}][#{progname}][#{severity}][dd.trace_id=#{ids.trace_id} dd.span_id=#{ids.span_id}] #{msg}\n"
 end
-
-# When a trace is active...
-Datadog.tracer.trace('logging.example') do
-  # And a warning is produced...
-  logger.warn('This is a warning.')
-
-  # Prints:
-  # [2018-12-18 22:42:25 +0000][my_app][WARN][dd.trace_id=5963550561812073440 dd.span_id=2232727802607726424] This is a warning.
-end
-
-# When no trace is active...
-# And a warning is produced...
-logger.warn('This is a warning.')
-
-# Prints:
-# [2018-12-18 22:44:19 +0000][my_app][WARN][dd.trace_id= dd.span_id=] This is a warning.
 ```
 
 ### OpenTracing

lib/ddtrace/correlation.rb

@@ -3,7 +3,18 @@ module Datadog
   # e.g. Retrieve a correlation to the current trace for logging, etc.
   module Correlation
     # Struct representing correlation
-    Identifier = Struct.new(:trace_id, :span_id)
+    Identifier = Struct.new(:trace_id, :span_id).tap do |struct|
+      # Do this #class_eval here for Ruby 1.9.3 support.
+      # Ruby 2.0+ supports passing a block to Struct::new instead.
+      struct.class_eval do
+        def initialize(*args)
+          super
+          self.trace_id = trace_id || 0
+          self.span_id = span_id || 0
+        end
+      end
+    end.freeze
+
     NULL_IDENTIFIER = Identifier.new.freeze
 
     module_function

lib/ddtrace/tracer.rb

@@ -359,7 +359,7 @@ def active_root_span
     end
 
     # Return a CorrelationIdentifier for active span
-    def active_correlation_ids
+    def active_correlation
       Datadog::Correlation.identifier_from_context(call_context)
     end
 

spec/ddtrace/correlation_spec.rb

@@ -12,8 +12,8 @@
 
       it 'returns an empty Correlation::Identifier' do
         is_expected.to be_a_kind_of(Datadog::Correlation::Identifier)
-        expect(correlation_ids.trace_id).to be nil
-        expect(correlation_ids.span_id).to be nil
+        expect(correlation_ids.trace_id).to be 0
+        expect(correlation_ids.span_id).to be 0
       end
     end
 

spec/ddtrace/tracer_spec.rb

@@ -97,8 +97,8 @@
     end
   end
 
-  describe '#active_correlation_ids' do
-    subject(:active_correlation_ids) { tracer.active_correlation_ids }
+  describe '#active_correlation' do
+    subject(:active_correlation) { tracer.active_correlation }
 
     context 'when a trace is active' do
       let(:span) { @span }
@@ -112,16 +112,16 @@
 
       it 'produces an Datadog::Correlation::Identifier with data' do
         is_expected.to be_a_kind_of(Datadog::Correlation::Identifier)
-        expect(active_correlation_ids.trace_id).to eq(span.trace_id)
-        expect(active_correlation_ids.span_id).to eq(span.span_id)
+        expect(active_correlation.trace_id).to eq(span.trace_id)
+        expect(active_correlation.span_id).to eq(span.span_id)
       end
     end
 
     context 'when no trace is active' do
       it 'produces an empty Datadog::Correlation::Identifier' do
         is_expected.to be_a_kind_of(Datadog::Correlation::Identifier)
-        expect(active_correlation_ids.trace_id).to be nil
-        expect(active_correlation_ids.span_id).to be nil
+        expect(active_correlation.trace_id).to be 0
+        expect(active_correlation.span_id).to be 0
       end
     end
   end