Repository: newrelic/newrelic-java-agent
Issue: HttpURLConnection instrumentation does not mark trace as external

## Description
When a transaction has an HTTP call using `HttpURLConnection`, the distributed traces for the HTTP call do show as being in the same transaction and not as a remote call.

## Expected Behavior
These HTTP calls show as remotes, like calls that use Apache's HTTP client.

## Steps to Reproduce
Have 2 servers with DT enabled.
From one server, make an HTTP call using `HttpURLConnection` to the other.
Check DT.

## Your Environment
Java 16
Agent 7.2.0-SNAPSHOT
But most likely all other versions are affected.

Changed files:
newrelic-api/src/main/java/com/newrelic/api/agent/TracedMethod.java
functional_test/src/test/java/com/newrelic/agent/instrumentation/pointcuts/net/HttpURLConnectionTest.java
instrumentation/httpurlconnection/src/main/java/java/net/HttpURLConnection.java
agent-bridge/src/main/java/com/newrelic/agent/bridge/external/ExternalMetrics.java
functional_test/src/test/java/test/newrelic/test/agent/HttpCommonsTest.java
instrumentation/httpurlconnection/src/test/java/com/nr/agent/instrumentation/httpurlconnection/MetricStateResponseCodeTest.java
instrumentation/httpurlconnection/src/main/java/com/nr/agent/instrumentation/httpurlconnection/MetricState.java

diff --git a/agent-bridge/src/main/java/com/newrelic/agent/bridge/external/ExternalMetrics.java b/agent-bridge/src/main/java/com/newrelic/agent/bridge/external/ExternalMetrics.java
index a1d60832a..a2207c4ef 100644
--- a/agent-bridge/src/main/java/com/newrelic/agent/bridge/external/ExternalMetrics.java
+++ b/agent-bridge/src/main/java/com/newrelic/agent/bridge/external/ExternalMetrics.java
@@ -54,7 +54,7 @@ public class ExternalMetrics {
         // transaction segment name always contains operations; metric name may or may not
         String operationsPath = fixOperations(operations);
 
-        if(operationsPath == null) {
+        if (operationsPath == null) {
             String metricName = MessageFormat.format(METRIC_NAME, host, library);
             method.setMetricNameFormatInfo(metricName, metricName, uri);
         } else {
@@ -89,7 +89,7 @@ public class ExternalMetrics {
 
         makeExternalComponentMetric(method, hostName, library, includeOperationInMetric, uri, operations);
 
-        if(UNKNOWN_HOST.equals(hostName)) {
+        if (UNKNOWN_HOST.equals(hostName)) {
             return; // NR doesn't add rollup metrics for "UnknownHost"
         }
 
diff --git a/functional_test/src/test/java/com/newrelic/agent/instrumentation/pointcuts/net/HttpURLConnectionTest.java b/functional_test/src/test/java/com/newrelic/agent/instrumentation/pointcuts/net/HttpURLConnectionTest.java
index 4f1827810..8b1ad9593 100644
--- a/functional_test/src/test/java/com/newrelic/agent/instrumentation/pointcuts/net/HttpURLConnectionTest.java
+++ b/functional_test/src/test/java/com/newrelic/agent/instrumentation/pointcuts/net/HttpURLConnectionTest.java
@@ -7,8 +7,16 @@
 
 package com.newrelic.agent.instrumentation.pointcuts.net;
 
-import static java.text.MessageFormat.format;
-import static org.junit.Assert.assertEquals;
+import com.google.common.collect.Sets;
+import com.newrelic.agent.AgentHelper;
+import com.newrelic.agent.TransactionDataList;
+import com.newrelic.agent.metric.MetricName;
+import com.newrelic.agent.service.ServiceFactory;
+import com.newrelic.api.agent.Trace;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.BeforeClass;
+import org.junit.Test;
 
 import java.io.BufferedReader;
 import java.io.BufferedWriter;
@@ -23,16 +31,8 @@ import java.net.URLConnection;
 import java.util.Map;
 import java.util.Set;
 
-import com.google.common.collect.Sets;
-import com.newrelic.agent.AgentHelper;
-import com.newrelic.agent.TransactionDataList;
-import com.newrelic.agent.metric.MetricName;
-import com.newrelic.agent.service.ServiceFactory;
-import com.newrelic.api.agent.Trace;
-import org.junit.Assert;
-import org.junit.Before;
-import org.junit.BeforeClass;
-import org.junit.Test;
+import static java.text.MessageFormat.format;
+import static org.junit.Assert.assertEquals;
 
 public class HttpURLConnectionTest {
 
@@ -489,43 +489,68 @@ public class HttpURLConnectionTest {
             int scopedNetworkIOCount, int unscopedNetworkIOCount) {
         Set<String> metrics = AgentHelper.getMetrics();
 
+        String httpURLConnectionMetric = "External/{0}/HttpURLConnection";
+        String httpURLConnectionGetInputStreamMetric = "External/{0}/HttpURLConnection/getInputStream";
+        String httpURLConnectionGetResponseCodeMetric = "External/{0}/HttpURLConnection/getResponseCode";
+        String externalHostAllMetric = "External/{0}/all";
+        String externalAllMetric = "External/all";
+        String externalAllOtherMetric = "External/allOther";
+
         if (scopedHttpUrlCount > 0 || unscopedHttpUrlCount > 0) {
-            Assert.assertTrue(metrics.toString(), metrics.contains(format("External/{0}/HttpURLConnection", url)));
+            Assert.assertTrue(metrics.toString(),
+                    metrics.contains(format(httpURLConnectionMetric, url)) ||
+                            metrics.contains(format(httpURLConnectionGetInputStreamMetric, url)) ||
+                            metrics.contains(format(httpURLConnectionGetResponseCodeMetric, url)));
         } else {
-            Assert.assertFalse(metrics.toString(), metrics.contains(format("External/{0}/HttpURLConnection", url)));
+            Assert.assertFalse(metrics.toString(),
+                    metrics.contains(format(httpURLConnectionMetric, url)) ||
+                            metrics.contains(format(httpURLConnectionGetInputStreamMetric, url)) ||
+                            metrics.contains(format(httpURLConnectionGetResponseCodeMetric, url)));
         }
 
         if (scopedNetworkIOCount > 0 || unscopedNetworkIOCount > 0) {
-            Assert.assertTrue(metrics.toString(), metrics.contains(format("External/{0}/all", url)));
-            Assert.assertTrue(metrics.toString(), metrics.contains("External/all"));
-            Assert.assertTrue(metrics.toString(), metrics.contains("External/allOther"));
+            Assert.assertTrue(metrics.toString(), metrics.contains(format(externalHostAllMetric, url)));
+            Assert.assertTrue(metrics.toString(), metrics.contains(externalAllMetric));
+            Assert.assertTrue(metrics.toString(), metrics.contains(externalAllOtherMetric));
         } else {
-            Assert.assertFalse(metrics.toString(), metrics.contains(format("External/{0}/all", url)));
-            Assert.assertFalse(metrics.toString(), metrics.contains("External/all"));
-            Assert.assertFalse(metrics.toString(), metrics.contains("External/allOther"));
+            Assert.assertFalse(metrics.toString(), metrics.contains(format(externalHostAllMetric, url)));
+            Assert.assertFalse(metrics.toString(), metrics.contains(externalAllMetric));
+            Assert.assertFalse(metrics.toString(), metrics.contains(externalAllOtherMetric));
         }
 
         Map<String, Integer> scopedMetrics = getMetricCounts(
-                MetricName.create(format("External/{0}/HttpURLConnection", url), scope),
-                MetricName.create(format("External/{0}/all", url), scope),
-                MetricName.create("External/all", scope),
-                MetricName.create("External/allOther", scope));
+                MetricName.create(format(httpURLConnectionMetric, url), scope),
+                MetricName.create(format(httpURLConnectionGetInputStreamMetric, url), scope),
+                MetricName.create(format(httpURLConnectionGetResponseCodeMetric, url), scope),
+                MetricName.create(format(externalHostAllMetric, url), scope),
+                MetricName.create(externalAllMetric, scope),
+                MetricName.create(externalAllOtherMetric, scope));
 
         Map<String, Integer> unscopedMetrics = getMetricCounts(
-                MetricName.create(format("External/{0}/HttpURLConnection", url)),
-                MetricName.create(format("External/{0}/all", url)),
-                MetricName.create("External/all"),
-                MetricName.create("External/allOther"));
-
-        assertEquals(scopedHttpUrlCount, (int) scopedMetrics.get(format("External/{0}/HttpURLConnection", url)));
-        assertEquals(scopedNetworkIOCount, (int) scopedMetrics.get(format("External/{0}/all", url)));
-        assertEquals(scopedNetworkIOCount, (int) scopedMetrics.get("External/all"));
-        assertEquals(scopedNetworkIOCount, (int) scopedMetrics.get("External/allOther"));
-
-        assertEquals(unscopedHttpUrlCount, (int) unscopedMetrics.get(format("External/{0}/HttpURLConnection", url)));
-        assertEquals(unscopedNetworkIOCount, (int) unscopedMetrics.get(format("External/{0}/all", url)));
-        assertEquals(unscopedNetworkIOCount, (int) unscopedMetrics.get("External/all"));
-        assertEquals(unscopedNetworkIOCount, (int) unscopedMetrics.get("External/allOther"));
+                MetricName.create(format(httpURLConnectionMetric, url)),
+                MetricName.create(format(httpURLConnectionGetInputStreamMetric, url)),
+                MetricName.create(format(httpURLConnectionGetResponseCodeMetric, url)),
+                MetricName.create(format(externalHostAllMetric, url)),
+                MetricName.create(externalAllMetric),
+                MetricName.create(externalAllOtherMetric));
+
+        int actualHttpURLConnectionScopedMetricCount = scopedMetrics.get(format(httpURLConnectionMetric, url)) +
+                scopedMetrics.get(format(httpURLConnectionGetInputStreamMetric, url)) +
+                scopedMetrics.get(format(httpURLConnectionGetResponseCodeMetric, url));
+
+        int actualHttpURLConnectionUnscopedMetricCount = unscopedMetrics.get(format(httpURLConnectionMetric, url)) +
+                unscopedMetrics.get(format(httpURLConnectionGetInputStreamMetric, url)) +
+                unscopedMetrics.get(format(httpURLConnectionGetResponseCodeMetric, url));
+
+        assertEquals(scopedHttpUrlCount, actualHttpURLConnectionScopedMetricCount);
+        assertEquals(scopedNetworkIOCount, (int) scopedMetrics.get(format(externalHostAllMetric, url)));
+        assertEquals(scopedNetworkIOCount, (int) scopedMetrics.get(externalAllMetric));
+        assertEquals(scopedNetworkIOCount, (int) scopedMetrics.get(externalAllOtherMetric));
+
+        assertEquals(unscopedHttpUrlCount, actualHttpURLConnectionUnscopedMetricCount);
+        assertEquals(unscopedNetworkIOCount, (int) unscopedMetrics.get(format(externalHostAllMetric, url)));
+        assertEquals(unscopedNetworkIOCount, (int) unscopedMetrics.get(externalAllMetric));
+        assertEquals(unscopedNetworkIOCount, (int) unscopedMetrics.get(externalAllOtherMetric));
     }
 
     private Map<String, Integer> getMetricCounts(MetricName... responseTimeMetricNames) {
diff --git a/functional_test/src/test/java/test/newrelic/test/agent/HttpCommonsTest.java b/functional_test/src/test/java/test/newrelic/test/agent/HttpCommonsTest.java
index f63fed034..b60341294 100644
--- a/functional_test/src/test/java/test/newrelic/test/agent/HttpCommonsTest.java
+++ b/functional_test/src/test/java/test/newrelic/test/agent/HttpCommonsTest.java
@@ -65,13 +65,13 @@ public class HttpCommonsTest {
         httpURLConnectionTx();
 
         Set<String> metrics = AgentHelper.getMetrics();
-        assertTrue(metrics.toString(), metrics.contains("External/" + HOST + "/HttpURLConnection"));
+        assertTrue(metrics.toString(), metrics.contains("External/" + HOST + "/HttpURLConnection/getResponseCode"));
 
         Map<String, Integer> metricCounts = getMetricCounts(
-                MetricName.create("External/" + HOST + "/HttpURLConnection",
+                MetricName.create("External/" + HOST + "/HttpURLConnection/getResponseCode",
                         "OtherTransaction/Custom/test.newrelic.test.agent.HttpCommonsTest/httpURLConnectionTx"));
 
-        assertEquals(1, (int) metricCounts.get("External/" + HOST + "/HttpURLConnection"));
+        assertEquals(1, (int) metricCounts.get("External/" + HOST + "/HttpURLConnection/getResponseCode"));
     }
 
     @Trace(dispatcher = true)
diff --git a/instrumentation/httpurlconnection/src/main/java/com/nr/agent/instrumentation/httpurlconnection/MetricState.java b/instrumentation/httpurlconnection/src/main/java/com/nr/agent/instrumentation/httpurlconnection/MetricState.java
index 08330214f..bc68e2353 100644
--- a/instrumentation/httpurlconnection/src/main/java/com/nr/agent/instrumentation/httpurlconnection/MetricState.java
+++ b/instrumentation/httpurlconnection/src/main/java/com/nr/agent/instrumentation/httpurlconnection/MetricState.java
@@ -12,11 +12,13 @@ import com.newrelic.agent.bridge.TracedMethod;
 import com.newrelic.agent.bridge.Transaction;
 import com.newrelic.agent.bridge.external.ExternalMetrics;
 import com.newrelic.agent.bridge.external.URISupport;
+import com.newrelic.api.agent.HttpParameters;
 
 import java.net.HttpURLConnection;
+import java.net.URI;
 
 public class MetricState {
-
+    private static final String LIBRARY = "HttpURLConnection";
     private boolean metricsRecorded;
     private boolean recordedANetworkCall;
 
@@ -25,8 +27,9 @@ public class MetricState {
         Transaction tx = AgentBridge.getAgent().getTransaction(false);
         if (!isConnected && method.isMetricProducer() && tx != null) {
             // This method doesn't have any network I/O so we are explicitly not recording external rollup metrics
-            makeMetric(connection, method, operation);
-            tx.getCrossProcessState().processOutboundRequestHeaders(new OutboundWrapper(connection), method);
+            makeNonRollupExternalMetric(connection, method, operation);
+            // Add CAT/Distributed tracing headers to this outbound request
+            method.addOutboundRequestHeaders(new OutboundWrapper(connection));
         }
     }
 
@@ -35,11 +38,12 @@ public class MetricState {
         if (method.isMetricProducer() && tx != null) {
             if (!recordedANetworkCall) {
                 this.recordedANetworkCall = true;
-                makeMetric(connection, method, "getInputStream");
+                makeNonRollupExternalMetric(connection, method, "getInputStream");
             }
 
             if (!isConnected) {
-                tx.getCrossProcessState().processOutboundRequestHeaders(new OutboundWrapper(connection), method);
+                // Add CAT/Distributed tracing headers to this outbound request
+                method.addOutboundRequestHeaders(new OutboundWrapper(connection));
             }
         }
     }
@@ -48,27 +52,46 @@ public class MetricState {
         Transaction tx = AgentBridge.getAgent().getTransaction(false);
         if (method.isMetricProducer() && tx != null && !recordedANetworkCall) {
             this.recordedANetworkCall = true;
-            makeMetric(connection, method, "getResponseCode");
+            makeNonRollupExternalMetric(connection, method, "getResponseCode");
         }
     }
 
-    public void getInboundPostamble(HttpURLConnection connection, TracedMethod method) {
+    public void getInboundPostamble(HttpURLConnection connection, int responseCode, String responseMessage, String requestMethod, TracedMethod method) {
         Transaction tx = AgentBridge.getAgent().getTransaction(false);
         if (method.isMetricProducer() && !metricsRecorded && tx != null) {
             this.metricsRecorded = true;
+            // This conversion is necessary as it strips query parameters from the URI
             String uri = URISupport.getURI(connection.getURL());
             InboundWrapper inboundWrapper = new InboundWrapper(connection);
-            tx.getCrossProcessState()
-                    .processInboundResponseHeaders(inboundWrapper, method, connection.getURL().getHost(), uri, true);
+
+            // Add CAT/Distributed tracing headers to this outbound request
+            method.addOutboundRequestHeaders(new OutboundWrapper(connection));
+
+            // This will result in External rollup metrics being generated
+            method.reportAsExternal(HttpParameters
+                    .library(LIBRARY)
+                    .uri(URI.create(uri))
+                    .procedure(requestMethod)
+                    .inboundHeaders(inboundWrapper)
+                    .status(responseCode, responseMessage)
+                    .build());
         }
     }
 
-    private void makeMetric(HttpURLConnection connection, TracedMethod method, String operation) {
+    /**
+     * Sets external metric name (i.e. External/{HOST}/HttpURLConnection).
+     * This does not create rollup metrics such as External/all, External/allWeb, External/allOther, External/{HOST}/all
+     *
+     * @param connection HttpURLConnection instance
+     * @param method     TracedMethod instance
+     * @param operation  String representation of operation
+     */
+    private void makeNonRollupExternalMetric(HttpURLConnection connection, TracedMethod method, String operation) {
         String uri = URISupport.getURI(connection.getURL());
         ExternalMetrics.makeExternalComponentMetric(
                 method,
                 connection.getURL().getHost(),
-                "HttpURLConnection",
+                LIBRARY,
                 false,
                 uri,
                 operation);
diff --git a/instrumentation/httpurlconnection/src/main/java/java/net/HttpURLConnection.java b/instrumentation/httpurlconnection/src/main/java/java/net/HttpURLConnection.java
index 53dd026e8..72a1a34eb 100644
--- a/instrumentation/httpurlconnection/src/main/java/java/net/HttpURLConnection.java
+++ b/instrumentation/httpurlconnection/src/main/java/java/net/HttpURLConnection.java
@@ -42,14 +42,12 @@ public abstract class HttpURLConnection extends URLConnection {
     @Trace(leaf = true)
     public void connect() throws IOException {
         lazyGetMetricState().nonNetworkPreamble(connected, this, "connect");
-
         Weaver.callOriginal();
     }
 
     @Trace(leaf = true)
     public synchronized OutputStream getOutputStream() throws IOException {
         lazyGetMetricState().nonNetworkPreamble(connected, this, "getOutputStream");
-
         return Weaver.callOriginal();
     }
 
@@ -71,8 +69,7 @@ public abstract class HttpURLConnection extends URLConnection {
             throw e;
         }
 
-        metricState.getInboundPostamble(this, method);
-
+        metricState.getInboundPostamble(this, 0, null, "getInputStream", method);
         return inputStream;
     }
 
@@ -94,8 +91,7 @@ public abstract class HttpURLConnection extends URLConnection {
             throw e;
         }
 
-        metricState.getInboundPostamble(this, method);
-
+        metricState.getInboundPostamble(this, responseCodeValue, null, "getResponseCode", method);
         return responseCodeValue;
     }
 
diff --git a/instrumentation/httpurlconnection/src/test/java/com/nr/agent/instrumentation/httpurlconnection/MetricStateResponseCodeTest.java b/instrumentation/httpurlconnection/src/test/java/com/nr/agent/instrumentation/httpurlconnection/MetricStateResponseCodeTest.java
index 0c73a0303..1939c342e 100644
--- a/instrumentation/httpurlconnection/src/test/java/com/nr/agent/instrumentation/httpurlconnection/MetricStateResponseCodeTest.java
+++ b/instrumentation/httpurlconnection/src/test/java/com/nr/agent/instrumentation/httpurlconnection/MetricStateResponseCodeTest.java
@@ -8,18 +8,14 @@
 package com.nr.agent.instrumentation.httpurlconnection;
 
 import com.newrelic.agent.bridge.AgentBridge;
-import com.newrelic.agent.introspec.HttpTestServer;
 import com.newrelic.agent.introspec.InstrumentationTestConfig;
 import com.newrelic.agent.introspec.InstrumentationTestRunner;
 import com.newrelic.agent.introspec.Introspector;
 import com.newrelic.agent.introspec.TraceSegment;
 import com.newrelic.agent.introspec.TransactionEvent;
 import com.newrelic.agent.introspec.TransactionTrace;
-import com.newrelic.agent.introspec.internal.HttpServerLocator;
 import com.newrelic.agent.introspec.internal.HttpServerRule;
 import com.newrelic.api.agent.Trace;
-import org.junit.After;
-import org.junit.Before;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.runner.RunWith;
@@ -67,8 +63,8 @@ public class MetricStateResponseCodeTest {
         String transactionName = fetchTransactionName(introspector, "callGetResponseCode");
 
         // We only have one call to this external metric.
-        assertTrue(introspector.getMetricsForTransaction(transactionName).containsKey("External/localhost/HttpURLConnection"));
-        assertEquals(1, introspector.getMetricsForTransaction(transactionName).get("External/localhost/HttpURLConnection").getCallCount());
+        assertTrue(introspector.getMetricsForTransaction(transactionName).containsKey("External/localhost/HttpURLConnection/getResponseCode"));
+        assertEquals(1, introspector.getMetricsForTransaction(transactionName).get("External/localhost/HttpURLConnection/getResponseCode").getCallCount());
 
         // The number of segments is equal to the number of calls to getResponseCode.
         TransactionTrace trace = introspector.getTransactionTracesForTransaction(transactionName).iterator().next();
@@ -94,8 +90,8 @@ public class MetricStateResponseCodeTest {
 
         // Only one external call.
         String transactionName = fetchTransactionName(introspector, "callGetResponseCodeThenGetInputStream");
-        assertTrue(introspector.getMetricsForTransaction(transactionName).containsKey("External/localhost/HttpURLConnection"));
-        assertEquals(1, introspector.getMetricsForTransaction(transactionName).get("External/localhost/HttpURLConnection").getCallCount());
+        assertTrue(introspector.getMetricsForTransaction(transactionName).containsKey("External/localhost/HttpURLConnection/getResponseCode"));
+        assertEquals(1, introspector.getMetricsForTransaction(transactionName).get("External/localhost/HttpURLConnection/getResponseCode").getCallCount());
 
         // Two child segments within the transaction.
         TransactionTrace trace = introspector.getTransactionTracesForTransaction(transactionName).iterator().next();
@@ -125,8 +121,8 @@ public class MetricStateResponseCodeTest {
 
         // Only one external call.
         String transactionName = fetchTransactionName(introspector, "callGetInputStreamThenResponseCode");
-        assertTrue(introspector.getMetricsForTransaction(transactionName).containsKey("External/localhost/HttpURLConnection"));
-        assertEquals(1, introspector.getMetricsForTransaction(transactionName).get("External/localhost/HttpURLConnection").getCallCount());
+        assertTrue(introspector.getMetricsForTransaction(transactionName).containsKey("External/localhost/HttpURLConnection/getInputStream"));
+        assertEquals(1, introspector.getMetricsForTransaction(transactionName).get("External/localhost/HttpURLConnection/getInputStream").getCallCount());
 
         // Two child segments within the transaction.
         TransactionTrace trace = introspector.getTransactionTracesForTransaction(transactionName).iterator().next();
@@ -204,14 +200,12 @@ public class MetricStateResponseCodeTest {
     @Trace(leaf = true)
     private void simulatedInstrumentedGetResponseCodeMethod(HttpURLConnection conn, MetricState target) {
         target.getResponseCodePreamble(conn, AgentBridge.getAgent().getTracedMethod());
-
-        target.getInboundPostamble(conn, AgentBridge.getAgent().getTracedMethod());
+        target.getInboundPostamble(conn, 0, null, "getResponseCode", AgentBridge.getAgent().getTracedMethod());
     }
 
     @Trace(leaf = true)
     private void simulatedInstrumentedGetInputStreamMethod(boolean isConnected, HttpURLConnection conn, MetricState target) {
         target.getInputStreamPreamble(isConnected, conn, AgentBridge.getAgent().getTracedMethod());
-
-        target.getInboundPostamble(conn, AgentBridge.getAgent().getTracedMethod());
+        target.getInboundPostamble(conn, 0, null, "getInputStream", AgentBridge.getAgent().getTracedMethod());
     }
 }
diff --git a/newrelic-api/src/main/java/com/newrelic/api/agent/TracedMethod.java b/newrelic-api/src/main/java/com/newrelic/api/agent/TracedMethod.java
index d5207ee0e..a9006a61c 100644
--- a/newrelic-api/src/main/java/com/newrelic/api/agent/TracedMethod.java
+++ b/newrelic-api/src/main/java/com/newrelic/api/agent/TracedMethod.java
@@ -70,7 +70,8 @@ public interface TracedMethod extends AttributeHolder {
      *        determines if the external call is HTTP or JMS.
      * @since 3.36.0
      * @deprecated Instead, use the Distributed Tracing API {@link Transaction#insertDistributedTraceHeaders(Headers)} to create a
-     * distributed tracing payload
+     * distributed tracing payload. However, note that the <code>insertDistributedTraceHeaders</code> API only adds distributed tracing
+     * headers and does not add legacy CAT headers. If CAT must be supported then instead use this deprecated API.
      */
     @Deprecated
     void addOutboundRequestHeaders(OutboundHeaders outboundHeaders);