datadog 2.19.0 → 2.21.0

data/lib/datadog/core/configuration/config_helper.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative 'supported_configurations'
+require_relative '../logger'
+
+module Datadog
+  module Core
+    module Configuration
+      class ConfigHelper
+        def initialize(
+          source_env: ENV,
+          supported_configurations: SUPPORTED_CONFIGURATIONS,
+          aliases: ALIASES,
+          alias_to_canonical: ALIAS_TO_CANONICAL,
+          raise_on_unknown_env_var: false
+        )
+          @source_env = source_env
+          @supported_configurations = supported_configurations
+          @aliases = aliases
+          @alias_to_canonical = alias_to_canonical
+          @raise_on_unknown_env_var = raise_on_unknown_env_var
+        end
+
+        def [](name)
+          get_environment_variable(name)
+        end
+
+        def fetch(name, default_value = UNSET)
+          if (item = get_environment_variable(name))
+            return item
+          end
+
+          return yield(name) if block_given?
+          return default_value unless default_value == UNSET
+
+          raise KeyError, "key not found: #{name}"
+        end
+
+        def key?(name)
+          !get_environment_variable(name).nil?
+        end
+
+        alias_method :has_key?, :key?
+        alias_method :include?, :key?
+        alias_method :member?, :key?
+
+        # Returns the environment variable value if the environment variable is a supported Datadog configuration (starts with DD_ or OTEL_)
+        # or if it is not a Datadog configuration. Otherwise, it returns nil.
+        #
+        # @param name [String] Environment variable name
+        # @param default_value [String, nil] Default value to return if the environment variable is not set
+        # @param source_env [Hash[String, String]] Environment variables to use
+        # @return [String, nil] The environment variable value
+        # @raise [RuntimeError] if the configuration is not supported
+        def get_environment_variable(name, default_value = nil, source_env: @source_env)
+          # datadog-ci-rb is using dd-trace-rb config DSL, which uses this method.
+          # Until we've correctly implemented support for datadog-ci-rb, we disable config inversion if ci is enabled.
+          if !defined?(::Datadog::CI) &&
+              (name.start_with?('DD_', 'OTEL_') || @alias_to_canonical[name]) &&
+              !@supported_configurations[name]
+            if defined?(@raise_on_unknown_env_var) && @raise_on_unknown_env_var # Only enabled for tests!
+              if @alias_to_canonical[name]
+                raise "Please use #{@alias_to_canonical[name]} instead of #{name}. See docs/AccessEnvironmentVariables.md for details."
+              else
+                raise "Missing #{name} env/configuration in \"supported-configurations.json\" file. See docs/AccessEnvironmentVariables.md for details."
+              end
+            end
+            # TODO: Send telemetry to know if we ever miss an env var
+            return nil
+          end
+
+          env_value = source_env[name]
+          if env_value.nil? && @aliases[name]
+            @aliases[name].each do |alias_name|
+              return source_env[alias_name] if source_env[alias_name]
+            end
+          end
+
+          env_value || default_value
+        end
+
+        # Only used in error message creation. Match get_environment_variable logic to return the resolved environment variable name.
+        def resolve_env(name, source_env: @source_env)
+          if source_env[name].nil? && @aliases[name]
+            @aliases[name].each do |alias_name|
+              return alias_name if source_env[alias_name]
+            end
+          end
+
+          name
+        end
+
+        # Anchor object that represents an undefined default value.
+        # This is necessary because `nil` is a valid default value.
+        UNSET = Object.new
+        private_constant :UNSET
+      end
+    end
+  end
+end

data/lib/datadog/core/configuration/deprecations.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'supported_configurations'
+require_relative '../logger'
+require_relative '../utils/only_once'
+
+module Datadog
+  module Core
+    module Configuration
+      module Deprecations
+        LOG_DEPRECATIONS_ONLY_ONCE = Datadog::Core::Utils::OnlyOnce.new
+
+        def self.log_deprecations_from_all_sources(logger, deprecations: DEPRECATIONS, alias_to_canonical: ALIAS_TO_CANONICAL)
+          LOG_DEPRECATIONS_ONLY_ONCE.run do
+            log_deprecated_environment_variables(logger, ENV, 'environment', deprecations, alias_to_canonical)
+            customer_config = StableConfig.configuration.dig(:local, :config)
+            log_deprecated_environment_variables(logger, customer_config, 'local', deprecations, alias_to_canonical) if customer_config
+            fleet_config = StableConfig.configuration.dig(:fleet, :config)
+            log_deprecated_environment_variables(logger, fleet_config, 'fleet', deprecations, alias_to_canonical) if fleet_config
+          end
+        end
+
+        private_class_method def self.log_deprecated_environment_variables(logger, source_env, source_name, deprecations, alias_to_canonical)
+          deprecations.each do |deprecated_env_var, message|
+            next unless source_env.key?(deprecated_env_var)
+
+            Datadog::Core.log_deprecation(disallowed_next_major: false, logger: logger) do
+              "#{deprecated_env_var} #{source_name} variable is deprecated" +
+                (alias_to_canonical[deprecated_env_var] ? ", use #{alias_to_canonical[deprecated_env_var]} instead." : ". #{message}.")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/core/configuration/ext.rb

@@ -9,7 +9,6 @@ module Datadog
         # @public_api
         module Diagnostics
           ENV_DEBUG_ENABLED = 'DD_TRACE_DEBUG'
-          ENV_OTEL_LOG_LEVEL = 'OTEL_LOG_LEVEL'
           ENV_HEALTH_METRICS_ENABLED = 'DD_HEALTH_METRICS_ENABLED'
           ENV_STARTUP_LOGS_ENABLED = 'DD_TRACE_STARTUP_LOGS'
         end

data/lib/datadog/core/configuration/option.rb

@@ -15,16 +15,25 @@ module Datadog
         # @!attribute [r] precedence_set
         #   When this option was last set, what was the value precedence used?
         #   @return [Precedence::Value]
-        attr_reader :definition, :precedence_set, :resolved_env
+        attr_reader :definition, :precedence_set
 
         # Option setting precedence.
         module Precedence
           # Represents an Option precedence level.
           # Each precedence has a `numeric` value; higher values means higher precedence.
           # `name` is for inspection purposes only.
-          Value = Struct.new(:numeric, :name, :origin) do
+
+          class Value
             include Comparable
 
+            attr_accessor :numeric, :name, :origin
+
+            def initialize(numeric, name, origin)
+              @numeric = numeric
+              @name = name
+              @origin = origin
+            end
+
             def <=>(other)
               return nil unless other.is_a?(Value)
 
@@ -59,7 +68,6 @@ module Datadog
           @context = context
           @value = nil
           @is_set = false
-          @resolved_env = nil
 
           # One value is stored per precedence, to allow unsetting a higher
           # precedence value and falling back to a lower precedence one.
@@ -75,7 +83,7 @@ module Datadog
         #
         # @param value [Object] the new value to be associated with this option
         # @param precedence [Precedence] from what precedence order this new value comes from
-        def set(value, precedence: Precedence::PROGRAMMATIC, resolved_env: nil)
+        def set(value, precedence: Precedence::PROGRAMMATIC)
           # Is there a higher precedence value set?
           if @precedence_set > precedence
             # This should be uncommon, as higher precedence values tend to
@@ -94,7 +102,7 @@ module Datadog
             return @value
           end
 
-          internal_set(value, precedence, resolved_env)
+          internal_set(value, precedence)
         end
 
         def unset(precedence)
@@ -112,7 +120,7 @@ module Datadog
               # Look for value that is set.
               # The hash `@value_per_precedence` has a custom default value of `UNSET`.
               if (value = @value_per_precedence[p]) != UNSET
-                internal_set(value, p, nil)
+                internal_set(value, p)
                 return nil
               end
             end
@@ -172,20 +180,17 @@ module Datadog
         private
 
         def coerce_env_variable(value)
-          return context_exec(value, &@definition.env_parser) if @definition.env_parser
+          env_parser = @definition.env_parser
+          return context_exec(value, &env_parser) if env_parser
 
           case @definition.type
           when :hash
             values = value.split(',') # By default we only want to support comma separated strings
 
-            values.map! do |v|
-              v.gsub!(/\A[\s,]*|[\s,]*\Z/, '')
+            values.each_with_object({}) do |v, hash| # $ Hash[String, String]
+              v.gsub!(/\A[\s,]*+|[\s,]*+\Z/, '')
+              next if v.empty?
 
-              v.empty? ? nil : v
-            end
-
-            values.compact!
-            values.each.with_object({}) do |v, hash|
               pair = v.split(':', 2)
               hash[pair[0]] = pair[1]
             end
@@ -196,14 +201,12 @@ module Datadog
           when :array
             values = value.split(',')
 
-            values.map! do |v|
-              v.gsub!(/\A[\s,]*|[\s,]*\Z/, '')
+            values.each_with_object([]) do |v, arr| # $ Array[String]
+              v.gsub!(/\A[\s,]*+|[\s,]*+\Z/, '')
+              next if v.empty?
 
-              v.empty? ? nil : v
+              arr << v
             end
-
-            values.compact!
-            values
           when :bool
             string_value = value.strip
             string_value = string_value.downcase
@@ -277,12 +280,11 @@ module Datadog
         end
 
         # Directly manipulates the current value and currently set precedence.
-        def internal_set(value, precedence, resolved_env)
+        def internal_set(value, precedence)
           old_value = @value
           (@value = context_exec(validate_type(value), old_value, &definition.setter)).tap do |v|
             @is_set = true
             @precedence_set = precedence
-            @resolved_env = resolved_env
             # Store original value to ensure we can always safely call `#internal_set`
             # when restoring a value from `@value_per_precedence`, and we are only running `definition.setter`
             # on the original value, not on a value that has already been processed by `definition.setter`.
@@ -304,54 +306,56 @@ module Datadog
         end
 
         def set_env_value
-          value, resolved_env = get_value_and_resolved_env_from(ENV)
-          set(value, precedence: Precedence::ENVIRONMENT, resolved_env: resolved_env) unless value.nil?
+          value = get_value_from_env
+          set(value, precedence: Precedence::ENVIRONMENT) unless value.nil?
         end
 
         def set_customer_stable_config_value
           customer_config = StableConfig.configuration.dig(:local, :config)
           return if customer_config.nil?
 
-          value, resolved_env = get_value_and_resolved_env_from(customer_config, source: 'local stable config')
-          set(value, precedence: Precedence::LOCAL_STABLE, resolved_env: resolved_env) unless value.nil?
+          value = get_value_from(customer_config, 'local')
+          set(value, precedence: Precedence::LOCAL_STABLE) unless value.nil?
         end
 
         def set_fleet_stable_config_value
           fleet_config = StableConfig.configuration.dig(:fleet, :config)
           return if fleet_config.nil?
 
-          value, resolved_env = get_value_and_resolved_env_from(fleet_config, source: 'fleet stable config')
-          set(value, precedence: Precedence::FLEET_STABLE, resolved_env: resolved_env) unless value.nil?
+          value = get_value_from(fleet_config, 'fleet')
+          set(value, precedence: Precedence::FLEET_STABLE) unless value.nil?
         end
 
-        def get_value_and_resolved_env_from(env_vars, source: 'environment variable')
-          value = nil
-          resolved_env = nil
-
-          if definition.env
-            Array(definition.env).each do |env|
-              next if env_vars[env].nil?
+        def get_value_from_env
+          env = definition.env
+          return unless env
 
-              resolved_env = env
-              value = coerce_env_variable(env_vars[env])
-              break
-            end
-          end
-
-          if value.nil? && definition.deprecated_env && env_vars[definition.deprecated_env]
-            resolved_env = definition.deprecated_env
-            value = coerce_env_variable(env_vars[definition.deprecated_env])
+          value = DATADOG_ENV[env]
+          coerce_env_variable(value) unless value.nil?
+        rescue ArgumentError
+          # This will be raised when the type is set to :int or :float but an invalid env var value is provided.
+          raise ArgumentError,
+            # ArgumentError will be thrown from coerce_env_variable, so we've already checked that env is not nil.
+            # @type var env: String
+            "Expected environment variable #{DATADOG_ENV.resolve_env(env)} " \
+            "to be a #{definition.type}, but '#{value}' was provided."
+        end
 
-            Datadog::Core.log_deprecation do
-              "#{definition.deprecated_env} #{source} is deprecated, use #{definition.env} instead."
-            end
-          end
+        def get_value_from(source_env, source_name)
+          env = definition.env
+          return unless env
 
-          [value, resolved_env]
+          # An instance of ConfigHelper could be used with any Hash but this is the only place where
+          # it's used with something else than ENV, let's keep it simple for now by overriding the source_env parameter.
+          value = DATADOG_ENV.get_environment_variable(env, source_env: source_env)
+          coerce_env_variable(value) unless value.nil?
         rescue ArgumentError
+          # This will be raised when the type is set to :int or :float but an invalid env var value is provided.
           raise ArgumentError,
-            "Expected #{source} #{resolved_env} to be a #{@definition.type}, " \
-                              "but '#{env_vars[resolved_env]}' was provided"
+            # ArgumentError will be thrown from coerce_env_variable, so we've already checked that env is not nil.
+            # @type var env: String
+            "Expected #{source_name} configuration file variable #{DATADOG_ENV.resolve_env(env, source_env: source_env)} " \
+            "to be a #{definition.type}, but '#{value}' was provided."
         end
 
         # Anchor object that represents a value that is not set.

data/lib/datadog/core/configuration/option_definition.rb

@@ -13,7 +13,6 @@ module Datadog
           :default,
           :default_proc,
           :env,
-          :deprecated_env,
           :env_parser,
           :name,
           :after_set,
@@ -22,11 +21,10 @@ module Datadog
           :type,
           :type_options
 
-        def initialize(name, meta = {}, &block)
+        def initialize(name, meta, &block)
           @default = meta[:default]
           @default_proc = meta[:default_proc]
           @env = meta[:env]
-          @deprecated_env = meta[:deprecated_env]
           @env_parser = meta[:env_parser]
           @name = name.to_sym
           @after_set = meta[:after_set]
@@ -44,14 +42,13 @@ module Datadog
         # Acts as DSL for building OptionDefinitions
         # @public_api
         class Builder
-          class InvalidOptionError < StandardError; end
+          InvalidOptionError = Class.new(StandardError)
 
           attr_reader \
             :helpers
 
           def initialize(name, options = {})
             @env = nil
-            @deprecated_env = nil
             @env_parser = nil
             @default = nil
             @default_proc = nil
@@ -75,10 +72,6 @@ module Datadog
             @env = value
           end
 
-          def deprecated_env(value) # standard:disable Style/TrivialAccessors
-            @deprecated_env = value
-          end
-
           # Invoked when the option is first read, and {#env} is defined.
           # The block provided is only invoked if the environment variable is present (not-nil).
           def env_parser(&block)
@@ -123,7 +116,6 @@ module Datadog
             default(options[:default]) if options.key?(:default)
             default_proc(&options[:default_proc]) if options.key?(:default_proc)
             env(options[:env]) if options.key?(:env)
-            deprecated_env(options[:deprecated_env]) if options.key?(:deprecated_env)
             env_parser(&options[:env_parser]) if options.key?(:env_parser)
             after_set(&options[:after_set]) if options.key?(:after_set)
             resetter(&options[:resetter]) if options.key?(:resetter)
@@ -140,7 +132,6 @@ module Datadog
               default: @default,
               default_proc: @default_proc,
               env: @env,
-              deprecated_env: @deprecated_env,
               env_parser: @env_parser,
               after_set: @after_set,
               resetter: @resetter,

data/lib/datadog/core/configuration/options.rb

@@ -40,14 +40,19 @@ module Datadog
 
           def default_helpers(name)
             option_name = name.to_sym
-
+            # @type var opt_getter: Configuration::OptionDefinition::helper_proc
+            opt_getter = proc do
+              # These Procs uses `get/set_option`, but we only add them to the OptionDefinition helpers here.
+              # Steep is right that these methods are not defined, but we only run these Procs in instance context.
+              get_option(option_name) # steep:ignore NoMethod
+            end
+            # @type var opt_setter: Configuration::OptionDefinition::helper_proc
+            opt_setter = proc do |value|
+              set_option(option_name, value) # steep:ignore NoMethod
+            end
             {
-              option_name.to_sym => proc do
-                get_option(option_name)
-              end,
-              :"#{option_name}=" => proc do |value|
-                set_option(option_name, value)
-              end
+              option_name.to_sym => opt_getter,
+              :"#{option_name}=" => opt_setter
             }
           end
 
@@ -68,7 +73,7 @@ module Datadog
           end
 
           def set_option(name, value, precedence: Configuration::Option::Precedence::PROGRAMMATIC)
-            resolve_option(name).set(value, precedence: precedence, resolved_env: resolved_env(name))
+            resolve_option(name).set(value, precedence: precedence)
           end
 
           def unset_option(name, precedence: Configuration::Option::Precedence::PROGRAMMATIC)
@@ -113,13 +118,10 @@ module Datadog
 
             assert_valid_option!(name)
             definition = self.class.options[name]
+            # @type self: Configuration::Options::GenericSettingsClass
             options[name] = definition.build(self)
           end
 
-          def resolved_env(name)
-            options[name].resolved_env if options.key?(name)
-          end
-
           def assert_valid_option!(name)
             raise(InvalidOptionError, "#{self.class.name} doesn't define the option: #{name}") unless option_defined?(name)
           end

data/lib/datadog/core/configuration/settings.rb

@@ -122,8 +122,8 @@ module Datadog
           # @default `DD_TRACE_DEBUG` environment variable, otherwise `false`
           # @return [Boolean]
           option :debug do |o|
-            o.env [Datadog::Core::Configuration::Ext::Diagnostics::ENV_DEBUG_ENABLED,
-              Datadog::Core::Configuration::Ext::Diagnostics::ENV_OTEL_LOG_LEVEL]
+            # Note: Alias (OTEL_LOG_LEVEL) defined in supported-configurations.json
+            o.env Datadog::Core::Configuration::Ext::Diagnostics::ENV_DEBUG_ENABLED
             o.default false
             o.type :bool
             o.env_parser do |value|
@@ -212,6 +212,7 @@ module Datadog
           # Log level for `Datadog.logger`.
           # @see Logger::Severity
           # @return Logger::Severity
+          # TODO: Add environment variable for this `DD_TRACE_LOG_LEVEL`
           option :level, default: ::Logger::INFO
         end
 
@@ -485,7 +486,7 @@ module Datadog
             # @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'
+              # Note: Deprecated alias (DD_PROFILING_PREVIEW_GVL_ENABLED) defined in supported-configurations.json
               o.env 'DD_PROFILING_GVL_ENABLED'
               o.default true
             end
@@ -604,7 +605,8 @@ module Datadog
 
           option :experimental_runtime_id_enabled do |o|
             o.type :bool
-            o.env ['DD_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED', 'DD_RUNTIME_METRICS_RUNTIME_ID_ENABLED']
+            # Note: Alias (DD_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED) defined in supported-configurations.json
+            o.env 'DD_RUNTIME_METRICS_RUNTIME_ID_ENABLED'
             o.default false
           end
 
@@ -620,7 +622,8 @@ module Datadog
           o.type :string, nilable: true
 
           # NOTE: service also gets set as a side effect of tags. See the WORKAROUND note in #initialize for details.
-          o.env [Core::Environment::Ext::ENV_SERVICE, Core::Environment::Ext::ENV_OTEL_SERVICE]
+          # Note: Alias (OTEL_SERVICE_NAME) defined in supported-configurations.json
+          o.env Core::Environment::Ext::ENV_SERVICE
           o.default Core::Environment::Ext::FALLBACK_SERVICE_NAME
 
           # There's a few cases where we don't want to use the fallback service name, so this helper allows us to get a
@@ -655,7 +658,8 @@ module Datadog
         # @return [Hash<String,String>]
         option :tags do |o|
           o.type :hash, nilable: true
-          o.env [Core::Environment::Ext::ENV_TAGS, Core::Environment::Ext::ENV_OTEL_RESOURCE_ATTRIBUTES]
+          # Note: Alias (OTEL_RESOURCE_ATTRIBUTES) defined in supported-configurations.json
+          o.env Core::Environment::Ext::ENV_TAGS
           o.env_parser do |env_value|
             # Parses a string containing key-value pairs and returns a hash.
             # Key-value pairs are delimited by ':' OR `=`, and pairs are separated by whitespace, comma, OR BOTH.