datadog-ci 0.4.0 → 0.5.0

data/lib/datadog/ci/null_span.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "datadog/tracing/span_operation"
+
+module Datadog
+  module CI
+    # Represents an ignored span when CI visibility is disabled.
+    # Replaces all methods with no-op.
+    #
+    # @public_api
+    class NullSpan < Span
+      def initialize
+        super(Datadog::Tracing::SpanOperation.new("null.span"))
+      end
+
+      def id
+      end
+
+      def name
+      end
+
+      def service
+      end
+
+      def span_type
+      end
+
+      def passed!
+      end
+
+      def failed!(exception: nil)
+      end
+
+      def skipped!(exception: nil, reason: nil)
+      end
+
+      def get_tag(key)
+      end
+
+      def set_tag(key, value)
+      end
+
+      def set_metric(key, value)
+      end
+
+      def finish
+      end
+
+      def set_tags(tags)
+      end
+
+      def set_environment_runtime_tags
+      end
+
+      def set_default_tags
+      end
+
+      def to_s
+        self.class.to_s
+      end
+    end
+  end
+end

data/lib/datadog/ci/recorder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "datadog/tracing"
+require "datadog/tracing/trace_digest"
 
 require "rbconfig"
 
@@ -8,36 +9,98 @@ require_relative "ext/app_types"
 require_relative "ext/test"
 require_relative "ext/environment"
 
+require_relative "context/global"
 require_relative "context/local"
 
 require_relative "span"
+require_relative "null_span"
 require_relative "test"
+require_relative "test_session"
+require_relative "test_module"
+require_relative "test_suite"
 
 module Datadog
   module CI
     # Common behavior for CI tests
+    # Note: this class has too many responsibilities and should be split into multiple classes
     class Recorder
-      attr_reader :environment_tags
+      attr_reader :environment_tags, :test_suite_level_visibility_enabled, :enabled
+
+      def initialize(enabled: true, test_suite_level_visibility_enabled: false)
+        @enabled = enabled
+        @test_suite_level_visibility_enabled = enabled && test_suite_level_visibility_enabled
 
-      def initialize
         @environment_tags = Ext::Environment.tags(ENV).freeze
         @local_context = Context::Local.new
+        @global_context = Context::Global.new
+      end
+
+      def start_test_session(service: nil, tags: {})
+        return skip_tracing unless test_suite_level_visibility_enabled
+
+        @global_context.fetch_or_activate_test_session do
+          tracer_span = start_datadog_tracer_span(
+            "test.session", build_span_options(service, Ext::AppTypes::TYPE_TEST_SESSION)
+          )
+          set_session_context(tags, tracer_span)
+
+          build_test_session(tracer_span, tags)
+        end
+      end
+
+      def start_test_module(test_module_name, service: nil, tags: {})
+        return skip_tracing unless test_suite_level_visibility_enabled
+
+        @global_context.fetch_or_activate_test_module do
+          set_inherited_globals(tags)
+          set_session_context(tags)
+
+          tracer_span = start_datadog_tracer_span(
+            test_module_name, build_span_options(service, Ext::AppTypes::TYPE_TEST_MODULE)
+          )
+          set_module_context(tags, tracer_span)
+
+          build_test_module(tracer_span, tags)
+        end
       end
 
-      # Creates a new span for a CI test
-      def trace_test(test_name, service_name: nil, operation_name: "test", tags: {}, &block)
-        span_options = {
-          resource: test_name,
-          service: service_name,
-          span_type: Ext::AppTypes::TYPE_TEST
-        }
+      def start_test_suite(test_suite_name, service: nil, tags: {})
+        return skip_tracing unless test_suite_level_visibility_enabled
+
+        @global_context.fetch_or_activate_test_suite(test_suite_name) do
+          set_inherited_globals(tags)
+          set_session_context(tags)
+          set_module_context(tags)
+
+          tracer_span = start_datadog_tracer_span(
+            test_suite_name, build_span_options(service, Ext::AppTypes::TYPE_TEST_SUITE)
+          )
+          set_suite_context(tags, span: tracer_span)
+
+          build_test_suite(tracer_span, tags)
+        end
+      end
+
+      def trace_test(test_name, test_suite_name, service: nil, tags: {}, &block)
+        return skip_tracing(block) unless enabled
+
+        set_inherited_globals(tags)
+        set_session_context(tags)
+        set_module_context(tags)
+        set_suite_context(tags, name: test_suite_name)
 
         tags[Ext::Test::TAG_NAME] = test_name
 
-        if block
-          Datadog::Tracing.trace(operation_name, **span_options) do |tracer_span, trace|
-            set_trace_origin(trace)
+        span_options = build_span_options(
+          service,
+          Ext::AppTypes::TYPE_TEST,
+          # :resource is needed for the agent APM protocol to work correctly (for older agent versions)
+          # :continue_from is required to start a new trace for each test
+          {resource: test_name, continue_from: Datadog::Tracing::TraceDigest.new}
+        )
 
+        if block
+          start_datadog_tracer_span(test_name, span_options) do |tracer_span|
             test = build_test(tracer_span, tags)
 
             @local_context.activate_test!(test) do
@@ -45,10 +108,7 @@ module Datadog
             end
           end
         else
-          tracer_span = Datadog::Tracing.trace(operation_name, **span_options)
-          trace = Datadog::Tracing.active_trace
-
-          set_trace_origin(trace)
+          tracer_span = start_datadog_tracer_span(test_name, span_options)
 
           test = build_test(tracer_span, tags)
           @local_context.activate_test!(test)
@@ -57,62 +117,174 @@ module Datadog
       end
 
       def trace(span_type, span_name, tags: {}, &block)
-        span_options = {
-          resource: span_name,
-          span_type: span_type
-        }
+        return skip_tracing(block) unless enabled
+
+        span_options = build_span_options(
+          nil, # service name is completely optional for custom spans
+          span_type,
+          {resource: span_name}
+        )
 
         if block
-          Datadog::Tracing.trace(span_name, **span_options) do |tracer_span, trace|
+          start_datadog_tracer_span(span_name, span_options) do |tracer_span|
             block.call(build_span(tracer_span, tags))
           end
         else
-          tracer_span = Datadog::Tracing.trace(span_name, **span_options)
+          tracer_span = start_datadog_tracer_span(span_name, span_options)
 
           build_span(tracer_span, tags)
         end
       end
 
+      def active_span
+        tracer_span = Datadog::Tracing.active_span
+        Span.new(tracer_span) if tracer_span
+      end
+
       def active_test
         @local_context.active_test
       end
 
+      def active_test_session
+        @global_context.active_test_session
+      end
+
+      def active_test_module
+        @global_context.active_test_module
+      end
+
+      def active_test_suite(test_suite_name)
+        @global_context.active_test_suite(test_suite_name)
+      end
+
       def deactivate_test(test)
         @local_context.deactivate_test!(test)
       end
 
-      def active_span
-        tracer_span = Datadog::Tracing.active_span
-        Span.new(tracer_span) if tracer_span
+      def deactivate_test_session
+        @global_context.deactivate_test_session!
+      end
+
+      def deactivate_test_module
+        @global_context.deactivate_test_module!
+      end
+
+      def deactivate_test_suite(test_suite_name)
+        @global_context.deactivate_test_suite!(test_suite_name)
       end
 
       private
 
+      def skip_tracing(block = nil)
+        if block
+          block.call(null_span)
+        else
+          null_span
+        end
+      end
+
       # Sets trace's origin to ciapp-test
       def set_trace_origin(trace)
         trace.origin = Ext::Test::CONTEXT_ORIGIN if trace
       end
 
-      def build_test(tracer_span, tags)
-        test = Test.new(tracer_span)
+      def build_test_session(tracer_span, tags)
+        test_session = TestSession.new(tracer_span)
+        set_initial_tags(test_session, tags)
+        test_session
+      end
 
-        test.set_default_tags
-        test.set_environment_runtime_tags
+      def build_test_module(tracer_span, tags)
+        test_module = TestModule.new(tracer_span)
+        set_initial_tags(test_module, tags)
+        test_module
+      end
 
-        test.set_tags(tags)
-        test.set_tags(environment_tags)
+      def build_test_suite(tracer_span, tags)
+        test_suite = TestSuite.new(tracer_span)
+        set_initial_tags(test_suite, tags)
+        test_suite
+      end
 
+      def build_test(tracer_span, tags)
+        test = Test.new(tracer_span)
+        set_initial_tags(test, tags)
         test
       end
 
       def build_span(tracer_span, tags)
         span = Span.new(tracer_span)
+        set_initial_tags(span, tags)
+        span
+      end
 
-        span.set_default_tags
-        span.set_environment_runtime_tags
-        span.set_tags(tags)
+      def build_span_options(service, span_type, other_options = {})
+        other_options[:service] = service || @global_context.service
+        other_options[:span_type] = span_type
 
-        span
+        other_options
+      end
+
+      def set_inherited_globals(tags)
+        # this code achieves the same as @global_context.inheritable_session_tags.merge(tags)
+        # but without allocating a new hash
+        @global_context.inheritable_session_tags.each do |key, value|
+          tags[key] = value unless tags.key?(key)
+        end
+      end
+
+      def set_initial_tags(ci_span, tags)
+        ci_span.set_default_tags
+        ci_span.set_environment_runtime_tags
+
+        ci_span.set_tags(tags)
+        ci_span.set_tags(environment_tags)
+      end
+
+      def set_session_context(tags, test_session = nil)
+        test_session ||= active_test_session
+        tags[Ext::Test::TAG_TEST_SESSION_ID] = test_session.id.to_s if test_session
+      end
+
+      def set_module_context(tags, test_module = nil)
+        test_module ||= active_test_module
+        if test_module
+          tags[Ext::Test::TAG_TEST_MODULE_ID] = test_module.id.to_s
+          tags[Ext::Test::TAG_MODULE] = test_module.name
+        end
+      end
+
+      def set_suite_context(tags, span: nil, name: nil)
+        return if span.nil? && name.nil?
+
+        test_suite = span || active_test_suite(name)
+
+        if test_suite
+          tags[Ext::Test::TAG_TEST_SUITE_ID] = test_suite.id.to_s
+          tags[Ext::Test::TAG_SUITE] = test_suite.name
+        else
+          tags[Ext::Test::TAG_SUITE] = name
+        end
+      end
+
+      def start_datadog_tracer_span(span_name, span_options, &block)
+        if block
+          Datadog::Tracing.trace(span_name, **span_options) do |tracer_span, trace|
+            set_trace_origin(trace)
+
+            yield tracer_span
+          end
+        else
+          tracer_span = Datadog::Tracing.trace(span_name, **span_options)
+          trace = Datadog::Tracing.active_trace
+          set_trace_origin(trace)
+
+          tracer_span
+        end
+      end
+
+      def null_span
+        @null_span ||= NullSpan.new
       end
     end
   end

data/lib/datadog/ci/span.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "ext/test"
+require_relative "utils/test_run"
 
 module Datadog
   module CI
@@ -15,11 +16,21 @@ module Datadog
         @tracer_span = tracer_span
       end
 
+      # @return [Integer] the ID of the span.
+      def id
+        tracer_span.id
+      end
+
       # @return [String] the name of the span.
       def name
         tracer_span.name
       end
 
+      # @return [String] the service name of the span.
+      def service
+        tracer_span.service
+      end
+
       # @return [String] the type of the span (for example "test" or type that was provided to [Datadog::CI.trace]).
       def span_type
         tracer_span.type
@@ -83,9 +94,7 @@ module Datadog
       # @param [Hash[String, String]] tags the tags to set.
       # @return [void]
       def set_tags(tags)
-        tags.each do |key, value|
-          tracer_span.set_tag(key, value)
-        end
+        tracer_span.set_tags(tags)
       end
 
       def set_environment_runtime_tags
@@ -93,6 +102,7 @@ module Datadog
         tracer_span.set_tag(Ext::Test::TAG_OS_PLATFORM, ::RbConfig::CONFIG["host_os"])
         tracer_span.set_tag(Ext::Test::TAG_RUNTIME_NAME, Core::Environment::Ext::LANG_ENGINE)
         tracer_span.set_tag(Ext::Test::TAG_RUNTIME_VERSION, Core::Environment::Ext::ENGINE_VERSION)
+        tracer_span.set_tag(Ext::Test::TAG_COMMAND, Utils::TestRun.command)
       end
 
       def set_default_tags

data/lib/datadog/ci/test.rb

@@ -5,7 +5,6 @@ require_relative "span"
 module Datadog
   module CI
     # Represents a single part of a test run.
-    # Could be a session, suite, test, or any custom span.
     #
     # @public_api
     class Test < Span

data/lib/datadog/ci/test_module.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "concurrent_span"
+
+module Datadog
+  module CI
+    # Represents a single test module.
+    # Read here on what test module could mean:
+    # https://docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#module
+    # This object can be shared between multiple threads.
+    #
+    # @public_api
+    class TestModule < ConcurrentSpan
+      # Finishes this test module.
+      # @return [void]
+      def finish
+        super
+
+        CI.deactivate_test_module
+      end
+    end
+  end
+end

data/lib/datadog/ci/test_session.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "concurrent_span"
+require_relative "ext/test"
+
+module Datadog
+  module CI
+    # Represents the whole test session process.
+    # Documentation on test sessions is here:
+    # https://docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#sessions
+    # This object can be shared between multiple threads.
+    #
+    # @public_api
+    class TestSession < ConcurrentSpan
+      # Finishes the current test session.
+      # @return [void]
+      def finish
+        super
+
+        CI.deactivate_test_session
+      end
+
+      def inheritable_tags
+        return @inheritable_tags if defined?(@inheritable_tags)
+
+        # this method is not synchronized because it does not iterate over the tags collection, but rather
+        # uses synchronized method to get each tag value
+        res = {}
+        Ext::Test::INHERITABLE_TAGS.each do |tag|
+          res[tag] = get_tag(tag)
+        end
+        @inheritable_tags = res.freeze
+      end
+    end
+  end
+end

data/lib/datadog/ci/test_suite.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "concurrent_span"
+
+module Datadog
+  module CI
+    # Represents a single test suite.
+    #
+    # Read here on what test suite means:
+    # https://docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#suite
+    #
+    # This object can be shared between multiple threads.
+    #
+    # @public_api
+    class TestSuite < ConcurrentSpan
+      # Finishes this test suite.
+      # @return [void]
+      def finish
+        super
+
+        CI.deactivate_test_suite(name)
+      end
+    end
+  end
+end

data/lib/datadog/ci/test_visibility/serializers/base.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require "set"
+
+require_relative "../../ext/test"
+
 module Datadog
   module CI
     module TestVisibility
@@ -9,11 +13,31 @@ module Datadog
           MINIMUM_DURATION_NANO = 0
           MAXIMUM_DURATION_NANO = 9223372036854775807
 
-          attr_reader :trace, :span
+          CONTENT_FIELDS = [
+            "name", "resource", "service",
+            "error", "start", "duration",
+            "meta", "metrics",
+            "type" => "span_type"
+          ].freeze
+
+          REQUIRED_FIELDS = [
+            "error",
+            "name",
+            "resource",
+            "start",
+            "duration"
+          ].freeze
+
+          attr_reader :trace, :span, :meta
 
           def initialize(trace, span)
             @trace = trace
             @span = span
+
+            @meta = @span.meta.reject { |key, _| Ext::Test::SPECIAL_TAGS.include?(key) }
+
+            @errors = {}
+            @validated = false
           end
 
           def to_msgpack(packer = nil)
@@ -40,7 +64,23 @@ module Datadog
 
           # validates according to citestcycle json schema
           def valid?
-            required_fields_present? && valid_start_time? && valid_duration?
+            validate! unless @validated
+
+            @errors.empty?
+          end
+
+          def validate!
+            @errors.clear
+
+            validate_required_fields!
+            validate_start_time!
+            validate_duration!
+
+            @validated = true
+          end
+
+          def validation_errors
+            @errors
           end
 
           def content_fields
@@ -67,6 +107,18 @@ module Datadog
             @span.parent_id
           end
 
+          def test_session_id
+            to_integer(@span.get_tag(Ext::Test::TAG_TEST_SESSION_ID))
+          end
+
+          def test_module_id
+            to_integer(@span.get_tag(Ext::Test::TAG_TEST_MODULE_ID))
+          end
+
+          def test_suite_id
+            to_integer(@span.get_tag(Ext::Test::TAG_TEST_SUITE_ID))
+          end
+
           def type
           end
 
@@ -98,10 +150,6 @@ module Datadog
             @duration ||= duration_nano(@span.duration)
           end
 
-          def meta
-            @span.meta
-          end
-
           def metrics
             @span.metrics
           end
@@ -122,16 +170,48 @@ module Datadog
 
           private
 
-          def valid_start_time?
-            !start.nil? && start >= MINIMUM_TIMESTAMP_NANO
+          def validate_start_time!
+            validate_required!("start")
+            validate_greater_than_or_equal!("start", MINIMUM_TIMESTAMP_NANO)
+          end
+
+          def validate_duration!
+            validate_required!("duration")
+            validate_greater_than_or_equal!("duration", MINIMUM_DURATION_NANO)
+            validate_less_than_or_equal!("duration", MAXIMUM_DURATION_NANO)
+          end
+
+          def validate_required_fields!
+            required_fields.each do |field|
+              validate_required!(field)
+            end
           end
 
-          def valid_duration?
-            !duration.nil? && duration >= MINIMUM_DURATION_NANO && duration <= MAXIMUM_DURATION_NANO
+          def validate_required!(field)
+            if send(field).nil?
+              add_error(field, "is required")
+            end
           end
 
-          def required_fields_present?
-            required_fields.all? { |field| !send(field).nil? }
+          def validate_greater_than_or_equal!(field, value)
+            return if send(field).nil?
+
+            if send(field) < value
+              add_error(field, "must be greater than or equal to #{value}")
+            end
+          end
+
+          def validate_less_than_or_equal!(field, value)
+            return if send(field).nil?
+
+            if send(field) > value
+              add_error(field, "must be less than or equal to #{value}")
+            end
+          end
+
+          def add_error(field, message)
+            @errors[field] ||= Set.new
+            @errors[field] << message
           end
 
           def required_fields
@@ -154,6 +234,14 @@ module Datadog
           def duration_nano(duration)
             (duration * 1e9).to_i
           end
+
+          def to_s
+            "#{self.class.name}(id:#{span_id},name:#{name})"
+          end
+
+          def to_integer(value)
+            value.to_i if value
+          end
         end
       end
     end