feat: allow HTTP operations to be configurable via environment variable (#1352)

*Issue #, if available:*

*Description of changes:*
When HTTP span names don't contain a URL path, we generate the HTTP
operation by truncating the URL path to only the first trailing value to
preserve low cardinality (i.e. /api/v1/users -> /api). This can result
in overly broad operation groupings for services with endpoint paths of
various depths.

This PR introduces an environment variable configuration,
`OTEL_AWS_HTTP_OPERATION_PATHS`, which allows users to configure their
own HTTP endpoint paths. If this variable is provided, the span name's
URL path will resolve to the longest matching path. Wildcards are
supported with the following syntaxes: `{version}`, `:version`, or
simply `*`. This way, users can decide how their service endpoint are
grouped into operation names shown in CloudWatch.

Added unit and integration tests to verify behavior, and did some E2E
testing with an instrumented HTTP server.

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.

Author: ezhang6811

CHANGELOG.md

@@ -13,6 +13,8 @@ If your change does not need a CHANGELOG entry, add the "skip changelog" label t
 
 ## Unreleased
 
+- Support environment-configured endpoint visibility for HTTP operation names
+  ([#1352](https://github.com/aws-observability/aws-otel-java-instrumentation/pull/1352))
 - Bump Netty to 4.1.132.Final to fix CVE-2026-33870 and CVE-2026-33871
   ([#1348](https://github.com/aws-observability/aws-otel-java-instrumentation/pull/1348))
 

awsagentprovider/src/main/java/software/amazon/opentelemetry/javaagent/providers/AwsMetricAttributesSpanExporter.java

@@ -88,6 +88,11 @@ private List<SpanData> addMetricAttributes(Collection<SpanData> spans) {
     List<SpanData> modifiedSpans = new ArrayList<>();
 
     for (SpanData span : spans) {
+      // If OTEL_AWS_HTTP_OPERATION_PATHS is configured and matches, wrap the span with the
+      // overridden name so that the exported trace carries the correct span name. This ensures
+      // getIngressOperation (called below) derives aws.local.operation from the overridden name.
+      span = AwsSpanProcessingUtil.applyOperationPathSpanName(span);
+
       // If the map has no items, no modifications are required. If there is one item, it means the
       // span either produces Service or Dependency metric attributes, and in either case we want to
       // modify the span with them. If there are two items, the span produces both Service and

awsagentprovider/src/main/java/software/amazon/opentelemetry/javaagent/providers/AwsSpanMetricsProcessor.java

@@ -132,6 +132,10 @@ public boolean isStartRequired() {
   public void onEnd(ReadableSpan span) {
     SpanData spanData = span.toSpanData();
 
+    // If OTEL_AWS_HTTP_OPERATION_PATHS is configured, wrap the span with the overridden name
+    // so that metrics use the configured operation path instead of the original span name.
+    spanData = AwsSpanProcessingUtil.applyOperationPathSpanName(spanData);
+
     Map<String, Attributes> attributeMap =
         generator.generateMetricAttributeMapFromSpan(spanData, resource);
 

awsagentprovider/src/main/java/software/amazon/opentelemetry/javaagent/providers/AwsSpanProcessingUtil.java

@@ -43,10 +43,12 @@
 import io.opentelemetry.api.trace.SpanKind;
 import io.opentelemetry.sdk.common.InstrumentationScopeInfo;
 import io.opentelemetry.sdk.trace.ReadableSpan;
+import io.opentelemetry.sdk.trace.data.DelegatingSpanData;
 import io.opentelemetry.sdk.trace.data.SpanData;
 import java.io.IOException;
 import java.io.InputStream;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 import java.util.regex.Pattern;
 
@@ -78,6 +80,153 @@ final class AwsSpanProcessingUtil {
   static final String LAMBDA_SCOPE_PREFIX = "io.opentelemetry.aws-lambda-";
   static final String SERVLET_SCOPE_PREFIX = "io.opentelemetry.servlet-";
 
+  // Environment variable for configurable operation name paths
+  static final String OTEL_AWS_HTTP_OPERATION_PATHS_CONFIG = "OTEL_AWS_HTTP_OPERATION_PATHS";
+
+  // Parsed and sorted (longest first) operation paths from env var, computed once
+  private static volatile List<String> operationPaths;
+
+  /**
+   * Parse the OTEL_AWS_HTTP_OPERATION_PATHS env var into a sorted list of path templates (longest
+   * first). Returns an empty list if the env var is not set.
+   */
+  static List<String> getOperationPaths() {
+    if (operationPaths == null) {
+      synchronized (AwsSpanProcessingUtil.class) {
+        if (operationPaths == null) {
+          String config = System.getenv(OTEL_AWS_HTTP_OPERATION_PATHS_CONFIG);
+          if (config == null || config.trim().isEmpty()) {
+            operationPaths = Collections.emptyList();
+          } else {
+            List<String> paths = new ArrayList<>();
+            for (String path : config.split(",")) {
+              String trimmed = path.trim();
+              if (!trimmed.isEmpty()) {
+                paths.add(trimmed);
+              }
+            }
+            // Sort longest first so longest prefix match wins. For patterns with the same
+            // number of segments, the original configuration order is preserved (stable sort).
+            paths.sort(
+                (a, b) -> {
+                  int aSegments = a.split("/").length;
+                  int bSegments = b.split("/").length;
+                  return Integer.compare(bSegments, aSegments);
+                });
+            operationPaths = Collections.unmodifiableList(paths);
+          }
+        }
+      }
+    }
+    return operationPaths;
+  }
+
+  // Visible for testing — allows tests to reset the cached paths
+  static void resetOperationPaths() {
+    synchronized (AwsSpanProcessingUtil.class) {
+      operationPaths = null;
+    }
+  }
+
+  /**
+   * If OTEL_AWS_HTTP_OPERATION_PATHS is configured and a pattern matches the span's URL path,
+   * returns a wrapped SpanData with the span name overridden to "METHOD /path/template". Returns
+   * the original span unchanged if no config is set or no pattern matches.
+   */
+  static SpanData applyOperationPathSpanName(SpanData span) {
+    List<String> paths = getOperationPaths();
+    if (paths.isEmpty()) {
+      return span;
+    }
+
+    String urlPath = getUrlPath(span);
+    if (urlPath == null || urlPath.isEmpty()) {
+      return span;
+    }
+
+    // Strip query string and fragment (relevant for http.target)
+    int idx = urlPath.indexOf('?');
+    if (idx >= 0) {
+      urlPath = urlPath.substring(0, idx);
+    }
+    idx = urlPath.indexOf('#');
+    if (idx >= 0) {
+      urlPath = urlPath.substring(0, idx);
+    }
+
+    // Normalize trailing slashes
+    while (urlPath.endsWith("/") && urlPath.length() > 1) {
+      urlPath = urlPath.substring(0, urlPath.length() - 1);
+    }
+
+    String[] urlSegments = urlPath.split("/", -1);
+    for (String pattern : paths) {
+      String normalizedPattern = pattern;
+      while (normalizedPattern.endsWith("/") && normalizedPattern.length() > 1) {
+        normalizedPattern = normalizedPattern.substring(0, normalizedPattern.length() - 1);
+      }
+      if (segmentsMatch(urlSegments, normalizedPattern.split("/", -1))) {
+        String httpMethod = getHttpMethod(span);
+        String newName = httpMethod != null ? httpMethod + " " + pattern : pattern;
+        return new DelegatingSpanData(span) {
+          @Override
+          public String getName() {
+            return newName;
+          }
+        };
+      }
+    }
+    return span;
+  }
+
+  /** Return the URL path from server span attributes, preferring url.path over http.target. */
+  private static String getUrlPath(SpanData span) {
+    if (isKeyPresent(span, URL_PATH)) {
+      return span.getAttributes().get(URL_PATH);
+    }
+    if (isKeyPresent(span, HTTP_TARGET)) {
+      return span.getAttributes().get(HTTP_TARGET);
+    }
+    return null;
+  }
+
+  /**
+   * Check if URL segments match a pattern's segments. Only pattern segments can be wildcards
+   * ({param}, :param, or *) — URL segments are always treated as literals. A wildcard pattern
+   * segment matches any non-empty URL segment. The pattern acts as a prefix — extra URL segments
+   * after the pattern are allowed.
+   */
+  private static boolean segmentsMatch(String[] urlSegments, String[] patternSegments) {
+    for (int i = 0; i < patternSegments.length; i++) {
+      if (i >= urlSegments.length) {
+        return false;
+      }
+      String ps = patternSegments[i];
+      String us = urlSegments[i];
+
+      // Pattern wildcard matches any non-empty URL segment
+      if (isWildcardSegment(ps)) {
+        if (us.isEmpty()) {
+          return false;
+        }
+        continue;
+      }
+
+      // Both literal — must be equal
+      if (!ps.equals(us)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /** A segment is a wildcard if it uses {param}, :param, or * format. */
+  private static boolean isWildcardSegment(String segment) {
+    return (segment.startsWith("{") && segment.endsWith("}"))
+        || segment.startsWith(":")
+        || segment.equals("*");
+  }
+
   static List<String> getDialectKeywords() {
     try (InputStream jsonFile =
         AwsSpanProcessingUtil.class
@@ -123,6 +272,7 @@ static String getIngressOperation(SpanData span) {
       }
       return getFunctionNameFromEnv() + "/FunctionHandler";
     }
+
     String operation = span.getName();
     if (shouldUseInternalOperation(span)) {
       operation = INTERNAL_OPERATION;
@@ -132,6 +282,16 @@ static String getIngressOperation(SpanData span) {
     return operation;
   }
 
+  /** Get the HTTP method from the span, checking new and deprecated semconv attributes. */
+  private static String getHttpMethod(SpanData span) {
+    if (isKeyPresent(span, HTTP_REQUEST_METHOD)) {
+      return span.getAttributes().get(HTTP_REQUEST_METHOD);
+    } else if (isKeyPresent(span, HTTP_METHOD)) {
+      return span.getAttributes().get(HTTP_METHOD);
+    }
+    return null;
+  }
+
   // define a function so that we can mock it in unit test
   static String getFunctionNameFromEnv() {
     return System.getenv(AWS_LAMBDA_FUNCTION_NAME_CONFIG);
@@ -256,11 +416,8 @@ private static boolean isValidOperation(SpanData span, String operation) {
     if (operation == null || operation.equals(UNKNOWN_OPERATION)) {
       return false;
     }
-    if (isKeyPresent(span, HTTP_REQUEST_METHOD)) {
-      String httpMethod = span.getAttributes().get(HTTP_REQUEST_METHOD);
-      return !operation.equals(httpMethod);
-    } else if (isKeyPresent(span, HTTP_METHOD)) {
-      String httpMethod = span.getAttributes().get(HTTP_METHOD);
+    String httpMethod = getHttpMethod(span);
+    if (httpMethod != null) {
       return !operation.equals(httpMethod);
     }
     return true;

awsagentprovider/src/test/java/software/amazon/opentelemetry/javaagent/providers/AwsSpanMetricsProcessorTest.java

@@ -15,7 +15,9 @@
 
 package software.amazon.opentelemetry.javaagent.providers;
 
+import static io.opentelemetry.semconv.HttpAttributes.HTTP_REQUEST_METHOD;
 import static io.opentelemetry.semconv.HttpAttributes.HTTP_RESPONSE_STATUS_CODE;
+import static io.opentelemetry.semconv.UrlAttributes.URL_PATH;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
@@ -625,4 +627,41 @@ private void verifyHistogramRecords(
     verify(latencyHistogramMock, times(wantedDependencyMetricInvocation))
         .record(eq(TEST_LATENCY_MILLIS), eq(metricAttributesMap.get(DEPENDENCY_METRIC)));
   }
+
+  @Test
+  public void testOnEndAppliesOperationPathSpanNameBeforeMetrics() {
+    // Build a span with url.path that matches a configured operation path
+    Attributes spanAttributes =
+        Attributes.builder()
+            .put(URL_PATH, "/api/users/42/stats")
+            .put(HTTP_REQUEST_METHOD, "GET")
+            .put(HTTP_RESPONSE_STATUS_CODE, 200L)
+            .build();
+    ReadableSpan readableSpanMock = buildReadableSpanMock(spanAttributes);
+
+    try (org.mockito.MockedStatic<AwsSpanProcessingUtil> utilStatic =
+        org.mockito.Mockito.mockStatic(
+            AwsSpanProcessingUtil.class,
+            org.mockito.Mockito.withSettings()
+                .defaultAnswer(org.mockito.Mockito.CALLS_REAL_METHODS))) {
+      utilStatic
+          .when(AwsSpanProcessingUtil::getOperationPaths)
+          .thenReturn(java.util.List.of("/api/users/{userId}/stats"));
+
+      // Capture the SpanData passed to the generator
+      org.mockito.ArgumentCaptor<io.opentelemetry.sdk.trace.data.SpanData> spanCaptor =
+          org.mockito.ArgumentCaptor.forClass(io.opentelemetry.sdk.trace.data.SpanData.class);
+      Map<String, Attributes> metricAttributesMap =
+          buildMetricAttributes(CONTAINS_ATTRIBUTES, readableSpanMock.toSpanData());
+      when(generatorMock.generateMetricAttributeMapFromSpan(any(), eq(testResource)))
+          .thenReturn(metricAttributesMap);
+
+      awsSpanMetricsProcessor.onEnd(readableSpanMock);
+
+      // Verify the generator received a span with the overridden name
+      verify(generatorMock)
+          .generateMetricAttributeMapFromSpan(spanCaptor.capture(), eq(testResource));
+      assertThat(spanCaptor.getValue().getName()).isEqualTo("GET /api/users/{userId}/stats");
+    }
+  }
 }