ddtrace 1.7.0 → 1.9.0

data/lib/datadog/core.rb

@@ -1,4 +1,5 @@
-# typed: strict
+# frozen_string_literal: true
+# typed: true
 
 require_relative 'core/extensions'
 
@@ -9,6 +10,25 @@ module Datadog
   # products. It is a dependency of each product. Contrast with Datadog::Kit
   # for higher-level features.
   module Core
+    class << self
+      # Records the occurrence of a deprecated operation in this library.
+      #
+      # Currently, these operations are logged to `Datadog.logger` at `warn` level.
+      #
+      # `disallowed_next_major` adds a message informing that the deprecated operation
+      # won't be allowed in the next major release.
+      #
+      # @yieldreturn [String] a String with the lazily evaluated deprecation message.
+      # @param [Boolean] disallowed_next_major whether this deprecation will be enforced in the next major release.
+      def log_deprecation(disallowed_next_major: true)
+        Datadog.logger.warn do
+          message = yield
+          message += ' This will be enforced in the next major release.' if disallowed_next_major
+          message
+        end
+        nil
+      end
+    end
   end
 
   extend Core::Extensions

data/lib/datadog/kit/appsec/events.rb

@@ -0,0 +1,75 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative '../identity'
+
+module Datadog
+  module Kit
+    module AppSec
+      # Tracking events
+      module Events
+        LOGIN_SUCCESS_EVENT = 'users.login.success'
+        LOGIN_FAILURE_EVENT = 'users.login.failure'
+
+        # Attach login success event information to the trace
+        #
+        # This method is experimental and may change in the future.
+        #
+        # @param trace [TraceOperation] Trace to attach data to.
+        # @param user [Hash<Symbol, String>] User information to pass to
+        #   Datadog::Kit::Identity.set_user. Must contain at least :id as key.
+        # @param others [Hash<String || Symbol, String>] Additional free-form
+        #   event information to attach to the trace.
+        def self.track_login_success(trace, user:, **others)
+          track(LOGIN_SUCCESS_EVENT, trace, **others)
+
+          user_options = user.dup
+          user_id = user.delete(:id)
+
+          raise ArgumentError, 'missing required key: :user => { :id }' if user_id.nil?
+
+          Kit::Identity.set_user(trace, id: user_id, **user_options)
+        end
+
+        # Attach login failure event information to the trace
+        #
+        # This method is experimental and may change in the future.
+        #
+        # @param trace [TraceOperation] Trace to attach data to.
+        # @param user_id [String] User id that attempted login
+        # @param user_exists [bool] Whether the user id that did a login attempt exists.
+        # @param others [Hash<String || Symbol, String>] Additional free-form
+        #   event information to attach to the trace.
+        def self.track_login_failure(trace, user_id:, user_exists:, **others)
+          track(LOGIN_FAILURE_EVENT, trace, **others)
+
+          raise ArgumentError, 'user_id cannot be nil' if user_id.nil?
+
+          trace.set_tag('appsec.events.users.login.failure.usr.id', user_id)
+          trace.set_tag('appsec.events.users.login.failure.usr.exists', user_exists)
+        end
+
+        # Attach custom event information to the trace
+        #
+        # This method is experimental and may change in the future.
+        #
+        # @param event [String] Mandatory. Event code.
+        # @param trace [TraceOperation] Trace to attach data to.
+        # @param others [Hash<Symbol, String>] Additional free-form
+        #   event information to attach to the trace. Key must not
+        #   be :track.
+        def self.track(event, trace, **others)
+          trace.set_tag("appsec.events.#{event}.track", 'true')
+
+          others.each do |k, v|
+            raise ArgumentError, 'key cannot be :track' if k.to_sym == :track
+
+            trace.set_tag("appsec.events.#{event}.#{k}", v) unless v.nil?
+          end
+
+          trace.keep!
+        end
+      end
+    end
+  end
+end

data/lib/datadog/kit/enable_core_dumps.rb

@@ -1,4 +1,5 @@
 # typed: ignore
+# frozen_string_literal: true
 
 module Datadog
   module Kit

data/lib/datadog/kit/identity.rb

@@ -1,4 +1,5 @@
 # typed: false
+# frozen_string_literal: true
 
 module Datadog
   module Kit
@@ -22,7 +23,7 @@ module Datadog
       #   currently possesses extracted from token or application security
       #   context. The value would come from the scope associated with an OAuth
       #   2.0 Access Token or an attribute value in a SAML 2.0 Assertion.
-      # @param others [Hash<String || Symbol, String>] Additional free-form
+      # @param others [Hash<Symbol, String>] Additional free-form
       #   user information to attach to the trace.
       #
       # rubocop:disable Metrics/CyclomaticComplexity
@@ -32,12 +33,12 @@ module Datadog
 
         # enforce types
 
-        raise TypeError, 'id must be a String'         unless id.is_a?(String)
-        raise TypeError, 'email must be a String'      unless email.nil? || email.is_a?(String)
-        raise TypeError, 'name must be a String'       unless name.nil? || name.is_a?(String)
-        raise TypeError, 'session_id must be a String' unless session_id.nil? || session_id.is_a?(String)
-        raise TypeError, 'role must be a String'       unless role.nil? || role.is_a?(String)
-        raise TypeError, 'scope must be a String'      unless scope.nil? || scope.is_a?(String)
+        raise TypeError, ':id must be a String'         unless id.is_a?(String)
+        raise TypeError, ':email must be a String'      unless email.nil? || email.is_a?(String)
+        raise TypeError, ':name must be a String'       unless name.nil? || name.is_a?(String)
+        raise TypeError, ':session_id must be a String' unless session_id.nil? || session_id.is_a?(String)
+        raise TypeError, ':role must be a String'       unless role.nil? || role.is_a?(String)
+        raise TypeError, ':scope must be a String'      unless scope.nil? || scope.is_a?(String)
 
         others.each do |k, v|
           raise TypeError, "#{k.inspect} must be a String" unless v.nil? || v.is_a?(String)

data/lib/datadog/opentelemetry/api/context.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+# typed: ignore
+
+require_relative 'trace/span'
+require_relative '../../tracing/trace_operation'
+
+module Datadog
+  module OpenTelemetry
+    module API
+      # The OpenTelemetry Context contains a key-value store that can be attached
+      # to a trace.
+      #
+      # It loosely matches our `TraceOperations#tags`, except for the following:
+      # * Context can store arbitrary objects as values. One example is for the key
+      #   `Context::Key.new('current-span')`, which is associated with a `Span` object.
+      #   In contrast, `TraceOperations#tags` only stores string values.
+      # * Context is how spans know who their parent span is. The parenting operation happens on every
+      #   span created. Parenting is not directly tied to the active Fiber or Thread.
+      # * Context is immutable: changing a value creates a copy of Context.
+      # * Context is not bound to a specific trace: it can be reused an arbitrary number of times.
+      module Context
+        CURRENT_SPAN_KEY = ::OpenTelemetry::Trace.const_get(:CURRENT_SPAN_KEY)
+        private_constant :CURRENT_SPAN_KEY
+
+        def initialize(entries, trace: nil)
+          @trace = trace || ::Datadog::Tracing.send(:tracer).send(:start_trace)
+          @trace.otel_values.merge!(entries) if entries
+          @trace.otel_context ||= self
+        end
+
+        # Because Context can be reused, we have to make sure we have
+        # a valid `TraceOperation` on every invocation.
+        def ensure_trace
+          return nil unless @trace
+
+          # The Context can be reused after the root span has finished.
+          @trace.send(:reset) if @trace.finished?
+          @trace
+        end
+
+        # Returns the corresponding value (or nil) for key
+        #
+        # @param [Key] key The lookup key
+        # @return [Object]
+        def value(key)
+          return nil unless @trace
+
+          @trace.otel_value(key)
+        end
+
+        alias [] value
+
+        # Returns a new Context where entries contains the newly added key and value
+        #
+        # @param [Key] key The key to store this value under
+        # @param [Object] value Object to be stored under key
+        # @return [Context]
+        def set_value(key, value)
+          set_values(key => value)
+        end
+
+        # Returns a new Context with the current context's entries merged with the
+        #   new entries
+        #
+        # @param [Hash] values The values to be merged with the current context's
+        #   entries.
+        # @param [Object] value Object to be stored under key
+        # @return [Context]
+        def set_values(values)
+          trace = nil
+          if (current_span = values[CURRENT_SPAN_KEY])
+            trace = current_span.datadog_trace
+          end
+
+          existing_values = @trace && @trace.otel_values || {}
+
+          ::OpenTelemetry::Context.new(existing_values.merge(values), trace: trace)
+        end
+
+        # The Datadog {TraceOperation} associated with this {Context}.
+        def trace
+          @trace
+        end
+
+        # Singleton class methods for {Context}
+        module SingletonClass
+          # Returns current context, which is never nil
+          #
+          # @return [Context]
+          def current
+            trace = Tracing.active_trace
+            return ::OpenTelemetry::Context::ROOT unless trace
+
+            trace.otel_context ||= ::OpenTelemetry::Context.from_trace(trace)
+          end
+
+          # Associates a Context with the caller's current Fiber. Every call to
+          # this operation should be paired with a corresponding call to detach.
+          #
+          # Returns a token to be used with the matching call to detach
+          #
+          # @param [Context] context The new context
+          # @return [Object] A token to be used when detaching
+          def attach(context)
+            previous_trace = Tracing.active_trace
+            continue_trace!(context)
+
+            stack.push(previous_trace && previous_trace.otel_context || ::OpenTelemetry::Context::ROOT)
+            stack.size
+          end
+
+          # Restores the previous Context associated with the current Fiber.
+          # The supplied token is used to check if the call to detach is balanced
+          # with a corresponding attach call. A warning is logged if the
+          # calls are unbalanced.
+          #
+          # @param [Object] token The token provided by the matching call to attach
+          # @return [Boolean] True if the calls matched, false otherwise
+          def detach(token)
+            s = stack
+            calls_matched = (token == s.size)
+            unless calls_matched
+              ::OpenTelemetry.handle_error(
+                exception: ::OpenTelemetry::Context::DetachError.new(
+                  'calls to detach should match corresponding calls to attach.'
+                )
+              )
+            end
+
+            previous_context = s.pop
+            continue_trace!(previous_context)
+            calls_matched
+          end
+
+          # Part of the OpenTelemetry public API for {Context}.
+          def clear
+            super
+            tracer = Tracing.send(:tracer)
+            tracer.send(:call_context).activate!(nil)
+          end
+
+          # Creates a new {Context} associated with a {TraceOperation}.
+          def from_trace(trace)
+            new({}, trace: trace)
+          end
+
+          private
+
+          def continue_trace!(context, &block)
+            call_context = Tracing.send(:tracer).send(:call_context)
+            if context && context.trace
+              call_context.activate!(context.ensure_trace, &block)
+            else
+              call_context.activate!(nil)
+            end
+          end
+        end
+
+        def self.prepended(base)
+          base.singleton_class.prepend(SingletonClass)
+        end
+
+        ::OpenTelemetry::Context.prepend(self)
+      end
+
+      # OpenTelemetry-specific {TraceOperation} features.
+      #
+      # These extensions providing matching between {TraceOperation}
+      # and OpenTelemetry {Context}.
+      module TraceOperation
+        attr_accessor :otel_context
+
+        # Stores values from Context#entries
+        def otel_value(key)
+          otel_values[key]
+        end
+
+        # Retrieves values for Context#entries
+        def otel_values
+          @otel_values ||= {}
+        end
+
+        Tracing::TraceOperation.include(self)
+      end
+    end
+  end
+end

data/lib/datadog/opentelemetry/api/trace/span.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+# typed: ignore
+
+module Datadog
+  module OpenTelemetry
+    module Trace
+      # Stores associated Datadog entities to the OpenTelemetry Span.
+      module Span
+        attr_accessor :datadog_trace, :datadog_span
+
+        ::OpenTelemetry::Trace::Span.prepend(self)
+      end
+    end
+  end
+end

data/lib/datadog/opentelemetry/sdk/configurator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+# typed: ignore
+
+require_relative 'span_processor'
+require_relative 'id_generator'
+require_relative 'propagator'
+
+module Datadog
+  module OpenTelemetry
+    module SDK
+      # The Configurator is responsible for setting wiring up
+      # different OpenTelemetry requirements together.
+      # Some of the requirements will be changed to Datadog versions.
+      module Configurator
+        def initialize
+          super
+          @id_generator = IdGenerator
+        end
+
+        # Ensure Datadog-configure propagation styles have are applied when configured.
+        #
+        # DEV: Support configuring propagation through the environment variable
+        # DEV: `OTEL_PROPAGATORS`, similar to `DD_TRACE_PROPAGATION*`?
+        def configure_propagation
+          @propagators = [Propagator.new(Tracing::Contrib::HTTP::Distributed::Propagation.new)]
+          super
+        end
+
+        # Ensure Datadog-configure trace writer is configured.
+        def wrapped_exporters_from_env
+          [SpanProcessor.new]
+        end
+
+        ::OpenTelemetry::SDK::Configurator.prepend(self)
+      end
+    end
+  end
+end

data/lib/datadog/opentelemetry/sdk/id_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# typed: ignore
+
+module Datadog
+  module OpenTelemetry
+    module SDK
+      # Generates Datadog-compatible IDs for OpenTelemetry traces.
+      # OpenTelemetry traces already produce Datadog-compatible IDs.
+      class IdGenerator
+        class << self
+          include ::OpenTelemetry::Trace
+
+          # Generates a valid trace identifier, a 16-byte string with at least one
+          # non-zero byte.
+          #
+          # @return [String] a valid trace ID.
+          def generate_trace_id
+            loop do
+              id = Random.bytes(8) # DEV: Change to 16 (16*8-byte) when 128-bit trace_id is supported.
+              return id unless id == ::OpenTelemetry::Trace::INVALID_SPAN_ID
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/opentelemetry/sdk/propagator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+# typed: ignore
+
+module Datadog
+  module OpenTelemetry
+    module SDK
+      # Compatibility wrapper to allow Datadog propagators to fulfill the
+      # OpenTelemetry propagator API.
+      class Propagator
+        def initialize(datadog_propagator)
+          @datadog_propagator = datadog_propagator
+        end
+
+        def inject(
+          carrier, context: ::OpenTelemetry::Context.current,
+          setter: ::OpenTelemetry::Context::Propagation.text_map_setter
+        )
+          unless setter == ::OpenTelemetry::Context::Propagation.text_map_setter
+            Datadog.logger.error(
+              'Custom setter is not supported. Please inform the `ddtrace` team at ' \
+            ' https://github.com/DataDog/dd-trace-rb of your use case so we can best support you. Using the default ' \
+            'OpenTelemetry::Context::Propagation.text_map_setter as a fallback setter.'
+            )
+          end
+
+          @datadog_propagator.inject!(context.trace.to_digest, carrier)
+        end
+
+        def extract(
+          carrier, context: ::OpenTelemetry::Context.current,
+          getter: ::OpenTelemetry::Context::Propagation.text_map_getter
+        )
+          unless getter == ::OpenTelemetry::Context::Propagation.text_map_getter
+            Datadog.logger.error(
+              'Custom getter is not supported. Please inform the `ddtrace` team at ' \
+            ' https://github.com/DataDog/dd-trace-rb of your use case so we can best support you. Using the default ' \
+            'OpenTelemetry::Context::Propagation.text_map_getter as a fallback getter.'
+            )
+          end
+
+          digest = @datadog_propagator.extract(carrier)
+          return context unless digest
+
+          trace_id = to_otel_id(digest.trace_id)
+          span_id = to_otel_id(digest.span_id)
+
+          if digest.trace_state || digest.trace_flags
+            trace_flags = ::OpenTelemetry::Trace::TraceFlags.from_byte(digest.trace_flags)
+            tracestate = Tracing::Distributed::TraceContext.new(fetcher: nil).send(:build_tracestate, digest)
+          else
+            trace_flags = if Tracing::Sampling::PrioritySampler.sampled?(digest.trace_sampling_priority)
+                            ::OpenTelemetry::Trace::TraceFlags::SAMPLED
+                          else
+                            ::OpenTelemetry::Trace::TraceFlags::DEFAULT
+                          end
+            tracestate = ::OpenTelemetry::Trace::Tracestate::DEFAULT
+          end
+
+          span_context = ::OpenTelemetry::Trace::SpanContext.new(
+            trace_id: trace_id,
+            span_id: span_id,
+            trace_flags: trace_flags,
+            tracestate: tracestate,
+            remote: true
+          )
+
+          span = ::OpenTelemetry::Trace.non_recording_span(span_context)
+
+          trace = Tracing.continue_trace!(digest)
+
+          span.datadog_trace = trace
+
+          ::OpenTelemetry::Trace.context_with_span(span, parent_context: context)
+        end
+
+        # Returns fields set by this propagator.
+        # DEV: Doesn't seem like it's used in production Otel code paths.
+        def fields
+          []
+        end
+
+        private
+
+        # Converts the {Numeric} Datadog id object to OpenTelemetry's byte array format.
+        def to_otel_id(dd_id)
+          Array(dd_id).pack('S')
+        end
+      end
+    end
+  end
+end

data/lib/datadog/opentelemetry/sdk/span_processor.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+# typed: ignore
+
+module Datadog
+  module OpenTelemetry
+    module SDK
+      # Keeps OpenTelemetry spans in sync with the Datadog execution context.
+      # Also responsible for flushing spans when their are finished.
+      class SpanProcessor
+        # Called when a {Span} is started, if the {Span#recording?}
+        # returns true.
+        #
+        # This method is called synchronously on the execution thread, should
+        # not throw or block the execution thread.
+        #
+        # @param [Span] span the {Span} that just started.
+        # @param [Context] parent_context the parent {Context} of the newly
+        #  started span.
+        def on_start(span, parent_context)
+          create_matching_datadog_span(span, parent_context)
+        end
+
+        # Called when a {Span} is ended, if the {Span#recording?}
+        # returns true.
+        #
+        # This method is called synchronously on the execution thread, should
+        # not throw or block the execution thread.
+        #
+        # @param [Span] span the {Span} that just ended.
+        def on_finish(span)
+          span.datadog_span.finish
+        end
+
+        # Export all ended spans to the configured `Exporter` that have not yet
+        # been exported.
+        #
+        # This method should only be called in cases where it is absolutely
+        # necessary, such as when using some FaaS providers that may suspend
+        # the process after an invocation, but before the `Processor` exports
+        # the completed spans.
+        #
+        # @param [optional Numeric] timeout An optional timeout in seconds.
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def force_flush(timeout: nil)
+          writer.force_flush(timeout: timeout) if writer.respond_to? :force_flush
+          Export::SUCCESS
+        end
+
+        # Called when {TracerProvider#shutdown} is called.
+        #
+        # @param [optional Numeric] timeout An optional timeout in seconds.
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def shutdown(timeout: nil)
+          writer.stop
+          Export::SUCCESS
+        end
+
+        private
+
+        def writer
+          Datadog.configuration.tracing.writer
+        end
+
+        def create_matching_datadog_span(span, parent_context)
+          if parent_context.trace
+            Tracing.send(:tracer).send(:call_context).activate!(parent_context.ensure_trace)
+          else
+            Tracing.continue_trace!(nil)
+          end
+
+          datadog_span = start_datadog_span(span)
+
+          span.datadog_span = datadog_span
+          span.datadog_trace = Tracing.active_trace
+        end
+
+        def start_datadog_span(span)
+          tags = span.resource.attribute_enumerator.to_h
+
+          kind = span.kind || 'internal'
+          tags[Tracing::Metadata::Ext::TAG_KIND] = kind
+
+          datadog_span = Tracing.trace(span.name, tags: tags)
+          datadog_span.set_error([nil, span.status.description]) unless span.status.ok?
+          datadog_span
+        end
+      end
+    end
+  end
+end

data/lib/datadog/opentelemetry.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# typed: ignore
+
+# Entrypoint file for OpenTelemetry integration.
+#
+# This file's path is part of the @public_api.
+#
+# OpenTelemetry includes metrics, tracing, logs, and profiling.
+# This file activates the integrations of all OpenTelemetry
+# components supported by Datadog.
+
+require_relative 'tracing'
+require_relative 'opentelemetry/api/context'
+
+# DEV: Should this be a Contrib integration, that depends on the `opentelemetry-sdk`
+# DEV: and checks for compatibility?
+# DEV: This is different from our existing OpenTracer API, but there are many safety
+# DEV: features built into Contrib instrumentation today.
+require_relative 'opentelemetry/sdk/configurator' if defined?(OpenTelemetry::SDK)
+
+module Datadog
+  # Datadog OpenTelemetry integration.
+  module OpenTelemetry
+    # Used by Telemetry to decide if OpenTelemetry instrumentation is enabled
+    LOADED = true
+
+    # Use `Datadog.logger` as the default logger
+    def logger
+      @logger ||= ::Datadog.logger
+    end
+
+    ::OpenTelemetry.singleton_class.prepend(self)
+  end
+end
+
+# OpenTelemetry does not wait until the "root" span is finished to flush:
+# the "root" span does not have special influence on flushing order.
+#
+# The "root" OpenTelemetry span might be a span that is never finished, but
+# instead a placeholder for distributed tracing information, and ultimately gets discarded.
+# Consumers of the OpenTelemetry SpanProcessor pipeline are free to flush spans whenever
+# an individual span is finished.
+# Currently, this closely translates to Datadog's partial flushing.
+#
+# @see OpenTelemetry::SDK::Trace::SpanProcessor#on_finish
+Datadog.configure do |c|
+  c.tracing.partial_flush.enabled = true
+end

data/lib/datadog/opentracer/distributed_headers.rb

@@ -1,7 +1,7 @@
 # typed: true
 
-require_relative '../tracing/span'
 require_relative '../tracing/distributed/datadog'
+require_relative '../tracing/utils'
 
 module Datadog
   module OpenTracer
@@ -47,7 +47,7 @@ module Datadog
 
       def id(header)
         value = @carrier[header].to_i
-        return if value.zero? || value >= Datadog::Tracing::Span::EXTERNAL_MAX_ID
+        return if value.zero? || value >= Datadog::Tracing::Utils::EXTERNAL_MAX_ID
 
         value < 0 ? value + 0x1_0000_0000_0000_0000 : value
       end