Single logger instance for invalid API call (#4073)

Co-authored-by: Anuraag Agrawal <anuraaga@gmail.com>
Co-authored-by: John Watson <jkwatson@gmail.com>

api/all/README.md

@@ -16,3 +16,7 @@
 From the root of the repo run `./gradlew clean :api:jmh` to run all the benchmarks
 or run `./gradlew clean :api:jmh -PjmhIncludeSingleClass=<ClassNameHere>`
 to run a specific benchmark class.
+
+---
+#### Logging API mis-use
+Define `logging.level.io.opentelemetry.ApiUsageLogging=TRACE` to enable TRACE logging for invalid API calls.

api/all/src/main/java/io/opentelemetry/api/baggage/ImmutableEntryMetadata.java

@@ -6,6 +6,7 @@
 package io.opentelemetry.api.baggage;
 
 import com.google.auto.value.AutoValue;
+import io.opentelemetry.api.internal.ValidationUtil;
 import javax.annotation.concurrent.Immutable;
 
 @Immutable
@@ -24,6 +25,7 @@ abstract class ImmutableEntryMetadata implements BaggageEntryMetadata {
    */
   static ImmutableEntryMetadata create(String metadata) {
     if (metadata == null) {
+      ValidationUtil.log("metadata is null");
       return EMPTY;
     }
     return new AutoValue_ImmutableEntryMetadata(metadata);

api/all/src/main/java/io/opentelemetry/api/internal/ValidationUtil.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.internal;
+
+import java.util.logging.Level;
+import java.util.logging.Logger;
+import javax.annotation.concurrent.Immutable;
+
+/** General internal validation utility methods. */
+@Immutable
+public final class ValidationUtil {
+
+  private ValidationUtil() {}
+
+  private static final Logger API_USAGE_LOGGER =
+      Logger.getLogger("io.opentelemetry.ApiUsageLogging");
+
+  public static void log(String msg) {
+    API_USAGE_LOGGER.log(Level.FINEST, msg, new AssertionError());
+  }
+}

api/all/src/main/java/io/opentelemetry/api/trace/DefaultTracer.java

@@ -7,6 +7,7 @@ package io.opentelemetry.api.trace;
 
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.internal.ValidationUtil;
 import io.opentelemetry.context.Context;
 import java.util.concurrent.TimeUnit;
 import javax.annotation.Nullable;
@@ -49,6 +50,7 @@ final class DefaultTracer implements Tracer {
     @Override
     public NoopSpanBuilder setParent(Context context) {
       if (context == null) {
+        ValidationUtil.log("context is null");
         return this;
       }
       spanContext = Span.fromContext(context).getSpanContext();

api/all/src/main/java/io/opentelemetry/api/trace/Span.java

@@ -10,6 +10,7 @@ import static java.util.concurrent.TimeUnit.SECONDS;
 
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.internal.ValidationUtil;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.ImplicitContextKeyed;
 import java.time.Instant;
@@ -42,6 +43,7 @@ public interface Span extends ImplicitContextKeyed {
    */
   static Span fromContext(Context context) {
     if (context == null) {
+      ValidationUtil.log("context is null");
       return Span.getInvalid();
     }
     Span span = context.get(SpanContextKey.KEY);
@@ -55,6 +57,7 @@ public interface Span extends ImplicitContextKeyed {
   @Nullable
   static Span fromContextOrNull(Context context) {
     if (context == null) {
+      ValidationUtil.log("context is null");
       return null;
     }
     return context.get(SpanContextKey.KEY);
@@ -74,7 +77,11 @@ public interface Span extends ImplicitContextKeyed {
    * to propagate a valid {@link SpanContext} downstream.
    */
   static Span wrap(SpanContext spanContext) {
-    if (spanContext == null || !spanContext.isValid()) {
+    if (spanContext == null) {
+      ValidationUtil.log("context is null");
+      return getInvalid();
+    }
+    if (!spanContext.isValid()) {
       return getInvalid();
     }
     return PropagatedSpan.create(spanContext);

api/all/src/main/java/io/opentelemetry/api/trace/SpanId.java

@@ -7,6 +7,7 @@ package io.opentelemetry.api.trace;
 
 import io.opentelemetry.api.internal.OtelEncodingUtils;
 import io.opentelemetry.api.internal.TemporaryBuffers;
+import io.opentelemetry.api.internal.ValidationUtil;
 import javax.annotation.concurrent.Immutable;
 
 /**
@@ -72,6 +73,7 @@ public final class SpanId {
    */
   public static String fromBytes(byte[] spanIdBytes) {
     if (spanIdBytes == null || spanIdBytes.length < BYTES_LENGTH) {
+      ValidationUtil.log("spanIdBytes is null or too short");
       return INVALID;
     }
     char[] result = TemporaryBuffers.chars(HEX_LENGTH);

api/all/src/main/java/io/opentelemetry/api/trace/TraceId.java

@@ -7,6 +7,7 @@ package io.opentelemetry.api.trace;
 
 import io.opentelemetry.api.internal.OtelEncodingUtils;
 import io.opentelemetry.api.internal.TemporaryBuffers;
+import io.opentelemetry.api.internal.ValidationUtil;
 import javax.annotation.concurrent.Immutable;
 
 /**
@@ -76,6 +77,7 @@ public final class TraceId {
    */
   public static String fromBytes(byte[] traceIdBytes) {
     if (traceIdBytes == null || traceIdBytes.length < BYTES_LENGTH) {
+      ValidationUtil.log("traceIdBytes is null or too short");
       return INVALID;
     }
     char[] result = TemporaryBuffers.chars(HEX_LENGTH);