Change supported-configurations.json to v2 format

Author: vpellan

docs/AccessEnvironmentVariables.md

@@ -72,36 +72,29 @@ Edit the `supported-configurations.json` file and add your variable (Please keep
 ```json
 {
   "supportedConfigurations": {
-    "DD_YOUR_NEW_VARIABLE": {
-      "version": ["A"]
-    }
+    "DD_YOUR_NEW_VARIABLE": [
+      {
+        "version": "A",
+        "type": "boolean",
+        "propertyKeys": ["tracing.new_variable"],
+        "defaultValue": "true", # optional, default value in string format that will be parsed
+        "aliases": ["DD_ALIAS_1", "DD_ALIAS_2"], # optional, these env vars can be set, but not used in dd-trace-rb code
+        "deprecated": true, # optional, true | false, will log a deprecation message if the env var is set
+      }
+    ]
   }
 }
 ```
 
 #### Configuration Structure
 
-- **supportedConfigurations**: Maps variable names to configuration metadata
-  - `version`: (Defaults to `["A"]`) Array indicating which implementations the tracer supports. Implementations are defined in the Configuration Registry and multiple implementations could be set for a single environment variable (e.g. the base one `A`, and an extra one `B` that adds new possible values). Versions are non-numeric to avoid confusion with library versions.
-
-  In the future, the structure will also contain more information such as the type, the default value...
-
-- **aliases**: Maps canonical variable names to arrays of alias names
-
-  ```json
-  "aliases": {
-    "DD_SERVICE": ["OTEL_SERVICE_NAME"]
-  }
-  ```
-
-- **deprecations**: Adds a log message to deprecated environment variables.
-
-  ```json
-  "deprecations": {
-    "DD_OLD_VARIABLE": "Please use DD_NEW_VARIABLE",
-    "DD_REMOVED_VARIABLE": "This feature will be removed in the next release"
-  }
-  ```
+- **supportedConfigurations**: Maps variable names to configuration metadata. For now, we only support a single version per configuration but it is an array for future usage.
+  - `version`: String indicating which implementations the tracer supports. Implementations are defined in the Configuration Registry. Versions are non-numeric to avoid confusion with library versions.
+  - `type`: Optional, one of `boolean | int | float | string | array | map`. Indicates the type of the configuration value. This will tells the parser how to parse the environment variable value.
+  - `propertyKeys`: Optional, array containing a single value, the path to access the configuration from `Datadog.configuration`. This is an array for future usage.
+  - `defaultValue`: Optional, the default value, as a string, that will be parsed like an environment variable value.
+  - `aliases`: Optional, maps the config to an array of alias names. These environment variables should not be used in dd-trace-rb code. These aliases are by default considered deprecated. To accept non-deprecated environment variables, you must also add them as a separate configuration.
+  - `deprecated`: Optional, true | false, adds a log message to deprecated environment variables.
 
 ### Step 2: Generate Configuration Assets
 

lib/datadog/core/configuration/supported_configurations.rb

@@ -6,14 +6,14 @@ module Datadog
 
         @source_env: env_hash
         @raise_on_unknown_env_var: bool
-        @supported_configurations: Hash[String, config]
+        @supported_configurations: Hash[String, configs]
         @aliases: Hash[String, Array[String]]
         @deprecations: Hash[String, String]
         @alias_to_canonical: Hash[String, String]
 
         def initialize: (
           ?source_env: env_hash,
-          ?supported_configurations: Hash[String, config],
+          ?supported_configurations: Hash[String, configs],
           ?aliases: Hash[String, Array[String]],
           ?alias_to_canonical: Hash[String, String],
           ?raise_on_unknown_env_var: bool

sig/datadog/core/configuration/config_helper.rbs

@@ -2,11 +2,12 @@ module Datadog
   module Core
     module Configuration
       type env_var_name = String
-      type config = Hash[Symbol, Array[String]]
+      type configs = Array[config]
+      type config = Hash[Symbol, String | Array[String | nil] | nil]
 
-      SUPPORTED_CONFIGURATIONS: Hash[env_var_name, config]
+      SUPPORTED_CONFIGURATIONS: Hash[env_var_name, configs]
       ALIASES: Hash[env_var_name, Array[env_var_name]]
-      DEPRECATIONS: Hash[env_var_name, String]
+      DEPRECATIONS: Array[env_var_name]
       ALIAS_TO_CANONICAL: Hash[env_var_name, env_var_name]
     end
   end

sig/datadog/core/configuration/supported_configurations.rbs

@@ -7,23 +7,41 @@
   describe 'consistency validation' do
     it 'validates that the generated data matches the JSON file' do
       json_data = JSON.parse(File.read('supported-configurations.json')).transform_keys(&:to_sym)
-      json_data[:supportedConfigurations].each_value { |config| config.transform_keys!(&:to_sym) }
-      alias_to_canonical = json_data[:aliases].each_with_object({}) do |(canonical, alias_list), h|
-        alias_list.each do |alias_name|
-          raise "The alias #{alias_name} is already used for #{h[alias_name]}." if h[alias_name]
+      aliases = {}
+      deprecations = Set.new
+      alias_to_canonical = {}
+      supported_configurations = json_data[:supportedConfigurations].each.with_object({}) do |(name, configs), h|
+        configs.each do |config|
+          config.transform_keys!(&:to_sym)
+          config[:aliases]&.each do |alias_name|
+            aliases[name] ||= []
+            aliases[name] << alias_name
+            alias_to_canonical[alias_name] = name
 
-          h[alias_name] = canonical
+            # If an alias is not registered as its own config, it is by default deprecated
+            deprecations.add(alias_name) unless json_data.dig(:supportedConfigurations, alias_name)
+          end
+          # Add deprecated configs with no replacement provided
+          deprecations.add(name) if config[:deprecations]
+          config.delete(:aliases)
+          config.delete(:deprecations)
         end
+        h[name] = configs
       end
 
       error_message = <<~ERROR_MESSAGE
         Configuration map mismatch between the JSON file and the generated file, please run `rake local_config_map:generate` and commit the changes.
         Please refer to `docs/AccessEnvironmentVariables.md` for more information.
       ERROR_MESSAGE
 
-      expect(json_data[:supportedConfigurations]).to eq(Datadog::Core::Configuration::SUPPORTED_CONFIGURATIONS), error_message
-      expect(json_data[:aliases]).to eq(Datadog::Core::Configuration::ALIASES), error_message
-      expect(json_data[:deprecations]).to eq(Datadog::Core::Configuration::DEPRECATIONS), error_message
+      expect(supported_configurations).to eq(Datadog::Core::Configuration::SUPPORTED_CONFIGURATIONS), error_message
+      # check order of the keys
+      expect(supported_configurations.keys).to eq(Datadog::Core::Configuration::SUPPORTED_CONFIGURATIONS.keys),
+        "The keys in supported-configurations.json are not correctly sorted. Please keep the keys sorted alphabetically."
+
+      # no need to check the order for these as they don't appear in the JSON file
+      expect(aliases).to eq(Datadog::Core::Configuration::ALIASES), error_message
+      expect(deprecations.to_a.sort).to eq(Datadog::Core::Configuration::DEPRECATIONS), error_message
       expect(alias_to_canonical).to eq(Datadog::Core::Configuration::ALIAS_TO_CANONICAL), error_message
     end
   end