OpenTelemetryRum.shutdown() and instrumentation uninstall (#1109)

* allow instrumentation to be uninstalled

# Conflicts:
#	core/src/main/java/io/opentelemetry/android/OpenTelemetryRumImpl.java

* allow instrumentation to be uninstalled

* allow slow rendering instrumentation to be shut down

* also shut down the sdk

* shut down the export scheduler as well.

* spotless

Author: breedx-splk

core/src/main/java/io/opentelemetry/android/NoopOpenTelemetryRum.java

@@ -25,4 +25,9 @@ public String getRumSessionId() {
 
     @Override
     public void emitEvent(String eventName, String body, Attributes attributes) {}
+
+    @Override
+    public void shutdown() {
+        // nop
+    }
 }

core/src/main/java/io/opentelemetry/android/OpenTelemetryRum.java

@@ -15,12 +15,7 @@
 import io.opentelemetry.sdk.metrics.SdkMeterProvider;
 import io.opentelemetry.sdk.trace.SdkTracerProvider;
 
-/**
- * Entrypoint for the OpenTelemetry Real User Monitoring library for Android.
- *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
- */
+/** Entrypoint for the OpenTelemetry Real User Monitoring library for Android. */
 public interface OpenTelemetryRum {
 
     /**
@@ -137,4 +132,10 @@ default void emitEvent(String eventName, Attributes attributes) {
      * @param attributes The attributes associated with the event, providing metadata.
      */
     void emitEvent(String eventName, String body, Attributes attributes);
+
+    /**
+     * Initiates orderly shutdown of this OpenTelemetryRum instance. After this method completes,
+     * the instance should be considered invalid and no longer used.
+     */
+    void shutdown();
 }

core/src/main/java/io/opentelemetry/android/OpenTelemetryRumBuilder.java

@@ -331,7 +331,13 @@ public OpenTelemetryRum build() {
         otelSdkReadyListeners.forEach(listener -> listener.accept(sdk));
 
         SdkPreconfiguredRumBuilder delegate =
-                new SdkPreconfiguredRumBuilder(application, sdk, sessionProvider, config);
+                new SdkPreconfiguredRumBuilder(application, sdk, sessionProvider, config)
+                        .setShutdownHook(
+                                () -> {
+                                    if (exportScheduleHandler != null) {
+                                        exportScheduleHandler.disable();
+                                    }
+                                });
 
         // AsyncTask is deprecated but the thread pool is still used all over the Android SDK
         // and it provides a way to get a background thread without having to create a new one.

core/src/main/java/io/opentelemetry/android/OpenTelemetryRumImpl.kt

@@ -14,6 +14,7 @@ import io.opentelemetry.sdk.OpenTelemetrySdk
 internal class OpenTelemetryRumImpl(
     private val openTelemetrySdk: OpenTelemetrySdk,
     private val sessionProvider: SessionProvider,
+    private val onShutdown: Runnable,
 ) : OpenTelemetryRum {
     private val logger: ExtendedLogger =
         openTelemetrySdk.logsBridge
@@ -36,4 +37,8 @@ internal class OpenTelemetryRumImpl(
             .setAllAttributes(attributes)
             .emit()
     }
+
+    override fun shutdown() {
+        onShutdown.run()
+    }
 }

core/src/main/java/io/opentelemetry/android/SdkPreconfiguredRumBuilder.kt

@@ -19,6 +19,7 @@ class SdkPreconfiguredRumBuilder internal constructor(
     private val sessionProvider: SessionProvider,
     private val config: OtelRumConfig,
 ) {
+    private var onShutdown: Runnable = Runnable {} // nop
     private val instrumentations = mutableListOf<AndroidInstrumentation>()
 
     /**
@@ -31,6 +32,15 @@ class SdkPreconfiguredRumBuilder internal constructor(
         return this
     }
 
+    /**
+     * Call this to provide a shutdown hook that will be called when the OpenTelemetryRum
+     * instance is shut down.
+     */
+    fun setShutdownHook(onShutdown: Runnable): SdkPreconfiguredRumBuilder {
+        this.onShutdown = onShutdown
+        return this
+    }
+
     /**
      * Creates a new instance of [OpenTelemetryRum] with the settings of this [ ].
      *
@@ -41,11 +51,19 @@ class SdkPreconfiguredRumBuilder internal constructor(
      * @return A new [OpenTelemetryRum] instance.
      */
     fun build(): OpenTelemetryRum {
-        val openTelemetryRum = OpenTelemetryRumImpl(sdk, sessionProvider)
+        val ctx = InstallationContext(application, sdk, sessionProvider)
+        val enabledInstrumentations = getEnabledInstrumentations()
+        val onShutdown: () -> Unit = {
+            for (instrumentation in enabledInstrumentations) {
+                instrumentation.uninstall(ctx)
+            }
+            sdk.shutdown()
+            onShutdown.run()
+        }
+        val openTelemetryRum = OpenTelemetryRumImpl(sdk, sessionProvider, onShutdown)
 
         // Install instrumentations
-        val ctx = InstallationContext(application, openTelemetryRum.openTelemetry, sessionProvider)
-        for (instrumentation in getEnabledInstrumentations()) {
+        for (instrumentation in enabledInstrumentations) {
             instrumentation.install(ctx)
         }
 

core/src/main/java/io/opentelemetry/android/features/diskbuffering/scheduler/DefaultExportScheduleHandler.kt

@@ -20,4 +20,9 @@ class DefaultExportScheduleHandler(
             periodicWorkService.enqueue(exportScheduler)
         }
     }
+
+    override fun disable() {
+        super.disable()
+        exportScheduler.shutdown()
+    }
 }

core/src/main/java/io/opentelemetry/android/features/diskbuffering/scheduler/DefaultExportScheduler.kt

@@ -16,6 +16,9 @@ import java.util.concurrent.TimeUnit
 class DefaultExportScheduler(
     periodicWorkProvider: () -> PeriodicWork,
 ) : PeriodicRunnable(periodicWorkProvider) {
+    @Volatile
+    private var isShutDown: Boolean = false
+
     companion object {
         private val DELAY_BEFORE_NEXT_EXPORT_IN_MILLIS = TimeUnit.SECONDS.toMillis(10)
     }
@@ -32,7 +35,11 @@ class DefaultExportScheduler(
         }
     }
 
-    override fun shouldStopRunning(): Boolean = SignalFromDiskExporter.get() == null
+    fun shutdown() {
+        isShutDown = true
+    }
+
+    override fun shouldStopRunning(): Boolean = isShutDown || (SignalFromDiskExporter.get() == null)
 
     override fun minimumDelayUntilNextRunInMillis(): Long = DELAY_BEFORE_NEXT_EXPORT_IN_MILLIS
 }

instrumentation/android-instrumentation/src/main/java/io/opentelemetry/android/instrumentation/AndroidInstrumentation.kt

@@ -30,6 +30,16 @@ interface AndroidInstrumentation {
      */
     fun install(ctx: InstallationContext)
 
+    /**
+     * This method can be called to uninstall the instrumentation. Implementations should remove all
+     * used resources and shut down cleanly.
+     *
+     * @param ctx The InstallationContext under which the instrumentation had been removed.
+     */
+    fun uninstall(ctx: InstallationContext) {
+        // NOP default implementation
+    }
+
     /**
      * The canonical short name for this instrumentation.
      */

instrumentation/slowrendering/src/main/java/io/opentelemetry/android/instrumentation/slowrendering/SlowRenderListener.java

@@ -26,6 +26,7 @@
 import io.opentelemetry.api.trace.Tracer;
 import java.time.Duration;
 import java.time.Instant;
+import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 import java.util.concurrent.Executors;
@@ -92,8 +93,21 @@ void start() {
                 TimeUnit.MILLISECONDS);
     }
 
+    public void shutdown() {
+        executorService.shutdownNow();
+        for (Map.Entry<Activity, PerActivityListener> entry : activities.entrySet()) {
+            Activity activity = entry.getKey();
+            PerActivityListener listener = entry.getValue();
+            activity.getWindow().removeOnFrameMetricsAvailableListener(listener);
+        }
+        activities.clear();
+    }
+
     @Override
     public void onActivityResumed(@NonNull Activity activity) {
+        if (executorService.isShutdown()) {
+            return;
+        }
         PerActivityListener listener = new PerActivityListener(activity);
         PerActivityListener existing = activities.putIfAbsent(activity, listener);
         if (existing == null) {
@@ -103,6 +117,9 @@ public void onActivityResumed(@NonNull Activity activity) {
 
     @Override
     public void onActivityPaused(@NonNull Activity activity) {
+        if (executorService.isShutdown()) {
+            return;
+        }
         PerActivityListener listener = activities.remove(activity);
         if (listener != null) {
             activity.getWindow().removeOnFrameMetricsAvailableListener(listener);

instrumentation/slowrendering/src/main/java/io/opentelemetry/android/instrumentation/slowrendering/SlowRenderingInstrumentation.java

@@ -5,21 +5,25 @@
 
 package io.opentelemetry.android.instrumentation.slowrendering;
 
+import static io.opentelemetry.android.common.RumConstants.OTEL_RUM_LOG_TAG;
+
 import android.os.Build;
 import android.util.Log;
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 import com.google.auto.service.AutoService;
-import io.opentelemetry.android.common.RumConstants;
 import io.opentelemetry.android.instrumentation.AndroidInstrumentation;
 import io.opentelemetry.android.instrumentation.InstallationContext;
 import java.time.Duration;
+import org.jetbrains.annotations.NotNull;
 
 /** Entrypoint for installing the slow rendering detection instrumentation. */
 @AutoService(AndroidInstrumentation.class)
 public final class SlowRenderingInstrumentation implements AndroidInstrumentation {
 
     private static final String INSTRUMENTATION_NAME = "slowrendering";
     Duration slowRenderingDetectionPollInterval = Duration.ofSeconds(1);
+    @Nullable private volatile SlowRenderListener detector = null;
 
     /**
      * Configures the rate at which frame render durations are polled.
@@ -30,7 +34,7 @@ public final class SlowRenderingInstrumentation implements AndroidInstrumentatio
     public SlowRenderingInstrumentation setSlowRenderingDetectionPollInterval(Duration interval) {
         if (interval.toMillis() <= 0) {
             Log.e(
-                    RumConstants.OTEL_RUM_LOG_TAG,
+                    OTEL_RUM_LOG_TAG,
                     "Invalid slowRenderingDetectionPollInterval: "
                             + interval
                             + "; must be positive");
@@ -44,12 +48,18 @@ public SlowRenderingInstrumentation setSlowRenderingDetectionPollInterval(Durati
     public void install(@NonNull InstallationContext ctx) {
         if (Build.VERSION.SDK_INT < Build.VERSION_CODES.N) {
             Log.w(
-                    RumConstants.OTEL_RUM_LOG_TAG,
+                    OTEL_RUM_LOG_TAG,
                     "Slow/frozen rendering detection is not supported on platforms older than Android N (SDK version 24).");
             return;
         }
+        if (detector != null) {
+            Log.w(
+                    OTEL_RUM_LOG_TAG,
+                    "SlowRenderingInstrumentation skipping installation (detector already installed)");
+            return;
+        }
 
-        SlowRenderListener detector =
+        detector =
                 new SlowRenderListener(
                         ctx.getOpenTelemetry().getTracer("io.opentelemetry.slow-rendering"),
                         slowRenderingDetectionPollInterval);
@@ -58,6 +68,19 @@ public void install(@NonNull InstallationContext ctx) {
         detector.start();
     }
 
+    @Override
+    public void uninstall(@NotNull InstallationContext ctx) {
+        if (detector == null) {
+            Log.w(
+                    OTEL_RUM_LOG_TAG,
+                    "SlowRenderingInstrumentation skipping uninstall (detector is null)");
+            return;
+        }
+        ctx.getApplication().unregisterActivityLifecycleCallbacks(detector);
+        detector.shutdown();
+        detector = null;
+    }
+
     @NonNull
     @Override
     public String getName() {