Add guidance for null checking, promote ApiUsageLogger to opentelemetry-common public API (#8318)

Author: jack-berg

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

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

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

@@ -7,7 +7,7 @@
 
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.common.Attributes;
-import io.opentelemetry.api.internal.ApiUsageLogger;
+import io.opentelemetry.common.impl.ApiUsageLogger;
 import io.opentelemetry.context.Context;
 import java.util.concurrent.TimeUnit;
 import javax.annotation.Nullable;
@@ -55,7 +55,7 @@ public Span startSpan() {
     @Override
     public NoopSpanBuilder setParent(Context context) {
       if (context == null) {
-        ApiUsageLogger.log("context is null");
+        ApiUsageLogger.logNullParam(SpanBuilder.class, "setParent", "context");
         return this;
       }
       spanContext = Span.fromContext(context).getSpanContext();

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

@@ -10,7 +10,7 @@
 
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.common.Attributes;
-import io.opentelemetry.api.internal.ApiUsageLogger;
+import io.opentelemetry.common.impl.ApiUsageLogger;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.ImplicitContextKeyed;
 import java.time.Instant;
@@ -43,7 +43,7 @@ static Span current() {
    */
   static Span fromContext(Context context) {
     if (context == null) {
-      ApiUsageLogger.log("context is null");
+      ApiUsageLogger.logNullParam(Span.class, "fromContext", "context");
       return Span.getInvalid();
     }
     Span span = context.get(SpanContextKey.KEY);
@@ -57,7 +57,7 @@ static Span fromContext(Context context) {
   @Nullable
   static Span fromContextOrNull(Context context) {
     if (context == null) {
-      ApiUsageLogger.log("context is null");
+      ApiUsageLogger.logNullParam(Span.class, "fromContextOrNull", "context");
       return null;
     }
     return context.get(SpanContextKey.KEY);
@@ -78,7 +78,7 @@ static Span getInvalid() {
    */
   static Span wrap(SpanContext spanContext) {
     if (spanContext == null) {
-      ApiUsageLogger.log("context is null");
+      ApiUsageLogger.logNullParam(Span.class, "wrap", "spanContext");
       return getInvalid();
     }
     return PropagatedSpan.create(spanContext);

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

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

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

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

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

@@ -8,11 +8,12 @@
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.api.incubator.propagation.ExtendedContextPropagators;
-import io.opentelemetry.api.internal.ApiUsageLogger;
 import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.SpanBuilder;
 import io.opentelemetry.api.trace.SpanContext;
 import io.opentelemetry.api.trace.SpanKind;
 import io.opentelemetry.api.trace.Tracer;
+import io.opentelemetry.common.impl.ApiUsageLogger;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.propagation.ContextPropagators;
 import java.util.Map;
@@ -63,7 +64,7 @@ public Span startSpan() {
     @Override
     public NoopSpanBuilder setParent(Context context) {
       if (context == null) {
-        ApiUsageLogger.log("context is null");
+        ApiUsageLogger.logNullParam(SpanBuilder.class, "setParent", "context");
         return this;
       }
       spanContext = Span.fromContext(context).getSpanContext();

api/all/src/test/java/io/opentelemetry/api/internal/ApiUsageLoggerTest.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.common.impl;
+
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * A utility for logging API misuse, allowing operators to diagnose invalid usage with a single
+ * logging configuration entry.
+ *
+ * <p>Logs at {@link Level#FINEST} by default, so messages are silent in production unless
+ * explicitly enabled. Each log record includes a {@link Throwable} to make the offending call site
+ * visible in the stack trace without requiring the exception to be thrown.
+ *
+ * <p>The first time any API misuse is detected, a one-time {@link Level#WARNING} is emitted to the
+ * {@code io.opentelemetry.usage} logger. This warning is visible under default logging
+ * configuration and signals that API misuse is occurring. To see the full details of every misuse
+ * event (message and stack trace), configure the {@code io.opentelemetry.usage} logger at {@link
+ * Level#FINEST}.
+ *
+ * <p>This class is not intended for use by application developers. Its API is stable and will not
+ * be changed or removed in a backwards-incompatible manner.
+ */
+public final class ApiUsageLogger {
+
+  /** The logger name used for all API-misuse diagnostics. */
+  private static final Logger LOGGER = Logger.getLogger("io.opentelemetry.usage");
+
+  private static final AtomicBoolean WARN_ONCE = new AtomicBoolean();
+
+  /**
+   * Log that {@code paramName} was null in {@code apiClass#methodName}.
+   *
+   * <p>Convenience overload of {@link #logUsageIssue(Class, String, String)} for the common case of
+   * a null parameter that should not be null.
+   *
+   * @param apiClass the public API class where the misuse occurred
+   * @param methodName the name of the method where the misuse occurred
+   * @param paramName the name of the parameter that was null
+   */
+  public static void logNullParam(Class<?> apiClass, String methodName, String paramName) {
+    logUsageIssue(apiClass, methodName, paramName + " is null");
+  }
+
+  /**
+   * Log a misuse of {@code apiClass#methodName} with the given {@code message}.
+   *
+   * <p>Logs at {@link Level#FINEST} and includes a stack trace.
+   *
+   * @param apiClass the public API class where the misuse occurred
+   * @param methodName the name of the method where the misuse occurred
+   * @param message a brief description of the problem
+   */
+  public static void logUsageIssue(Class<?> apiClass, String methodName, String message) {
+    if (WARN_ONCE.compareAndSet(false, true)) {
+      LOGGER.warning(
+          "OpenTelemetry API usage issue detected. To see more details, enable FINEST logging for io.opentelemetry.usage. Stacktraces are includes to identify the offending call site.");
+    }
+    if (LOGGER.isLoggable(Level.FINEST)) {
+      LOGGER.log(
+          Level.FINEST,
+          apiClass.getSimpleName() + "." + methodName + "(): " + message,
+          new Throwable());
+    }
+  }
+
+  private ApiUsageLogger() {}
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/trace/ExtendedDefaultTracer.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.common.impl;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import io.github.netmikey.logunit.api.LogCapturer;
+import io.opentelemetry.internal.testing.slf4j.SuppressLogger;
+import java.lang.reflect.Field;
+import java.util.concurrent.atomic.AtomicBoolean;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+import org.slf4j.event.Level;
+
+@SuppressLogger(loggerName = "io.opentelemetry.usage")
+class ApiUsageLoggerTest {
+
+  @RegisterExtension
+  LogCapturer apiUsageLogs =
+      LogCapturer.create().captureForLogger("io.opentelemetry.usage", Level.TRACE);
+
+  @BeforeEach
+  void resetWarnOnce() throws Exception {
+    Field warnOnce = ApiUsageLogger.class.getDeclaredField("WARN_ONCE");
+    warnOnce.setAccessible(true);
+    ((AtomicBoolean) warnOnce.get(null)).set(false);
+  }
+
+  @Test
+  void log() {
+    ApiUsageLogger.logUsageIssue(ApiUsageLoggerTest.class, "log", "thing went wrong");
+    apiUsageLogs.assertContains("ApiUsageLoggerTest.log(): thing went wrong");
+  }
+
+  @Test
+  void logNullParam() {
+    ApiUsageLogger.logNullParam(ApiUsageLoggerTest.class, "logNullParam", "myParam");
+    apiUsageLogs.assertContains("ApiUsageLoggerTest.logNullParam(): myParam is null");
+  }
+
+  @Test
+  void warnOnce() {
+    ApiUsageLogger.logUsageIssue(ApiUsageLoggerTest.class, "warnOnce", "first");
+    ApiUsageLogger.logUsageIssue(ApiUsageLoggerTest.class, "warnOnce", "second");
+    long count =
+        apiUsageLogs.getEvents().stream()
+            .filter(e -> e.getMessage().contains("OpenTelemetry API usage issue detected"))
+            .count();
+    assertEquals(1, count);
+  }
+}