feat(server): opt-in uncaught exception capture

.changeset/core-uncaught-gate.md

@@ -0,0 +1,5 @@
+---
+'posthog': patch
+---
+
+Uncaught-exception events now use the canonical `onuncaughtexception` mechanism type.

.changeset/server-uncaught-exceptions.md

@@ -0,0 +1,5 @@
+---
+'posthog-server': minor
+---
+
+Add `captureUncaughtExceptions`: opt in to capturing uncaught JVM exceptions as error tracking events, with a best-effort flush before the process exits. The SDK's flush timer is now a daemon thread and no longer keeps a finished JVM alive until `close()`.

posthog-server/api/posthog-server.api

@@ -134,6 +134,7 @@ public class com/posthog/server/PostHogConfig {
 	public final fun addIntegration (Lcom/posthog/PostHogIntegration;)V
 	public static final fun builder (Ljava/lang/String;)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun getApiKey ()Ljava/lang/String;
+	public final fun getCaptureUncaughtExceptions ()Z
 	public final fun getDebug ()Z
 	public final fun getEncryption ()Lcom/posthog/PostHogEncryption;
 	public final fun getEvaluationContexts ()Ljava/util/List;
@@ -158,6 +159,7 @@ public class com/posthog/server/PostHogConfig {
 	public final fun getRemoteConfig ()Z
 	public final fun getSendFeatureFlagEvent ()Z
 	public final fun removeBeforeSend (Lcom/posthog/PostHogBeforeSend;)V
+	public final fun setCaptureUncaughtExceptions (Z)V
 	public final fun setDebug (Z)V
 	public final fun setEncryption (Lcom/posthog/PostHogEncryption;)V
 	public final fun setEvaluationContexts (Ljava/util/List;)V
@@ -185,6 +187,7 @@ public class com/posthog/server/PostHogConfig {
 public final class com/posthog/server/PostHogConfig$Builder {
 	public fun <init> (Ljava/lang/String;)V
 	public final fun build ()Lcom/posthog/server/PostHogConfig;
+	public final fun captureUncaughtExceptions (Z)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun debug (Z)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun encryption (Lcom/posthog/PostHogEncryption;)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun evaluationContexts (Ljava/util/List;)Lcom/posthog/server/PostHogConfig$Builder;

posthog-server/src/main/java/com/posthog/server/PostHog.kt

@@ -2,9 +2,11 @@ package com.posthog.server
 
 import com.posthog.FeatureFlagResult
 import com.posthog.PostHogStateless
+import com.posthog.errortracking.PostHogErrorTrackingAutoCaptureIntegration
 import com.posthog.internal.FeatureFlag
 import com.posthog.server.internal.EvaluationsHost
 import com.posthog.server.internal.PostHogFeatureFlags
+import com.posthog.server.internal.PostHogUncaughtExceptionCapture
 
 @Suppress("DEPRECATION")
 public class PostHog : PostHogStateless(), PostHogInterface {
@@ -26,12 +28,51 @@ public class PostHog : PostHogStateless(), PostHogInterface {
             }
         }
 
+    /**
+     * Uncaught-exception integration installed when [PostHogConfig.captureUncaughtExceptions] is
+     * enabled, retained so it can be uninstalled on [close].
+     */
+    private var uncaughtExceptionIntegration: PostHogErrorTrackingAutoCaptureIntegration? = null
+
     override fun <T : PostHogConfig> setup(config: T) {
-        super.setup(config.asCoreConfig())
+        // Hold setupLock across the whole lifecycle so the enabled-transition check and the handler
+        // install stay atomic with the base's own setup. The monitor is reentrant, so super.setup
+        // re-acquires it harmlessly. Without this, two concurrent setup() calls could both observe
+        // alreadySetUp as false and the rejected one would install a handler bound to a config the
+        // base discarded; and a concurrent close() could read uncaughtExceptionIntegration before it
+        // was assigned and leak the process-wide handler after the client closed.
+        synchronized(setupLock) {
+            // The base keeps its original state when it rejects a setup (already set up, or an invalid
+            // config), so only wire anything on top when THIS call is the one that enabled the client —
+            // otherwise a second setup() could install a handler bound to a config the base discarded.
+            val alreadySetUp = isEnabled()
+            super.setup(config.asCoreConfig())
+            if (alreadySetUp || !isEnabled()) {
+                return
+            }
+
+            // Core setup never installs integrations for the stateless base, so wire the uncaught
+            // handler explicitly (all mechanics live in PostHogUncaughtExceptionCapture).
+            // Single-owner by design: the handler is process-wide, so only the first client that opts in
+            // installs it. With several live clients all opting in, closing the owner restores the
+            // previous handler and the remaining clients do not take over — capture stops until a client
+            // is set up again. Server apps use one client per process, so we don't ref-count here.
+            if (config.captureUncaughtExceptions) {
+                getConfig<com.posthog.PostHogConfig>()?.let { coreConfig ->
+                    uncaughtExceptionIntegration = PostHogUncaughtExceptionCapture.install(this, coreConfig)
+                }
+            }
+        }
     }
 
     override fun close() {
-        super.close()
+        // Same lock as setup so the uninstall + field clear cannot race a concurrent setup() that is
+        // still assigning uncaughtExceptionIntegration; super.close re-acquires the reentrant lock.
+        synchronized(setupLock) {
+            uncaughtExceptionIntegration?.uninstall()
+            uncaughtExceptionIntegration = null
+            super.close()
+        }
     }
 
     override fun identify(

posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt

@@ -200,6 +200,40 @@ public open class PostHogConfig constructor(
      */
     public var inAppExcludes: List<String> = DEFAULT_IN_APP_EXCLUDES
 
+    /**
+     * Opt in to capturing uncaught exceptions for the whole JVM as `$exception` events.
+     *
+     * When true, [PostHog] installs a [Thread.defaultUncaughtExceptionHandler] on setup that
+     * captures the crashing exception (`handled=false`, mechanism `onuncaughtexception`,
+     * `$exception_source: jvm.uncaught_exception_handler`), flushes, and then delegates to the
+     * previously registered handler. The handler is removed again on [PostHog.close].
+     *
+     * A main-thread crash is captured with `$exception_level` `fatal` (the process is expected to
+     * terminate); an uncaught exception on any other thread kills only that thread, so it is
+     * captured with level `error` and delivered like a regular event.
+     *
+     * Unlike the Android SDK, this is gated purely on this local flag — the server SDK never
+     * fetches remote config, so no remote toggle is involved.
+     *
+     * The JVM has a single process-wide default handler, so capture is single-owner: the first
+     * client that opts in installs the handler, later opted-in clients do not. Closing the owner
+     * restores the previous handler — other still-open clients do not take over; capture resumes
+     * with the next client that is set up with this flag enabled. Server apps normally run one
+     * client per process, where none of this matters.
+     *
+     * Delivery for a fatal (main-thread) crash: the event takes a dedicated queue path that
+     * enqueues and sends in one ordered task, draining the queue batch by batch and ignoring
+     * [flushAt], while the crashing thread waits on it for a bounded timeout — so the crash gets a
+     * network attempt before the JVM exits without ever blocking the crashing thread indefinitely.
+     * Delivery stays best-effort, the same guarantee class the Android SDK provides: the drain can
+     * hit its timeout, the HTTP attempt can fail, and an immediate hard exit can cut it short. See
+     * [PostHog] for details.
+     *
+     * Docs https://posthog.com/docs/error-tracking
+     * Defaults to false
+     */
+    public var captureUncaughtExceptions: Boolean = false
+
     private val beforeSendCallbacks = mutableListOf<PostHogBeforeSend>()
     private val integrations = mutableListOf<PostHogIntegration>()
 
@@ -382,6 +416,7 @@ public open class PostHogConfig constructor(
         private var releaseIdentifier: String? = null
         private var inAppIncludes: List<String> = emptyList()
         private var inAppExcludes: List<String> = DEFAULT_IN_APP_EXCLUDES
+        private var captureUncaughtExceptions: Boolean = false
 
         /**
          * Sets the PostHog ingestion host.
@@ -594,6 +629,15 @@ public open class PostHogConfig constructor(
          */
         public fun inAppExcludes(inAppExcludes: List<String>): Builder = apply { this.inAppExcludes = inAppExcludes.toList() }
 
+        /**
+         * Opts in to capturing uncaught JVM exceptions as `$exception` events.
+         *
+         * @param captureUncaughtExceptions true to install a global uncaught-exception handler on setup.
+         * @return This builder.
+         */
+        public fun captureUncaughtExceptions(captureUncaughtExceptions: Boolean): Builder =
+            apply { this.captureUncaughtExceptions = captureUncaughtExceptions }
+
         /**
          * Builds a [PostHogConfig] from the accumulated values.
          *
@@ -628,6 +672,7 @@ public open class PostHogConfig constructor(
             config.releaseIdentifier = releaseIdentifier
             config.inAppIncludes = inAppIncludes
             config.inAppExcludes = inAppExcludes
+            config.captureUncaughtExceptions = captureUncaughtExceptions
             return config
         }
     }