Factor out and make session timeouts more explicit. (#887)

* factor out and make session timeouts more explicit.

* fix build after rebase

Author: breedx-splk

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### ⚠️⚠️ Breaking changes
+
+- Remove `setSessionTimeout()` on `OtelRumConfig` in favor of new `setSessionConfig()`.([#xxx](https://github.com/open-telemetry/opentelemetry-android/pull/xxx))
+
 ## Version 0.10.0 (2025-03-06)
 
 - This version builds on opentelemetry-java-instrumentation

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

@@ -8,6 +8,9 @@
 import android.app.Application;
 import io.opentelemetry.android.config.OtelRumConfig;
 import io.opentelemetry.android.internal.services.Services;
+import io.opentelemetry.android.internal.session.SessionIdTimeoutHandler;
+import io.opentelemetry.android.internal.session.SessionManagerImpl;
+import io.opentelemetry.android.session.SessionManager;
 import io.opentelemetry.api.OpenTelemetry;
 import io.opentelemetry.sdk.OpenTelemetrySdk;
 import io.opentelemetry.sdk.logs.SdkLoggerProvider;
@@ -64,8 +67,17 @@ static OpenTelemetryRumBuilder builder(Application application, OtelRumConfig co
     static SdkPreconfiguredRumBuilder builder(
             Application application, OpenTelemetrySdk openTelemetrySdk, OtelRumConfig config) {
 
+        SessionIdTimeoutHandler timeoutHandler =
+                new SessionIdTimeoutHandler(config.getSessionConfig());
+        SessionManager sessionManager =
+                SessionManagerImpl.create(timeoutHandler, config.getSessionConfig());
         return new SdkPreconfiguredRumBuilder(
-                application, openTelemetrySdk, config, Services.get(application));
+                application,
+                openTelemetrySdk,
+                timeoutHandler,
+                sessionManager,
+                config,
+                Services.get(application));
     }
 
     /** Returns a no-op implementation of {@link OpenTelemetryRum}. */

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

@@ -37,6 +37,7 @@
 import io.opentelemetry.android.internal.services.periodicwork.PeriodicWork;
 import io.opentelemetry.android.internal.session.SessionIdTimeoutHandler;
 import io.opentelemetry.android.internal.session.SessionManagerImpl;
+import io.opentelemetry.android.session.SessionConfig;
 import io.opentelemetry.android.session.SessionManager;
 import io.opentelemetry.android.session.SessionProvider;
 import io.opentelemetry.api.baggage.propagation.W3CBaggagePropagator;
@@ -117,8 +118,9 @@ private static TextMapPropagator buildDefaultPropagator() {
     }
 
     public static OpenTelemetryRumBuilder create(Application application, OtelRumConfig config) {
-        return new OpenTelemetryRumBuilder(
-                application, config, new SessionIdTimeoutHandler(config.getSessionTimeout()));
+        SessionConfig sessionConfig = config.getSessionConfig();
+        SessionIdTimeoutHandler timeoutHandler = new SessionIdTimeoutHandler(sessionConfig);
+        return new OpenTelemetryRumBuilder(application, config, timeoutHandler);
     }
 
     OpenTelemetryRumBuilder(
@@ -320,8 +322,7 @@ public OpenTelemetryRum build() {
                 new BufferDelegatingMetricExporter();
 
         if (sessionManager == null) {
-            sessionManager =
-                    SessionManagerImpl.create(timeoutHandler, config.getSessionTimeout().toNanos());
+            sessionManager = SessionManagerImpl.create(timeoutHandler, config.getSessionConfig());
         }
 
         OpenTelemetrySdk sdk =

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

@@ -12,7 +12,6 @@ import io.opentelemetry.android.instrumentation.AndroidInstrumentationLoader
 import io.opentelemetry.android.instrumentation.InstallationContext
 import io.opentelemetry.android.internal.services.Services
 import io.opentelemetry.android.internal.session.SessionIdTimeoutHandler
-import io.opentelemetry.android.internal.session.SessionManagerImpl
 import io.opentelemetry.android.session.SessionManager
 import io.opentelemetry.sdk.OpenTelemetrySdk
 
@@ -21,8 +20,8 @@ class SdkPreconfiguredRumBuilder
     internal constructor(
         private val application: Application,
         private val sdk: OpenTelemetrySdk,
-        private val timeoutHandler: SessionIdTimeoutHandler = SessionIdTimeoutHandler(),
-        private val sessionManager: SessionManager = SessionManagerImpl(timeoutHandler = timeoutHandler),
+        private val timeoutHandler: SessionIdTimeoutHandler,
+        private val sessionManager: SessionManager,
         private val config: OtelRumConfig,
         private val services: Services,
     ) {

core/src/main/java/io/opentelemetry/android/config/OtelRumConfig.java

@@ -8,8 +8,8 @@
 import io.opentelemetry.android.ScreenAttributesSpanProcessor;
 import io.opentelemetry.android.features.diskbuffering.DiskBufferingConfig;
 import io.opentelemetry.android.internal.services.network.CurrentNetworkProvider;
+import io.opentelemetry.android.session.SessionConfig;
 import io.opentelemetry.api.common.Attributes;
-import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.function.Supplier;
@@ -27,7 +27,7 @@ public class OtelRumConfig {
     private boolean includeScreenAttributes = true;
     private boolean discoverInstrumentations = true;
     private DiskBufferingConfig diskBufferingConfig = DiskBufferingConfig.create();
-    private Duration sessionTimeout = Duration.ofMinutes(15);
+    private SessionConfig sessionConfig = SessionConfig.withDefaults();
     private final List<String> suppressedInstrumentations = new ArrayList<>();
 
     /**
@@ -132,15 +132,20 @@ public OtelRumConfig setDiskBufferingConfig(DiskBufferingConfig diskBufferingCon
         return this;
     }
 
-    /** Call this method to set session timeout in minutes */
-    public OtelRumConfig setSessionTimeout(Duration sessionTimeout) {
-        this.sessionTimeout = sessionTimeout;
+    /**
+     * Sets the session configuration, which includes inactivity timeout and maximum lifetime
+     * durations.
+     *
+     * @return this
+     */
+    public OtelRumConfig setSessionConfig(SessionConfig sessionConfig) {
+        this.sessionConfig = sessionConfig;
         return this;
     }
 
-    /** Call this method to retrieve session timeout */
-    public Duration getSessionTimeout() {
-        return sessionTimeout;
+    /** Call this method to retrieve the session config */
+    public SessionConfig getSessionConfig() {
+        return sessionConfig;
     }
 
     /**

core/src/main/java/io/opentelemetry/android/internal/session/SessionIdTimeoutHandler.kt

@@ -6,8 +6,9 @@
 package io.opentelemetry.android.internal.session
 
 import io.opentelemetry.android.internal.services.applifecycle.ApplicationStateListener
+import io.opentelemetry.android.session.SessionConfig
 import io.opentelemetry.sdk.common.Clock
-import java.time.Duration
+import kotlin.time.Duration
 
 /**
  * This class encapsulates the following criteria about the sessionId timeout:
@@ -25,7 +26,7 @@ import java.time.Duration
  */
 internal class SessionIdTimeoutHandler(
     private val clock: Clock,
-    private val sessionTimeout: Duration,
+    private val sessionBackgroundInactivityTimeout: Duration,
 ) : ApplicationStateListener {
     @Volatile
     private var timeoutStartNanos: Long = 0
@@ -34,10 +35,9 @@ internal class SessionIdTimeoutHandler(
     private var state = State.FOREGROUND
 
     // for testing
-    @JvmOverloads
-    internal constructor(sessionTimeout: Duration = DEFAULT_SESSION_TIMEOUT) : this(
+    internal constructor(sessionConfig: SessionConfig) : this(
         Clock.getDefault(),
-        sessionTimeout,
+        sessionConfig.backgroundInactivityTimeout,
     )
 
     override fun onApplicationForegrounded() {
@@ -54,7 +54,7 @@ internal class SessionIdTimeoutHandler(
             return false
         }
         val elapsedTime = clock.nanoTime() - timeoutStartNanos
-        return elapsedTime >= sessionTimeout.toNanos()
+        return elapsedTime >= sessionBackgroundInactivityTimeout.inWholeNanoseconds
     }
 
     fun bump() {
@@ -73,9 +73,4 @@ internal class SessionIdTimeoutHandler(
         /** A temporary state representing the first event after the app has been brought back.  */
         TRANSITIONING_TO_FOREGROUND,
     }
-
-    companion object {
-        @JvmField
-        val DEFAULT_SESSION_TIMEOUT: Duration = Duration.ofMinutes(15)
-    }
 }

core/src/main/java/io/opentelemetry/android/internal/session/SessionManagerImpl.kt

@@ -6,20 +6,21 @@
 package io.opentelemetry.android.internal.session
 
 import io.opentelemetry.android.session.Session
+import io.opentelemetry.android.session.SessionConfig
 import io.opentelemetry.android.session.SessionIdGenerator
 import io.opentelemetry.android.session.SessionManager
 import io.opentelemetry.android.session.SessionObserver
 import io.opentelemetry.android.session.SessionStorage
 import io.opentelemetry.sdk.common.Clock
 import java.util.Collections.synchronizedList
-import java.util.concurrent.TimeUnit
+import kotlin.time.Duration
 
 internal class SessionManagerImpl(
     private val clock: Clock = Clock.getDefault(),
     private val sessionStorage: SessionStorage = SessionStorage.InMemory(),
     private val timeoutHandler: SessionIdTimeoutHandler,
     private val idGenerator: SessionIdGenerator = SessionIdGenerator.DEFAULT,
-    private val sessionLifetimeNanos: Long = TimeUnit.HOURS.toNanos(4),
+    private val maxSessionLifetime: Duration,
 ) : SessionManager {
     // TODO: Make thread safe / wrap with AtomicReference?
     private var session: Session = Session.NONE
@@ -66,18 +67,18 @@ internal class SessionManagerImpl(
 
     private fun sessionHasExpired(): Boolean {
         val elapsedTime = clock.now() - session.getStartTimestamp()
-        return elapsedTime >= sessionLifetimeNanos
+        return elapsedTime >= maxSessionLifetime.inWholeNanoseconds
     }
 
     companion object {
         @JvmStatic
         fun create(
             timeoutHandler: SessionIdTimeoutHandler,
-            sessionLifetimeNanos: Long,
+            sessionConfig: SessionConfig,
         ): SessionManagerImpl =
             SessionManagerImpl(
                 timeoutHandler = timeoutHandler,
-                sessionLifetimeNanos = sessionLifetimeNanos,
+                maxSessionLifetime = sessionConfig.maxLifetime,
             )
     }
 }

core/src/test/java/io/opentelemetry/android/internal/session/SessionIdTimeoutHandlerTest.kt

@@ -5,20 +5,21 @@
 
 package io.opentelemetry.android.internal.session
 
-import io.opentelemetry.android.internal.session.SessionIdTimeoutHandler.Companion.DEFAULT_SESSION_TIMEOUT
+import io.opentelemetry.android.session.SessionConfig
 import io.opentelemetry.sdk.testing.time.TestClock
 import org.junit.jupiter.api.Assertions.assertFalse
 import org.junit.jupiter.api.Assertions.assertTrue
 import org.junit.jupiter.api.Test
 import java.time.Duration
 import java.util.concurrent.TimeUnit
+import kotlin.time.Duration.Companion.nanoseconds
 
 class SessionIdTimeoutHandlerTest {
     @Test
     fun shouldNeverTimeOutInForeground() {
         val clock: TestClock = TestClock.create()
         val timeoutHandler =
-            SessionIdTimeoutHandler(clock, DEFAULT_SESSION_TIMEOUT)
+            SessionIdTimeoutHandler(clock, SessionConfig.withDefaults().backgroundInactivityTimeout)
 
         assertFalse(timeoutHandler.hasTimedOut())
         timeoutHandler.bump()
@@ -32,7 +33,7 @@ class SessionIdTimeoutHandlerTest {
     fun shouldApply15MinutesTimeoutToAppsInBackground() {
         val clock: TestClock = TestClock.create()
         val timeoutHandler =
-            SessionIdTimeoutHandler(clock, DEFAULT_SESSION_TIMEOUT)
+            SessionIdTimeoutHandler(clock, SessionConfig.withDefaults().backgroundInactivityTimeout)
 
         timeoutHandler.onApplicationBackgrounded()
         timeoutHandler.bump()
@@ -64,7 +65,7 @@ class SessionIdTimeoutHandlerTest {
     fun shouldApplyTimeoutToFirstSpanAfterAppBeingMovedToForeground() {
         val clock: TestClock = TestClock.create()
         val timeoutHandler =
-            SessionIdTimeoutHandler(clock, DEFAULT_SESSION_TIMEOUT)
+            SessionIdTimeoutHandler(clock, SessionConfig.withDefaults().backgroundInactivityTimeout)
 
         timeoutHandler.onApplicationBackgrounded()
         timeoutHandler.bump()
@@ -84,7 +85,7 @@ class SessionIdTimeoutHandlerTest {
     fun shouldApplyCustomTimeoutToFirstSpanAfterAppBeingMovedToForeground() {
         val clock: TestClock = TestClock.create()
         val timeoutHandler =
-            SessionIdTimeoutHandler(clock, Duration.ofNanos(5))
+            SessionIdTimeoutHandler(clock, 5.nanoseconds)
 
         timeoutHandler.onApplicationBackgrounded()
         timeoutHandler.bump()

core/src/test/java/io/opentelemetry/android/internal/session/SessionManagerImplTest.kt

@@ -22,6 +22,7 @@ import org.junit.jupiter.api.BeforeEach
 import org.junit.jupiter.api.Test
 import java.util.concurrent.TimeUnit
 import java.util.regex.Pattern
+import kotlin.time.Duration.Companion.hours
 
 internal class SessionManagerImplTest {
     @MockK
@@ -40,6 +41,7 @@ internal class SessionManagerImplTest {
             SessionManagerImpl(
                 TestClock.create(),
                 timeoutHandler = timeoutHandler,
+                maxSessionLifetime = 4.hours,
             )
         val sessionId = sessionManager.getSessionId()
         assertThat(sessionId).isNotNull()
@@ -54,6 +56,7 @@ internal class SessionManagerImplTest {
             SessionManagerImpl(
                 clock,
                 timeoutHandler = timeoutHandler,
+                maxSessionLifetime = 4.hours,
             )
         val value = sessionManager.getSessionId()
         assertThat(value).isEqualTo(sessionManager.getSessionId())
@@ -82,6 +85,7 @@ internal class SessionManagerImplTest {
             SessionManagerImpl(
                 clock,
                 timeoutHandler = timeoutHandler,
+                maxSessionLifetime = 4.hours,
             )
         sessionManager.addObserver(observer)
 
@@ -121,7 +125,7 @@ internal class SessionManagerImplTest {
 
     @Test
     fun shouldCreateNewSessionIdAfterTimeout() {
-        val sessionId = SessionManagerImpl(timeoutHandler = timeoutHandler)
+        val sessionId = SessionManagerImpl(timeoutHandler = timeoutHandler, maxSessionLifetime = 4.hours)
 
         val value = sessionId.getSessionId()
         verify { timeoutHandler.bump() }

session/src/main/kotlin/io/opentelemetry/android/session/SessionConfig.kt

@@ -0,0 +1,20 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.android.session
+
+import kotlin.time.Duration
+import kotlin.time.Duration.Companion.hours
+import kotlin.time.Duration.Companion.minutes
+
+data class SessionConfig(
+    val backgroundInactivityTimeout: Duration = 15.minutes,
+    val maxLifetime: Duration = 4.hours,
+) {
+    companion object {
+        @JvmStatic
+        fun withDefaults(): SessionConfig = SessionConfig()
+    }
+}