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 217

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 197

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 225

settings :advanced do
  # @deprecated No longer does anything, and will be removed on dd-trace-rb 2.0.
  #
  # This was used prior to the GA of the new CPU Profiling 2.0 profiler. The CPU Profiling 2.0 profiler does not
  # use or need this setting and thus it doesn't do anything.
  option :max_events do |o|
    o.after_set do |_, _, precedence|
      unless precedence == Datadog::Core::Configuration::Option::Precedence::DEFAULT
        Datadog.logger.warn(
          'The profiling.advanced.max_events setting has been deprecated for removal and no ' \
          'longer does anything. Please remove it from your Datadog.configure block.'
        )
      end
    end
  end

  # 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

  # @deprecated No longer does anything, and will be removed on dd-trace-rb 2.0.
  #
  # This was added as a temporary support option in case of issues with the new `Profiling::HttpTransport` class
  # but we're now confident it's working nicely so we've removed the old code path.
  option :legacy_transport_enabled do |o|
    o.after_set do |_, _, precedence|
      unless precedence == Datadog::Core::Configuration::Option::Precedence::DEFAULT
        Datadog.logger.warn(
          'The profiling.advanced.legacy_transport_enabled setting has been deprecated for removal and no ' \
          'longer does anything. Please remove it from your Datadog.configure block.'
        )
      end
    end
  end

  # @deprecated No longer does anything, and will be removed on dd-trace-rb 2.0.
  #
  # This was used prior to the GA of the new CPU Profiling 2.0 profiler. Using CPU Profiling 2.0 is now the
  # default and this doesn't do anything.
  option :force_enable_new_profiler do |o|
    o.after_set do |_, _, precedence|
      unless precedence == Datadog::Core::Configuration::Option::Precedence::DEFAULT
        Datadog.logger.warn(
          'The profiling.advanced.force_enable_new_profiler setting has been deprecated for removal and no ' \
          'longer does anything. Please remove it from your Datadog.configure block.'
        )
      end
    end
  end

  # @deprecated No longer does anything, and will be removed on dd-trace-rb 2.0.
  #
  # This was used prior to the GA of the new CPU Profiling 2.0 profiler. Using CPU Profiling 2.0 is now the
  # default and this doesn't do anything.
  option :force_enable_legacy_profiler do |o|
    o.after_set do |_, _, precedence|
      unless precedence == Datadog::Core::Configuration::Option::Precedence::DEFAULT
        Datadog.logger.warn(
          'The profiling.advanced.force_enable_legacy_profiler setting has been deprecated for removal and no ' \
          'longer does anything. Please remove it from your Datadog.configure block.'
        )
      end
    end
  end

  # @deprecated No longer does anything, and will be removed on dd-trace-rb 2.0.
  #
  # GC profiling is now on by default and controlled by {:gc_enabled}.
  option :force_enable_gc_profiling do |o|
    o.after_set do |_, _, precedence|
      unless precedence == Datadog::Core::Configuration::Option::Precedence::DEFAULT
        Datadog.logger.warn(
          'The profiling.advanced.force_enable_gc_profiling setting has been deprecated for removal and no ' \
          'longer does anything (the feature is now on by default). ' \
          'Please remove this setting from your Datadog.configure block.'
        )
      end
    end
  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.
  #
  # @deprecated Use {:allocation_enabled} (outside of advanced section) instead.
  option :allocation_counting_enabled do |o|
    o.after_set do |_, _, precedence|
      unless precedence == Datadog::Core::Configuration::Option::Precedence::DEFAULT
        Datadog.logger.warn(
          'The profiling.advanced.allocation_counting_enabled setting has been deprecated for removal and no ' \
          'longer does anything. Please remove it from your Datadog.configure block. ' \
          'Allocation counting is now controlled by the profiling.allocation_enabled setting instead.'
        )
      end
    end
  end

  # @deprecated Use {:allocation_enabled} (outside of advanced section) instead.
  option :experimental_allocation_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.experimental_allocation_enabled setting has been deprecated for removal and ' \
          'no longer does anything. Please remove it from your Datadog.configure block. ' \
          'Allocation profiling is now controlled by the profiling.allocation_enabled setting instead.'
        )
      end
    end
  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 allocation sampling rate: a sample will be collected every x allocations.
  #
  # This feature is now controlled via {:overhead_target_percentage}
  option :experimental_allocation_sample_rate do |o|
    o.after_set do |_, _, precedence|
      unless precedence == Datadog::Core::Configuration::Option::Precedence::DEFAULT
        Datadog.logger.warn(
          'The profiling.advanced.experimental_allocation_sample_rate setting has been deprecated for removal ' \
          'and no longer does anything. Please remove it from your Datadog.configure block. ' \
          'Allocation sample rate is now handled by a dynamic sampler which will adjust the sampling rate to ' \
          'keep to the configured `profiling.advanced.overhead_target_percentage`.'
        )
      end
    end
  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

  # Enables data collection for the timeline feature. This is still experimental and not recommended yet.
  #
  # @default `DD_PROFILING_EXPERIMENTAL_TIMELINE_ENABLED` environment variable as a boolean, otherwise `false`
  option :experimental_timeline_enabled do |o|
    o.after_set do |_, _, precedence|
      unless precedence == Datadog::Core::Configuration::Option::Precedence::DEFAULT
        Datadog.logger.warn(
          'The profiling.advanced.experimental_timeline_enabled setting has been deprecated for removal ' \
          'and no longer does anything. Please remove it from your Datadog.configure block. ' \
          'The timeline feature counting is now controlled by the `timeline_enabled` setting instead.'
        )
      end
    end
  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

  # 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
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 204

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 537

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