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

Inherits:
Object
  • Object
show all
Defined in:
lib/datadog/core/configuration/settings.rb

Defined Under Namespace

Classes: Endpoint

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#allocation_counting_enabled ⇒ Object

Can be used to enable/disable the Datadog::Profiling.allocation_count feature.

Requires allocation profiling to be enabled.

Defaults to:

  • false



336
337
338
 
# File 'lib/datadog/core/configuration/settings.rb', line 336

def allocation_counting_enabled
  @allocation_counting_enabled
end

#code_provenance_enabled ⇒ Object

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.



313
314
315
 
# File 'lib/datadog/core/configuration/settings.rb', line 313

def code_provenance_enabled
  @code_provenance_enabled
end

#dir_interruption_workaround_enabled ⇒ Object

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.

otherwise true

Defaults to:

  • DD_PROFILING_DIR_INTERRUPTION_WORKAROUND_ENABLED environment variable as a boolean,



447
448
449
 
# File 'lib/datadog/core/configuration/settings.rb', line 447

def dir_interruption_workaround_enabled
  @dir_interruption_workaround_enabled
end

#experimental_cpu_sampling_interval_ms ⇒ Object

Experimental: Controls the CPU sampling interval in milliseconds. This sets how often the profiler attempts to take a CPU sample. Valid values are 1 to 10.

Lower values increase accuracy but also increase overhead. If you need to reduce profiler overhead, use the overhead_target_percentage setting instead.

No config via environment variable yet

Defaults to:

  • 10



632
633
634
 
# File 'lib/datadog/core/configuration/settings.rb', line 632

def experimental_cpu_sampling_interval_ms
  @experimental_cpu_sampling_interval_ms
end

#experimental_crash_tracking_enabled ⇒ Object

DEV-3.0: Remove experimental_crash_tracking_enabled option



499
500
501
 
# File 'lib/datadog/core/configuration/settings.rb', line 499

def experimental_crash_tracking_enabled
  @experimental_crash_tracking_enabled
end

#experimental_heap_enabled ⇒ Object

Can be used to enable/disable the collection of heap profiles.

This feature is in preview and disabled by default. Requires Ruby 3.1+.

Defaults to:

  • DD_PROFILING_EXPERIMENTAL_HEAP_ENABLED environment variable as a boolean, otherwise false



348
349
350
 
# File 'lib/datadog/core/configuration/settings.rb', line 348

def experimental_heap_enabled
  @experimental_heap_enabled
end

#experimental_heap_sample_rate ⇒ Object

Can be used to configure the heap sampling rate: a heap sample will be collected for every x allocation samples.

The higher the value, the less accuracy in heap tracking but the smaller the overhead.

If you needed to tweak this, please tell us why on https://github.com/DataDog/dd-trace-rb/issues/new, so we can fix it!

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.

Defaults to:

  • DD_PROFILING_EXPERIMENTAL_HEAP_SAMPLE_RATE environment variable, otherwise 1.



380
381
382
 
# File 'lib/datadog/core/configuration/settings.rb', line 380

def experimental_heap_sample_rate
  @experimental_heap_sample_rate
end

#experimental_heap_size_enabled ⇒ Object

Can be used to enable/disable the collection of heap size profiles.

This feature is in preview and by default is enabled whenever heap profiling is enabled.

follows the value of experimental_heap_enabled.

Defaults to:

  • DD_PROFILING_EXPERIMENTAL_HEAP_SIZE_ENABLED environment variable as a boolean, otherwise it



362
363
364
 
# File 'lib/datadog/core/configuration/settings.rb', line 362

def experimental_heap_size_enabled
  @experimental_heap_size_enabled
end

#experimental_use_system_dns ⇒ Object

Fallback to system dns instead of using libdatadog built-in resolver.

Defaults to:

  • DD_PROFILING_EXPERIMENTAL_USE_SYSTEM_DNS environment variable as a boolean, otherwise true



640
641
642
 
# File 'lib/datadog/core/configuration/settings.rb', line 640

def experimental_use_system_dns
  @experimental_use_system_dns
end

#gc_enabled ⇒ Object

Can be used to enable/disable garbage collection profiling.

Defaults to:

  • DD_PROFILING_GC_ENABLED environment variable, otherwise true



325
326
327
 
# File 'lib/datadog/core/configuration/settings.rb', line 325

def gc_enabled
  @gc_enabled
end

#gvl_enabled ⇒ Object

Controls GVL profiling. This will show when threads are waiting for GVL in the timeline view.

This feature requires Ruby 3.2+.

Defaults to:

  • DD_PROFILING_GVL_ENABLED environment variable as a boolean, otherwise true



530
531
532
 
# File 'lib/datadog/core/configuration/settings.rb', line 530

def gvl_enabled
  @gvl_enabled
end

#heap_clean_after_gc_enabled ⇒ Object

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.

Defaults to:

  • true



586
587
588
 
# File 'lib/datadog/core/configuration/settings.rb', line 586

def heap_clean_after_gc_enabled
  @heap_clean_after_gc_enabled
end

#max_frames ⇒ Object

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.

Defaults to:

  • DD_PROFILING_MAX_FRAMES environment variable, otherwise 400



289
290
291
 
# File 'lib/datadog/core/configuration/settings.rb', line 289

def max_frames
  @max_frames
end

#native_filenames_enabled ⇒ Object

Controls if the profiler should use native filenames for frames in stack traces for functions implemented using native code. Setting to false will make the profiler fall back to default Ruby stack trace behavior (only show .rb files).

Defaults to:

  • true



596
597
598
 
# File 'lib/datadog/core/configuration/settings.rb', line 596

def native_filenames_enabled
  @native_filenames_enabled
end

#no_signals_workaround_enabled ⇒ Object

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. 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!

Defaults to:

  • DD_PROFILING_NO_SIGNALS_WORKAROUND_ENABLED environment variable as a boolean, otherwise :auto



428
429
430
 
# File 'lib/datadog/core/configuration/settings.rb', line 428

def no_signals_workaround_enabled
  @no_signals_workaround_enabled
end

#overhead_target_percentage ⇒ Object

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.

Defaults to:

  • DD_PROFILING_OVERHEAD_TARGET_PERCENTAGE as a float, otherwise 2.0



481
482
483
 
# File 'lib/datadog/core/configuration/settings.rb', line 481

def overhead_target_percentage
  @overhead_target_percentage
end

#preview_gvl_enabled ⇒ Object

Deprecated for removal.

Use :gvl_enabled instead.



511
512
513
 
# File 'lib/datadog/core/configuration/settings.rb', line 511

def preview_gvl_enabled
  @preview_gvl_enabled
end

#preview_otel_context_enabled ⇒ Object

Controls if the profiler should attempt to read context from the otel library

Defaults to:

  • false



554
555
556
 
# File 'lib/datadog/core/configuration/settings.rb', line 554

def preview_otel_context_enabled
  @preview_otel_context_enabled
end

#shutdown_on_exec_enabled ⇒ Object

The profiler gathers data by sending SIGPROF unix signals to Ruby application threads.

When using Kernel#exec on Linux, it can happen that a signal sent before calling exec arrives after the new process is running, causing it to fail with the Profiling timer expired error message. To avoid this, the profiler installs a monkey patch on Kernel#exec to stop profiling before actually calling exec. This monkey patch is available for Ruby 2.7+; let us know if you need it on earlier Rubies. For more details see https://github.com/DataDog/dd-trace-rb/issues/5101 .

otherwise true

Defaults to:

  • DD_PROFILING_SHUTDOWN_ON_EXEC_ENABLED environment variable as a boolean,



464
465
466
 
# File 'lib/datadog/core/configuration/settings.rb', line 464

def shutdown_on_exec_enabled
  @shutdown_on_exec_enabled
end

#sighandler_sampling_enabled ⇒ Object

Controls if the profiler should sample directly from the signal handler. Sampling directly from the signal handler improves accuracy of the data collected.

We recommend using this setting with Ruby 3.2.5+ / Ruby 3.3.4+ and above as they include additional safety measures added in https://github.com/ruby/ruby/pull/11036. We have not validated it thoroughly with earlier versions, but in practice it should work on Ruby 3.0+ (the key change was https://github.com/ruby/ruby/pull/3296).

Enabling this on Ruby 2 is not recommended as it may cause VM crashes and/or incorrect data.

Defaults to:

  • true on Ruby 3.2.5+ / Ruby 3.3.4+, false on older Rubies



613
614
615
 
# File 'lib/datadog/core/configuration/settings.rb', line 613

def sighandler_sampling_enabled
  @sighandler_sampling_enabled
end

#skip_mysql2_check ⇒ Object

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.

Defaults to:

  • DD_PROFILING_SKIP_MYSQL2_CHECK environment variable, otherwise false



391
392
393
 
# File 'lib/datadog/core/configuration/settings.rb', line 391

def skip_mysql2_check
  @skip_mysql2_check
end

#timeline_enabled ⇒ Object

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!

Defaults to:

  • DD_PROFILING_TIMELINE_ENABLED environment variable as a boolean, otherwise true



403
404
405
 
# File 'lib/datadog/core/configuration/settings.rb', line 403

def timeline_enabled
  @timeline_enabled
end

#upload_period_seconds ⇒ Object

Controls how often the profiler reports data, in seconds. Cannot be lower than 60 seconds.

We do not recommend tweaking this value.

Defaults to:

  • DD_PROFILING_UPLOAD_PERIOD environment variable, otherwise 60



492
493
494
 
# File 'lib/datadog/core/configuration/settings.rb', line 492

def upload_period_seconds
  @upload_period_seconds
end

#waiting_for_gvl_threshold_ns ⇒ Object

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.

Defaults to:

  • 10_000_000 (10ms)



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

def waiting_for_gvl_threshold_ns
  @waiting_for_gvl_threshold_ns
end

Instance Method Details

#endpoint ⇒ Datadog::Core::Configuration::Settings::DSL::Profiling::Advanced::Endpoint

Returns a configuration object.

Returns:



296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/datadog/core/configuration/settings.rb', line 296

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