fix(serviceevents): align route/operation labels with Application Signals (#784)

## Description

Service Events emitted operation/route labels that diverged from
CloudWatch Application Signals for two cases. This PR aligns Service
Events **to** App Signals (one-way; App Signals behavior is untouched).

### 1. Django leading slash
Django routes were prepended with a leading slash (`GET
/billings/<int:owner_id>/...`), whereas App Signals emits them
slash-less (`GET billings/<int:owner_id>/...`). The slash-prepend in
`django_instrumentation` is removed so matched Django routes match App
Signals.

### 2. Unmatched-route sentinel
Unmatched requests (404s, scanner/bot traffic) were collapsed to a
`<unmatched>` sentinel, while App Signals collapses an unresolved span
name to its **first path segment**. The sentinel is replaced with a
shared `unmatched_route_label()` that delegates to App Signals'
`extract_api_path_value`, so both produce the same first-segment label
(`/wp-admin/setup.php` → `/wp-admin`) across Flask, FastAPI, and Django.
This keeps the cardinality bound on scanner traffic while matching App
Signals.

### Docs
Because Django routes are now recorded slash-less, `config.py` documents
that Django endpoint include/exclude patterns and latency thresholds
must omit the leading slash (e.g. `GET api/*`), while Flask/FastAPI keep
it (e.g. `GET /api/*`).

## Testing
- `pytest` serviceevents suite: 714 passing
- `black --check`, `isort --check`, `codespell`: clean
- Contract-test helpers updated (`route_label`/`operation_label`; Django
overrides return slash-less).

## Note
App Signals' extractor
(`_aws_span_processing_util.extract_api_path_value`) is **not** modified
— Service Events only delegates to it.

---------

Co-authored-by: ADOT Patch workflow <adot-patch-workflow@github.com>

Author: vastin

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/serviceevents/config.py

@@ -186,6 +186,10 @@ class ServiceEventsConfig:
     # Per-endpoint latency thresholds for latency-triggered incident snapshots
     # Format: "METHOD /route:threshold_ms,METHOD /route:threshold_ms,..."
     # Example: "POST /api/checkout:500,GET /api/health:50,GET /api/reports:5000"
+    # Django note: routes are matched WITHOUT a leading slash (e.g. "api/checkout"), to
+    # mirror Application Signals. Write Django patterns slash-less, e.g. "POST api/checkout:500".
+    # Exception: unmatched/scanner requests (no route) are recorded with a leading-slash
+    # first-segment label (e.g. "/wp-admin"), so thresholds targeting them keep the slash.
     latency_thresholds: List[str] = field(default_factory=list)  # OTEL_AWS_SERVICE_EVENTS_LATENCY_THRESHOLDS
 
     # Incident Snapshot Request Payload Capture Settings. Hardcoded off — no longer a
@@ -195,6 +199,12 @@ class ServiceEventsConfig:
     # Endpoint Filtering - glob patterns in format "METHOD /route" or "* /route" or "METHOD *"
     # If include_patterns is set, only track matching endpoints; then exclude_patterns removes from that set
     # Example: "GET /api/*,POST /api/*" or "* /health,* /metrics"
+    # Django note: routes are recorded WITHOUT a leading slash (e.g. "api/users"), to mirror
+    # Application Signals. Write Django patterns slash-less, e.g. "GET api/*"; Flask/FastAPI
+    # routes carry the leading slash, so their patterns keep it, e.g. "GET /api/*".
+    # Exception: unmatched/scanner requests (no route) are recorded with a leading-slash
+    # first-segment label (e.g. "/wp-admin"), so filters targeting them keep the slash even
+    # on Django, e.g. "* /wp-admin".
     endpoint_include_patterns: List[str] = field(
         default_factory=list
     )  # OTEL_AWS_SERVICE_EVENTS_ENDPOINT_INCLUDE_PATTERNS
@@ -430,6 +440,12 @@ def get_latency_threshold_patterns(self) -> List[Tuple[str, float]]:
             - "GET /api/*:100" - any GET to /api/* routes
             - "* *:200" - all endpoints (catch-all)
 
+        Django note: routes are recorded WITHOUT a leading slash (to mirror Application
+        Signals), so Django thresholds must omit it, e.g. "GET api/users:500". Flask/FastAPI
+        routes carry the leading slash, e.g. "GET /api/users:500". Exception: unmatched/scanner
+        requests (no route) are recorded with a leading-slash first-segment label (e.g.
+        "/wp-admin"), so thresholds targeting them keep the slash even on Django.
+
         Returns:
             List of (pattern, threshold_ms) tuples. Order matters - first match wins.
         """
@@ -481,8 +497,14 @@ def should_track_endpoint(self, route: str, method: str) -> bool:
         - "?" matches any single character
         - Format: "METHOD /route" (e.g., "GET /api/*", "* /health", "POST /api/users")
 
+        Django note: routes are recorded WITHOUT a leading slash (to mirror Application
+        Signals), so Django patterns must omit it, e.g. "GET api/*". Flask/FastAPI routes
+        carry the leading slash, e.g. "GET /api/*". Exception: unmatched/scanner requests
+        (no route) are recorded with a leading-slash first-segment label (e.g. "/wp-admin"),
+        so patterns targeting them keep the slash even on Django, e.g. "* /wp-admin".
+
         Args:
-            route: The endpoint route (e.g., "/api/users")
+            route: The endpoint route (e.g., "/api/users" for Flask/FastAPI, "api/users" for Django)
             method: The HTTP method (e.g., "GET", "POST")
 
         Returns:

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/serviceevents/instrumentation/_constants.py

@@ -1,19 +1,36 @@
 # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-"""Shared constants for the framework instrumentations (Flask, FastAPI, Django).
+"""Shared route helpers for the framework instrumentations (Flask, FastAPI, Django).
 
 Keeping these in one module makes cross-framework behavior structural rather than a
 promise enforced by comments — a single edit here changes every framework at once.
 """
 
-# Route label for a request that matched no URL rule (unmatched 404s, scanner/bot traffic
-# to nonexistent URLs like /wp-admin or /.env). Recording the raw path for these would make
-# every probed URL its own metric series — a cardinality explosion. Collapsing to one
-# sentinel keeps the 404-rate signal without the cardinality, identically across frameworks.
-#
-# Note: this value also flows through ServiceEventsConfig.should_track_endpoint(route, ...).
-# With the default (empty) endpoint filters every request is tracked, so unmatched requests
-# are still recorded under this label. A customer who sets endpoint_include_patterns scopes
-# tracking to matching routes only, so unmatched requests are intentionally excluded then.
-UNMATCHED_ROUTE = "<unmatched>"
+from typing import Optional
+
+from amazon.opentelemetry.distro._aws_span_processing_util import extract_api_path_value
+
+
+def unmatched_route_label(raw_path: Optional[str]) -> str:
+    """Route label for a request that matched no URL rule (unmatched 404s, scanner/bot
+    traffic to nonexistent URLs like /wp-admin or /.env).
+
+    Recording the raw path for these would make every probed URL its own metric series —
+    a cardinality explosion. Instead, collapse to the first path segment, e.g.
+    "/wp-admin/setup.php" -> "/wp-admin". This is exactly what Application Signals does
+    for a span whose name can't be resolved to a route
+    (_aws_span_processing_util.extract_api_path_value), so ServiceEvents and Application
+    Signals produce the same operation label for unmatched requests. The first-segment
+    bound keeps cardinality from a single nonexistent prefix in check while still
+    distinguishing the common scanner targets.
+
+    Note: this value also flows through ServiceEventsConfig.should_track_endpoint(route,
+    ...). With the default (empty) endpoint filters every request is tracked, so unmatched
+    requests are still recorded (under their first-segment label). A customer who sets
+    endpoint_include_patterns scopes tracking to matching routes only, so unmatched
+    requests are excluded unless a pattern matches the first-segment label.
+    """
+    # extract_api_path_value treats None/"" as "/" and always returns a leading-slash,
+    # first-segment value, identically across frameworks.
+    return extract_api_path_value(raw_path or "")

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/serviceevents/instrumentation/django_instrumentation.py

@@ -17,7 +17,7 @@
 import time
 from typing import Any, Optional
 
-from amazon.opentelemetry.distro.serviceevents.instrumentation._constants import UNMATCHED_ROUTE
+from amazon.opentelemetry.distro.serviceevents.instrumentation._constants import unmatched_route_label
 from amazon.opentelemetry.distro.serviceevents.instrumentation.flask_instrumentation import (
     _extract_error_from_call_path,
 )
@@ -35,8 +35,8 @@
 _serviceevents_config = None
 
 # Django only calls process_view after a URL resolves to a view, so an unmatched 404 never
-# gets a route stored and _finalize_request falls back to the shared UNMATCHED_ROUTE sentinel
-# (see _constants for why the raw path is not used).
+# gets a route stored and _finalize_request falls back to the shared first-segment unmatched
+# label derived from the raw path (see _constants for the cardinality rationale).
 
 
 def _get_request_body(request) -> Optional[Any]:
@@ -81,21 +81,24 @@ def _get_request_body(request) -> Optional[Any]:
 
 def _get_route_pattern(request) -> str:
     """
-    Get the route pattern (e.g. /users/<int:id>/) from the Django request.
+    Get the route pattern (e.g. users/<int:id>/) from the Django request.
 
     Args:
         request: Django HttpRequest object
 
     Returns:
-        Route pattern string (e.g., "/users/<int:id>/")
+        Route pattern string (e.g., "users/<int:id>/")
     """
     # Try to get the route pattern from resolver_match (available after URL resolution)
     if hasattr(request, "resolver_match") and request.resolver_match is not None:
-        # resolver_match.route is the URL pattern (e.g., "users/<int:id>/")
+        # resolver_match.route is the URL pattern (e.g., "users/<int:id>/"). Django stores
+        # it without a leading slash by convention; return it verbatim so the operation
+        # label matches Application Signals, which derives the same value from span.name
+        # (the upstream OTel Django instrumentation also leaves it slash-less). Flask and
+        # FastAPI route patterns already carry a leading slash natively, so all three
+        # frameworks agree with App Signals without further normalization here.
         route = getattr(request.resolver_match, "route", None)
         if route:
-            if not route.startswith("/"):
-                route = "/" + route
             return route
 
     # Fallback to path_info
@@ -159,11 +162,13 @@ def _finalize_request(request, response, exception):  # pylint: disable=too-many
 
         # Get route and method from stored values (set in process_view). A missing
         # _serviceevents_route means process_view never ran — i.e. the URL matched no
-        # urlpattern (unmatched 404). Use a single sentinel for those instead of the raw
-        # path so scanner/bot traffic to nonexistent URLs can't explode metric cardinality.
+        # urlpattern (unmatched 404). Collapse those to the first path segment instead of
+        # the raw path so scanner/bot traffic to nonexistent URLs can't explode metric
+        # cardinality, matching Application Signals' unmatched-route handling.
         route = getattr(request, "_serviceevents_route", None)
         if route is None:
-            route = UNMATCHED_ROUTE
+            raw_path = getattr(request, "path_info", None) or getattr(request, "path", None)
+            route = unmatched_route_label(raw_path)
         method = getattr(request, "_serviceevents_method", request.method)
 
         # Extract error info if error occurred

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/serviceevents/instrumentation/fastapi_instrumentation.py

@@ -17,7 +17,7 @@
 from typing import Any, Dict, Optional
 from urllib.parse import parse_qs
 
-from amazon.opentelemetry.distro.serviceevents.instrumentation._constants import UNMATCHED_ROUTE
+from amazon.opentelemetry.distro.serviceevents.instrumentation._constants import unmatched_route_label
 from amazon.opentelemetry.distro.serviceevents.instrumentation.flask_instrumentation import (
     _capture_active_trace_context,
     _extract_error_from_call_path,
@@ -98,9 +98,10 @@ def _get_route_pattern(scope) -> str:
     if resolved is not None:
         return resolved
 
-    # No route matched (404 / scanner traffic). Collapse to a single sentinel rather than
-    # the raw path so probed URLs can't explode metric cardinality. Matches Flask/Django.
-    return UNMATCHED_ROUTE
+    # No route matched (404 / scanner traffic). Collapse to the first path segment rather
+    # than the raw path so probed URLs can't explode metric cardinality. Matches
+    # Flask/Django and Application Signals' unmatched-route handling.
+    return unmatched_route_label(scope.get("path"))
 
 
 def _resolve_route_template(scope) -> Optional[str]:
@@ -304,8 +305,8 @@ async def send_wrapper(message):
 
             # Re-resolve the route now that the app has run. At middleware entry
             # scope["route"] is unset, so `route` was whatever _get_route_pattern could
-            # determine pre-routing: a pre-resolved template, or the <unmatched> sentinel
-            # when nothing matched. Starlette/FastAPI routing populates scope["route"] in
+            # determine pre-routing: a pre-resolved template, or the first-segment
+            # unmatched label when nothing matched. Starlette/FastAPI routing populates scope["route"] in
             # place during dispatch, so by here it resolves to the template (/users/{id}).
             # Use the template for the exported endpoint telemetry below to avoid a
             # per-URL metric cardinality explosion. (The pre-await operation context

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/serviceevents/instrumentation/flask_instrumentation.py

@@ -14,7 +14,7 @@
 import time
 from typing import Any, Dict, Optional
 
-from amazon.opentelemetry.distro.serviceevents.instrumentation._constants import UNMATCHED_ROUTE
+from amazon.opentelemetry.distro.serviceevents.instrumentation._constants import unmatched_route_label
 from amazon.opentelemetry.distro.serviceevents.instrumentation._safety import never_raises
 from amazon.opentelemetry.distro.serviceevents.python_monitor import (
     _ServiceEventsMonitorState,
@@ -349,9 +349,9 @@ def _get_route_pattern(request) -> str:
         return f"/{request.endpoint}"
 
     # No url_rule and no endpoint means the URL matched no route (404 / scanner traffic).
-    # Collapse to a single sentinel rather than the raw path so probed URLs can't explode
-    # metric cardinality.
-    return UNMATCHED_ROUTE
+    # Collapse to the first path segment rather than the raw path so probed URLs can't
+    # explode metric cardinality, matching Application Signals' unmatched-route handling.
+    return unmatched_route_label(getattr(request, "path", None))
 
 
 def _extract_error_from_call_path(exception, route, method) -> Optional[Dict]:

aws-opentelemetry-distro/tests/amazon/opentelemetry/distro/serviceevents/instrumentation/test_django_instrumentation.py

@@ -20,12 +20,12 @@ class TestGetRoutePattern(TestCase):
     """Tests for _get_route_pattern."""
 
     def test_get_route_pattern_from_resolver_match(self):
-        """resolver_match.route is returned when available."""
+        """resolver_match.route is returned verbatim (slash-less, as Django stores it)."""
         request = MagicMock()
         request.resolver_match = MagicMock()
         request.resolver_match.route = "users/<int:id>"
         result = _get_route_pattern(request)
-        self.assertEqual(result, "/users/<int:id>")
+        self.assertEqual(result, "users/<int:id>")
 
     def test_get_route_pattern_from_path_info(self):
         """Falls back to path_info when resolver_match is None."""
@@ -44,13 +44,14 @@ def test_get_route_pattern_from_path(self):
         result = _get_route_pattern(request)
         self.assertEqual(result, "/api/users/42")
 
-    def test_get_route_pattern_adds_leading_slash(self):
-        """Leading slash is added if route doesn't start with one."""
+    def test_get_route_pattern_preserves_slashless_route(self):
+        """A slash-less Django route is returned as-is (no leading slash added), to
+        match Application Signals which derives the same value from span.name."""
         request = MagicMock()
         request.resolver_match = MagicMock()
         request.resolver_match.route = "api/orders"
         result = _get_route_pattern(request)
-        self.assertEqual(result, "/api/orders")
+        self.assertEqual(result, "api/orders")
 
 
 class TestGetRequestBody(TestCase):
@@ -404,17 +405,17 @@ def test_call_handles_exception(self):
 
     @patch("amazon.opentelemetry.distro.serviceevents.instrumentation.django_instrumentation.set_current_operation")
     def test_process_view_sets_operation_context(self, mock_set_operation):
-        """process_view calls set_current_operation with a METHOD /route string."""
+        """process_view calls set_current_operation with a "METHOD route" string."""
         mock_get_response = MagicMock()
         middleware = ServiceEventsDjangoMiddleware(mock_get_response)
         request = self._make_request()
 
         middleware.process_view(request, MagicMock(), [], {})
 
         mock_set_operation.assert_called_once()
-        # The operation should be "METHOD /route"
+        # The operation should be "METHOD route" (Django route is slash-less, matching App Signals)
         call_args = mock_set_operation.call_args[0][0]
-        self.assertEqual(call_args, "GET /api/test")
+        self.assertEqual(call_args, "GET api/test")
 
     @patch("amazon.opentelemetry.distro.serviceevents.instrumentation.django_instrumentation.set_current_operation")
     def test_process_view_begins_investigation(self, mock_set_operation):
@@ -503,7 +504,7 @@ def test_process_view_swallows_trace_capture_failure(self, mock_set_operation):
 
         self.assertIsNone(result)
         # Setup block ran before the trace capture failed, so route context was stored.
-        self.assertEqual(request._serviceevents_route, "/api/test")
+        self.assertEqual(request._serviceevents_route, "api/test")
 
     @patch(
         "amazon.opentelemetry.distro.serviceevents.instrumentation.django_instrumentation.set_current_operation",
@@ -561,8 +562,9 @@ def _make_request(self, method="GET", path="/api/test", route="api/test", view_n
         request.META = {}
         request._serviceevents_start_time = 1000000000
         request._serviceevents_skip = False
-        # Set serviceevents context attributes (normally set by process_view)
-        request._serviceevents_route = "/" + route if not route.startswith("/") else route
+        # Set serviceevents context attributes (normally set by process_view). The route is
+        # stored verbatim (Django routes are slash-less, matching App Signals).
+        request._serviceevents_route = route
         request._serviceevents_method = method
         request._serviceevents_path = path
         request._serviceevents_endpoint = view_name
@@ -588,7 +590,7 @@ def test_records_endpoint_metric(self, mock_clear):
 
         mock_ec.record_request.assert_called_once()
         call_kwargs = mock_ec.record_request.call_args[1]
-        self.assertEqual(call_kwargs["route"], "/api/test")
+        self.assertEqual(call_kwargs["route"], "api/test")
         self.assertEqual(call_kwargs["method"], "GET")
         self.assertEqual(call_kwargs["status_code"], 200)
         self.assertIsNone(call_kwargs["error_info"])
@@ -693,8 +695,9 @@ def test_skips_when_no_start_time(self, mock_clear):
         mock_ec.record_request.assert_not_called()
 
     @patch("amazon.opentelemetry.distro.serviceevents.instrumentation.django_instrumentation.clear_current_operation")
-    def test_unmatched_route_collapses_to_sentinel(self, mock_clear):
-        """An unmatched-route 404 (process_view never ran) records the sentinel, not the raw path."""
+    def test_unmatched_route_collapses_to_first_segment(self, mock_clear):
+        """An unmatched-route 404 (process_view never ran) records the first path segment,
+        not the full raw path — matching Application Signals."""
         mock_ec = MagicMock()
         django_mod._endpoint_collector = mock_ec
 
@@ -728,14 +731,14 @@ def test_unmatched_route_collapses_to_sentinel(self, mock_clear):
 
         mock_ec.record_request.assert_called_once()
         call_kwargs = mock_ec.record_request.call_args[1]
-        # Must be the collapsed sentinel, NOT the raw probed path.
-        self.assertEqual(call_kwargs["route"], "<unmatched>")
-        self.assertNotIn("wp-admin", call_kwargs["route"])
+        # Must be the collapsed first segment, NOT the full raw probed path.
+        self.assertEqual(call_kwargs["route"], "/wp-admin")
+        self.assertNotIn("setup-config.php", call_kwargs["route"])
         self.assertEqual(call_kwargs["status_code"], 404)
 
     @patch("amazon.opentelemetry.distro.serviceevents.instrumentation.django_instrumentation.clear_current_operation")
-    def test_matched_route_unaffected_by_sentinel(self, mock_clear):
-        """A normally-resolved request still records its real route, not the sentinel."""
+    def test_matched_route_unaffected_by_unmatched_label(self, mock_clear):
+        """A normally-resolved request still records its real route, not the unmatched label."""
         mock_ec = MagicMock()
         django_mod._endpoint_collector = mock_ec
 
@@ -750,7 +753,7 @@ def test_matched_route_unaffected_by_sentinel(self, mock_clear):
             _finalize_request(request, response, None)
 
         call_kwargs = mock_ec.record_request.call_args[1]
-        self.assertEqual(call_kwargs["route"], "/users/<int:id>")
+        self.assertEqual(call_kwargs["route"], "users/<int:id>")
 
     @patch("amazon.opentelemetry.distro.serviceevents.instrumentation.django_instrumentation.clear_current_operation")
     def test_passes_correct_request_data(self, mock_clear):