From a08700a2b66eac4ab697276d2d119aa464dd3765 Mon Sep 17 00:00:00 2001
From: Munir Abdinur <munir.abdinur@datadoghq.com>
Date: Fri, 7 Jun 2024 16:21:07 -0400
Subject: [PATCH] Improve documentation for otel values

---
 lib/datadog/core/configuration/settings.rb    | 5 ++++-
 lib/datadog/tracing/configuration/settings.rb | 6 ++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/lib/datadog/core/configuration/settings.rb b/lib/datadog/core/configuration/settings.rb
index 0b5efb30c5d..dd91ed4651a 100644
--- a/lib/datadog/core/configuration/settings.rb
+++ b/lib/datadog/core/configuration/settings.rb
@@ -129,6 +129,8 @@ def initialize(*_)
             o.env_parser do |value|
               if value
                 value = value.strip.downcase
+                # Debug is enabled when DD_TRACE_DEBUG is true or 1 OR
+                # when OTEL_LOG_LEVEL is set to debug
                 ['true', '1', 'debug'].include?(value)
               end
             end
@@ -524,11 +526,12 @@ def initialize(*_)
             values.each_with_object({}) do |tag, tags|
               key, value = tag.split(':', 2)
               if value.nil?
-                # tags following the Opentelemetry spec are in the format key=value
+                # support tags/attributes delimited by the OpenTelemetry separator (`=`)
                 key, value = tag.split('=', 2)
               end
               next if value.nil? || value.empty?
 
+              # maps OpenTelemetry semantic attributes to Datadog tags
               case key.downcase
               when 'deployment.environment'
                 tags['env'] = value
diff --git a/lib/datadog/tracing/configuration/settings.rb b/lib/datadog/tracing/configuration/settings.rb
index 60dd3147f36..4b94b6d9eeb 100644
--- a/lib/datadog/tracing/configuration/settings.rb
+++ b/lib/datadog/tracing/configuration/settings.rb
@@ -136,8 +136,11 @@ def self.extended(base)
                 o.type :bool
                 o.env_parser do |value|
                   value = value&.downcase
+                  # Tracing is disabled when OTEL_TRACES_EXPORTER is none or
+                  # DD_TRACE_ENABLED is 0 or false.
                   if ['none', 'false', '0'].include?(value)
                     false
+                  # Tracing is enabled when DD_TRACE_ENABLED is true or 1
                   elsif ['true', '1'].include?(value)
                     true
                   else
@@ -276,6 +279,9 @@ def self.extended(base)
                       Datadog.logger.warn("The value '#{value}' is not yet supported. 'parentbased_#{value}' will be used instead.")
                       value = "parentbased_#{value}"
                     end
+                    # OTEL_TRACES_SAMPLER can be set to always_on, always_off, traceidratio, and/or parentbased value.
+                    # These values are mapped to a sample rate.
+                    # DD_TRACE_SAMPLE_RATE sets the sample rate to float.
                     case value
                     when 'parentbased_always_on'
                       1.0