Merge branch 'main' into suppression-keys

Author: laurit

.github/scripts/check-latest-dep-test-overrides.sh

@@ -0,0 +1,21 @@
+#!/bin/bash -e
+
+# all missing version coverage should be documented in supported-libraries.md
+
+if grep -r --include build.gradle.kts latestDepTestLibrary instrumentation \
+    | grep -v :+\" \
+    | grep -v "// see .* module" \
+    | grep -v "// see test suite below" \
+    | grep -v "// no longer applicable" \
+    | grep -v "// related dependency" \
+    | grep -v "// native on-by-default instrumentation after this version" \
+    | grep -v "// documented limitation" \
+    | grep -v "instrumentation/jaxrs-client/jaxrs-client-2.0-testing/build.gradle.kts"; then
+
+  echo
+  echo "Found an undocumented latestDepTestLibrary (see above)."
+  echo
+  echo "See .gith/scripts/check-latest-dep-test-overrides.sh in this repository"
+  echo "and add one of the required comments."
+  exit 1
+fi

.github/scripts/find-instrumentation-with-upper-version-limits.sh

@@ -126,6 +126,13 @@ jobs:
 
       - run: .github/scripts/check-javaagent-suppression-keys.sh
 
+  check-latest-dep-test-overrides:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - run: .github/scripts/check-latest-dep-test-overrides.sh
+
   build:
     runs-on: ubuntu-latest
     steps:

.github/workflows/build-common.yml

@@ -4,8 +4,18 @@ Comparing source compatibility of opentelemetry-instrumentation-api-2.12.0-SNAPS
 	GENERIC TEMPLATES: === REQUEST:java.lang.Object, === RESPONSE:java.lang.Object
 	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.instrumentation.api.semconv.http.HttpClientAttributesExtractorBuilder<REQUEST,RESPONSE> setCapturedRequestHeaders(java.util.Collection<java.lang.String>)
 	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.instrumentation.api.semconv.http.HttpClientAttributesExtractorBuilder<REQUEST,RESPONSE> setCapturedResponseHeaders(java.util.Collection<java.lang.String>)
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.instrumentation.api.semconv.http.HttpClientAttributesExtractorBuilder<REQUEST,RESPONSE> setKnownMethods(java.util.Collection<java.lang.String>)
 ***  MODIFIED CLASS: PUBLIC FINAL io.opentelemetry.instrumentation.api.semconv.http.HttpServerAttributesExtractorBuilder  (not serializable)
 	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
 	GENERIC TEMPLATES: === REQUEST:java.lang.Object, === RESPONSE:java.lang.Object
 	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.instrumentation.api.semconv.http.HttpServerAttributesExtractorBuilder<REQUEST,RESPONSE> setCapturedRequestHeaders(java.util.Collection<java.lang.String>)
 	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.instrumentation.api.semconv.http.HttpServerAttributesExtractorBuilder<REQUEST,RESPONSE> setCapturedResponseHeaders(java.util.Collection<java.lang.String>)
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.instrumentation.api.semconv.http.HttpServerAttributesExtractorBuilder<REQUEST,RESPONSE> setKnownMethods(java.util.Collection<java.lang.String>)
+***  MODIFIED CLASS: PUBLIC FINAL io.opentelemetry.instrumentation.api.semconv.http.HttpServerRouteBuilder  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	GENERIC TEMPLATES: === REQUEST:java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.instrumentation.api.semconv.http.HttpServerRouteBuilder<REQUEST> setKnownMethods(java.util.Collection<java.lang.String>)
+***  MODIFIED CLASS: PUBLIC FINAL io.opentelemetry.instrumentation.api.semconv.http.HttpSpanNameExtractorBuilder  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	GENERIC TEMPLATES: === REQUEST:java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.instrumentation.api.semconv.http.HttpSpanNameExtractorBuilder<REQUEST> setKnownMethods(java.util.Collection<java.lang.String>)

docs/apidiffs/current_vs_latest/opentelemetry-instrumentation-api.txt

@@ -84,14 +84,16 @@ Response decoratedMethod(Request request) {
   }
 
   Context context = instrumenter.start(parentContext, request);
+  Response response;
   try (Scope scope = context.makeCurrent()) {
-    Response response = actualMethod(request);
-    instrumenter.end(context, request, response, null);
-    return response;
-  } catch (Throwable error) {
-    instrumenter.end(context, request, null, error);
-    throw error;
+    response = actualMethod(request);
+  } catch (Throwable t) {
+    instrumenter.end(context, request, null, t);
+    throw t;
   }
+  // calling end after the scope is closed is a best practice
+  instrumenter.end(context, request, response, null);
+  return response;
 }
 ```
 

docs/contributing/using-instrumenter-api.md

@@ -31,7 +31,6 @@
 import java.util.Collection;
 import java.util.List;
 import java.util.Objects;
-import java.util.Set;
 import java.util.function.Consumer;
 import java.util.function.Function;
 import java.util.function.Supplier;
@@ -155,11 +154,11 @@ public DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> setCapturedRespon
    * not supplement it.
    *
    * @param knownMethods A set of recognized HTTP request methods.
-   * @see HttpClientAttributesExtractorBuilder#setKnownMethods(Set)
+   * @see HttpClientAttributesExtractorBuilder#setKnownMethods(Collection)
    */
   @CanIgnoreReturnValue
   public DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> setKnownMethods(
-      Set<String> knownMethods) {
+      Collection<String> knownMethods) {
     httpAttributesExtractorBuilder.setKnownMethods(knownMethods);
     httpSpanNameExtractorBuilder.setKnownMethods(knownMethods);
     return this;

docs/supported-libraries.md

@@ -30,7 +30,6 @@
 import java.util.Collection;
 import java.util.List;
 import java.util.Objects;
-import java.util.Set;
 import java.util.function.Consumer;
 import java.util.function.Function;
 import java.util.function.Supplier;
@@ -153,11 +152,11 @@ public DefaultHttpServerInstrumenterBuilder<REQUEST, RESPONSE> setCapturedRespon
    * not supplement it.
    *
    * @param knownMethods A set of recognized HTTP request methods.
-   * @see HttpServerAttributesExtractorBuilder#setKnownMethods(Set)
+   * @see HttpServerAttributesExtractorBuilder#setKnownMethods(Collection)
    */
   @CanIgnoreReturnValue
   public DefaultHttpServerInstrumenterBuilder<REQUEST, RESPONSE> setKnownMethods(
-      Set<String> knownMethods) {
+      Collection<String> knownMethods) {
     httpAttributesExtractorBuilder.setKnownMethods(knownMethods);
     httpSpanNameExtractorBuilder.setKnownMethods(knownMethods);
     httpServerRouteBuilder.setKnownMethods(knownMethods);

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/builder/internal/DefaultHttpClientInstrumenterBuilder.java

@@ -137,11 +137,34 @@ public HttpClientAttributesExtractorBuilder<REQUEST, RESPONSE> setCapturedRespon
    */
   @CanIgnoreReturnValue
   public HttpClientAttributesExtractorBuilder<REQUEST, RESPONSE> setKnownMethods(
-      Set<String> knownMethods) {
+      Collection<String> knownMethods) {
     this.knownMethods = new HashSet<>(knownMethods);
     return this;
   }
 
+  /**
+   * Configures the extractor to recognize an alternative set of HTTP request methods.
+   *
+   * <p>By default, this extractor defines "known" methods as the ones listed in <a
+   * href="https://www.rfc-editor.org/rfc/rfc9110.html#name-methods">RFC9110</a> and the PATCH
+   * method defined in <a href="https://www.rfc-editor.org/rfc/rfc5789.html">RFC5789</a>. If an
+   * unknown method is encountered, the extractor will use the value {@value HttpConstants#_OTHER}
+   * instead of it and put the original value in an extra {@code http.request.method_original}
+   * attribute.
+   *
+   * <p>Note: calling this method <b>overrides</b> the default known method sets completely; it does
+   * not supplement it.
+   *
+   * @param knownMethods A set of recognized HTTP request methods.
+   */
+  // don't deprecate this since users will get deprecation warning without a clean way to suppress
+  // it if they're using Set
+  @CanIgnoreReturnValue
+  public HttpClientAttributesExtractorBuilder<REQUEST, RESPONSE> setKnownMethods(
+      Set<String> knownMethods) {
+    return setKnownMethods((Collection<String>) knownMethods);
+  }
+
   // visible for tests
   @CanIgnoreReturnValue
   HttpClientAttributesExtractorBuilder<REQUEST, RESPONSE> setResendCountIncrementer(

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/builder/internal/DefaultHttpServerInstrumenterBuilder.java

@@ -144,11 +144,34 @@ public HttpServerAttributesExtractorBuilder<REQUEST, RESPONSE> setCapturedRespon
    */
   @CanIgnoreReturnValue
   public HttpServerAttributesExtractorBuilder<REQUEST, RESPONSE> setKnownMethods(
-      Set<String> knownMethods) {
+      Collection<String> knownMethods) {
     this.knownMethods = new HashSet<>(knownMethods);
     return this;
   }
 
+  /**
+   * Configures the extractor to recognize an alternative set of HTTP request methods.
+   *
+   * <p>By default, this extractor defines "known" methods as the ones listed in <a
+   * href="https://www.rfc-editor.org/rfc/rfc9110.html#name-methods">RFC9110</a> and the PATCH
+   * method defined in <a href="https://www.rfc-editor.org/rfc/rfc5789.html">RFC5789</a>. If an
+   * unknown method is encountered, the extractor will use the value {@value HttpConstants#_OTHER}
+   * instead of it and put the original value in an extra {@code http.request.method_original}
+   * attribute.
+   *
+   * <p>Note: calling this method <b>overrides</b> the default known method sets completely; it does
+   * not supplement it.
+   *
+   * @param knownMethods A set of recognized HTTP request methods.
+   */
+  // don't deprecate this since users will get deprecation warning without a clean way to suppress
+  // it if they're using Set
+  @CanIgnoreReturnValue
+  public HttpServerAttributesExtractorBuilder<REQUEST, RESPONSE> setKnownMethods(
+      Set<String> knownMethods) {
+    return setKnownMethods((Collection<String>) knownMethods);
+  }
+
   // visible for tests
   @CanIgnoreReturnValue
   HttpServerAttributesExtractorBuilder<REQUEST, RESPONSE> setHttpRouteGetter(