Deprecate InetSocketAddressNetServerAttributesGetter and move its met…

instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/net/InetSocketAddressNetClientAttributesGetter.java

@@ -5,8 +5,6 @@
 
 package io.opentelemetry.instrumentation.api.instrumenter.net;
 
-import java.net.Inet6Address;
-import java.net.InetAddress;
 import java.net.InetSocketAddress;
 import javax.annotation.Nullable;
 
@@ -27,48 +25,24 @@ protected abstract InetSocketAddress getPeerSocketAddress(
   @Nullable
   @Override
   public String getSockFamily(REQUEST request, @Nullable RESPONSE response) {
-    InetSocketAddress address = getPeerSocketAddress(request, response);
-    if (address == null) {
-      return null;
-    }
-    InetAddress remoteAddress = address.getAddress();
-    if (remoteAddress instanceof Inet6Address) {
-      return "inet6";
-    }
-    return null;
+    return InetSocketAddressUtil.getSockFamily(getPeerSocketAddress(request, response), null);
   }
 
   @Override
   @Nullable
   public final String getSockPeerAddr(REQUEST request, @Nullable RESPONSE response) {
-    InetSocketAddress address = getPeerSocketAddress(request, response);
-    if (address == null) {
-      return null;
-    }
-    InetAddress remoteAddress = address.getAddress();
-    if (remoteAddress != null) {
-      return remoteAddress.getHostAddress();
-    }
-    return null;
+    return InetSocketAddressUtil.getHostAddress(getPeerSocketAddress(request, response));
   }
 
   @Override
   @Nullable
   public String getSockPeerName(REQUEST request, @Nullable RESPONSE response) {
-    InetSocketAddress address = getPeerSocketAddress(request, response);
-    if (address == null) {
-      return null;
-    }
-    return address.getHostString();
+    return InetSocketAddressUtil.getHostName(getPeerSocketAddress(request, response));
   }
 
   @Nullable
   @Override
   public Integer getSockPeerPort(REQUEST request, @Nullable RESPONSE response) {
-    InetSocketAddress address = getPeerSocketAddress(request, response);
-    if (address == null) {
-      return null;
-    }
-    return address.getPort();
+    return InetSocketAddressUtil.getPort(getPeerSocketAddress(request, response));
   }
 }

instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/net/InetSocketAddressNetServerAttributesGetter.java

@@ -5,86 +5,28 @@
 
 package io.opentelemetry.instrumentation.api.instrumenter.net;
 
-import java.net.Inet6Address;
-import java.net.InetAddress;
 import java.net.InetSocketAddress;
 import javax.annotation.Nullable;
 
 /**
  * Extractor of <a
  * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/span-general.md#general-network-connection-attributes">Network
- * attributes</a> from a {@link InetSocketAddress}. Most network libraries will provide access to a
- * {@link InetSocketAddress} so this is a convenient alternative to {@link
- * NetServerAttributesExtractor}. There is no meaning to implement both in the same instrumentation.
+ * attributes</a> from a {@link InetSocketAddress}.
+ *
+ * @deprecated Use {@link NetServerAttributesGetter} and its {@link
+ *     NetServerAttributesGetter#getPeerSocketAddress(Object)} {@link
+ *     NetServerAttributesGetter#getHostSocketAddress(Object)} methods instead.
  */
+@Deprecated
 public abstract class InetSocketAddressNetServerAttributesGetter<REQUEST>
     implements NetServerAttributesGetter<REQUEST> {
 
-  @Nullable
-  protected abstract InetSocketAddress getPeerSocketAddress(REQUEST request);
-
-  // optional
-  @Nullable
-  protected abstract InetSocketAddress getHostSocketAddress(REQUEST request);
-
   @Nullable
   @Override
-  public String getSockFamily(REQUEST request) {
-    InetSocketAddress address = getPeerSocketAddress(request);
-    if (address == null) {
-      address = getHostSocketAddress(request);
-    }
-    if (address == null) {
-      return null;
-    }
-    InetAddress inetAddress = address.getAddress();
-    if (inetAddress instanceof Inet6Address) {
-      return "inet6";
-    }
-    return null;
-  }
-
-  @Override
-  @Nullable
-  public final String getSockPeerAddr(REQUEST request) {
-    return getAddress(getPeerSocketAddress(request));
-  }
-
-  @Override
-  @Nullable
-  public final Integer getSockPeerPort(REQUEST request) {
-    return getPort(getPeerSocketAddress(request));
-  }
-
-  @Nullable
-  @Override
-  public String getSockHostAddr(REQUEST request) {
-    return getAddress(getHostSocketAddress(request));
-  }
+  public abstract InetSocketAddress getPeerSocketAddress(REQUEST request);
 
+  // optional
   @Nullable
   @Override
-  public Integer getSockHostPort(REQUEST request) {
-    return getPort(getHostSocketAddress(request));
-  }
-
-  @Nullable
-  private static String getAddress(InetSocketAddress address) {
-    if (address == null) {
-      return null;
-    }
-    InetAddress remoteAddress = address.getAddress();
-    if (remoteAddress != null) {
-      return remoteAddress.getHostAddress();
-    }
-    return null;
-  }
-
-  @Nullable
-  private static Integer getPort(InetSocketAddress address) {
-    if (address == null) {
-      return null;
-    }
-    return address.getPort();
-  }
+  public abstract InetSocketAddress getHostSocketAddress(REQUEST request);
 }

instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/net/InetSocketAddressUtil.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.instrumenter.net;
+
+import java.net.Inet6Address;
+import java.net.InetAddress;
+import java.net.InetSocketAddress;
+import javax.annotation.Nullable;
+
+final class InetSocketAddressUtil {
+
+  @Nullable
+  static String getSockFamily(
+      @Nullable InetSocketAddress address, @Nullable InetSocketAddress otherAddress) {
+    if (address == null) {
+      address = otherAddress;
+    }
+    if (address == null) {
+      return null;
+    }
+    InetAddress remoteAddress = address.getAddress();
+    if (remoteAddress instanceof Inet6Address) {
+      return "inet6";
+    }
+    return null;
+  }
+
+  @Nullable
+  static String getHostName(@Nullable InetSocketAddress address) {
+    if (address == null) {
+      return null;
+    }
+    return address.getHostString();
+  }
+
+  @Nullable
+  static String getHostAddress(@Nullable InetSocketAddress address) {
+    if (address == null) {
+      return null;
+    }
+    InetAddress remoteAddress = address.getAddress();
+    if (remoteAddress == null) {
+      return null;
+    }
+    return remoteAddress.getHostAddress();
+  }
+
+  @Nullable
+  static Integer getPort(@Nullable InetSocketAddress address) {
+    if (address == null) {
+      return null;
+    }
+    return address.getPort();
+  }
+
+  private InetSocketAddressUtil() {}
+}

instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/net/NetServerAttributesExtractor.java

@@ -15,8 +15,7 @@
 /**
  * Extractor of <a
  * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/span-general.md#general-network-connection-attributes">Network
- * attributes</a>. It is common to have access to {@link java.net.InetSocketAddress}, in which case
- * it is more convenient to use {@link InetSocketAddressNetServerAttributesGetter}.
+ * attributes</a>.
  */
 public final class NetServerAttributesExtractor<REQUEST, RESPONSE>
     implements AttributesExtractor<REQUEST, RESPONSE> {

instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/net/NetServerAttributesGetter.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.instrumentation.api.instrumenter.net;
 
+import java.net.InetSocketAddress;
 import javax.annotation.Nullable;
 
 /**
@@ -48,28 +49,105 @@ default String getProtocolVersion(REQUEST request) {
   @Nullable
   Integer getHostPort(REQUEST request);
 
+  /**
+   * Returns the protocol <a
+   * href="https://man7.org/linux/man-pages/man7/address_families.7.html">address family</a> which
+   * is used for communication.
+   *
+   * <p>Examples: `inet`, `inet6`.
+   *
+   * <p>By default, this method attempts to retrieve the address family using one of the {@link
+   * #getPeerSocketAddress(Object)} and {@link #getHostSocketAddress(Object)} methods. If neither of
+   * these methods is implemented, it will simply return {@code null}. If the instrumented library
+   * does not expose {@link InetSocketAddress} in its API, you might want to implement this method
+   * instead of {@link #getPeerSocketAddress(Object)} and {@link #getHostSocketAddress(Object)}.
+   */
   @Nullable
   default String getSockFamily(REQUEST request) {
+    return InetSocketAddressUtil.getSockFamily(
+        getPeerSocketAddress(request), getHostSocketAddress(request));
+  }
+
+  /**
+   * Returns an {@link InetSocketAddress} object representing the peer socket address.
+   *
+   * <p>Implementing this method is equivalent to implementing all three of {@link
+   * #getSockFamily(Object)}, {@link #getSockPeerAddr(Object)} and {@link #getSockPeerPort(Object)}.
+   */
+  @Nullable
+  default InetSocketAddress getPeerSocketAddress(REQUEST request) {
     return null;
   }
 
+  /**
+   * Returns the remote socket peer address: IPv4 or IPv6 for internet protocols, path for local
+   * communication, etc.
+   *
+   * <p>Examples: `127.0.0.1`, `/tmp/mysql.sock`.
+   *
+   * <p>By default, this method attempts to retrieve the peer address using the {@link
+   * #getPeerSocketAddress(Object)} method. If this method is not implemented, it will simply return
+   * {@code null}. If the instrumented library does not expose {@link InetSocketAddress} in its API,
+   * you might want to implement this method instead of {@link #getPeerSocketAddress(Object)}.
+   */
   @Nullable
   default String getSockPeerAddr(REQUEST request) {
-    return null;
+    return InetSocketAddressUtil.getHostAddress(getPeerSocketAddress(request));
   }
 
+  /**
+   * Returns the remote socket peer port.
+   *
+   * <p>Examples: `16456`.
+   *
+   * <p>By default, this method attempts to retrieve the peer port using the {@link
+   * #getPeerSocketAddress(Object)} method. If this method is not implemented, it will simply return
+   * {@code null}. If the instrumented library does not expose {@link InetSocketAddress} in its API,
+   * you might want to implement this method instead of {@link #getPeerSocketAddress(Object)}.
+   */
   @Nullable
   default Integer getSockPeerPort(REQUEST request) {
+    return InetSocketAddressUtil.getPort(getPeerSocketAddress(request));
+  }
+
+  /**
+   * Returns an {@link InetSocketAddress} object representing the host socket address.
+   *
+   * <p>Implementing this method is equivalent to implementing all three of {@link
+   * #getSockFamily(Object)}, {@link #getSockHostAddr(Object)} and {@link #getSockHostPort(Object)}.
+   */
+  @Nullable
+  default InetSocketAddress getHostSocketAddress(REQUEST request) {
     return null;
   }
 
+  /**
+   * Returns the local socket address. Useful in case of a multi-IP host.
+   *
+   * <p>Examples: `192.168.0.1`.
+   *
+   * <p>By default, this method attempts to retrieve the host address using the {@link
+   * #getHostSocketAddress(Object)} method. If this method is not implemented, it will simply return
+   * {@code null}. If the instrumented library does not expose {@link InetSocketAddress} in its API,
+   * you might want to implement this method instead of {@link #getHostSocketAddress(Object)}.
+   */
   @Nullable
   default String getSockHostAddr(REQUEST request) {
-    return null;
+    return InetSocketAddressUtil.getHostAddress(getHostSocketAddress(request));
   }
 
+  /**
+   * Returns the local socket port number.
+   *
+   * <p>Examples: `35555`.
+   *
+   * <p>By default, this method attempts to retrieve the host port using the {@link
+   * #getHostSocketAddress(Object)} method. If this method is not implemented, it will simply return
+   * {@code null}. If the instrumented library does not expose {@link InetSocketAddress} in its API,
+   * you might want to implement this method instead of {@link #getHostSocketAddress(Object)}.
+   */
   @Nullable
   default Integer getSockHostPort(REQUEST request) {
-    return null;
+    return InetSocketAddressUtil.getPort(getHostSocketAddress(request));
   }
 }