Improve Unity WebGL handling for stackless Unity log-callback exception reports. (#282)

* Add capture-mode enum for Unity exception log-handler

* Add fallback enum for optional WebGL JS stack capture

* Add BacktraceUnityLogCapture helper

Add helper for Unity log-callback diagnostics and stackless classification

* Add BacktraceUnityLogHandler wrapper

ILogHandler that intercepts Debug.LogException

* Add config fields for log handler capture and WebGL JS stack fallback

* Add BacktraceWebGLJavaScriptStack WebGL JS stack helper

* Add Addressables integration options

* Add optional Addressables integration

* Serialize custom report annotations

* Add AddAnnotation API and preserve source code on reports without frames

* Update SetThreadInformations to stop synthesizing faulting thread when no managed frames exist

* Update BacktraceSync.jslib

Add BT_CaptureJavaScriptStack jslib export for stack-at-capture

* Update BacktraceClient.cs

Capture original Debug.LogException
Classify stackless logs
Lock background queue

* Add tests for stackless log diagnostics and custom annotations

* Remove Addressables integration

* Add internal no-environment fallback

* Add internal CreateFromUnityLogCallback factory

* Update BacktraceReport.cs

Make AddAnnotation internal
Remove chaining
Add no-fallback factory

* Update Annotations.cs

Remove chaining in custom annotation overload

* Replace with stack source aware attribute/annotation helpers

* Create BacktraceUnityLogExceptionCandidate.cs

Add candidate model for original exception capture

* Create BacktraceUnityLogExceptionCandidateStore.cs

Add candidate store with prefix matching

* Create BacktraceUnityLogReportFactory.cs

Add factory that picks stack source per Unity log callback

* Record original exception only and remove direct send

* Update BacktraceClient.cs

Wire candidate store and report factory
Drop suppression queue

* Rewrite for stack-source attributes and no-fallback factory

* Create BacktraceUnityLogReportFactoryTests.cs

Add factory tests for stack-source

* add created classes metadata

* Update Tests

* Make log-handler and callback capture path dynamic

* Add callback capture path to candidate report builders

* Update SourceCodeFlowWithLogManagerTests.cs

Update source-code flow tests for stackless and frame bearing paths

* Update BacktraceUnityLogCapture.cs

Restrict candidate prefixes to type+message
Fall back to type only when empty

* Set backtrace.unity.stack_source on Unity-callback-only reports

* Update prefix tests for better matching and empty-message fallback

* Add regression test for same type & different message candidate mismatch

* Assert stack_source on Unity-callback only paths

* Update BacktraceClient.cs

Filter capture-path by prefix and fall back to log type

* Clear stale stackless reason when frames are recovered

Update Test case to assert reports with recovered frames drop stackless reason

* Keep original exception path when its stack is unparseable and Unity stack is empty

Update Test case to cover original exception unparsed-stack diagnostic

* Add candidate thread id to CreateOriginalExceptionAttributes

* Forward candidate thread id to original exception attributes

* Update BacktraceUnityLogCaptureTests.cs

Pass thread id to helper tests and assert it

* Update BacktraceUnityLogReportFactoryTests.cs

Add Test case for candidate thread id propagation for background-thread captures

Author: melekr

Runtime/BacktraceClient.cs

@@ -0,0 +1,56 @@
+using System;
+using UnityEngine;
+
+namespace Backtrace.Unity
+{
+    internal sealed class BacktraceUnityLogHandler : ILogHandler
+    {
+        private readonly BacktraceClient _client;
+        private readonly ILogHandler _innerLogHandler;
+
+        internal ILogHandler InnerLogHandler
+        {
+            get { return _innerLogHandler; }
+        }
+
+        internal BacktraceUnityLogHandler(
+            BacktraceClient client,
+            ILogHandler innerLogHandler)
+        {
+            _client = client;
+            _innerLogHandler = innerLogHandler;
+        }
+
+        public void LogException(Exception exception, UnityEngine.Object context)
+        {
+            try
+            {
+                if (_client != null)
+                {
+                    _client.RecordUnityLogHandlerException(exception, context);
+                }
+            }
+            catch
+            {
+                // Never allow Backtrace instrumentation to interfere with Unity logging.
+            }
+
+            if (_innerLogHandler != null)
+            {
+                _innerLogHandler.LogException(exception, context);
+            }
+        }
+
+        public void LogFormat(
+            LogType logType,
+            UnityEngine.Object context,
+            string format,
+            params object[] args)
+        {
+            if (_innerLogHandler != null)
+            {
+                _innerLogHandler.LogFormat(logType, context, format, args);
+            }
+        }
+    }
+}

Runtime/BacktraceUnityLogHandler.cs

@@ -232,6 +232,24 @@ public class BacktraceConfiguration : ScriptableObject
         [Tooltip("If exception does not have a stack trace, use a normalized exception message to generate fingerprint.")]
         public bool UseNormalizedExceptionMessage = false;
 
+        /// <summary>
+        /// Controls whether the SDK wraps Debug.unityLogger.logHandler to capture
+        /// original Exception objects before Unity reduces them to log-callback messages.
+        /// Automatic enables this on WebGL builds and disables it elsewhere.
+        /// </summary>
+        [Tooltip("Controls whether Backtrace wraps Debug.unityLogger.logHandler to capture original Exception objects passed through Debug.LogException. Automatic enables this on WebGL and disables it elsewhere.")]
+        public BacktraceUnityLogHandlerExceptionCaptureMode UnityLogHandlerExceptionCapture =
+            BacktraceUnityLogHandlerExceptionCaptureMode.Automatic;
+
+        /// <summary>
+        /// WebGL only. Attach a best-effort browser JavaScript stack-at-capture annotation
+        /// for stackless Unity Error/Exception log callbacks. Disabled by default because
+        /// this is supplemental context, not the original managed C# throw-site stack.
+        /// </summary>
+        [Tooltip("WebGL only. Attach a best-effort browser JavaScript stack-at-capture annotation for stackless Unity Error/Exception log callbacks. Disabled by default.")]
+        public BacktraceWebGLJavaScriptStackFallbackMode WebGLJavaScriptStackFallback =
+            BacktraceWebGLJavaScriptStackFallbackMode.Disabled;
+
         /// <summary>
         /// Determine minidump type support - minidump generation is supported on Windows.
         /// </summary>

Runtime/BacktraceUnityLogHandler.cs.meta

@@ -175,8 +175,14 @@ public string ToJson()
         /// </summary>
         private void SetThreadInformations()
         {
-            var faultingThread = !(Report.Exception is BacktraceUnhandledException
-                && string.IsNullOrEmpty(Report.Exception.StackTrace));
+            var hasManagedFrames = Report.DiagnosticStack != null && Report.DiagnosticStack.Count != 0;
+            var faultingThread = hasManagedFrames;
+            if (faultingThread &&
+                Report.Exception is BacktraceUnhandledException &&
+                string.IsNullOrEmpty(Report.Exception.StackTrace))
+            {
+                faultingThread = false;
+            }
 
             ThreadData = new ThreadData(Report.DiagnosticStack, faultingThread);
             ThreadInformations = ThreadData.ThreadInformations;
@@ -191,7 +197,10 @@ private void SetThreadInformations()
         private void SetAttributes(Dictionary<string, string> clientAttributes, int gameObjectDepth)
         {
             Attributes = new BacktraceAttributes(Report, clientAttributes);
-            Annotation = new Annotations(Report.ExceptionTypeReport ? Report.Exception : null, gameObjectDepth);
+            Annotation = new Annotations(
+                Report.ExceptionTypeReport ? Report.Exception : null,
+                gameObjectDepth,
+                Report.CustomAnnotations);
         }
     }
 }

Runtime/Model/BacktraceConfiguration.cs

@@ -81,6 +81,17 @@ public class BacktraceReport
         /// </summary>
         public BacktraceSourceCode SourceCode = null;
 
+        /// <summary>
+        /// Custom report annotations serialized under the top-level annotations object.
+        /// </summary>
+        private readonly Dictionary<string, Dictionary<string, string>> _customAnnotations =
+            new Dictionary<string, Dictionary<string, string>>();
+
+        internal IDictionary<string, Dictionary<string, string>> CustomAnnotations
+        {
+            get { return _customAnnotations; }
+        }
+
         /// <summary>
         /// Create new instance of Backtrace report to sending a report with custom client message
         /// </summary>
@@ -91,11 +102,12 @@ public BacktraceReport(
             string message,
             Dictionary<string, string> attributes = null,
             List<string> attachmentPaths = null)
-            : this(null as Exception, attributes, attachmentPaths)
         {
+            Attributes = attributes ?? new Dictionary<string, string>();
+            AttachmentPaths = attachmentPaths ?? new List<string>();
+            Exception = null;
+            ExceptionTypeReport = false;
             Message = message;
-            // analyse stack trace information in both constructor 
-            // to include error message in both source code properties.
             SetStacktraceInformation();
             SetDefaultAttributes();
         }
@@ -124,6 +136,44 @@ public BacktraceReport(
             SetDefaultAttributes();
         }
 
+        private BacktraceReport(
+            Exception exception,
+            Dictionary<string, string> attributes,
+            List<string> attachmentPaths,
+            bool allowEnvironmentStackFallback)
+        {
+            Attributes = attributes ?? new Dictionary<string, string>();
+            AttachmentPaths = attachmentPaths ?? new List<string>();
+            Exception = exception;
+            ExceptionTypeReport = exception != null;
+            if (ExceptionTypeReport)
+            {
+                Message = exception.Message;
+                SetClassifierInfo();
+                if (allowEnvironmentStackFallback)
+                {
+                    SetStacktraceInformation();
+                }
+                else
+                {
+                    SetStacktraceInformationWithoutEnvironmentFallback();
+                }
+            }
+            SetDefaultAttributes();
+        }
+
+        internal static BacktraceReport CreateWithoutEnvironmentStackFallback(
+            Exception exception,
+            Dictionary<string, string> attributes = null,
+            List<string> attachmentPaths = null)
+        {
+            return new BacktraceReport(
+                exception,
+                attributes,
+                attachmentPaths,
+                allowEnvironmentStackFallback: false);
+        }
+
 
         /// <summary>
         /// Sets report symbolication type
@@ -149,7 +199,7 @@ private void SetDefaultAttributes()
         /// <param name="text"></param>
         internal void AssignSourceCodeToReport(string text)
         {
-            if (DiagnosticStack == null || DiagnosticStack.Count == 0)
+            if (string.IsNullOrEmpty(text))
             {
                 return;
             }
@@ -158,7 +208,11 @@ internal void AssignSourceCodeToReport(string text)
             {
                 Text = text
             };
-            // assign log information to first stack frame
+
+            if (DiagnosticStack == null || DiagnosticStack.Count == 0)
+            {
+                return;
+            }
             foreach (var diagnosticStack in DiagnosticStack)
             {
                 diagnosticStack.SourceCode = BacktraceSourceCode.SOURCE_CODE_PROPERTY;
@@ -237,6 +291,30 @@ internal void SetReportFingerprint(bool generateFingerprint)
             }
         }
 
+        internal void AddAnnotation(
+            string name,
+            IDictionary<string, string> values)
+        {
+            if (string.IsNullOrEmpty(name) || values == null || values.Count == 0)
+            {
+                return;
+            }
+            var annotation = new Dictionary<string, string>();
+            foreach (var value in values)
+            {
+                if (string.IsNullOrEmpty(value.Key))
+                {
+                    continue;
+                }
+                annotation[value.Key] = value.Value ?? string.Empty;
+            }
+            if (annotation.Count == 0)
+            {
+                return;
+            }
+            _customAnnotations[name] = annotation;
+        }
+
         internal BacktraceData ToBacktraceData(Dictionary<string, string> clientAttributes, int gameObjectDepth)
         {
             return new BacktraceData(this, clientAttributes, gameObjectDepth);
@@ -248,6 +326,13 @@ internal void SetStacktraceInformation()
             var stacktrace = new BacktraceStackTrace(Exception);
             DiagnosticStack = stacktrace.StackFrames;
         }
+
+        private void SetStacktraceInformationWithoutEnvironmentFallback()
+        {
+            var stacktrace =
+                BacktraceStackTrace.CreateWithoutEnvironmentFallback(Exception);
+            DiagnosticStack = stacktrace.StackFrames;
+        }
         /// <summary>
         /// create a copy of BacktraceReport for inner exception object inside exception
         /// </summary>

Runtime/Model/BacktraceData.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Collections.Generic;
 using System.Diagnostics;
 
@@ -14,64 +14,89 @@ internal class BacktraceStackTrace
         /// </summary>
         public readonly List<BacktraceStackFrame> StackFrames = new List<BacktraceStackFrame>();
 
-
-        /// <summary>
-        /// Current exception
-        /// </summary>
         private readonly Exception _exception;
+        private readonly bool _allowEnvironmentStackFallback;
 
         public BacktraceStackTrace(Exception exception)
         {
             _exception = exception;
+            _allowEnvironmentStackFallback = true;
+            Initialize();
+        }
+
+        private BacktraceStackTrace(
+            Exception exception,
+            bool allowEnvironmentStackFallback)
+        {
+            _exception = exception;
+            _allowEnvironmentStackFallback = allowEnvironmentStackFallback;
             Initialize();
         }
 
+        internal static BacktraceStackTrace CreateWithoutEnvironmentFallback(
+            Exception exception)
+        {
+            return new BacktraceStackTrace(
+                exception,
+                allowEnvironmentStackFallback: false);
+        }
+
         private void Initialize()
         {
-            bool generateExceptionInformation = _exception != null;
+            var generateExceptionInformation = _exception != null;
             if (_exception != null)
             {
-                if (_exception is BacktraceUnhandledException)
+                var unhandledException = _exception as BacktraceUnhandledException;
+                if (unhandledException != null)
                 {
-                    var current = _exception as BacktraceUnhandledException;
-                    StackFrames.InsertRange(0, current.StackFrames);
+                    StackFrames.InsertRange(0, unhandledException.StackFrames);
+                    return;
                 }
-                else
+
+                var exceptionStackTrace = new StackTrace(_exception, true);
+                var exceptionFrames = exceptionStackTrace.GetFrames();
+                if (exceptionFrames == null || exceptionFrames.Length == 0)
                 {
-                    var exceptionStackTrace = new StackTrace(_exception, true);
-                    var exceptionFrames = exceptionStackTrace.GetFrames();
-                    if (exceptionFrames == null || exceptionFrames.Length == 0)
+                    if (!_allowEnvironmentStackFallback)
                     {
-                        exceptionFrames = new StackTrace(true).GetFrames();
+                        return;
                     }
-                    SetStacktraceInformation(exceptionFrames, true);
+                    exceptionFrames = new StackTrace(true).GetFrames();
                 }
+                SetStacktraceInformation(exceptionFrames, true);
+                return;
             }
-            else
+
+            if (!_allowEnvironmentStackFallback)
             {
-                //initialize environment stack trace
-                var stackTrace = new StackTrace(true);
-                //reverse frame order
-                var frames = stackTrace.GetFrames();
-                SetStacktraceInformation(frames, generateExceptionInformation);
+                return;
             }
+
+            var stackTrace = new StackTrace(true);
+            var frames = stackTrace.GetFrames();
+            SetStacktraceInformation(frames, generateExceptionInformation);
         }
 
-        private void SetStacktraceInformation(StackFrame[] frames, bool generatedByException = false)
+        private void SetStacktraceInformation(
+            StackFrame[] frames,
+            bool generatedByException = false)
         {
             if (frames == null || frames.Length == 0)
             {
                 return;
             }
-            int startingIndex = 0;
+            var startingIndex = 0;
             foreach (var frame in frames)
             {
-                var backtraceFrame = new BacktraceStackFrame(frame, generatedByException);
+                var backtraceFrame = new BacktraceStackFrame(
+                    frame,
+                    generatedByException);
                 if (backtraceFrame.InvalidFrame)
                 {
                     continue;
                 }
-                backtraceFrame.StackFrameType = Types.BacktraceStackFrameType.Dotnet;
+                backtraceFrame.StackFrameType =
+                    Types.BacktraceStackFrameType.Dotnet;
                 StackFrames.Insert(startingIndex, backtraceFrame);
                 startingIndex++;
             }