Issue 1699 extend destination field

CHANGELOG.asciidoc

@@ -43,6 +43,8 @@ setting `disable_instrumentations=jdbc` would disable jdbc and also enable exper
 ** Previously, by default `disable_instrumentations` contained `experimental`
 ** Now by default `disable_instrumentations` is empty and `enable_experimental_instrumentations=false`
 ** Set `disable_instrumentations=true` to enable experimental instrumentations
+* Adding public APIs for setting `destination.service.resource`, `destination.address` and `destination.port` fields
+for exit spans - {pull}1788[#1788]
 
 [float]
 ===== Bug fixes

apm-agent-api/src/main/java/co/elastic/apm/api/AbstractSpanImpl.java

@@ -160,4 +160,12 @@ public void injectTraceHeaders(HeaderInjector headerInjector) {
     private void doInjectTraceHeaders(MethodHandle addHeader, HeaderInjector headerInjector) {
         // co.elastic.apm.agent.pluginapi.AbstractSpanInstrumentation.InjectTraceHeadersInstrumentation
     }
+
+    protected void doSetDestinationAddress(@Nullable String address, int port) {
+        // co.elastic.apm.agent.pluginapi.AbstractSpanInstrumentation.SetDestinationAddressInstrumentation
+    }
+
+    protected void doSetDestinationService(@Nullable String resource) {
+        // co.elastic.apm.agent.pluginapi.AbstractSpanInstrumentation.SetDestinationServiceInstrumentation
+    }
 }

apm-agent-api/src/main/java/co/elastic/apm/api/NoopSpan.java

@@ -165,4 +165,16 @@ public Span setOutcome(Outcome outcome) {
     public void injectTraceHeaders(HeaderInjector headerInjector) {
         // noop
     }
+
+    @Nonnull
+    @Override
+    public Span setDestinationAddress(@Nullable String address, int port) {
+        return this;
+    }
+
+    @Nonnull
+    @Override
+    public Span setDestinationService(@Nullable String resource) {
+        return this;
+    }
 }

apm-agent-api/src/main/java/co/elastic/apm/api/NoopTransaction.java

@@ -205,4 +205,16 @@ public Transaction setOutcome(Outcome outcome) {
     public void injectTraceHeaders(HeaderInjector headerInjector) {
         // noop
     }
+
+    @Nonnull
+    @Override
+    public Span setDestinationAddress(@Nullable String address, int port) {
+        return this;
+    }
+
+    @Nonnull
+    @Override
+    public Span setDestinationService(@Nullable String resource) {
+        return this;
+    }
 }

apm-agent-api/src/main/java/co/elastic/apm/api/Span.java

@@ -424,4 +424,34 @@ public interface Span {
      */
     void injectTraceHeaders(HeaderInjector headerInjector);
 
+    /**
+     * Provides a way to manually set the destination address and port for this span. If used, values will override
+     * the automatically discovered ones, if there are such.
+     * Any value set through this method will take precedence over the automatically discovered one.
+     *
+     * NOTE: this is only relevant for spans that represent outgoing communication. Trying to invoke this method
+     * on a {@link Transaction} object will result with an {@link UnsupportedOperationException}.
+     *
+     * @param address a string representation of the destination host name or IP. {@code null} and empty values will
+     *                will cause the exclusion of the address field from the span context.
+     * @param port the destination port. Non-positive values will cause the exclusion of the port field from the span context.
+     * @return this span
+     */
+    @Nonnull
+    Span setDestinationAddress(@Nullable String address, int port);
+
+    /**
+     * Provides a way to manually set the {@code destination.service.resource} field, which is used for the construction
+     * of service maps and the identification of downstream services.
+     * Any value set through this method will take precedence over the automatically inferred one.
+     *
+     * NOTE: this is only relevant for spans that represent outgoing communication. Trying to invoke this method
+     * on a {@link Transaction} object will result with an {@link UnsupportedOperationException}.
+     *
+     * @param resource the string representation of the downstream service. Will be used to override automatically
+     *                 inferred value, even if {@code null}.
+     * @return this span
+     */
+    @Nonnull
+    Span setDestinationService(@Nullable String resource);
 }

apm-agent-api/src/main/java/co/elastic/apm/api/SpanImpl.java

@@ -25,6 +25,7 @@
 package co.elastic.apm.api;
 
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 
 /**
  * If the agent is active, it injects the implementation into this class.
@@ -116,4 +117,18 @@ public Span setOutcome(Outcome outcome) {
         doSetOutcome(outcome);
         return this;
     }
+
+    @Nonnull
+    @Override
+    public Span setDestinationAddress(@Nullable String address, int port) {
+        doSetDestinationAddress(address, port);
+        return this;
+    }
+
+    @Nonnull
+    @Override
+    public Span setDestinationService(@Nullable String resource) {
+        doSetDestinationService(resource);
+        return this;
+    }
 }

apm-agent-api/src/main/java/co/elastic/apm/api/TransactionImpl.java

@@ -25,6 +25,7 @@
 package co.elastic.apm.api;
 
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 
 /**
  * If the agent is active, it injects the implementation from
@@ -164,4 +165,24 @@ public Transaction setOutcome(Outcome outcome) {
         doSetOutcome(outcome);
         return this;
     }
+
+    /**
+     * @deprecated - used only for {@link co.elastic.apm.api.Span}
+     */
+    @Nonnull
+    @Override
+    @Deprecated
+    public Transaction setDestinationAddress(@Nullable String address, int port) {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * @deprecated - used only for {@link co.elastic.apm.api.Span}
+     */
+    @Nonnull
+    @Override
+    @Deprecated
+    public Transaction setDestinationService(@Nullable String resource) {
+        throw new UnsupportedOperationException();
+    }
 }

apm-agent-core/src/main/java/co/elastic/apm/agent/impl/context/Destination.java

@@ -41,15 +41,29 @@ public class Destination implements Recyclable {
      */
     private final StringBuilder address = new StringBuilder();
 
+    private boolean addressSetByUser;
+
     /**
      * The destination's port used within this context.
      */
     private int port;
 
+    private boolean portSetByUser;
+
     public Destination withAddress(@Nullable CharSequence address) {
-        if (address != null) {
-            return withAddress(address, 0, address.length());
+        if (address != null && !addressSetByUser) {
+            withAddress(address, 0, address.length());
+        }
+        return this;
+    }
+
+    public Destination withUserAddress(@Nullable CharSequence address) {
+        if (address == null || address.length() == 0) {
+            this.address.setLength(0);
+        } else {
+            withAddress(address, 0, address.length());
         }
+        addressSetByUser = true;
         return this;
     }
 
@@ -58,7 +72,15 @@ public StringBuilder getAddress() {
     }
 
     public Destination withPort(int port) {
-        this.port = port;
+        if (!portSetByUser) {
+            this.port = port;
+        }
+        return this;
+    }
+
+    public Destination withUserPort(int port) {
+        withPort(port);
+        portSetByUser = true;
         return this;
     }
 
@@ -78,8 +100,10 @@ public Destination withAddressPort(@Nullable String addressPort) {
                 int port = parsePort(addressPort, separator + 1, addressPort.length());
 
                 if (port > 0) {
-                    return withPort(port)
-                        .withAddress(addressPort, 0, separator);
+                    withPort(port);
+                    if (!addressSetByUser) {
+                        withAddress(addressPort, 0, separator);
+                    }
                 }
             }
         }
@@ -102,13 +126,7 @@ private static int parsePort(CharSequence input, int start, int end) {
         return port;
     }
 
-    /**
-     * @param address address buffer
-     * @param start   address start (inclusive)
-     * @param end     address end (exclusive)
-     * @return destination with updated address
-     */
-    private Destination withAddress(CharSequence address, int start, int end) {
+    private void withAddress(CharSequence address, int start, int end) {
         if (address.length() > 0 && start < end) {
             int startIndex = start;
             int endIndex = end - 1;
@@ -127,7 +145,6 @@ private Destination withAddress(CharSequence address, int start, int end) {
                 this.address.append(address, startIndex, endIndex + 1);
             }
         }
-        return this;
     }
 
     /**
@@ -146,7 +163,9 @@ public boolean hasContent() {
     @Override
     public void resetState() {
         address.setLength(0);
+        addressSetByUser = false;
         port = 0;
+        portSetByUser = false;
         service.resetState();
     }
 
@@ -185,57 +204,83 @@ public static class Service implements Recyclable {
          */
         private final StringBuilder resource = new StringBuilder();
 
+        private boolean resourceSetByUser;
+
         /**
          * Used for detecting “sameness” of services and then the display name of a service in the Service Map.
          * In other words, the {@link Service#resource} is used to query data for ALL destinations. However,
          * some `resources` may be nodes of the same cluster, in which case we also want to be aware.
          * Eventually, we may decide to actively fetch a cluster name or similar and we could use that to detect "sameness".
          * For now, for HTTP we use scheme, host, and non-default port. For anything else, we use {@code span.subtype}
          * (for example- postgresql, elasticsearch).
+         *
+         * @deprecated will be removed
          */
         private final StringBuilder name = new StringBuilder();
 
         /**
          * For displaying icons or similar. Currently, this should be equal to the {@code span.type}.
+         *
+         * @deprecated will be removed
          */
         @Nullable
         private String type;
 
+        public Service withUserResource(@Nullable String resource) {
+            if (resource == null || resource.isEmpty()) {
+                this.resource.setLength(0);
+            } else {
+                setResourceValue(resource);
+            }
+            resourceSetByUser = true;
+            return this;
+        }
+
         public Service withResource(String resource) {
-            this.resource.append(resource);
+            if (!resourceSetByUser) {
+                setResourceValue(resource);
+            }
             return this;
         }
 
+        private void setResourceValue(String newValue) {
+            resource.setLength(0);
+            resource.append(newValue);
+        }
+
         public StringBuilder getResource() {
             return resource;
         }
 
+        @Deprecated
         public Service withName(String name) {
-            this.name.append(name);
             return this;
         }
 
+        @Deprecated
         public StringBuilder getName() {
             return name;
         }
 
-        public Service withType(String type) {
-            this.type = type;
+        @Deprecated
+        public Service withType(@Nullable String type) {
             return this;
         }
 
         @Nullable
+        @Deprecated
         public String getType() {
             return type;
         }
 
         public boolean hasContent() {
-            return resource.length() > 0 || name.length() > 0 || type != null;
+            return resource.length() > 0;
         }
 
         @Override
         public void resetState() {
             resource.setLength(0);
+            resourceSetByUser = false;
             name.setLength(0);
             type = null;
         }

apm-agent-core/src/main/java/co/elastic/apm/agent/report/serialize/DslJsonSerializer.java

@@ -857,25 +857,36 @@ private void serializeDestination(Destination destination) {
         if (destination.hasContent()) {
             writeFieldName("destination");
             jw.writeByte(OBJECT_START);
-            if (destination.getAddress().length() > 0) {
-                writeField("address", destination.getAddress());
+            boolean isExistAddress = destination.getAddress().length() > 0;
+            boolean isExistPort = destination.getPort() > 0;
+            boolean isServiceHasContent = destination.getService().hasContent();
+            if (isExistAddress) {
+                if (isExistPort || isServiceHasContent) {
+                    writeField("address", destination.getAddress());
+                } else {
+                    writeLastField("address", destination.getAddress());
+                }
             }
-            if (destination.getPort() > 0) {
-                writeField("port", destination.getPort());
+            if (isExistPort) {
+                if (isServiceHasContent) {
+                    writeField("port", destination.getPort());
+                } else {
+                    writeLastField("port", destination.getPort());
+                }
             }
-            serializeService(destination.getService());
+            serializeService(isServiceHasContent, destination.getService());
             jw.writeByte(OBJECT_END);
             jw.writeByte(COMMA);
         }
     }
 
-    private void serializeService(Destination.Service service) {
-        if (service.hasContent()) {
+    private void serializeService(boolean isServiceHasContent, Destination.Service service) {
+        if (isServiceHasContent) {
             writeFieldName("service");
             jw.writeByte(OBJECT_START);
-            writeField("name", service.getName());
-            writeField("resource", service.getResource());
-            writeLastField("type", service.getType());
+            writeEmptyField("name");
+            writeEmptyField("type");
+            writeLastField("resource", service.getResource());
             jw.writeByte(OBJECT_END);
         }
     }
@@ -1243,6 +1254,12 @@ private void serializeUser(final User user) {
         jw.writeByte(OBJECT_END);
     }
 
+    void writeEmptyField(final String fieldName) {
+        writeFieldName(fieldName);
+        writeStringValue("");
+        jw.writeByte(COMMA);
+    }
+
     void writeField(final String fieldName, final StringBuilder value) {
         if (value.length() > 0) {
             writeFieldName(fieldName);