Merge pull request #2454 from DataDog/b3-deprecation-warning

docs/GettingStarted.md

@@ -2078,8 +2078,8 @@ end
 | `telemetry.enabled`                                     | `DD_INSTRUMENTATION_TELEMETRY_ENABLED` | `false`                                                             | Allows you to enable sending telemetry data to Datadog. In a future release, we will be setting this to  `true` by default, as documented [here](https://docs.datadoghq.com/tracing/configure_data_security/#telemetry-collection).                                                                                                                                                                                          |
 | **Tracing**                                             |                                |                                                                   |                                                                                                                                                                                                                                           |
 | `tracing.analytics.enabled`                             | `DD_TRACE_ANALYTICS_ENABLED`   | `nil`                                                             | Enables or disables trace analytics. See [Sampling](#sampling) for more details.                                                                                                                                                          |
-| `tracing.distributed_tracing.propagation_extract_style` | `DD_PROPAGATION_STYLE_EXTRACT` | `['Datadog','B3','B3 single header']`                             | Distributed tracing header formats to extract. See [Distributed Tracing](#distributed-tracing) for more details.                                                                                                                          |
-| `tracing.distributed_tracing.propagation_inject_style`  | `DD_PROPAGATION_STYLE_INJECT`  | `['Datadog']`                                                     | Distributed tracing header formats to inject. See [Distributed Tracing](#distributed-tracing) for more details.                                                                                                                           |
+| `tracing.distributed_tracing.propagation_extract_style` | `DD_TRACE_PROPAGATION_STYLE_EXTRACT` | `['Datadog','b3multi','b3']` | Distributed tracing header formats to extract. See [Distributed Tracing](#distributed-tracing) for more details.|
+| `tracing.distributed_tracing.propagation_inject_style`  | `DD_TRACE_PROPAGATION_STYLE_INJECT`  | `['Datadog']`                                                     | Distributed tracing header formats to inject. See [Distributed Tracing](#distributed-tracing) for more details.                                                                                                                           |
 | `tracing.enabled`                                       | `DD_TRACE_ENABLED`             | `true`                                                            | Enables or disables tracing. If set to `false` instrumentation will still run, but no traces are sent to the trace agent.                                                                                                                 |
 | `tracing.instrument(<integration-name>, <options...>)`  |                                |                                                                   | Activates instrumentation for a specific library. See [Integration instrumentation](#integration-instrumentation) for more details.                                                                                                       |
 | `tracing.log_injection`                                 | `DD_LOGS_INJECTION`            | `true`                                                            | Injects [Trace Correlation](#trace-correlation) information into Rails logs if present. Supports the default logger (`ActiveSupport::TaggedLogging`), `lograge`, and `semantic_logger`.                                                   |

docs/UpgradeGuide.md

@@ -694,7 +694,7 @@ end
 | Configuration                         | Changed  | Many settings have been namespaced under specific categories                                                        | Update your configuration to these [new settings](#1.0-configuration-settings) where appropriate.                                                                         |
 | Configuration                         | Removed  | `Datadog.configure(client, options)`                                                                                | Use `Datadog.configure_onto(client, options)` instead.                                                                                                           |
 | Configuration                         | Removed  | `DD_#{integration}_ANALYTICS_ENABLED` and `DD_#{integration}_ANALYTICS_SAMPLE_RATE` environment variables           | Use `DD_TRACE_#{integration}_ANALYTICS_ENABLED` and `DD_TRACE_#{integration}_ANALYTICS_SAMPLE_RATE` instead.                                                              |
-| Configuration                         | Removed  | `DD_PROPAGATION_INJECT_STYLE` and `DD_PROPAGATION_EXTRACT_STYLE` environment variables                              | Use `DD_PROPAGATION_STYLE_INJECT` and `DD_PROPAGATION_STYLE_EXTRACT` instead.                                                                                             |
+| Configuration                         | Removed  | `DD_PROPAGATION_INJECT_STYLE` and `DD_PROPAGATION_EXTRACT_STYLE` environment variables                              | Use `DD_TRACE_PROPAGATION_STYLE_INJECT` and `DD_TRACE_PROPAGATION_STYLE_EXTRACT` instead.                                                                                             |
 | Integrations                          | Changed  | `-` in HTTP header tag names are kept, and no longer replaced with `_`                                              | For example: `http.response.headers.content_type` is changed to `http.response.headers.content-type`.                                                                     |
 | Integrations                          | Changed  | `Contrib::Configurable#default_configuration` moved to `Tracing::Contrib::Configurable#new_configuration`           | Use `Tracing::Contrib::Configurable#new_configuration` instead.                                                                                                           |
 | Integrations                          | Changed  | `Datadog.configuration.registry` moved to `Datadog.registry`                                                        | Use `Datadog.registry` instead.                                                                                                                                           |

lib/datadog/core.rb

@@ -1,4 +1,5 @@
-# typed: strict
+# frozen_string_literal: true
+# typed: true
 
 require_relative 'core/extensions'
 
@@ -9,6 +10,25 @@ module Datadog
   # products. It is a dependency of each product. Contrast with Datadog::Kit
   # for higher-level features.
   module Core
+    class << self
+      # Records the occurrence of a deprecated operation in this library.
+      #
+      # Currently, these operations are logged to `Datadog.logger` at `warn` level.
+      #
+      # `disallowed_next_major` adds a message informing that the deprecated operation
+      # won't be allowed in the next major release.
+      #
+      # @yieldreturn [String] a String with the lazily evaluated deprecation message.
+      # @param [Boolean] disallowed_next_major whether this deprecation will be enforced in the next major release.
+      def log_deprecation(disallowed_next_major: true)
+        Datadog.logger.warn do
+          message = yield
+          message += ' This will be enforced in the next major release.' if disallowed_next_major
+          message
+        end
+        nil
+      end
+    end
   end
 
   extend Core::Extensions

lib/datadog/core/configuration/settings.rb

@@ -431,8 +431,8 @@ def initialize(*_)
           #
           # The supported formats are:
           # * `Datadog`: Datadog propagation format, described by [Distributed Tracing](https://docs.datadoghq.com/tracing/setup_overview/setup/ruby/#distributed-tracing).
-          # * `B3`: B3 Propagation using multiple headers, described by [openzipkin/b3-propagation](https://github.com/openzipkin/b3-propagation#multiple-headers).
-          # * `B3 single header`: B3 Propagation using a single header, described by [openzipkin/b3-propagation](https://github.com/openzipkin/b3-propagation#single-header).
+          # * `b3multi`: B3 Propagation using multiple headers, described by [openzipkin/b3-propagation](https://github.com/openzipkin/b3-propagation#multiple-headers).
+          # * `b3`: B3 Propagation using a single header, described by [openzipkin/b3-propagation](https://github.com/openzipkin/b3-propagation#single-header).
           #
           # @public_api
           settings :distributed_tracing do
@@ -442,23 +442,40 @@ def initialize(*_)
             # The tracer will try to find distributed headers in the order they are present in the list provided to this option.
             # The first format to have valid data present will be used.
             #
-            # @default `DD_PROPAGATION_STYLE_EXTRACT` environment variable (comma-separated list),
-            #   otherwise `['Datadog','B3','B3 single header']`.
+            # @default `DD_TRACE_PROPAGATION_STYLE_EXTRACT` environment variable (comma-separated list),
+            #   otherwise `['Datadog','b3multi','b3']`.
             # @return [Array<String>]
             option :propagation_extract_style do |o|
               o.default do
+                # DEV-2.0: Change default value to `tracecontext, Datadog`.
                 # Look for all headers by default
                 env_to_list(
-                  Tracing::Configuration::Ext::Distributed::ENV_PROPAGATION_STYLE_EXTRACT,
+                  [Tracing::Configuration::Ext::Distributed::ENV_PROPAGATION_STYLE_EXTRACT,
+                   Tracing::Configuration::Ext::Distributed::ENV_PROPAGATION_STYLE_EXTRACT_OLD],
                   [
                     Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG,
-                    Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3,
+                    Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_MULTI_HEADER,
                     Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_SINGLE_HEADER
                   ],
                   comma_separated_only: true
                 )
               end
 
+              o.on_set do |styles|
+                # Modernize B3 options
+                # DEV-2.0: Can be removed with the removal of deprecated B3 constants.
+                styles.map! do |style|
+                  case style
+                  when Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3
+                    Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_MULTI_HEADER
+                  when Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_SINGLE_HEADER_OLD
+                    Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_SINGLE_HEADER
+                  else
+                    style
+                  end
+                end
+              end
+
               o.lazy
             end
 
@@ -467,17 +484,34 @@ def initialize(*_)
             #
             # The tracer will inject data from all styles specified in this option.
             #
-            # @default `DD_PROPAGATION_STYLE_INJECT` environment variable (comma-separated list), otherwise `['Datadog']`.
+            # @default `DD_TRACE_PROPAGATION_STYLE_INJECT` environment variable (comma-separated list), otherwise `['Datadog']`.
             # @return [Array<String>]
             option :propagation_inject_style do |o|
               o.default do
+                # DEV-2.0: Change default value to `tracecontext, Datadog`.
                 env_to_list(
-                  Tracing::Configuration::Ext::Distributed::ENV_PROPAGATION_STYLE_INJECT,
+                  [Tracing::Configuration::Ext::Distributed::ENV_PROPAGATION_STYLE_INJECT,
+                   Tracing::Configuration::Ext::Distributed::ENV_PROPAGATION_STYLE_INJECT_OLD],
                   [Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG],
                   comma_separated_only: true # Only inject Datadog headers by default
                 )
               end
 
+              o.on_set do |styles|
+                # Modernize B3 options
+                # DEV-2.0: Can be removed with the removal of deprecated B3 constants.
+                styles.map! do |style|
+                  case style
+                  when Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3
+                    Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_MULTI_HEADER
+                  when Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_SINGLE_HEADER_OLD
+                    Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_SINGLE_HEADER
+                  else
+                    style
+                  end
+                end
+              end
+
               o.lazy
             end
           end

lib/datadog/core/environment/variable_helpers.rb

@@ -9,18 +9,45 @@ module Environment
       module VariableHelpers
         extend self
 
-        def env_to_bool(var, default = nil)
-          var = decode_array(var)
+        # Reads an environment variable as a Boolean.
+        #
+        # @param [String] var environment variable
+        # @param [Array<String>] var list of environment variables
+        # @param [Boolean] default the default value if the keys in `var` are not present in the environment
+        # @param [Boolean] deprecation_warning when `var` is a list, record a deprecation log when
+        #   the first key in `var` is not used.
+        # @return [Boolean] if the environment value is the string `true`
+        # @return [default] if the environment value is not found
+        def env_to_bool(var, default = nil, deprecation_warning: true)
+          var = decode_array(var, deprecation_warning)
           var && ENV.key?(var) ? ENV[var].to_s.strip.downcase == 'true' : default
         end
 
-        def env_to_int(var, default = nil)
-          var = decode_array(var)
+        # Reads an environment variable as an Integer.
+        #
+        # @param [String] var environment variable
+        # @param [Array<String>] var list of environment variables
+        # @param [Integer] default the default value if the keys in `var` are not present in the environment
+        # @param [Boolean] deprecation_warning when `var` is a list, record a deprecation log when
+        #   the first key in `var` is not used.
+        # @return [Integer] if the environment value is a valid Integer
+        # @return [default] if the environment value is not found
+        def env_to_int(var, default = nil, deprecation_warning: true)
+          var = decode_array(var, deprecation_warning)
           var && ENV.key?(var) ? ENV[var].to_i : default
         end
 
-        def env_to_float(var, default = nil)
-          var = decode_array(var)
+        # Reads an environment variable as a Float.
+        #
+        # @param [String] var environment variable
+        # @param [Array<String>] var list of environment variables
+        # @param [Float] default the default value if the keys in `var` are not present in the environment
+        # @param [Boolean] deprecation_warning when `var` is a list, record a deprecation log when
+        #   the first key in `var` is not used.
+        # @return [Float] if the environment value is a valid Float
+        # @return [default] if the environment value is not found
+        def env_to_float(var, default = nil, deprecation_warning: true)
+          var = decode_array(var, deprecation_warning)
           var && ENV.key?(var) ? ENV[var].to_f : default
         end
 
@@ -33,8 +60,16 @@ def env_to_float(var, default = nil)
         # either trailing or leading are trimmed.
         #
         # Empty entries, after trimmed, are also removed from the result.
-        def env_to_list(var, default = [], comma_separated_only:)
-          var = decode_array(var)
+        #
+        # @param [String] var environment variable
+        # @param [Array<String>] var list of environment variables
+        # @param [Array<Object>] default the default value if the keys in `var` are not present in the environment
+        # @param [Boolean] deprecation_warning when `var` is a list, record a deprecation log when
+        #   the first key in `var` is not used.
+        # @return [Array<Object>] if the environment value is a valid list
+        # @return [default] if the environment value is not found
+        def env_to_list(var, default = [], comma_separated_only:, deprecation_warning: true)
+          var = decode_array(var, deprecation_warning)
           if var && ENV.key?(var)
             value = ENV[var]
 
@@ -59,8 +94,21 @@ def env_to_list(var, default = [], comma_separated_only:)
 
         private
 
-        def decode_array(var)
-          var.is_a?(Array) ? var.find { |env_var| ENV.key?(env_var) } : var
+        def decode_array(var, deprecation_warning)
+          if var.is_a?(Array)
+            var.find.with_index do |env_var, i|
+              found = ENV.key?(env_var)
+
+              # Check if we are using a non-preferred environment variable
+              if deprecation_warning && found && i != 0
+                Datadog::Core.log_deprecation { "#{env_var} environment variable is deprecated, use #{var.first} instead." }
+              end
+
+              found
+            end
+          else
+            var
+          end
         end
       end
     end

lib/datadog/tracing/configuration/ext.rb

@@ -18,11 +18,37 @@ module Correlation
 
         # @public_api
         module Distributed
+          # Custom Datadog format
           PROPAGATION_STYLE_DATADOG = 'Datadog'.freeze
+
+          PROPAGATION_STYLE_B3_MULTI_HEADER = 'b3multi'.freeze
+          # @deprecated Use `b3multi` instead.
           PROPAGATION_STYLE_B3 = 'B3'.freeze
-          PROPAGATION_STYLE_B3_SINGLE_HEADER = 'B3 single header'.freeze
-          ENV_PROPAGATION_STYLE_INJECT = 'DD_PROPAGATION_STYLE_INJECT'.freeze
-          ENV_PROPAGATION_STYLE_EXTRACT = 'DD_PROPAGATION_STYLE_EXTRACT'.freeze
+
+          PROPAGATION_STYLE_B3_SINGLE_HEADER = 'b3'.freeze
+          # @deprecated Use `b3` instead.
+          PROPAGATION_STYLE_B3_SINGLE_HEADER_OLD = 'B3 single header'.freeze
+
+          # W3C Trace Context
+          PROPAGATION_STYLE_TRACE_CONTEXT = 'tracecontext'.freeze
+
+          # Sets both extract and inject propagation style tho the provided value.
+          # Has lower precedence than `DD_TRACE_PROPAGATION_STYLE_INJECT` or
+          # `DD_TRACE_PROPAGATION_STYLE_EXTRACT`.
+          ENV_PROPAGATION_STYLE_EXTRACT = 'DD_TRACE_PROPAGATION_STYLE'.freeze
+
+          ENV_PROPAGATION_STYLE_INJECT = 'DD_TRACE_PROPAGATION_STYLE_INJECT'.freeze
+          # @deprecated Use `DD_TRACE_PROPAGATION_STYLE_INJECT` instead.
+          ENV_PROPAGATION_STYLE_INJECT_OLD = 'DD_PROPAGATION_STYLE_INJECT'.freeze
+
+          ENV_PROPAGATION_STYLE_EXTRACT = 'DD_TRACE_PROPAGATION_STYLE_EXTRACT'.freeze
+          # @deprecated Use `DD_TRACE_PROPAGATION_STYLE_EXTRACT` instead.
+          ENV_PROPAGATION_STYLE_EXTRACT_OLD = 'DD_PROPAGATION_STYLE_EXTRACT'.freeze
+
+          # A no-op propagator. Compatible with OpenTelemetry's `none` propagator.
+          # @see https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_propagators
+          PROPAGATION_STYLE_NONE = 'none'.freeze
+
           ENV_X_DATADOG_TAGS_MAX_LENGTH = 'DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH'.freeze
         end