Implement endpoint renaming

Author: cataphract

dd-trace-cpp

@@ -107,6 +107,15 @@ struct datadog_main_conf_t {
   // `agent_url` is set by the `datadog_agent_url` directive.
   std::optional<std::string> agent_url;
 
+  // DD_APM_RESOURCE_RENAMING_ENABLED
+  // Whether generation of http.endpoint is enabled.
+  ngx_flag_t resource_renaming_enabled{NGX_CONF_UNSET};
+
+  // DD_APM_RESOURCE_RENAMING_ALWAYS_SIMPLIFIED_ENDPOINT
+  // Whether http.endpoint is always calculated, even when http.route is
+  // present.
+  ngx_flag_t resource_renaming_always_simplified_endpoint{NGX_CONF_UNSET};
+
 #ifdef WITH_WAF
   // DD_APPSEC_ENABLED
   ngx_flag_t appsec_enabled{NGX_CONF_UNSET};

src/datadog_conf.h

@@ -165,6 +165,25 @@ constexpr datadog::nginx::directive tracing_directives[] = {
         nullptr,
     },
 
+    {
+        "datadog_resource_renaming_enabled",
+        NGX_HTTP_MAIN_CONF | NGX_CONF_TAKE1,
+        ngx_conf_set_flag_slot,
+        NGX_HTTP_MAIN_CONF_OFFSET,
+        offsetof(datadog_main_conf_t, resource_renaming_enabled),
+        nullptr,
+    },
+
+    {
+        "datadog_resource_renaming_always_simplified_endpoint",
+        NGX_HTTP_MAIN_CONF | NGX_CONF_TAKE1,
+        ngx_conf_set_flag_slot,
+        NGX_HTTP_MAIN_CONF_OFFSET,
+        offsetof(datadog_main_conf_t,
+                 resource_renaming_always_simplified_endpoint),
+        nullptr,
+    },
+
     // aliases opentracing (legacy)
     ALIAS_COMMAND("datadog_tracing", "opentracing", anywhere | NGX_CONF_TAKE1),
     ALIAS_COMMAND("datadog_operation_name", "opentracing_operation_name",

src/tracing/directives.h

@@ -68,6 +68,29 @@ dd::Expected<dd::Tracer> TracingLibrary::make_tracer(
     config.agent.url = nginx_conf.agent_url;
   }
 
+  if (nginx_conf.resource_renaming_enabled != NGX_CONF_UNSET) {
+    config.resource_renaming_enabled = {nginx_conf.resource_renaming_enabled ==
+                                        1};
+  }
+#ifdef WITH_WAF
+  else {
+    // we don't have it, in config
+    // if we also don't have in the environment it defaults to whether appsec
+    // is enabled
+    const char *env_renaming =
+        std::getenv("DD_TRACE_RESOURCE_RENAMING_ENABLED");
+    if (!env_renaming || !env_renaming[0]) {
+      config.resource_renaming_enabled = {nginx_conf.appsec_enabled == 1};
+    }
+  }
+#endif
+
+  if (nginx_conf.resource_renaming_always_simplified_endpoint !=
+      NGX_CONF_UNSET) {
+    config.resource_renaming_always_simplified_endpoint = {
+        nginx_conf.resource_renaming_always_simplified_endpoint == 1};
+  }
+
   // Set sampling rules based on any `datadog_sample_rate` directives.
   std::vector<sampling_rule_t> rules = nginx_conf.sampling_rules;
   // Sort by descending depth, so that rules in a `location` block come before

src/tracing_library.cpp

@@ -0,0 +1 @@
+# Endpoint renaming integration tests

test/cases/endpoint_renaming/__init__.py

@@ -0,0 +1,38 @@
+# Test configuration for endpoint renaming always mode
+# This configuration tests that endpoint renaming works even when http.route is present
+
+load_module /datadog-tests/ngx_http_datadog_module.so;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    datadog_agent_url http://agent:8126;
+    datadog_service_name test-service;
+
+    datadog_resource_renaming_enabled on;
+    datadog_resource_renaming_always_simplified_endpoint on;
+
+    server {
+        listen 80;
+        server_name localhost;
+
+        location / {
+            return 200 "$datadog_config_json";
+        }
+
+        location /api/users {
+            return 200 "User endpoint";
+        }
+
+        location /api/products {
+            return 200 "Product endpoint";
+        }
+
+        location /api/orders {
+            datadog_tag "http.route" "/api/orders/:id";
+            return 200 "Order endpoint";
+        }
+    }
+}

test/cases/endpoint_renaming/conf/always.conf

@@ -0,0 +1,45 @@
+# Test configuration for endpoint renaming with appsec enabled
+# This configuration tests that endpoint renaming defaults to enabled (fallback mode)
+# when appsec is enabled, without explicit resource_renaming_enabled directive
+
+thread_pool waf_thread_pool threads=2 max_queue=5;
+
+load_module /datadog-tests/ngx_http_datadog_module.so;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    datadog_agent_url http://agent:8126;
+    datadog_service_name test-service;
+
+    # Enable appsec - this should enable endpoint renaming by default
+    datadog_appsec_enabled on;
+    datadog_waf_thread_pool_name waf_thread_pool;
+
+    # No explicit datadog_resource_renaming_enabled directive
+    # Should default to on (fallback mode) because appsec is enabled
+
+    server {
+        listen 80;
+        server_name localhost;
+
+        location / {
+            return 200 "$datadog_config_json";
+        }
+
+        location /api/users {
+            return 200 "User endpoint";
+        }
+
+        location /api/products {
+            return 200 "Product endpoint";
+        }
+
+        location /api/orders {
+            datadog_tag "http.route" "/api/orders/:id";
+            return 200 "Order endpoint";
+        }
+    }
+}

test/cases/endpoint_renaming/conf/appsec_enabled.conf

@@ -0,0 +1,33 @@
+# Test configuration for endpoint renaming disabled (default)
+# This configuration tests that endpoint renaming is disabled by default
+
+load_module /datadog-tests/ngx_http_datadog_module.so;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    datadog_agent_url http://agent:8126;
+    datadog_service_name test-service;
+
+    # Endpoint renaming should be disabled by default
+    # No datadog_resource_renaming_enabled directive
+
+    server {
+        listen 80;
+        server_name localhost;
+
+        location / {
+            return 200 "$datadog_config_json";
+        }
+
+        location /api/users {
+            return 200 "User endpoint";
+        }
+
+        location /api/products {
+            return 200 "Product endpoint";
+        }
+    }
+}

test/cases/endpoint_renaming/conf/disabled.conf

@@ -0,0 +1,38 @@
+# Test configuration for endpoint renaming enabled
+# This configuration tests that endpoint renaming works when enabled
+
+load_module /datadog-tests/ngx_http_datadog_module.so;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    datadog_agent_url http://agent:8126;
+    datadog_service_name test-service;
+
+    # Enable endpoint renaming (fallback mode)
+    datadog_resource_renaming_enabled on;
+
+    server {
+        listen 80;
+        server_name localhost;
+
+        location / {
+            return 200 "$datadog_config_json";
+        }
+
+        location /api/users {
+            return 200 "User endpoint";
+        }
+
+        location /api/products {
+            return 200 "Product endpoint";
+        }
+
+        location /api/orders {
+            datadog_tag "http.route" "/api/orders/:id";
+            return 200 "Order endpoint";
+        }
+    }
+}

test/cases/endpoint_renaming/conf/fallback.conf

@@ -0,0 +1,158 @@
+from .. import case
+from .. import formats
+
+from pathlib import Path
+
+
+class TestEndpointRenaming(case.TestCase):
+    """Test cases for endpoint renaming (http.endpoint tag generation).
+
+    The endpoint renaming feature generates http.endpoint tags by analyzing
+    URL paths and replacing dynamic segments with patterns like {param:int},
+    {param:hex}, etc.
+    """
+
+    last_config = ''
+
+    def replace_config(self, new_config):
+        """Replace nginx configuration if different from last config."""
+        if new_config != TestEndpointRenaming.last_config:
+            conf_path = Path(__file__).parent / "conf" / new_config
+            conf_text = conf_path.read_text()
+            status, log_lines = self.orch.nginx_replace_config(
+                conf_text, conf_path.name)
+            self.assertEqual(0, status, log_lines)
+            TestEndpointRenaming.last_config = new_config
+
+    def send_request_and_get_span(self, url, config_name):
+        self.replace_config(config_name)
+        self.orch.sync_service('agent')
+
+        status, _, _ = self.orch.send_nginx_http_request(url)
+
+        self.orch.reload_nginx()
+        log_lines = self.orch.sync_service('agent')
+
+        spans = formats.parse_spans(log_lines)
+        nginx_spans = [s for s in spans if s.get('service') == 'test-service']
+
+        self.assertEquals(len(nginx_spans), 1, "Expected exactly one span")
+
+        return status, nginx_spans[0]
+
+    def test_endpoint_renaming_disabled_by_default(self):
+        """Verify that endpoint renaming is disabled by default.
+
+        When disabled, no http.endpoint tag should be added to spans.
+        """
+        status, span = self.send_request_and_get_span("/api/users/123",
+                                                      "disabled.conf")
+        self.assertEqual(200, status)
+
+        meta = span.get('meta', {})
+        self.assertNotIn(
+            'http.endpoint', meta,
+            f"http.endpoint should not be present when disabled: {meta}")
+
+    def test_endpoint_renaming_fallback_mode(self):
+        """Verify endpoint renaming in fallback mode.
+
+        When enabled in fallback mode, http.endpoint should be added
+        when http.route is not present. For this endpoint, it's not present
+        """
+        status, span = self.send_request_and_get_span("/api/users/123",
+                                                      "fallback.conf")
+        self.assertEqual(200, status)
+
+        meta = span.get('meta', {})
+        self.assertIn('http.endpoint', meta,
+                      "http.endpoint should be present in fallback mode")
+        self.assertEqual(
+            meta['http.endpoint'], '/api/users/{param:int}',
+            f"Expected /api/users/{{param:int}}, got {meta['http.endpoint']}")
+
+    def test_fallback_mode_respects_http_route(self):
+        """Verify fallback mode does NOT calculate endpoint when http.route is set."""
+        status, span = self.send_request_and_get_span("/api/orders/789",
+                                                      "fallback.conf")
+        self.assertEqual(200, status)
+
+        meta = span.get('meta', {})
+        # In fallback mode with http.route set, http.endpoint should NOT be present
+        self.assertIn('http.route', meta, "http.route should be present")
+        self.assertEqual(meta['http.route'], '/api/orders/:id')
+        self.assertNotIn(
+            'http.endpoint', meta,
+            "http.endpoint should NOT be set when http.route exists in fallback mode"
+        )
+
+    def test_endpoint_renaming_always_mode(self):
+        """Verify endpoint renaming in always mode.
+
+        When enabled in always mode, http.endpoint should always be calculated,
+        even when http.route is present.
+        """
+        status, span = self.send_request_and_get_span(
+            "/api/products/abc-123-def", "always.conf")
+        self.assertEqual(200, status)
+
+        meta = span.get('meta', {})
+        self.assertIn('http.endpoint', meta,
+                      "http.endpoint should be present in always mode")
+        # Verify the pattern: /api/products/abc-123-def -> /api/products/{param:hex_id}
+        self.assertEqual(
+            meta['http.endpoint'], '/api/products/{param:hex_id}',
+            f"Expected /api/products/{{param:hex_id}}, got {meta['http.endpoint']}"
+        )
+
+    def test_always_mode_ignores_http_route(self):
+        """Verify always mode calculates endpoint even when http.route is set."""
+        status, span = self.send_request_and_get_span("/api/orders/999",
+                                                      "always.conf")
+        self.assertEqual(200, status)
+
+        meta = span.get('meta', {})
+        # In always mode, both http.route and http.endpoint should be present
+        self.assertIn('http.route', meta, "http.route should be present")
+        self.assertIn('http.endpoint', meta,
+                      "http.endpoint should be present in always mode")
+        self.assertEqual(meta['http.route'], '/api/orders/:id')
+        self.assertEqual(meta['http.endpoint'], '/api/orders/{param:int}')
+
+    def test_appsec_enables_fallback_mode_by_default(self):
+        """Verify that when appsec is enabled, endpoint renaming defaults to fallback mode.
+
+        With appsec enabled and no explicit resource_renaming_enabled directive,
+        the feature should be enabled in fallback mode:
+        - http.endpoint calculated when http.route not present
+        - http.endpoint NOT calculated when http.route is present
+        """
+        if self.waf_disabled:
+            self.skipTest("WAF is disabled - appsec test requires WAF support")
+
+        # Test without http.route - should calculate endpoint
+        status, span = self.send_request_and_get_span("/api/users/456",
+                                                      "appsec_enabled.conf")
+        self.assertEqual(200, status)
+
+        meta = span.get('meta', {})
+        self.assertIn(
+            'http.endpoint', meta,
+            "http.endpoint should be present when appsec is enabled (fallback mode)"
+        )
+        self.assertEqual(
+            meta['http.endpoint'], '/api/users/{param:int}',
+            f"Expected /api/users/{{param:int}}, got {meta['http.endpoint']}")
+
+        # Test with http.route - should NOT calculate endpoint (fallback mode)
+        status, span = self.send_request_and_get_span("/api/orders/555",
+                                                      "appsec_enabled.conf")
+        self.assertEqual(200, status)
+
+        meta = span.get('meta', {})
+        self.assertIn('http.route', meta, "http.route should be present")
+        self.assertEqual(meta['http.route'], '/api/orders/:id')
+        self.assertNotIn(
+            'http.endpoint', meta,
+            "http.endpoint should NOT be set when http.route exists in fallback mode (appsec enabled)"
+        )