Class: Datadog::Core::Configuration::Settings::DSL::Profiling

Inherits:

Object

• Object
• Datadog::Core::Configuration::Settings::DSL::Profiling

Defined in:

lib/datadog/core/configuration/settings.rb

Overview

Datadog Profiler-specific configurations.

See Also:

• https://docs.datadoghq.com/tracing/profiler/

Defined Under Namespace

Classes: Advanced, Exporter, Upload

Instance Attribute Summary

• #allocation_enabled ⇒ Object

  Can be used to enable/disable collection of allocation profiles.

• #enabled ⇒ Boolean

  Enable profiling.

Instance Method Summary

• #advanced ⇒ Datadog::Core::Configuration::Settings::DSL::Profiling::Advanced

  A configuration object.

• #exporter ⇒ Datadog::Core::Configuration::Settings::DSL::Profiling::Exporter

  A configuration object.

• #upload ⇒ Datadog::Core::Configuration::Settings::DSL::Profiling::Upload

  A configuration object.

Instance Attribute Details

#allocation_enabled ⇒ Object

Can be used to enable/disable collection of allocation profiles.

This feature is disabled by default

Defaults to:

• DD_PROFILING_ALLOCATION_ENABLED environment variable as a boolean, otherwise false

# File 'lib/datadog/core/configuration/settings.rb', line 247

def allocation_enabled
  @allocation_enabled
end

#enabled ⇒ Boolean

Enable profiling.

Returns:

• (Boolean)

Defaults to:

• DD_PROFILING_ENABLED environment variable, otherwise false

# File 'lib/datadog/core/configuration/settings.rb', line 227

def enabled
  @enabled
end

Instance Method Details

#advanced ⇒ Datadog::Core::Configuration::Settings::DSL::Profiling::Advanced

Returns a configuration object.

Returns:

• (Datadog::Core::Configuration::Settings::DSL::Profiling::Advanced) —

  a configuration object

# File 'lib/datadog/core/configuration/settings.rb', line 254

settings :advanced do
  # Controls the maximum number of frames for each thread sampled. Can be tuned to avoid omitted frames in the
  # produced profiles. Increasing this may increase the overhead of profiling.
  #
  # @default `DD_PROFILING_MAX_FRAMES` environment variable, otherwise 400
  option :max_frames do |o|
    o.type :int
    o.env Profiling::Ext::ENV_MAX_FRAMES
    o.default 400
  end

  # @public_api
  settings :endpoint do
    settings :collection do
      # When using profiling together with tracing, this controls if endpoint names
      # are gathered and reported together with profiles.
      #
      # @default `DD_PROFILING_ENDPOINT_COLLECTION_ENABLED` environment variable, otherwise `true`
      # @return [Boolean]
      option :enabled do |o|
        o.env Profiling::Ext::ENV_ENDPOINT_COLLECTION_ENABLED
        o.default true
        o.type :bool
      end
    end
  end

  # Can be used to disable the gathering of names and versions of gems in use by the service, used to power
  # grouping and categorization of stack traces.
  option :code_provenance_enabled do |o|
    o.type :bool
    o.default true
  end

  # Can be used to enable/disable garbage collection profiling.
  #
  # @warn To avoid https://bugs.ruby-lang.org/issues/18464 even when enabled, GC profiling is only started
  #       for Ruby versions 2.x, 3.1.4+, 3.2.3+ and 3.3.0+
  #       (more details in {Datadog::Profiling::Component.enable_gc_profiling?})
  #
  # @warn Due to a VM bug in the Ractor implementation (https://bugs.ruby-lang.org/issues/19112) this feature
  #       stops working when Ractors get garbage collected.
  #
  # @default `DD_PROFILING_GC_ENABLED` environment variable, otherwise `true`
  option :gc_enabled do |o|
    o.type :bool
    o.env 'DD_PROFILING_GC_ENABLED'
    o.default true
  end

  # Can be used to enable/disable the Datadog::Profiling.allocation_count feature.
  #
  # Requires allocation profiling to be enabled.
  #
  # @default false
  option :allocation_counting_enabled do |o|
    o.type :bool
    o.default false
  end

  # Can be used to enable/disable the collection of heap profiles.
  #
  # This feature is alpha and disabled by default
  #
  # @warn To enable heap profiling you are required to also enable allocation profiling.
  #
  # @default `DD_PROFILING_EXPERIMENTAL_HEAP_ENABLED` environment variable as a boolean, otherwise `false`
  option :experimental_heap_enabled do |o|
    o.type :bool
    o.env 'DD_PROFILING_EXPERIMENTAL_HEAP_ENABLED'
    o.default false
  end

  # Can be used to enable/disable the collection of heap size profiles.
  #
  # This feature is alpha and enabled by default when heap profiling is enabled.
  #
  # @warn To enable heap size profiling you are required to also enable allocation and heap profiling.
  #
  # @default `DD_PROFILING_EXPERIMENTAL_HEAP_SIZE_ENABLED` environment variable as a boolean, otherwise
  # whatever the value of DD_PROFILING_EXPERIMENTAL_HEAP_ENABLED is.
  option :experimental_heap_size_enabled do |o|
    o.type :bool
    o.env 'DD_PROFILING_EXPERIMENTAL_HEAP_SIZE_ENABLED'
    o.default true # This gets ANDed with experimental_heap_enabled in the profiler component.
  end

  # Can be used to configure the heap sampling rate: a heap sample will be collected for every x allocation
  # samples.
  #
  # The lower the value, the more accuracy in heap tracking but the bigger the overhead. In particular, a
  # value of 1 will track ALL allocations samples for heap profiles.
  #
  # The effective heap sampling rate in terms of allocations (not allocation samples) can be calculated via
  # effective_heap_sample_rate = allocation_sample_rate * heap_sample_rate.
  #
  # @default `DD_PROFILING_EXPERIMENTAL_HEAP_SAMPLE_RATE` environment variable, otherwise `10`.
  option :experimental_heap_sample_rate do |o|
    o.type :int
    o.env 'DD_PROFILING_EXPERIMENTAL_HEAP_SAMPLE_RATE'
    o.default 10
  end

  # Can be used to disable checking which version of `libmysqlclient` is being used by the `mysql2` gem.
  #
  # This setting is only used when the `mysql2` gem is installed.
  #
  # @default `DD_PROFILING_SKIP_MYSQL2_CHECK` environment variable, otherwise `false`
  option :skip_mysql2_check do |o|
    o.type :bool
    o.env 'DD_PROFILING_SKIP_MYSQL2_CHECK'
    o.default false
  end

  # Controls data collection for the timeline feature.
  #
  # If you needed to disable this, please tell us why on <https://github.com/DataDog/dd-trace-rb/issues/new>,
  # so we can fix it!
  #
  # @default `DD_PROFILING_TIMELINE_ENABLED` environment variable as a boolean, otherwise `true`
  option :timeline_enabled do |o|
    o.type :bool
    o.env 'DD_PROFILING_TIMELINE_ENABLED'
    o.default true
  end

  # The profiler gathers data by sending `SIGPROF` unix signals to Ruby application threads.
  #
  # Sending `SIGPROF` is a common profiling approach, and may cause system calls from native
  # extensions/libraries to be interrupted with a system
  # [EINTR error code.](https://man7.org/linux/man-pages/man7/signal.7.html#:~:text=Interruption%20of%20system%20calls%20and%20library%20functions%20by%20signal%20handlers)
  # Rarely, native extensions or libraries called by them may have missing or incorrect error handling for the
  # `EINTR` error code.
  #
  # The "no signals" workaround, when enabled, enables an alternative mode for the profiler where it does not
  # send `SIGPROF` unix signals. The downside of this approach is that the profiler data will have lower
  # quality.
  #
  # This workaround is automatically enabled when gems that are known to have issues handling
  # `EINTR` error codes are detected. If you suspect you may be seeing an issue due to the profiler's use of
  # signals, you can try manually enabling this mode as a fallback.
  # Please also report these issues to us on <https://github.com/DataDog/dd-trace-rb/issues/new>, so we can
  # work with the gem authors to fix them!
  #
  # @default `DD_PROFILING_NO_SIGNALS_WORKAROUND_ENABLED` environment variable as a boolean, otherwise `:auto`
  option :no_signals_workaround_enabled do |o|
    o.env 'DD_PROFILING_NO_SIGNALS_WORKAROUND_ENABLED'
    o.default :auto
    o.env_parser do |value|
      if value
        value = value.strip.downcase
        ['true', '1'].include?(value)
      end
    end
  end

  # The profiler gathers data by sending `SIGPROF` unix signals to Ruby application threads.
  #
  # We've discovered that this can trigger a bug in a number of Ruby APIs in the `Dir` class, as
  # described in https://bugs.ruby-lang.org/issues/20586 .
  # This was fixed for Ruby 3.4+, and this setting is a no-op for those versions.
  #
  # @default `DD_PROFILING_DIR_INTERRUPTION_WORKAROUND_ENABLED` environment variable as a boolean,
  # otherwise `true`
  option :dir_interruption_workaround_enabled do |o|
    o.env 'DD_PROFILING_DIR_INTERRUPTION_WORKAROUND_ENABLED'
    o.type :bool
    o.default true
  end

  # Configures how much wall-time overhead the profiler targets. The profiler will dynamically adjust the
  # interval between samples it takes so as to try and maintain the property that it spends no longer than
  # this amount of wall-clock time profiling. For example, with the default value of 2%, the profiler will
  # try and cause no more than 1.2 seconds per minute of overhead. Decreasing this value will reduce the
  # accuracy of the data collected. Increasing will impact the application.
  #
  # We do not recommend tweaking this value.
  #
  # This value should be a percentage i.e. a number between 0 and 100, not 0 and 1.
  #
  # @default `DD_PROFILING_OVERHEAD_TARGET_PERCENTAGE` as a float, otherwise 2.0
  option :overhead_target_percentage do |o|
    o.type :float
    o.env 'DD_PROFILING_OVERHEAD_TARGET_PERCENTAGE'
    o.default 2.0
  end

  # Controls how often the profiler reports data, in seconds. Cannot be lower than 60 seconds.
  #
  # We do not recommend tweaking this value.
  #
  # @default `DD_PROFILING_UPLOAD_PERIOD` environment variable, otherwise 60
  option :upload_period_seconds do |o|
    o.type :int
    o.env 'DD_PROFILING_UPLOAD_PERIOD'
    o.default 60
  end

  # DEV-3.0: Remove `experimental_crash_tracking_enabled` option
  option :experimental_crash_tracking_enabled do |o|
    o.after_set do |_, _, precedence|
      unless precedence == Datadog::Core::Configuration::Option::Precedence::DEFAULT
        Core.log_deprecation(key: :experimental_crash_tracking_enabled) do
          'The profiling.advanced.experimental_crash_tracking_enabled setting has been deprecated for removal '\
          'and no longer does anything. Please remove it from your Datadog.configure block.'
        end
      end
    end
  end

  # @deprecated Use {:gvl_enabled} instead.
  option :preview_gvl_enabled do |o|
    o.type :bool
    o.default false
    o.after_set do |_, _, precedence|
      unless precedence == Datadog::Core::Configuration::Option::Precedence::DEFAULT
        Datadog.logger.warn(
          'The profiling.advanced.preview_gvl_enabled setting has been deprecated for removal and ' \
          'no longer does anything. Please remove it from your Datadog.configure block. ' \
          'GVL profiling is now controlled by the profiling.advanced.gvl_enabled setting instead.'
        )
      end
    end
  end

  # Controls GVL profiling. This will show when threads are waiting for GVL in the timeline view.
  #
  # This feature requires Ruby 3.2+.
  #
  # @default `DD_PROFILING_GVL_ENABLED` environment variable as a boolean, otherwise `true`
  option :gvl_enabled do |o|
    o.type :bool
    o.deprecated_env 'DD_PROFILING_PREVIEW_GVL_ENABLED'
    o.env 'DD_PROFILING_GVL_ENABLED'
    o.default true
  end

  # Controls the smallest time period the profiler will report a thread waiting for the GVL.
  #
  # The default value was set to minimize overhead. Periods smaller than the set value will not be reported (e.g.
  # the thread will be reported as whatever it was doing before it waited for the GVL).
  #
  # We do not recommend setting this to less than 1ms. Tweaking this value can increase application latency and
  # memory use.
  #
  # @default 10_000_000 (10ms)
  option :waiting_for_gvl_threshold_ns do |o|
    o.type :int
    o.default 10_000_000
  end

  # Controls if the profiler should attempt to read context from the otel library
  #
  # @default false
  option :preview_otel_context_enabled do |o|
    o.env 'DD_PROFILING_PREVIEW_OTEL_CONTEXT_ENABLED'
    o.default false
    o.env_parser do |value|
      if value
        value = value.strip.downcase
        if ['only', 'both'].include?(value)
          value
        elsif ['true', '1'].include?(value)
          'both'
        else
          'false'
        end
      end
    end
    o.setter do |value|
      if value == true
        :both
      elsif ['only', 'both', :only, :both].include?(value)
        value.to_sym
      else
        false
      end
    end
  end

  # Controls if the heap profiler should attempt to clean young objects after GC, rather than just at
  # serialization time. This lowers memory usage and high percentile latency.
  #
  # Only has effect when used together with `gc_enabled: true` and `experimental_heap_enabled: true`.
  #
  # @default true
  option :heap_clean_after_gc_enabled do |o|
    o.type :bool
    o.env 'DD_PROFILING_HEAP_CLEAN_AFTER_GC_ENABLED'
    o.default true
  end
end

#exporter ⇒ Datadog::Core::Configuration::Settings::DSL::Profiling::Exporter

Returns a configuration object.

Returns:

• (Datadog::Core::Configuration::Settings::DSL::Profiling::Exporter) —

  a configuration object

# File 'lib/datadog/core/configuration/settings.rb', line 234

settings :exporter do
  option :transport
end

#upload ⇒ Datadog::Core::Configuration::Settings::DSL::Profiling::Upload

Returns a configuration object.

Returns:

• (Datadog::Core::Configuration::Settings::DSL::Profiling::Upload) —

  a configuration object

# File 'lib/datadog/core/configuration/settings.rb', line 548

settings :upload do
  # Network timeout for reporting profiling data to Datadog.
  #
  # @default `DD_PROFILING_UPLOAD_TIMEOUT` environment variable, otherwise `30.0`
  option :timeout_seconds do |o|
    o.type :float
    o.env Profiling::Ext::ENV_UPLOAD_TIMEOUT
    o.default 30.0
  end
end