javadocs, deps and class restrictions, unit tests

Author: srprash

awsagentprovider/build.gradle.kts

@@ -41,14 +41,14 @@ dependencies {
   // Export configuration
   compileOnly("io.opentelemetry:opentelemetry-exporter-otlp")
   // For Udp emitter
-  implementation("io.opentelemetry:opentelemetry-exporter-otlp-common")
-  implementation("io.opentelemetry:opentelemetry-exporter-common")
+  compileOnly("io.opentelemetry:opentelemetry-exporter-otlp-common")
 
   testImplementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
   testImplementation("io.opentelemetry:opentelemetry-sdk-testing")
   testImplementation("io.opentelemetry:opentelemetry-extension-aws")
   testImplementation("io.opentelemetry:opentelemetry-extension-trace-propagators")
   testImplementation("com.google.guava:guava")
+  testRuntimeOnly("io.opentelemetry:opentelemetry-exporter-otlp-common")
 
   compileOnly("com.google.code.findbugs:jsr305:3.0.2")
   testImplementation("org.mockito:mockito-core:5.3.1")

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

@@ -28,12 +28,26 @@
 import java.util.logging.Logger;
 import javax.annotation.concurrent.Immutable;
 
+/**
+ * Exports spans via UDP, using OpenTelemetry's protobuf model. The protobuf modelled spans are
+ * Base64 encoded and prefixed with AWS X-Ray specific information before being sent over to {@link
+ * UdpSender}.
+ *
+ * <p>This exporter is NOT meant for generic use since the payload is prefixed with AWS X-Ray
+ * specific information.
+ */
 @Immutable
-public class OtlpUdpSpanExporter implements SpanExporter {
+class OtlpUdpSpanExporter implements SpanExporter {
 
   private static final Logger logger = Logger.getLogger(OtlpUdpSpanExporter.class.getName());
+
+  // The protocol header and delimiter is required for sending data to X-Ray Daemon or when running
+  // in Lambda.
+  // https://docs.aws.amazon.com/xray/latest/devguide/xray-api-sendingdata.html#xray-api-daemon
   private static final String PROTOCOL_HEADER = "{\"format\": \"json\", \"version\": 1}";
   private static final char PROTOCOL_DELIMITER = '\n';
+
+  // These prefixes help the backend identify if the spans payload is sampled or not.
   private static final String FORMAT_OTEL_SAMPLED_TRACES_BINARY_PREFIX = "T1S";
   private static final String FORMAT_OTEL_UNSAMPLED_TRACES_BINARY_PREFIX = "T1U";
 

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

@@ -19,7 +19,7 @@
 
 import java.net.SocketException;
 
-public final class OtlpUdpSpanExporterBuilder {
+final class OtlpUdpSpanExporterBuilder {
 
   private static final String DEFAULT_HOST = "127.0.0.1";
   private static final int DEFAULT_PORT = 2000;

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

@@ -24,19 +24,22 @@
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
-public class UdpSender {
+/**
+ * This class represents a UDP sender that sends data to a specified endpoint. It is used to send
+ * data to a remote host and port using UDP protocol.
+ */
+class UdpSender {
   private static final Logger logger = Logger.getLogger(UdpSender.class.getName());
 
-  private final DatagramSocket socket;
+  private DatagramSocket socket;
   private final InetSocketAddress endpoint;
 
   public UdpSender(String host, int port) throws SocketException {
     this.endpoint = new InetSocketAddress(host, port);
     try {
-      socket = new DatagramSocket();
+      this.socket = new DatagramSocket();
     } catch (SocketException e) {
       logger.log(Level.SEVERE, "Exception while instantiating UdpSender socket.", e);
-      throw e;
     }
   }
 

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

@@ -26,6 +26,7 @@
 import io.opentelemetry.sdk.resources.Resource;
 import io.opentelemetry.sdk.trace.data.SpanData;
 import io.opentelemetry.sdk.trace.data.StatusData;
+import java.nio.charset.StandardCharsets;
 import java.util.Collections;
 import org.junit.jupiter.api.Test;
 
@@ -62,7 +63,7 @@ public void testUdpExporterWithInvalidEndpoint() {
   }
 
   @Test
-  public void testExport() {
+  public void testExportDefaultBehavior() {
     UdpSender senderMock = mock(UdpSender.class);
 
     // mock SpanData
@@ -73,9 +74,43 @@ public void testExport() {
 
     // assert that the senderMock.send is called once
     verify(senderMock, times(1)).send(any(byte[].class));
+    verify(senderMock)
+        .send(
+            argThat(
+                (byte[] bytes) -> {
+                  assertThat(bytes.length).isGreaterThan(0);
+                  String payload = new String(bytes, StandardCharsets.UTF_8);
+                  assertThat(payload)
+                      .startsWith("{\"format\": \"json\", \"version\": 1}" + "\n" + "T1S");
+                  return true;
+                }));
   }
 
-  private static SpanData buildSpanDataMock() {
+  @Test
+  public void testExportWithSampledFalse() {
+    UdpSender senderMock = mock(UdpSender.class);
+
+    // mock SpanData
+    SpanData spanData = buildSpanDataMock();
+
+    OtlpUdpSpanExporter exporter =
+        new OtlpUdpSpanExporterBuilder().setSender(senderMock).setSampled(false).build();
+    exporter.export(Collections.singletonList(spanData));
+
+    verify(senderMock, times(1)).send(any(byte[].class));
+    verify(senderMock)
+        .send(
+            argThat(
+                (byte[] bytes) -> {
+                  assertThat(bytes.length).isGreaterThan(0);
+                  String payload = new String(bytes, StandardCharsets.UTF_8);
+                  assertThat(payload)
+                      .startsWith("{\"format\": \"json\", \"version\": 1}" + "\n" + "T1U");
+                  return true;
+                }));
+  }
+
+  private SpanData buildSpanDataMock() {
     SpanData mockSpanData = mock(SpanData.class);
 
     Attributes spanAttributes =