Introduce fatal SDK logger (#4288)

* Check for mixed SDK versions

* Format code

* format + api

* Init noops if mixed versions detected

* Add BuildConfig

* config entries for agentless module sdk names

* Add MANIFEST.MF for JARs

* Throw on startup; use manifests for backend; reuse code for otel

* Format code

* Format code

* changelog

* api

* changelog

* Remove duplicate addPackage calls

* remove test assertion for package

* Introduce fatal SDK logger

* Format code

* changelog

* api

---------

Co-authored-by: Sentry Github Bot <bot+github-bot@sentry.io>

Author: adinauer

CHANGELOG.md

@@ -16,6 +16,9 @@
 - Increase http timeouts from 5s to 30s to have a better chance of events being delivered without retry ([#4276](https://github.com/getsentry/sentry-java/pull/4276))
 - Add `MANIFEST.MF` to Sentry JARs ([#4272](https://github.com/getsentry/sentry-java/pull/4272))
 - Retain baggage sample rate/rand values as doubles ([#4279](https://github.com/getsentry/sentry-java/pull/4279))
+- Introduce fatal SDK logger ([#4288](https://github.com/getsentry/sentry-java/pull/4288))
+  - We use this to print out messages when there is a problem that prevents the SDK from working correctly.
+  - One example for this is when the SDK has been configured with mixed dependency versions where we print out details, which module and version are affected.
 
 ### Fixes
 

sentry-android-core/api/sentry-android-core.api

@@ -63,6 +63,15 @@ public final class io/sentry/android/core/AndroidDateUtils {
 	public static fun getCurrentSentryDateTime ()Lio/sentry/SentryDate;
 }
 
+public final class io/sentry/android/core/AndroidFatalLogger : io/sentry/ILogger {
+	public fun <init> ()V
+	public fun <init> (Ljava/lang/String;)V
+	public fun isEnabled (Lio/sentry/SentryLevel;)Z
+	public fun log (Lio/sentry/SentryLevel;Ljava/lang/String;Ljava/lang/Throwable;)V
+	public fun log (Lio/sentry/SentryLevel;Ljava/lang/String;[Ljava/lang/Object;)V
+	public fun log (Lio/sentry/SentryLevel;Ljava/lang/Throwable;Ljava/lang/String;[Ljava/lang/Object;)V
+}
+
 public final class io/sentry/android/core/AndroidLogger : io/sentry/ILogger {
 	public fun <init> ()V
 	public fun <init> (Ljava/lang/String;)V

sentry-android-core/src/main/java/io/sentry/android/core/AndroidFatalLogger.java

@@ -0,0 +1,66 @@
+package io.sentry.android.core;
+
+import android.util.Log;
+import io.sentry.ILogger;
+import io.sentry.SentryLevel;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+@ApiStatus.Internal
+public final class AndroidFatalLogger implements ILogger {
+
+  private final @NotNull String tag;
+
+  public AndroidFatalLogger() {
+    this("Sentry");
+  }
+
+  public AndroidFatalLogger(final @NotNull String tag) {
+    this.tag = tag;
+  }
+
+  @SuppressWarnings("AnnotateFormatMethod")
+  @Override
+  public void log(
+      final @NotNull SentryLevel level,
+      final @NotNull String message,
+      final @Nullable Object... args) {
+    if (args == null || args.length == 0) {
+      Log.println(toLogcatLevel(level), tag, message);
+    } else {
+      Log.println(toLogcatLevel(level), tag, String.format(message, args));
+    }
+  }
+
+  @SuppressWarnings("AnnotateFormatMethod")
+  @Override
+  public void log(
+      final @NotNull SentryLevel level,
+      final @Nullable Throwable throwable,
+      final @NotNull String message,
+      final @Nullable Object... args) {
+    if (args == null || args.length == 0) {
+      log(level, message, throwable);
+    } else {
+      log(level, String.format(message, args), throwable);
+    }
+  }
+
+  @Override
+  public void log(
+      final @NotNull SentryLevel level,
+      final @NotNull String message,
+      final @Nullable Throwable throwable) {
+    Log.wtf(tag, message, throwable);
+  }
+
+  @Override
+  public boolean isEnabled(@Nullable SentryLevel level) {
+    return true;
+  }
+
+  private int toLogcatLevel(final @NotNull SentryLevel sentryLevel) {
+    return Log.ASSERT;
+  }
+}

sentry-android-core/src/main/java/io/sentry/android/core/AndroidOptionsInitializer.java

@@ -110,6 +110,7 @@ static void loadDefaultAndMetadataOptions(
 
     // Firstly set the logger, if `debug=true` configured, logging can start asap.
     options.setLogger(logger);
+    options.setFatalLogger(new AndroidFatalLogger());
 
     options.setDefaultScopeType(ScopeType.CURRENT);
     options.setOpenTelemetryMode(SentryOpenTelemetryMode.OFF);

sentry/api/sentry.api

@@ -3057,6 +3057,7 @@ public class io/sentry/SentryOptions {
 	public fun getEventProcessors ()Ljava/util/List;
 	public fun getExecutorService ()Lio/sentry/ISentryExecutorService;
 	public fun getExperimental ()Lio/sentry/ExperimentalOptions;
+	public fun getFatalLogger ()Lio/sentry/ILogger;
 	public fun getFlushTimeoutMillis ()J
 	public fun getFullyDisplayedReporter ()Lio/sentry/FullyDisplayedReporter;
 	public fun getGestureTargetLocators ()Ljava/util/List;
@@ -3196,6 +3197,7 @@ public class io/sentry/SentryOptions {
 	public fun setEnvelopeReader (Lio/sentry/IEnvelopeReader;)V
 	public fun setEnvironment (Ljava/lang/String;)V
 	public fun setExecutorService (Lio/sentry/ISentryExecutorService;)V
+	public fun setFatalLogger (Lio/sentry/ILogger;)V
 	public fun setFlushTimeoutMillis (J)V
 	public fun setForceInit (Z)V
 	public fun setFullyDisplayedReporter (Lio/sentry/FullyDisplayedReporter;)V

sentry/src/main/java/io/sentry/DefaultVersionDetector.java

@@ -14,6 +14,7 @@ public DefaultVersionDetector(final @NotNull SentryOptions options) {
 
   @Override
   public boolean checkForMixedVersions() {
-    return SentryIntegrationPackageStorage.getInstance().checkForMixedVersions(options.getLogger());
+    return SentryIntegrationPackageStorage.getInstance()
+        .checkForMixedVersions(options.getFatalLogger());
   }
 }

sentry/src/main/java/io/sentry/ManifestVersionDetector.java

@@ -16,6 +16,7 @@ public ManifestVersionDetector(final @NotNull SentryOptions options) {
   @Override
   public boolean checkForMixedVersions() {
     ManifestVersionReader.getInstance().readManifestFiles();
-    return SentryIntegrationPackageStorage.getInstance().checkForMixedVersions(options.getLogger());
+    return SentryIntegrationPackageStorage.getInstance()
+        .checkForMixedVersions(options.getFatalLogger());
   }
 }

sentry/src/main/java/io/sentry/Sentry.java

@@ -292,6 +292,7 @@ private static void init(final @NotNull SentryOptions options, final boolean glo
           .getLogger()
           .log(SentryLevel.INFO, "GlobalHubMode: '%s'", String.valueOf(globalHubModeToUse));
       Sentry.globalHubMode = globalHubModeToUse;
+      initFatalLogger(options);
       final boolean shouldInit =
           InitUtil.shouldInit(globalScope.getOptions(), options, isEnabled());
       if (shouldInit) {
@@ -392,6 +393,12 @@ private static void initLogger(final @NotNull SentryOptions options) {
     }
   }
 
+  private static void initFatalLogger(final @NotNull SentryOptions options) {
+    if (options.getFatalLogger() instanceof NoOpLogger) {
+      options.setFatalLogger(new SystemOutLogger());
+    }
+  }
+
   private static void initScopesStorage(SentryOptions options) {
     getScopesStorage().close();
     if (SentryOpenTelemetryMode.OFF == options.getOpenTelemetryMode()) {

sentry/src/main/java/io/sentry/SentryOptions.java

@@ -127,6 +127,8 @@ public class SentryOptions {
   /** Logger interface to log useful debugging information if debug is enabled */
   private @NotNull ILogger logger = NoOpLogger.getInstance();
 
+  @ApiStatus.Experimental private @NotNull ILogger fatalLogger = NoOpLogger.getInstance();
+
   /** minimum LogLevel to be used if debug is enabled */
   private @NotNull SentryLevel diagnosticLevel = DEFAULT_DIAGNOSTIC_LEVEL;
 
@@ -646,6 +648,26 @@ public void setLogger(final @Nullable ILogger logger) {
     this.logger = (logger == null) ? NoOpLogger.getInstance() : new DiagnosticLogger(this, logger);
   }
 
+  /**
+   * Returns the Logger interface for logging important SDK messages
+   *
+   * @return the logger for fatal SDK messages
+   */
+  @ApiStatus.Experimental
+  public @NotNull ILogger getFatalLogger() {
+    return fatalLogger;
+  }
+
+  /**
+   * Sets the Logger interface for important SDK messages. If null, logger will be NoOp
+   *
+   * @param logger the logger for fatal SDK messages
+   */
+  @ApiStatus.Experimental
+  public void setFatalLogger(final @Nullable ILogger logger) {
+    this.fatalLogger = (logger == null) ? NoOpLogger.getInstance() : logger;
+  }
+
   /**
    * Returns the minimum LogLevel
    *