chore(tracing): add tracing_instrumentations and tracing_sampling_rate in kong.conf, deprecate opentelemetry_* (#10122)

KAG-446

Co-authored-by: Wangchong Zhou <[email protected]>

Author: mayocream

kong.conf.default

@@ -103,34 +103,37 @@
                                  # such in the Lua namespace:
                                  # `kong.vaults.{name}.*`.
 
-#opentelemetry_tracing = off     # Comma-separated list of tracing instrumentations
-                                 # this node should load. By default, no instrumentations
-                                 # are enabled.
-                                 #
-                                 # Valid values to this setting are:
-                                 #
-                                 # - `off`: do not enable instrumentations.
-                                 # - `request`: only enable request-level instrumentations.
-                                 # - `all`: enable all the following instrumentations.
-                                 # - `db_query`: trace database query, including
-                                 #   Postgres and Cassandra.
-                                 # - `dns_query`: trace DNS query.
-                                 # - `router`: trace router execution, including
-                                 #   router rebuilding.
-                                 # - `http_client`: trace OpenResty HTTP client requests.
-                                 # - `balancer`: trace balancer retries.
-                                 # - `plugin_rewrite`: trace plugins iterator
-                                 #   execution with rewrite phase.
-                                 # - `plugin_access`: trace plugins iterator
-                                 #   execution with access phase.
-                                 # - `plugin_header_filter`: trace plugins iterator
-                                 #   execution with header_filter phase.
-                                 #
-                                 # **Note:** In the current implementation,
-                                 # tracing instrumentations are not enabled in
-                                 # stream mode.
-
-#opentelemetry_tracing_sampling_rate = 1.0  # Tracing instrumentation sampling rate.
+#opentelemetry_tracing = off                # Deprecated: use tracing_instrumentatios instead
+
+#tracing_instrumentations = off             # Comma-separated list of tracing instrumentations
+                                            # this node should load. By default, no instrumentations
+                                            # are enabled.
+                                            #
+                                            # Valid values to this setting are:
+                                            #
+                                            # - `off`: do not enable instrumentations.
+                                            # - `request`: only enable request-level instrumentations.
+                                            # - `all`: enable all the following instrumentations.
+                                            # - `db_query`: trace database query, including
+                                            #   Postgres and Cassandra.
+                                            # - `dns_query`: trace DNS query.
+                                            # - `router`: trace router execution, including
+                                            #   router rebuilding.
+                                            # - `http_client`: trace OpenResty HTTP client requests.
+                                            # - `balancer`: trace balancer retries.
+                                            # - `plugin_rewrite`: trace plugins iterator
+                                            #   execution with rewrite phase.
+                                            # - `plugin_access`: trace plugins iterator
+                                            #   execution with access phase.
+                                            # - `plugin_header_filter`: trace plugins iterator
+                                            #   execution with header_filter phase.
+                                            #
+                                            # **Note:** In the current implementation,
+                                            # tracing instrumentations are not enabled in
+                                            # stream mode.
+
+#opentelemetry_tracing_sampling_rate = 1.0  # Deprecated: use tracing_sampling_rate instead
+#tracing_sampling_rate = 1.0                # Tracing instrumentation sampling rate.
                                             # Tracer samples a fixed percentage of all spans
                                             # following the sampling rate.
                                             #

kong/conf_loader/init.lua

@@ -547,8 +547,18 @@ local CONF_PARSERS = {
   lmdb_environment_path = { typ = "string" },
   lmdb_map_size = { typ = "string" },
 
-  opentelemetry_tracing = { typ = "array" },
-  opentelemetry_tracing_sampling_rate = { typ = "number" },
+  tracing_instrumentations= {
+    typ = "array",
+    deprecated = {
+      replacement = "opentelemetry_tracing",
+    },
+  },
+  tracing_sampling_rate = {
+    typ = "number",
+    deprecated = {
+      replacement = "opentelemetry_tracing_sampling_rate",
+    },
+  },
 
   proxy_server = { typ = "string" },
   proxy_server_ssl_verify = { typ = "boolean" },
@@ -1174,27 +1184,27 @@ local function check_and_parse(conf, opts)
     errors[#errors + 1] = "upstream_keepalive_idle_timeout must be 0 or greater"
   end
 
-  if conf.opentelemetry_tracing and #conf.opentelemetry_tracing > 0 then
+  if conf.tracing_instrumentations and #conf.tracing_instrumentations > 0 then
     local instrumentation = require "kong.tracing.instrumentation"
     local available_types_map = tablex.deepcopy(instrumentation.available_types)
     available_types_map["all"] = true
     available_types_map["off"] = true
     available_types_map["request"] = true
 
-    for _, trace_type in ipairs(conf.opentelemetry_tracing) do
+    for _, trace_type in ipairs(conf.tracing_instrumentations) do
       if not available_types_map[trace_type] then
         errors[#errors + 1] = "invalid opentelemetry tracing type: " .. trace_type
       end
     end
 
-    if #conf.opentelemetry_tracing > 1
-      and tablex.find(conf.opentelemetry_tracing, "off")
+    if #conf.tracing_instrumentations > 1
+      and tablex.find(conf.tracing_instrumentations, "off")
     then
       errors[#errors + 1] = "invalid opentelemetry tracing types: off, other types are mutually exclusive"
     end
 
-    if conf.opentelemetry_tracing_sampling_rate < 0 or conf.opentelemetry_tracing_sampling_rate > 1 then
-      errors[#errors + 1] = "opentelemetry_tracing_sampling_rate must be between 0 and 1"
+    if conf.tracing_sampling_rate < 0 or conf.tracing_sampling_rate > 1 then
+      errors[#errors + 1] = "tracing_sampling_rate must be between 0 and 1"
     end
   end
 

kong/globalpatches.lua

@@ -463,7 +463,7 @@ return function(options)
 
       -- DNS query is lazily patched, it will only be wrapped
       -- when instrumentation module is initialized later and
-      -- `opentelemetry_tracing` includes "dns_query" or set
+      -- `tracing_instrumentations` includes "dns_query" or set
       -- to "all".
       local instrumentation = require "kong.tracing.instrumentation"
       instrumentation.set_patch_dns_query_fn(toip, function(wrap)

kong/templates/kong_defaults.lua

@@ -190,4 +190,6 @@ openresty_path =
 
 opentelemetry_tracing = off
 opentelemetry_tracing_sampling_rate = 1.0
+tracing_instrumentations = off
+tracing_sampling_rate = 1.0
 ]]

kong/tracing/instrumentation.lua

@@ -335,8 +335,8 @@ function _M.runloop_log_after(ctx)
 end
 
 function _M.init(config)
-  local trace_types = config.opentelemetry_tracing
-  local sampling_rate = config.opentelemetry_tracing_sampling_rate
+  local trace_types = config.tracing_instrumentations
+  local sampling_rate = config.tracing_sampling_rate
   assert(type(trace_types) == "table" and next(trace_types))
   assert(sampling_rate >= 0 and sampling_rate <= 1)
 

spec/02-integration/14-tracing/01-instrumentations_spec.lua

@@ -38,7 +38,7 @@ for _, strategy in helpers.each_strategy() do
         database = strategy,
         nginx_conf = "spec/fixtures/custom_nginx.template",
         plugins = "tcp-trace-exporter",
-        opentelemetry_tracing = types,
+        tracing_instrumentations = types,
       })
 
       proxy_client = helpers.proxy_client()

spec/03-plugins/37-opentelemetry/04-exporter_spec.lua

@@ -91,7 +91,7 @@ for _, strategy in helpers.each_strategy() do
         database = strategy,
         nginx_conf = "spec/fixtures/custom_nginx.template",
         plugins = "opentelemetry",
-        opentelemetry_tracing = types,
+        tracing_instrumentations = types,
       }, nil, nil, fixtures))
     end
 

spec/03-plugins/37-opentelemetry/05-otelcol_spec.lua

@@ -47,7 +47,7 @@ for _, strategy in helpers.each_strategy() do
         database = strategy,
         nginx_conf = "spec/fixtures/custom_nginx.template",
         plugins = "opentelemetry",
-        opentelemetry_tracing = types,
+        tracing_instrumentations = types,
       })
 
       proxy_url = fmt("http://%s:%s", helpers.get_proxy_ip(), helpers.get_proxy_port())