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



86
87
88
 
# File 'lib/datadog/core/configuration/settings.rb', line 86

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



161
162
163
 
# File 'lib/datadog/core/configuration/settings.rb', line 161

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')



316
317
318
 
# File 'lib/datadog/core/configuration/settings.rb', line 316

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



340
341
342
 
# File 'lib/datadog/core/configuration/settings.rb', line 340

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 {}



351
352
353
 
# File 'lib/datadog/core/configuration/settings.rb', line 351

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 }



401
402
403
 
# File 'lib/datadog/core/configuration/settings.rb', line 401

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



421
422
423
 
# File 'lib/datadog/core/configuration/settings.rb', line 421

def version
  @version
end

Instance Method Details

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

Datadog Agent configuration.

Returns:



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

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:



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
153
154
155
 
# File 'lib/datadog/core/configuration/settings.rb', line 96

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.default { env_to_bool(Datadog::Core::Configuration::Ext::Diagnostics::ENV_DEBUG_ENABLED, false) }
    o.lazy
    o.on_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.default { env_to_bool(Datadog::Core::Configuration::Ext::Diagnostics::ENV_HEALTH_METRICS_ENABLED, false) }
      o.lazy
    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|
      # Defaults to nil as we want to know when the default value is being used
      o.default { env_to_bool(Datadog::Core::Configuration::Ext::Diagnostics::ENV_STARTUP_LOGS_ENABLED, nil) }
      o.lazy
    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:



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

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.on_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:



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
 
# File 'lib/datadog/core/configuration/settings.rb', line 193

settings :profiling do
  # Enable profiling.
  #
  # @default `DD_PROFILING_ENABLED` environment variable, otherwise `false`
  # @return [Boolean]
  option :enabled do |o|
    o.default { env_to_bool(Profiling::Ext::ENV_ENABLED, false) }
    o.lazy
  end

  # @public_api
  settings :exporter do
    option :transport
  end

  # @public_api
  settings :advanced do
    # This should never be reduced, as it can cause the resulting profiles to become biased.
    # The current default should be enough for most services, allowing 16 threads to be sampled around 30 times
    # per second for a 60 second period.
    option :max_events, default: 32768

    # 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.
    option :max_frames do |o|
      o.default { env_to_int(Profiling::Ext::ENV_MAX_FRAMES, 400) }
      o.lazy
    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.default { env_to_bool(Profiling::Ext::ENV_ENDPOINT_COLLECTION_ENABLED, true) }
          o.lazy
        end
      end
    end

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

    # 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.on_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

    # Forces enabling the new profiler. We do not yet recommend turning on this option.
    #
    # Note that setting this to "false" (or not setting it) will not prevent the new profiler from
    # being automatically used in the future.
    # This option will be deprecated for removal once the new profiler gets enabled by default for all customers.
    option :force_enable_new_profiler do |o|
      o.default { env_to_bool('DD_PROFILING_FORCE_ENABLE_NEW', false) }
      o.lazy
    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 toggle was added because, although this feature is safe and enabled by default 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.
    #
    # Furthermore, currently this feature can add a lot of overhead for GC-heavy workloads.
    #
    # We expect the once the above issues are overcome, we'll automatically enable the feature on fixed Ruby
    # versions.
    option :force_enable_gc_profiling do |o|
      o.default { env_to_bool('DD_PROFILING_FORCE_ENABLE_GC', false) }
      o.lazy
    end
  end

  # @public_api
  settings :upload do
    option :timeout_seconds do |o|
      o.setter { |value| value.nil? ? 30.0 : value.to_f }
      o.default { env_to_float(Profiling::Ext::ENV_UPLOAD_TIMEOUT, 30.0) }
      o.lazy
    end
  end
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:



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

settings :runtime_metrics do
  # Enable runtime metrics.
  # @default `DD_RUNTIME_METRICS_ENABLED` environment variable, otherwise `false`
  # @return [Boolean]
  option :enabled do |o|
    o.default { env_to_bool(Core::Runtime::Ext::Metrics::ENV_ENABLED, false) }
    o.lazy
  end

  option :opts, default: ->(_i) { {} }, lazy: true
  option :statsd
end

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

Client-side telemetry configuration

Returns:



429
430
431
432
433
434
435
436
437
438
439
 
# File 'lib/datadog/core/configuration/settings.rb', line 429

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 `false`. In a future release,
  #   this value will be changed to `true` by default as documented [here](https://docs.datadoghq.com/tracing/configure_data_security/#telemetry-collection).
  # @return [Boolean]
  option :enabled do |o|
    o.default { env_to_bool(Core::Telemetry::Ext::ENV_ENABLED, false) }
    o.lazy
  end
end