datadog-ci 0.3.0 → 0.4.0

data/lib/datadog/ci/recorder.rb

@@ -1,82 +1,118 @@
 # frozen_string_literal: true
 
 require "datadog/tracing"
-require "datadog/tracing/contrib/analytics"
+
+require "rbconfig"
 
 require_relative "ext/app_types"
 require_relative "ext/test"
 require_relative "ext/environment"
 
-require "rbconfig"
+require_relative "context/local"
+
+require_relative "span"
+require_relative "test"
 
 module Datadog
   module CI
     # Common behavior for CI tests
-    module Recorder
+    class Recorder
+      attr_reader :environment_tags
+
+      def initialize
+        @environment_tags = Ext::Environment.tags(ENV).freeze
+        @local_context = Context::Local.new
+      end
+
       # Creates a new span for a CI test
-      def self.trace(span_name, options = {})
+      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
-        }.merge(options[:span_options] || {})
+        }
+
+        tags[Ext::Test::TAG_NAME] = test_name
 
-        if block_given?
-          ::Datadog::Tracing.trace(span_name, **span_options) do |span, trace|
-            set_tags!(trace, span, options)
-            yield(span, trace)
+        if block
+          Datadog::Tracing.trace(operation_name, **span_options) do |tracer_span, trace|
+            set_trace_origin(trace)
+
+            test = build_test(tracer_span, tags)
+
+            @local_context.activate_test!(test) do
+              block.call(test)
+            end
           end
         else
-          span = ::Datadog::Tracing.trace(span_name, **span_options)
-          trace = ::Datadog::Tracing.active_trace
-          set_tags!(trace, span, options)
-          span
+          tracer_span = Datadog::Tracing.trace(operation_name, **span_options)
+          trace = Datadog::Tracing.active_trace
+
+          set_trace_origin(trace)
+
+          test = build_test(tracer_span, tags)
+          @local_context.activate_test!(test)
+          test
         end
       end
 
-      # Adds tags to a CI test span.
-      def self.set_tags!(trace, span, tags = {})
-        tags ||= {}
-
-        # Set default tags
-        trace.origin = Ext::Test::CONTEXT_ORIGIN if trace
-        ::Datadog::Tracing::Contrib::Analytics.set_measured(span)
-        span.set_tag(Ext::Test::TAG_SPAN_KIND, Ext::AppTypes::TYPE_TEST)
+      def trace(span_type, span_name, tags: {}, &block)
+        span_options = {
+          resource: span_name,
+          span_type: span_type
+        }
 
-        # Set environment tags
-        @environment_tags ||= Ext::Environment.tags(ENV)
-        @environment_tags.each { |k, v| span.set_tag(k, v) }
+        if block
+          Datadog::Tracing.trace(span_name, **span_options) do |tracer_span, trace|
+            block.call(build_span(tracer_span, tags))
+          end
+        else
+          tracer_span = Datadog::Tracing.trace(span_name, **span_options)
 
-        # Set contextual tags
-        span.set_tag(Ext::Test::TAG_FRAMEWORK, tags[:framework]) if tags[:framework]
-        span.set_tag(Ext::Test::TAG_FRAMEWORK_VERSION, tags[:framework_version]) if tags[:framework_version]
-        span.set_tag(Ext::Test::TAG_NAME, tags[:test_name]) if tags[:test_name]
-        span.set_tag(Ext::Test::TAG_SUITE, tags[:test_suite]) if tags[:test_suite]
-        span.set_tag(Ext::Test::TAG_TYPE, tags[:test_type]) if tags[:test_type]
+          build_span(tracer_span, tags)
+        end
+      end
 
-        set_environment_runtime_tags!(span)
+      def active_test
+        @local_context.active_test
+      end
 
-        span
+      def deactivate_test(test)
+        @local_context.deactivate_test!(test)
       end
 
-      def self.passed!(span)
-        span.set_tag(Ext::Test::TAG_STATUS, Ext::Test::Status::PASS)
+      def active_span
+        tracer_span = Datadog::Tracing.active_span
+        Span.new(tracer_span) if tracer_span
       end
 
-      def self.failed!(span, exception = nil)
-        span.status = 1
-        span.set_tag(Ext::Test::TAG_STATUS, Ext::Test::Status::FAIL)
-        span.set_error(exception) unless exception.nil?
+      private
+
+      # Sets trace's origin to ciapp-test
+      def set_trace_origin(trace)
+        trace.origin = Ext::Test::CONTEXT_ORIGIN if trace
       end
 
-      def self.skipped!(span, exception = nil)
-        span.set_tag(Ext::Test::TAG_STATUS, Ext::Test::Status::SKIP)
-        span.set_error(exception) unless exception.nil?
+      def build_test(tracer_span, tags)
+        test = Test.new(tracer_span)
+
+        test.set_default_tags
+        test.set_environment_runtime_tags
+
+        test.set_tags(tags)
+        test.set_tags(environment_tags)
+
+        test
       end
 
-      private_class_method def self.set_environment_runtime_tags!(span)
-        span.set_tag(Ext::Test::TAG_OS_ARCHITECTURE, ::RbConfig::CONFIG["host_cpu"])
-        span.set_tag(Ext::Test::TAG_OS_PLATFORM, ::RbConfig::CONFIG["host_os"])
-        span.set_tag(Ext::Test::TAG_RUNTIME_NAME, Core::Environment::Ext::LANG_ENGINE)
-        span.set_tag(Ext::Test::TAG_RUNTIME_VERSION, Core::Environment::Ext::ENGINE_VERSION)
+      def build_span(tracer_span, tags)
+        span = Span.new(tracer_span)
+
+        span.set_default_tags
+        span.set_environment_runtime_tags
+        span.set_tags(tags)
+
+        span
       end
     end
   end

data/lib/datadog/ci/span.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "ext/test"
+
+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 Span
+      attr_reader :tracer_span
+
+      def initialize(tracer_span)
+        @tracer_span = tracer_span
+      end
+
+      # @return [String] the name of the span.
+      def name
+        tracer_span.name
+      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
+      end
+
+      # Sets the status of the span to "pass".
+      # @return [void]
+      def passed!
+        tracer_span.set_tag(Ext::Test::TAG_STATUS, Ext::Test::Status::PASS)
+      end
+
+      # Sets the status of the span to "fail".
+      # @param [Exception] exception the exception that caused the test to fail.
+      # @return [void]
+      def failed!(exception: nil)
+        tracer_span.status = 1
+        tracer_span.set_tag(Ext::Test::TAG_STATUS, Ext::Test::Status::FAIL)
+        tracer_span.set_error(exception) unless exception.nil?
+      end
+
+      # Sets the status of the span to "skip".
+      # @param [Exception] exception the exception that caused the test to fail.
+      # @param [String] reason the reason why the test was skipped.
+      # @return [void]
+      def skipped!(exception: nil, reason: nil)
+        tracer_span.set_tag(Ext::Test::TAG_STATUS, Ext::Test::Status::SKIP)
+        tracer_span.set_error(exception) unless exception.nil?
+        tracer_span.set_tag(Ext::Test::TAG_SKIP_REASON, reason) unless reason.nil?
+      end
+
+      # Gets tag value by key.
+      # @param [String] key the key of the tag.
+      # @return [String] the value of the tag.
+      def get_tag(key)
+        tracer_span.get_tag(key)
+      end
+
+      # Sets tag value by key.
+      # @param [String] key the key of the tag.
+      # @param [String] value the value of the tag.
+      # @return [void]
+      def set_tag(key, value)
+        tracer_span.set_tag(key, value)
+      end
+
+      # Sets metric value by key.
+      # @param [String] key the key of the metric.
+      # @param [Numeric] value the value of the metric.
+      # @return [void]
+      def set_metric(key, value)
+        tracer_span.set_metric(key, value)
+      end
+
+      # Finishes the span.
+      # @return [void]
+      def finish
+        tracer_span.finish
+      end
+
+      # Sets multiple tags at once.
+      # @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
+      end
+
+      def set_environment_runtime_tags
+        tracer_span.set_tag(Ext::Test::TAG_OS_ARCHITECTURE, ::RbConfig::CONFIG["host_cpu"])
+        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)
+      end
+
+      def set_default_tags
+        tracer_span.set_tag(Ext::Test::TAG_SPAN_KIND, Ext::AppTypes::TYPE_TEST)
+      end
+
+      def to_s
+        "#{self.class}(name:#{name},tracer_span:#{@tracer_span})"
+      end
+    end
+  end
+end

data/lib/datadog/ci/test.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+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
+      # @return [String] the name of the test.
+      def name
+        get_tag(Ext::Test::TAG_NAME)
+      end
+
+      # Finishes the current test.
+      # @return [void]
+      def finish
+        super
+
+        CI.deactivate_test(self)
+      end
+    end
+  end
+end

data/lib/datadog/ci/utils/url.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Datadog
+  module CI
+    module Utils
+      module Url
+        def self.filter_sensitive_info(url)
+          return nil if url.nil?
+
+          url.gsub(%r{((https?|ssh)://)[^/]*@}, '\1')
+        end
+      end
+    end
+  end
+end

data/lib/datadog/ci/version.rb

@@ -4,7 +4,7 @@ module Datadog
   module CI
     module VERSION
       MAJOR = "0"
-      MINOR = "3"
+      MINOR = "4"
       PATCH = "0"
       PRE = nil
       BUILD = nil

data/lib/datadog/ci.rb

@@ -5,11 +5,200 @@ require_relative "ci/version"
 require "datadog/core"
 
 module Datadog
-  # Namespace for Datadog CI instrumentation:
-  # e.g. rspec, cucumber, etc...
+  # Datadog CI visibility public API.
+  #
+  # @public_api
   module CI
-    class Error < StandardError; end
-    # Your code goes here...
+    class << self
+      # Return a {Datadog::CI::Test ci_test} that will trace a test called `test_name`.
+      # Raises an error if a test is already active.
+      #
+      # You could trace your test using a <tt>do-block</tt> like:
+      #
+      # ```
+      # Datadog::CI.trace_test(
+      #   "test_add_two_numbers",
+      #   service_name: "my-web-site-tests",
+      #   operation_name: "test",
+      #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
+      # ) do |ci_test|
+      #   result = run_test
+      #
+      #   if result.ok?
+      #     ci_test.passed!
+      #   else
+      #     ci_test.failed!(exception: result.exception)
+      #   end
+      # end
+      # ```
+      #
+      # The {#trace_test} method can also be used without a block in this way:
+      # ```
+      # ci_test = Datadog::CI.trace_test(
+      #   "test_add_two_numbers',
+      #   service: "my-web-site-tests",
+      #   operation_name: "test",
+      #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
+      # )
+      # run_test
+      # ci_test.finish
+      # ```
+      #
+      # Remember that in this case, calling {Datadog::CI::Test#finish} is mandatory.
+      #
+      # @param [String] test_name {Datadog::CI::Test} name (example: "test_add_two_numbers").
+      # @param [String] operation_name defines label for a test span in trace view ("test" if it's missing)
+      # @param [String] service_name the service name for this test
+      # @param [Hash<String,String>] tags extra tags which should be added to the test.
+      # @return [Object] If a block is provided, returns the result of the block execution.
+      # @return [Datadog::CI::Test] If no block is provided, returns the active,
+      #         unfinished {Datadog::CI::Test}.
+      # @yield Optional block where new newly created {Datadog::CI::Test} captures the execution.
+      # @yieldparam [Datadog::CI::Test] ci_test the newly created and active [Datadog::CI::Test]
+      #
+      # @public_api
+      def trace_test(test_name, service_name: nil, operation_name: "test", tags: {}, &block)
+        recorder.trace_test(test_name, service_name: service_name, operation_name: operation_name, tags: tags, &block)
+      end
+
+      # Same as {#trace_test} but it does not accept a block.
+      # Raises an error if a test is already active.
+      #
+      # Usage:
+      #
+      # ```
+      # ci_test = Datadog::CI.start_test(
+      #   "test_add_two_numbers',
+      #   service: "my-web-site-tests",
+      #   operation_name: "test",
+      #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
+      # )
+      # run_test
+      # ci_test.finish
+      # ```
+      #
+      # @param [String] test_name {Datadog::CI::Test} name (example: "test_add_two_numbers").
+      # @param [String] operation_name the resource this span refers, or `test` if it's missing
+      # @param [String] service_name the service name for this span.
+      # @param [Hash<String,String>] tags extra tags which should be added to the test.
+      # @return [Datadog::CI::Test] Returns the active, unfinished {Datadog::CI::Test}.
+      #
+      # @public_api
+      def start_test(test_name, service_name: nil, operation_name: "test", tags: {})
+        recorder.trace_test(test_name, service_name: service_name, operation_name: operation_name, tags: tags)
+      end
+
+      # Trace any custom span inside a test. For example, you could trace:
+      # - cucumber step
+      # - database query
+      # - any custom operation you want to see in your trace view
+      #
+      # You can use thi method with a <tt>do-block</tt> like:
+      #
+      # ```
+      # Datadog::CI.trace(
+      #   "step",
+      #   "Given I have 42 cucumbers",
+      #   tags: {}
+      # ) do
+      #   run_operation
+      # end
+      # ```
+      #
+      # The {#trace} method can also be used without a block in this way:
+      # ```
+      # ci_span = Datadog::CI.trace(
+      #   "step",
+      #   "Given I have 42 cucumbers",
+      #   tags: {}
+      # )
+      # run_test
+      # ci_span.finish
+      # ```
+      # Remember that in this case, calling {Datadog::CI::Span#finish} is mandatory.
+      #
+      # @param [String] span_type custom, user-defined span type (for example "step" or "query").
+      # @param [String] span_name the resource this span refers, or `test` if it's missing
+      # @param [Hash<String,String>] tags extra tags which should be added to the span.
+      # @return [Object] If a block is provided, returns the result of the block execution.
+      # @return [Datadog::CI::Span] If no block is provided, returns the active,
+      #         unfinished {Datadog::CI::Span}.
+      # @yield Optional block where new newly created {Datadog::CI::Span} captures the execution.
+      # @yieldparam [Datadog::CI::Span] ci_span the newly created and active [Datadog::CI::Span]
+      #
+      # @public_api
+      def trace(span_type, span_name, tags: {}, &block)
+        recorder.trace(span_type, span_name, tags: tags, &block)
+      end
+
+      # The active, unfinished custom span if it matches given type.
+      # If no span is active, or if the active span is not a custom span with given type, returns nil.
+      #
+      # The active span belongs to an {.active_test}.
+      #
+      # Usage:
+      #
+      # ```
+      # # start span
+      # Datadog::CI.trace(
+      #   "step",
+      #   "Given I have 42 cucumbers",
+      #   tags: {}
+      # )
+      #
+      # # somewhere else, access the active "step" span
+      # step_span = Datadog::CI.active_span("step")
+      # step_span.finish()
+      # ```
+      #
+      # @param [String] span_type type of the span to retrieve (for example "step" or "query") that was provided to {.trace}
+      # @return [Datadog::CI::Span] the active span
+      # @return [nil] if no span is active, or if the active span is not a custom span with given type
+      def active_span(span_type)
+        span = recorder.active_span
+        span if span && span.span_type == span_type
+      end
+
+      # The active, unfinished test span.
+      #
+      # Usage:
+      #
+      # ```
+      # # start a test
+      # Datadog::CI.start_test(
+      #   "test_add_two_numbers',
+      #   service: "my-web-site-tests",
+      #   operation_name: "test",
+      #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
+      # )
+      #
+      # # somewhere else, access the active test
+      # test_span = Datadog::CI.active_test
+      # test_span.passed!
+      # test_span.finish
+      # ```
+      #
+      # @return [Datadog::CI::Test] the active test
+      # @return [nil] if no test is active
+      def active_test
+        recorder.active_test
+      end
+
+      # Internal only, to finish a test use Datadog::CI::Test#finish
+      def deactivate_test(test)
+        recorder.deactivate_test(test)
+      end
+
+      private
+
+      def components
+        Datadog.send(:components)
+      end
+
+      def recorder
+        components.ci_recorder
+      end
+    end
   end
 end
 

data/sig/datadog/ci/configuration/components.rbs

@@ -2,6 +2,10 @@ module Datadog
   module CI
     module Configuration
       module Components : Datadog::Core::Configuration::Components
+        @ci_recorder: Datadog::CI::Recorder
+
+        attr_reader ci_recorder: Datadog::CI::Recorder
+
         def initialize: (untyped settings) -> void
 
         def activate_ci!: (untyped settings) -> untyped

data/sig/datadog/ci/context/local.rbs

@@ -0,0 +1,21 @@
+module Datadog
+  module CI
+    module Context
+      class Local
+        @key: Symbol
+
+        def initialize: () -> void
+
+        def activate_test!: (Datadog::CI::Test test) ?{ () -> untyped } -> void
+
+        def deactivate_test!: (Datadog::CI::Test test) -> void
+
+        def active_test: () -> Datadog::CI::Test?
+
+        private
+
+        def active_test=: (Datadog::CI::Test? test) -> untyped
+      end
+    end
+  end
+end

data/sig/datadog/ci/ext/environment/extractor.rbs

@@ -18,8 +18,6 @@ module Datadog
           def normalize_git!: () -> void
 
           def expand_workspace!: () -> void
-
-          def filter_sensitive_info: (String? url) -> String?
         end
       end
     end

data/sig/datadog/ci/ext/environment/providers/github_actions.rbs

@@ -5,6 +5,7 @@ module Datadog
         module Providers
           class GithubActions < Extractor
             @ref: String
+            @github_server_url: String?
 
             def provider_name: () -> "github"
 
@@ -29,6 +30,10 @@ module Datadog
             def git_branch_or_tag: () -> String?
 
             def ci_env_vars: () -> String?
+
+            private
+
+            def github_server_url: () -> String?
           end
         end
       end

data/sig/datadog/ci/recorder.rbs

@@ -1,18 +1,30 @@
 module Datadog
   module CI
-    module Recorder
-      self.@environment_tags: Hash[String, String]
+    class Recorder
+      @environment_tags: Hash[String, String]
+      @local_context: Datadog::CI::Context::Local
 
-      def self.trace: (untyped span_name, ?::Hash[untyped, untyped] options) ?{ (untyped, untyped) -> untyped } -> untyped
-      def self.set_tags!: (untyped trace, untyped span, ?::Hash[untyped, untyped] tags) -> untyped
+      attr_reader environment_tags: Hash[String, String]
 
-      def self.passed!: (untyped span) -> untyped
+      def trace_test: (String span_name, ?service_name: String?, ?operation_name: String, ?tags: Hash[untyped, untyped]) ?{ (Datadog::CI::Test span) -> untyped } -> untyped
 
-      def self.failed!: (untyped span, ?untyped? exception) -> untyped
+      def trace: (String span_type, String span_name, ?tags: Hash[untyped, untyped]) ?{ (Datadog::CI::Span span) -> untyped } -> untyped
 
-      def self.skipped!: (untyped span, ?untyped? exception) -> untyped
+      def active_test: () -> Datadog::CI::Test?
 
-      def self.set_environment_runtime_tags!: (untyped span) -> untyped
+      def active_span: () -> Datadog::CI::Span?
+
+      def deactivate_test: (Datadog::CI::Test test) -> void
+
+      def create_datadog_span: (String span_name, ?span_options: Hash[untyped, untyped], ?tags: Hash[untyped, untyped]) ?{ (Datadog::CI::Span span) -> untyped } -> untyped
+
+      def set_trace_origin: (Datadog::Tracing::TraceOperation trace) -> untyped
+
+      private
+
+      def build_test: (Datadog::Tracing::SpanOperation tracer_span, Hash[untyped, untyped] tags) -> Datadog::CI::Test
+
+      def build_span: (Datadog::Tracing::SpanOperation tracer_span, Hash[untyped, untyped] tags) -> Datadog::CI::Span
     end
   end
 end

data/sig/datadog/ci/span.rbs

@@ -0,0 +1,35 @@
+module Datadog
+  module CI
+    class Span
+      @tracer_span: Datadog::Tracing::SpanOperation
+
+      attr_reader tracer_span: Datadog::Tracing::SpanOperation
+
+      def initialize: (Datadog::Tracing::SpanOperation tracer_span) -> void
+
+      def name: () -> String
+
+      def passed!: () -> void
+
+      def failed!: (?exception: untyped?) -> void
+
+      def skipped!: (?exception: untyped?, ?reason: String?) -> void
+
+      def get_tag: (String key) -> untyped?
+
+      def set_tag: (String key, untyped? value) -> void
+
+      def set_metric: (String key, untyped value) -> void
+
+      def set_tags: (Hash[untyped, untyped] tags) -> void
+
+      def finish: () -> void
+
+      def span_type: () -> String
+
+      def set_environment_runtime_tags: () -> void
+
+      def set_default_tags: () -> void
+    end
+  end
+end

data/sig/datadog/ci/test.rbs

@@ -0,0 +1,7 @@
+module Datadog
+  module CI
+    class Test < Span
+      def finish: () -> void
+    end
+  end
+end

data/sig/datadog/ci/utils/url.rbs

@@ -0,0 +1,9 @@
+module Datadog
+  module CI
+    module Utils
+      module Url
+        def self.filter_sensitive_info: (String? url) -> String?
+      end
+    end
+  end
+end