ddtrace 0.45.0 → 0.52.0

data/lib/ddtrace/profiling.rb

@@ -0,0 +1,151 @@
+# typed: true
+require 'datadog/core/environment/variable_helpers'
+require 'ddtrace/utils/only_once'
+
+module Datadog
+  # Contains profiler for generating stack profiles, etc.
+  module Profiling # rubocop:disable Metrics/ModuleLength
+    GOOGLE_PROTOBUF_MINIMUM_VERSION = Gem::Version.new('3.0')
+    private_constant :GOOGLE_PROTOBUF_MINIMUM_VERSION
+
+    SKIPPED_NATIVE_EXTENSION_ONLY_ONCE = Datadog::Utils::OnlyOnce.new
+    private_constant :SKIPPED_NATIVE_EXTENSION_ONLY_ONCE
+
+    def self.supported?
+      unsupported_reason.nil?
+    end
+
+    def self.unsupported_reason
+      # NOTE: Only the first matching reason is returned, so try to keep a nice order on reasons -- e.g. tell users
+      # first that they can't use this on JRuby before telling them that they are missing protobuf
+
+      ruby_engine_unsupported? ||
+        native_library_failed_to_load? ||
+        protobuf_gem_unavailable? ||
+        protobuf_version_unsupported? ||
+        protobuf_failed_to_load?
+    end
+
+    private_class_method def self.ruby_engine_unsupported?
+      'JRuby is not supported' if RUBY_ENGINE == 'jruby'
+    end
+
+    private_class_method def self.protobuf_gem_unavailable?
+      # NOTE: On environments where protobuf is already loaded, we skip the check. This allows us to support environments
+      # where no Gem.loaded_version is NOT available but customers are able to load protobuf; see for instance
+      # https://github.com/teamcapybara/capybara/commit/caf3bcd7664f4f2691d0ca9ef3be9a2a954fecfb
+      if !defined?(::Google::Protobuf) && Gem.loaded_specs['google-protobuf'].nil?
+        "Missing google-protobuf dependency; please add `gem 'google-protobuf', '~> 3.0'` to your Gemfile or gems.rb file"
+      end
+    end
+
+    private_class_method def self.protobuf_version_unsupported?
+      # See above for why we skip the check when protobuf is already loaded; note that when protobuf was already loaded
+      # we skip the version check to avoid the call to Gem.loaded_specs. Unfortunately, protobuf does not seem to
+      # expose the gem version constant elsewhere, so in that setup we are not able to check the version.
+      if !defined?(::Google::Protobuf) && Gem.loaded_specs['google-protobuf'].version < GOOGLE_PROTOBUF_MINIMUM_VERSION
+        'Your google-protobuf is too old; ensure that you have google-protobuf >= 3.0 by ' \
+        "adding `gem 'google-protobuf', '~> 3.0'` to your Gemfile or gems.rb file"
+      end
+    end
+
+    private_class_method def self.protobuf_failed_to_load?
+      unless protobuf_loaded_successfully?
+        'There was an error loading the google-protobuf library; see previous warning message for details'
+      end
+    end
+
+    # The `google-protobuf` gem depends on a native component, and its creators helpfully tried to provide precompiled
+    # versions of this extension on rubygems.org.
+    #
+    # Unfortunately, for a long time, the supported Ruby versions metadata on these precompiled versions of the extension
+    # was not correctly set. (This is fixed in newer versions -- but not all Ruby versions we want to support can use
+    # these.)
+    #
+    # Thus, the gem can still be installed, but can be in a broken state. To avoid breaking customer applications, we
+    # use this helper to load it and gracefully handle failures.
+    private_class_method def self.protobuf_loaded_successfully?
+      return @protobuf_loaded if defined?(@protobuf_loaded)
+
+      begin
+        require 'google/protobuf'
+        @protobuf_loaded = true
+      rescue LoadError => e
+        # NOTE: We use Kernel#warn here because this code gets run BEFORE Datadog.logger is actually set up.
+        # In the future it'd be nice to shuffle the logger startup to happen first to avoid this special case.
+        Kernel.warn(
+          '[DDTRACE] Error while loading google-protobuf gem. ' \
+          "Cause: '#{e.message}' Location: '#{Array(e.backtrace).first}'. " \
+          'This can happen when google-protobuf is missing its native components. ' \
+          'To fix this, try removing and reinstalling the gem, forcing it to recompile the components: ' \
+          '`gem uninstall google-protobuf -a; BUNDLE_FORCE_RUBY_PLATFORM=true bundle install`. ' \
+          'If the error persists, please contact support via <https://docs.datadoghq.com/help/> or ' \
+          'file a bug at <https://github.com/DataDog/dd-trace-rb/blob/master/CONTRIBUTING.md#found-a-bug>.'
+        )
+        @protobuf_loaded = false
+      end
+    end
+
+    private_class_method def self.native_library_failed_to_load?
+      success, exception = try_loading_native_library
+
+      unless success
+        if exception
+          'There was an error loading the profiling native extension due to ' \
+          "'#{exception.message}' at '#{exception.backtrace.first}'"
+        else
+          'The profiling native extension did not load correctly. ' \
+          'If the error persists, please contact support via <https://docs.datadoghq.com/help/> or ' \
+          'file a bug at <https://github.com/DataDog/dd-trace-rb/blob/master/CONTRIBUTING.md#found-a-bug>.'
+        end
+      end
+    end
+
+    private_class_method def self.try_loading_native_library
+      if Datadog::Core::Environment::VariableHelpers.env_to_bool('DD_PROFILING_NO_EXTENSION', false)
+        SKIPPED_NATIVE_EXTENSION_ONLY_ONCE.run do
+          Kernel.warn(
+            '[DDTRACE] Skipped loading of profiling native extension due to DD_PROFILING_NO_EXTENSION environment ' \
+            'variable being set. ' \
+            'This option is experimental and will lead to the profiler not working in future releases. ' \
+            'If you needed to use this, please tell us why on <https://github.com/DataDog/dd-trace-rb/issues/new>.'
+          )
+        end
+
+        return [true, nil]
+      end
+
+      begin
+        require "ddtrace_profiling_native_extension.#{RUBY_VERSION}_#{RUBY_PLATFORM}"
+        success =
+          defined?(Datadog::Profiling::NativeExtension) && Datadog::Profiling::NativeExtension.send(:native_working?)
+        [success, nil]
+      rescue StandardError, LoadError => e
+        [false, e]
+      end
+    end
+
+    private_class_method def self.load_profiling
+      return false unless supported?
+
+      require 'ddtrace/profiling/ext/cpu'
+      require 'ddtrace/profiling/ext/forking'
+
+      require 'ddtrace/profiling/collectors/stack'
+      require 'ddtrace/profiling/exporter'
+      require 'ddtrace/profiling/recorder'
+      require 'ddtrace/profiling/scheduler'
+      require 'ddtrace/profiling/tasks/setup'
+      require 'ddtrace/profiling/transport/io'
+      require 'ddtrace/profiling/transport/http'
+      require 'ddtrace/profiling/profiler'
+      require 'ddtrace/profiling/native_extension'
+      require 'ddtrace/profiling/trace_identifiers/helper'
+      require 'ddtrace/profiling/pprof/pprof_pb'
+
+      true
+    end
+
+    load_profiling if supported?
+  end
+end

data/lib/ddtrace/propagation/grpc_propagator.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'ddtrace/context'
 require 'ddtrace/ext/distributed'
 
@@ -19,6 +20,7 @@ module Datadog
     def self.extract(metadata)
       metadata = Carrier.new(metadata)
       return Datadog::Context.new unless metadata.valid?
+
       Datadog::Context.new(trace_id: metadata.trace_id,
                            span_id: metadata.parent_id,
                            sampling_priority: metadata.sampling_priority,

data/lib/ddtrace/propagation/http_propagator.rb

@@ -1,3 +1,4 @@
+# typed: false
 require 'ddtrace/configuration'
 require 'ddtrace/context'
 require 'ddtrace/ext/distributed'
@@ -31,7 +32,7 @@ module Datadog
         rescue => e
           Datadog.logger.error(
             'Error injecting propagated context into the environment. ' \
-            "Cause: #{e} Location: #{e.backtrace.first}"
+            "Cause: #{e} Location: #{Array(e.backtrace).first}"
           )
         end
       end
@@ -54,7 +55,7 @@ module Datadog
         rescue => e
           Datadog.logger.error(
             'Error extracting propagated context from the environment. ' \
-            "Cause: #{e} Location: #{e.backtrace.first}"
+            "Cause: #{e} Location: #{Array(e.backtrace).first}"
           )
         end
 

data/lib/ddtrace/quantization/hash.rb

@@ -1,3 +1,4 @@
+# typed: true
 module Datadog
   module Quantization
     # Quantization for HTTP resources

data/lib/ddtrace/quantization/http.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'uri'
 require 'set'
 
@@ -5,6 +6,8 @@ module Datadog
   module Quantization
     # Quantization for HTTP resources
     module HTTP
+      include Kernel # Ensure that kernel methods are always available (https://sorbet.org/docs/error-reference#7003)
+
       PLACEHOLDER = '?'.freeze
 
       module_function
@@ -61,6 +64,7 @@ module Datadog
       # e.g. Reduces "foo&bar=bar&bar=bar&foo" to "foo&bar=bar&bar=bar"
       def collect_query(query, options = {})
         return query unless block_given?
+
         uniq = options[:uniq].nil? ? false : options[:uniq]
         keys = Set.new
 

data/lib/ddtrace/runtime/metrics.rb

@@ -1,17 +1,18 @@
+# typed: true
 require 'ddtrace/ext/integration'
 require 'ddtrace/ext/runtime'
 
 require 'ddtrace/metrics'
-require 'ddtrace/runtime/class_count'
-require 'ddtrace/runtime/gc'
-require 'ddtrace/runtime/identity'
-require 'ddtrace/runtime/thread_count'
+require 'datadog/core/environment/class_count'
+require 'datadog/core/environment/gc'
+require 'datadog/core/environment/identity'
+require 'datadog/core/environment/thread_count'
 
 module Datadog
   module Runtime
     # For generating runtime metrics
     class Metrics < Datadog::Metrics
-      def initialize(options = {})
+      def initialize(**options)
         super
 
         # Initialize service list
@@ -29,7 +30,7 @@ module Datadog
         # Tag span with language and runtime ID for association with metrics.
         # We only tag spans that performed internal application work.
         unless span.get_tag(Datadog::Ext::Integration::TAG_PEER_SERVICE)
-          span.set_tag(Ext::Runtime::TAG_LANG, Runtime::Identity.lang)
+          span.set_tag(Ext::Runtime::TAG_LANG, Core::Environment::Identity.lang)
         end
       end
 
@@ -52,17 +53,23 @@ module Datadog
       def flush
         return unless enabled?
 
-        try_flush { gauge(Ext::Runtime::Metrics::METRIC_CLASS_COUNT, ClassCount.value) if ClassCount.available? }
-        try_flush { gauge(Ext::Runtime::Metrics::METRIC_THREAD_COUNT, ThreadCount.value) if ThreadCount.available? }
-        try_flush { gc_metrics.each { |metric, value| gauge(metric, value) } if GC.available? }
+        try_flush do
+          if Core::Environment::ClassCount.available?
+            gauge(Ext::Runtime::Metrics::METRIC_CLASS_COUNT, Core::Environment::ClassCount.value)
+          end
+        end
+        try_flush do
+          if Core::Environment::ThreadCount.available?
+            gauge(Ext::Runtime::Metrics::METRIC_THREAD_COUNT, Core::Environment::ThreadCount.value)
+          end
+        end
+        try_flush { gc_metrics.each { |metric, value| gauge(metric, value) } if Core::Environment::GC.available? }
       end
 
       def gc_metrics
-        Hash[
-          GC.stat.flat_map do |k, v|
-            nested_gc_metric(Ext::Runtime::Metrics::METRIC_GC_PREFIX, k, v)
-          end
-        ]
+        Core::Environment::GC.stat.flat_map do |k, v|
+          nested_gc_metric(Ext::Runtime::Metrics::METRIC_GC_PREFIX, k, v)
+        end.to_h
       end
 
       def try_flush

data/lib/ddtrace/sampler.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'forwardable'
 
 require 'ddtrace/ext/priority'
@@ -81,7 +82,7 @@ module Datadog
       :default_key
 
     def initialize(default_key, default_rate = 1.0, &block)
-      raise ArgumentError, 'No resolver given!' unless block_given?
+      raise ArgumentError, 'No resolver given!' unless block
 
       @default_key = default_key
       @resolver = block

data/lib/ddtrace/sampling/matcher.rb

@@ -1,3 +1,4 @@
+# typed: true
 module Datadog
   module Sampling
     # Checks if a span conforms to a matching criteria.

data/lib/ddtrace/sampling/rate_limiter.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'ddtrace/utils/time'
 
 module Datadog

data/lib/ddtrace/sampling/rule.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'forwardable'
 
 require 'ddtrace/sampling/matcher'
@@ -28,7 +29,7 @@ module Datadog
       def match?(span)
         @matcher.match?(span)
       rescue => e
-        Datadog.logger.error("Matcher failed. Cause: #{e.message} Source: #{e.backtrace.first}")
+        Datadog.logger.error("Matcher failed. Cause: #{e.message} Source: #{Array(e.backtrace).first}")
         nil
       end
 

data/lib/ddtrace/sampling/rule_sampler.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'forwardable'
 
 require 'ddtrace/ext/priority'
@@ -5,6 +6,7 @@ require 'ddtrace/ext/priority'
 require 'ddtrace/ext/sampling'
 require 'ddtrace/sampler'
 require 'ddtrace/sampling/rate_limiter'
+require 'ddtrace/sampling/rule'
 
 module Datadog
   module Sampling
@@ -45,15 +47,8 @@ module Datadog
         @default_sampler = if default_sampler
                              default_sampler
                            elsif default_sample_rate
-                             # We want to allow 0.0 to drop all traces, but \RateSampler
-                             # considers 0.0 an invalid rate and falls back to 100% sampling.
-                             #
-                             # We address that here by not setting the rate in the constructor,
-                             # but using the setter method.
-                             #
-                             # We don't want to make this change directly to \RateSampler
-                             # because it breaks its current contract to existing users.
-                             Datadog::RateSampler.new.tap { |s| s.sample_rate = default_sample_rate }
+                             # Add to the end of the rule list a rule always matches any span
+                             @rules << SimpleRule.new(sample_rate: default_sample_rate)
                            else
                              RateByServiceSampler.new(1.0, env: -> { Datadog.tracer.tags[:env] })
                            end
@@ -88,6 +83,7 @@ module Datadog
 
       def update(*args)
         return false unless @default_sampler.respond_to?(:update)
+
         @default_sampler.update(*args)
       end
 
@@ -109,7 +105,7 @@ module Datadog
           set_limiter_metrics(span, rate_limiter.effective_rate)
         end
       rescue StandardError => e
-        Datadog.logger.error("Rule sampling failed. Cause: #{e.message} Source: #{e.backtrace.first}")
+        Datadog.logger.error("Rule sampling failed. Cause: #{e.message} Source: #{Array(e.backtrace).first}")
         yield(span)
       end
 

data/lib/ddtrace/sampling.rb

@@ -1,2 +1,3 @@
+# typed: strict
 require 'ddtrace/sampling/rule'
 require 'ddtrace/sampling/rule_sampler'

data/lib/ddtrace/span.rb

@@ -1,12 +1,14 @@
+# typed: true
 # frozen_string_literal: true
 
 require 'time'
-require 'thread'
-
 require 'ddtrace/utils'
+require 'ddtrace/ext/distributed'
+require 'ddtrace/ext/environment'
 require 'ddtrace/ext/errors'
+require 'ddtrace/ext/http'
+require 'ddtrace/ext/net'
 require 'ddtrace/ext/priority'
-require 'ddtrace/environment'
 require 'ddtrace/analytics'
 require 'ddtrace/forced_tracing'
 require 'ddtrace/diagnostics/health'
@@ -38,14 +40,32 @@ module Datadog
     EXTERNAL_MAX_ID = 1 << 64
 
     # This limit is for numeric tags because uint64 could end up rounded.
-    NUMERIC_TAG_SIZE_RANGE = (-1 << 53..1 << 53)
-
-    attr_accessor :name, :service, :resource, :span_type,
+    NUMERIC_TAG_SIZE_RANGE = (-1 << 53..1 << 53).freeze
+
+    # Some associated values should always be sent as Tags, never as Metrics, regardless
+    # if their value is numeric or not.
+    # The Datadog agent will look for these values only as Tags, not Metrics.
+    # @see https://github.com/DataDog/datadog-agent/blob/2ae2cdd315bcda53166dd8fa0dedcfc448087b9d/pkg/trace/stats/aggregation.go#L13-L17
+    ENSURE_AGENT_TAGS = {
+      Ext::DistributedTracing::ORIGIN_KEY => true,
+      Ext::Environment::TAG_VERSION => true,
+      Ext::HTTP::STATUS_CODE => true,
+      Ext::NET::TAG_HOSTNAME => true
+    }.freeze
+
+    # Simple indirection used to contain the latest resource name for a span.
+    # The profiler keeps a reference to these objects while sampling so it can extract the latest resource after the
+    # fact, as some integrations only set the correct name at the end of the span.
+    ResourceContainer = Struct.new(:latest)
+
+    attr_accessor :name, :service, :span_type,
                   :span_id, :trace_id, :parent_id,
                   :status, :sampled,
-                  :tracer, :context, :duration, :start_time, :end_time
+                  :tracer, :context
 
-    attr_reader :parent
+    attr_reader :parent, :start_time, :end_time, :resource_container
+
+    attr_writer :duration
 
     # Create a new span linked to the given tracer. Call the \Tracer method <tt>start_span()</tt>
     # and then <tt>finish()</tt> once the tracer operation is over.
@@ -61,7 +81,7 @@ module Datadog
 
       @name = name
       @service = options.fetch(:service, nil)
-      @resource = options.fetch(:resource, name)
+      @resource_container = ResourceContainer.new(options.fetch(:resource, name))
       @span_type = options.fetch(:span_type, nil)
 
       @span_id = Datadog::Utils.next_id
@@ -101,11 +121,8 @@ module Datadog
       # Keys must be unique between tags and metrics
       @metrics.delete(key)
 
-      # Ensure `http.status_code` is always a string so it is added to
-      #   @meta instead of @metrics
-      # DEV: This is necessary because the agent looks to `meta['http.status_code']` for
-      #   tagging necessary metrics
-      value = value.to_s if key == Ext::HTTP::STATUS_CODE
+      # DEV: This is necessary because the agent looks at `meta[key]`, not `metrics[key]`.
+      value = value.to_s if ENSURE_AGENT_TAGS[key]
 
       # NOTE: Adding numeric tags as metrics is stop-gap support
       #       for numeric typed tags. Eventually they will become
@@ -180,7 +197,7 @@ module Datadog
       # behavior and so we maintain it for backward compatibility for those
       # who are using async manual instrumentation that may rely on this
 
-      @start_time = start_time || Time.now.utc
+      @start_time = start_time || Utils::Time.now.utc
       @duration_start = start_time.nil? ? duration_marker : nil
 
       self
@@ -206,7 +223,7 @@ module Datadog
 
       @allocation_count_finish = now_allocations
 
-      now = Time.now.utc
+      now = Utils::Time.now.utc
 
       # Provide a default start_time if unset.
       # Using `now` here causes duration to be 0; this is expected
@@ -272,7 +289,7 @@ module Datadog
         trace_id: @trace_id,
         name: @name,
         service: @service,
-        resource: @resource,
+        resource: resource,
         type: @span_type,
         meta: @meta,
         metrics: @metrics,
@@ -326,7 +343,7 @@ module Datadog
       packer.write('service')
       packer.write(@service)
       packer.write('resource')
-      packer.write(@resource)
+      packer.write(resource)
       packer.write('type')
       packer.write(@span_type)
       packer.write('meta')
@@ -358,7 +375,7 @@ module Datadog
         q.text "Trace ID: #{@trace_id}\n"
         q.text "Type: #{@span_type}\n"
         q.text "Service: #{@service}\n"
-        q.text "Resource: #{@resource}\n"
+        q.text "Resource: #{resource}\n"
         q.text "Error: #{@status}\n"
         q.text "Start: #{start_time}\n"
         q.text "End: #{end_time}\n"
@@ -397,6 +414,14 @@ module Datadog
       end
     end
 
+    def resource
+      @resource_container.latest
+    end
+
+    def resource=(resource)
+      @resource_container.latest = resource
+    end
+
     private
 
     def duration_marker

data/lib/ddtrace/sync_writer.rb

@@ -1,11 +1,19 @@
+# typed: true
 require 'ddtrace/ext/net'
-require 'ddtrace/runtime/socket'
+require 'datadog/core/environment/socket'
 require 'ddtrace/runtime/metrics'
+require 'ddtrace/utils/only_once'
 
 module Datadog
   # SyncWriter flushes both services and traces synchronously
   # DEV: To be replaced by Datadog::Workers::TraceWriter.
+  #
+  # Note: If you're wondering if this class is used at all, since there are no other references to it on the codebase,
+  # the separate `datadog-lambda` uses it as of February 2021:
+  # <https://github.com/DataDog/datadog-lambda-rb/blob/c15f0f0916c90123416dc44e7d6800ef4a7cfdbf/lib/datadog/lambda.rb#L38>
   class SyncWriter
+    DEPRECATION_WARN_ONLY_ONCE = Datadog::Utils::OnlyOnce.new
+
     attr_reader \
       :priority_sampler,
       :transport
@@ -13,7 +21,8 @@ module Datadog
     def initialize(options = {})
       @transport = options.fetch(:transport) do
         transport_options = options.fetch(:transport_options, {})
-        Transport::HTTP.default(transport_options)
+        transport_options[:agent_settings] = options[:agent_settings] if options.key?(:agent_settings)
+        Transport::HTTP.default(**transport_options)
       end
 
       @priority_sampler = options.fetch(:priority_sampler, nil)
@@ -21,17 +30,15 @@ module Datadog
 
     def write(trace, services = nil)
       unless services.nil?
-        Datadog::Patcher.do_once('SyncWriter#write') do
+        DEPRECATION_WARN_ONLY_ONCE.run do
           Datadog.logger.warn(%(
             write: Writing services has been deprecated and no longer need to be provided.
-            write(traces, services) can be updted to write(traces)
+            write(traces, services) can be updated to write(traces)
           ))
         end
       end
 
-      perform_concurrently(
-        proc { flush_trace(trace) }
-      )
+      flush_trace(trace)
     rescue => e
       Datadog.logger.debug(e)
     end
@@ -44,23 +51,18 @@ module Datadog
 
     private
 
-    def perform_concurrently(*tasks)
-      tasks.map { |task| Thread.new(&task) }.each(&:join)
-    end
-
     def flush_trace(trace)
       processed_traces = Pipeline.process!([trace])
       return if processed_traces.empty?
+
       inject_hostname!(processed_traces.first) if Datadog.configuration.report_hostname
       transport.send_traces(processed_traces)
     end
 
     def inject_hostname!(trace)
       unless trace.first.nil?
-        hostname = Datadog::Runtime::Socket.hostname
-        unless hostname.nil? || hostname.empty?
-          trace.first.set_tag(Ext::NET::TAG_HOSTNAME, hostname)
-        end
+        hostname = Datadog::Core::Environment::Socket.hostname
+        trace.first.set_tag(Ext::NET::TAG_HOSTNAME, hostname) unless hostname.nil? || hostname.empty?
       end
     end
   end

data/lib/ddtrace/tasks/exec.rb

@@ -0,0 +1,47 @@
+# typed: true
+module Datadog
+  module Tasks
+    # Wraps command with Datadog tracing
+    class Exec
+      attr_reader :args
+
+      def initialize(args)
+        @args = args
+      end
+
+      def run
+        set_rubyopt!
+        exec_with_error_handling(args)
+      end
+
+      def rubyopts
+        [
+          '-rddtrace/profiling/preload'
+        ]
+      end
+
+      private
+
+      def set_rubyopt!
+        existing_rubyopt = ENV['RUBYOPT']
+
+        ENV['RUBYOPT'] = existing_rubyopt ? "#{existing_rubyopt} #{rubyopts.join(' ')}" : rubyopts.join(' ')
+      end
+
+      # If there's an error here, rather than throwing a cryptic stack trace, let's instead have clearer messages, and
+      # follow the same status codes as the shell uses
+      # See also:
+      # * https://www.gnu.org/software/bash/manual/html_node/Exit-Status.html
+      # * https://github.com/rubygems/rubygems/blob/dd93966cac224532035deda533cba2685dfa30cc/bundler/lib/bundler/cli/exec.rb#L45
+      def exec_with_error_handling(args)
+        Kernel.exec(*args)
+      rescue Errno::ENOENT => e
+        Kernel.warn "ddtracerb exec failed: #{e.message} (command was '#{args.join(' ')}')"
+        Kernel.exit 127
+      rescue Errno::EACCES, Errno::ENOEXEC => e
+        Kernel.warn "ddtracerb exec failed: #{e.message} (command was '#{args.join(' ')}')"
+        Kernel.exit 126
+      end
+    end
+  end
+end

data/lib/ddtrace/tasks/help.rb

@@ -0,0 +1,15 @@
+# typed: true
+module Datadog
+  module Tasks
+    # Prints help message for usage of `ddtrace`
+    class Help
+      def run
+        puts %(
+Usage: ddtrace [command] [arguments]
+  exec [command]: Executes command with tracing & profiling preloaded.
+  help:           Prints this help message.
+        )
+      end
+    end
+  end
+end