Class: Datadog::Core::Configuration::Settings

Inherits:
Object
  • Object
show all
Extended by:
Tracing::Configuration::Settings
Includes:
Base
Defined in:
lib/datadog/core/configuration/settings.rb

Overview

Global configuration settings for the Datadog library.

Defined Under Namespace

Modules: DSL

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Tracing::Configuration::Settings

extended

Methods included from Base

included

Instance Attribute Details

#api_key ⇒ String?

Datadog API key.

For internal use only.

Returns:

  • (String, nil)

Defaults to:

  • DD_API_KEY environment variable, otherwise nil



82
83
84
 
# File 'lib/datadog/core/configuration/settings.rb', line 82

def api_key
  @api_key
end

#env ⇒ String?

The env tag in Datadog. Use it to separate out your staging, development, and production environments.

Returns:

  • (String, nil)

See Also:

Defaults to:

  • DD_ENV environment variable, otherwise nil



158
159
160
 
# File 'lib/datadog/core/configuration/settings.rb', line 158

def env
  @env
end

#service ⇒ String

The service tag in Datadog. Use it to group related traces into a service.

Returns:

  • (String)

See Also:

Defaults to:

  • DD_SERVICE environment variable, otherwise the program name (e.g. 'ruby', 'rails', 'pry')



425
426
427
 
# File 'lib/datadog/core/configuration/settings.rb', line 425

def service
  @service
end

#site ⇒ String?

The Datadog site host to send data to. By default, data is sent to the Datadog US site: app.datadoghq.com.

If your organization is on another site, you must update this value to the new site.

For internal use only.

Returns:

  • (String, nil)

See Also:

Defaults to:

  • DD_SITE environment variable, otherwise nil which sends data to app.datadoghq.com



452
453
454
 
# File 'lib/datadog/core/configuration/settings.rb', line 452

def site
  @site
end

#tags ⇒ Hash<String,String>

Default tags

These tags are used by all Datadog products, when applicable. e.g. trace spans, profiles, etc.

Returns:

  • (Hash<String,String>)

Defaults to:

  • DD_TAGS environment variable (in the format 'tag1:value1,tag2:value2'), otherwise {}



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

def tags
  @tags
end

#time_now_provider ⇒ Proc<Time>

The time provider used by Datadog. It must respect the interface of Time.

When testing, it can be helpful to use a different time provider.

For Timecop, for example, ->{ Time.now_without_mock_time } allows Datadog features to use the real wall time when time is frozen.

Returns:

  • (Proc<Time>)

Defaults to:

  • ->{ Time.now }



526
527
528
 
# File 'lib/datadog/core/configuration/settings.rb', line 526

def time_now_provider
  @time_now_provider
end

#version ⇒ String?

The version tag in Datadog. Use it to enable Deployment Tracking.

Returns:

  • (String, nil)

See Also:

Defaults to:

  • DD_VERSION environment variable, otherwise nils



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

def version
  @version
end

Instance Method Details

#agent ⇒ Datadog::Core::Configuration::Settings::DSL::Agent

Datadog Agent configuration.

Returns:



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/datadog/core/configuration/settings.rb', line 52

settings :agent do
  # Agent hostname or IP.
  # @default `DD_AGENT_HOST` environment variable, otherwise `127.0.0.1`
  # @return [String,nil]
  option :host

  # Agent APM TCP port.
  # @see https://docs.datadoghq.com/getting_started/tracing/#datadog-apm
  # @default `DD_TRACE_AGENT_PORT` environment variable, otherwise `8126`
  # @return [String,nil]
  option :port

  # TODO: add declarative statsd configuration. Currently only usable via an environment variable.
  # Statsd configuration for agent access.
  # @public_api
  # settings :statsd do
  #   # Agent Statsd UDP port.
  #   # @configure_with {Datadog::Statsd}
  #   # @default `DD_AGENT_HOST` environment variable, otherwise `8125`
  #   # @return [String,nil]
  #   option :port
  # end
end

#diagnostics ⇒ Datadog::Core::Configuration::Settings::DSL::Diagnostics

Datadog diagnostic settings.

Enabling these surfaces debug information that can be helpful to diagnose issues related to Datadog internals.

Returns:



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/datadog/core/configuration/settings.rb', line 92

settings :diagnostics do
  # Outputs all spans created by the host application to `Datadog.logger`.
  #
  # **This option is very verbose!** It's only recommended for non-production
  # environments.
  #
  # This option is helpful when trying to understand what information the
  # Datadog features are sending to the Agent or backend.
  # @default `DD_TRACE_DEBUG` environment variable, otherwise `false`
  # @return [Boolean]
  option :debug do |o|
    o.env Datadog::Core::Configuration::Ext::Diagnostics::ENV_DEBUG_ENABLED
    o.default false
    o.type :bool
    o.after_set do |enabled|
      # Enable rich debug print statements.
      # We do not need to unnecessarily load 'pp' unless in debugging mode.
      require 'pp' if enabled
    end
  end
  # Internal {Datadog::Statsd} metrics collection.
  #
  # @public_api
  settings :health_metrics do
    # Enable health metrics collection.
    #
    # @default `DD_HEALTH_METRICS_ENABLED` environment variable, otherwise `false`
    # @return [Boolean]
    option :enabled do |o|
      o.env Datadog::Core::Configuration::Ext::Diagnostics::ENV_HEALTH_METRICS_ENABLED
      o.default false
      o.type :bool
    end

    # {Datadog::Statsd} instance to collect health metrics.
    #
    # If `nil`, health metrics creates a new {Datadog::Statsd} client with default agent configuration.
    #
    # @default `nil`
    # @return [Datadog::Statsd,nil] a custom {Datadog::Statsd} instance
    # @return [nil] an instance with default agent configuration will be lazily created
    option :statsd
  end

  # Tracer startup debug log statement configuration.
  # @public_api
  settings :startup_logs do
    # Enable startup logs collection.
    #
    # If `nil`, defaults to logging startup logs when `ddtrace` detects that the application
    # is *not* running in a development environment.
    #
    # @default `DD_TRACE_STARTUP_LOGS` environment variable, otherwise `nil`
    # @return [Boolean, nil]
    option :enabled do |o|
      o.env Datadog::Core::Configuration::Ext::Diagnostics::ENV_STARTUP_LOGS_ENABLED
      # Defaults to nil as we want to know when the default value is being used
      o.type :bool, nilable: true
    end
  end
end

#logger ⇒ Datadog::Core::Configuration::Settings::DSL::Logger

Internal Datadog.logger configuration.

This logger instance is only used internally by the gem.

Returns:



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/datadog/core/configuration/settings.rb', line 170

settings :logger do
  # The `Datadog.logger` object.
  #
  # Can be overwritten with a custom logger object that respects the
  # [built-in Ruby Logger](https://ruby-doc.org/stdlib-3.0.1/libdoc/logger/rdoc/Logger.html)
  # interface.
  #
  # @return Logger::Severity
  option :instance do |o|
    o.after_set { |value| set_option(:level, value.level) unless value.nil? }
  end

  # Log level for `Datadog.logger`.
  # @see Logger::Severity
  # @return Logger::Severity
  option :level, default: ::Logger::INFO
end

#profiling ⇒ Datadog::Core::Configuration::Settings::DSL::Profiling

Datadog Profiler-specific configurations.

Returns:

See Also:



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
 
# File 'lib/datadog/core/configuration/settings.rb', line 192

settings :profiling do
  # Enable profiling.
  #
  # @default `DD_PROFILING_ENABLED` environment variable, otherwise `false`
  # @return [Boolean]
  option :enabled do |o|
    o.env Profiling::Ext::ENV_ENABLED
    o.default false
    o.type :bool
  end

  # @public_api
  settings :exporter do
    option :transport
  end

  # @public_api
  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
        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

    # 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, default: true

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

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

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

    # Forces enabling of profiling of time/resources spent in Garbage Collection.
    #
    # Note that setting this to "false" (or not setting it) will not prevent the feature from being
    # being automatically enabled in the future.
    #
    # This feature defaults to off for two reasons:
    # 1. Currently this feature can add a lot of overhead for GC-heavy workloads.
    # 2. Although this feature is safe on Ruby 2.x, on Ruby 3.x it can break in applications that make use of
    #    Ractors due to two Ruby VM bugs:
    #    https://bugs.ruby-lang.org/issues/19112 AND https://bugs.ruby-lang.org/issues/18464.
    #    If you use Ruby 3.x and your application does not use Ractors (or if your Ruby has been patched), the
    #    feature is fully safe to enable and this toggle can be used to do so.
    #
    # We expect the once the above issues are overcome, we'll automatically enable the feature on fixed Ruby
    # versions.
    #
    # @default `DD_PROFILING_FORCE_ENABLE_GC` environment variable, otherwise `false`
    option :force_enable_gc_profiling do |o|
      o.env 'DD_PROFILING_FORCE_ENABLE_GC'
      o.type :bool
      o.default false
    end

    # Can be used to enable/disable the Datadog::Profiling.allocation_count feature.
    #
    # This feature is safe and enabled by default on Ruby 2.x, but has a few caveats on Ruby 3.x.
    #
    # Caveat 1 (severe):
    # On Ruby versions 3.0 (all), 3.1.0 to 3.1.3, and 3.2.0 to 3.2.2 this is disabled by default because it
    # can trigger a VM bug that causes a segmentation fault during garbage collection of Ractors
    # (https://bugs.ruby-lang.org/issues/18464). We don't recommend using this feature on such Rubies.
    # This bug is fixed on Ruby versions 3.1.4, 3.2.3 and 3.3.0.
    #
    # Caveat 2 (annoyance):
    # On all known versions of Ruby 3.x, due to https://bugs.ruby-lang.org/issues/19112, when a ractor gets
    # garbage collected, Ruby will disable all active tracepoints, which this feature internally relies on.
    # Thus this feature is only usable if you're not using Ractors.
    #
    # @default `true` on Ruby 2.x and 3.1.4+, 3.2.3+ and 3.3.0+; `false` for Ruby 3.0 and unpatched Rubies.
    option :allocation_counting_enabled do |o|
      o.default do
        RUBY_VERSION.start_with?('2.') ||
          (RUBY_VERSION.start_with?('3.1.') && RUBY_VERSION >= '3.1.4') ||
          (RUBY_VERSION.start_with?('3.2.') && RUBY_VERSION >= '3.2.3') ||
          RUBY_VERSION >= '3.3.'
      end
    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.type :bool
      o.env 'DD_PROFILING_EXPERIMENTAL_TIMELINE_ENABLED'
      o.default false
    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
  end

  # @public_api
  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
end

#remote ⇒ Datadog::Core::Configuration::Settings::DSL::Remote

Remote configuration

Returns:



594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
 
# File 'lib/datadog/core/configuration/settings.rb', line 594

settings :remote do
  # Enable remote configuration. This allows fetching of remote configuration for live updates.
  #
  # @default `DD_REMOTE_CONFIGURATION_ENABLED` environment variable, otherwise `true`.
  #   By default, remote configuration is disabled in development environments.
  # @return [Boolean]
  option :enabled do |o|
    o.env Core::Remote::Ext::ENV_ENABLED
    o.default do
      if Datadog::Core::Environment::Execution.development?
        Datadog.logger.debug do
          'Development environment detected, disabling Remote Configuration. ' \
            'You can enable it with DD_REMOTE_CONFIGURATION_ENABLED=true.'
        end
        false
      else
        true
      end
    end
    o.type :bool
  end

  # Tune remote configuration polling interval.
  # This is a private setting. Do not use outside of Datadog. It might change at any point in time.
  #
  # @default `DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS` environment variable, otherwise `5.0` seconds.
  # @return [Float]
  # @!visibility private
  option :poll_interval_seconds do |o|
    o.env Core::Remote::Ext::ENV_POLL_INTERVAL_SECONDS
    o.type :float
    o.default 5.0
  end

  # Declare service name to bind to remote configuration. Use when
  # DD_SERVICE does not match the correct integration for which remote
  # configuration applies.
  #
  # @default `nil`.
  # @return [String,nil]
  option :service
end

#runtime_metrics ⇒ Datadog::Core::Configuration::Settings::DSL::RuntimeMetrics

Runtime Metrics are StatsD metrics collected by the tracer to gain additional insights into an application's performance.

Returns:



407
408
409
410
411
412
413
414
415
416
417
418
419
 
# File 'lib/datadog/core/configuration/settings.rb', line 407

settings :runtime_metrics do
  # Enable runtime metrics.
  # @default `DD_RUNTIME_METRICS_ENABLED` environment variable, otherwise `false`
  # @return [Boolean]
  option :enabled do |o|
    o.env Core::Runtime::Ext::Metrics::ENV_ENABLED
    o.default false
    o.type :bool
  end

  option :opts, default: {}, type: :hash
  option :statsd
end

#telemetry ⇒ Datadog::Core::Configuration::Settings::DSL::Telemetry

Client-side telemetry configuration

Returns:



555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
 
# File 'lib/datadog/core/configuration/settings.rb', line 555

settings :telemetry do
  # Enable telemetry collection. This allows telemetry events to be emitted to the telemetry API.
  #
  # @default `DD_INSTRUMENTATION_TELEMETRY_ENABLED` environment variable, otherwise `true`.
  #   Can be disabled as documented [here](https://docs.datadoghq.com/tracing/configure_data_security/#telemetry-collection).
  #   By default, telemetry is disabled in development environments.
  # @return [Boolean]
  option :enabled do |o|
    o.env Core::Telemetry::Ext::ENV_ENABLED
    o.default do
      if Datadog::Core::Environment::Execution.development?
        Datadog.logger.debug do
          'Development environment detected, disabling Telemetry. ' \
            'You can enable it with DD_INSTRUMENTATION_TELEMETRY_ENABLED=true.'
        end
        false
      else
        true
      end
    end
    o.type :bool
  end

  # The interval in seconds when telemetry must be sent.
  #
  # This method is used internally, for testing purposes only.
  #
  # @default `DD_TELEMETRY_HEARTBEAT_INTERVAL` environment variable, otherwise `60`.
  # @return [Float]
  # @!visibility private
  option :heartbeat_interval_seconds do |o|
    o.type :float
    o.env Core::Telemetry::Ext::ENV_HEARTBEAT_INTERVAL
    o.default 60.0
  end
end