feat: Structured Logging

CHANGELOG.md

@@ -1,11 +1,15 @@
 # Changelog
 
-## Unreleased 
+## Unreleased
 
 ### Breaking Changes
 
 - `sentry-native` is now built on Ubuntu 22.04 instead of Ubuntu 20.04, which reached EOL in May 2025. If you are running you game on a server on Ubuntu 20.04, you should update the OS before upgrading to this SDK version. ([#2355](https://github.com/getsentry/sentry-unity/pull/2355))
 
+### Features
+
+- Added support for Structured Logging. The `SentrySdk.Logger` API is now exposed for Unity users, enabling structured log capture. The SDK can also automatically capture and send Debug logs based on the options configured. ([#2368](https://github.com/getsentry/sentry-unity/pull/2368))
+
 ### Dependencies
 
 - Bump CLI from v2.56.0 to v2.56.1 ([#2356](https://github.com/getsentry/sentry-unity/pull/2356))

samples/unity-of-bugs/Assets/Resources/Sentry/SentryOptions.asset

@@ -35,11 +35,17 @@ MonoBehaviour:
   <MaxViewHierarchyRootObjects>k__BackingField: 100
   <MaxViewHierarchyObjectChildCount>k__BackingField: 20
   <MaxViewHierarchyDepth>k__BackingField: 10
+  <EnableStructuredLogging>k__BackingField: 1
+  <OnDebugLog>k__BackingField: 0
+  <OnDebugLogWarning>k__BackingField: 1
+  <OnDebugLogAssertion>k__BackingField: 1
+  <OnDebugLogError>k__BackingField: 1
+  <OnDebugLogException>k__BackingField: 1
+  <AttachBreadcrumbsToEvents>k__BackingField: 0
   <BreadcrumbsForLogs>k__BackingField: 1
   <BreadcrumbsForWarnings>k__BackingField: 1
   <BreadcrumbsForAsserts>k__BackingField: 1
   <BreadcrumbsForErrors>k__BackingField: 1
-  <BreadcrumbsForExceptions>k__BackingField: 1
   <CaptureLogErrorEvents>k__BackingField: 1
   <MaxBreadcrumbs>k__BackingField: 100
   <ReportAssembliesMode>k__BackingField: 1

samples/unity-of-bugs/Assets/Scripts/BugFarmButtons.cs

@@ -71,7 +71,7 @@ public void LogError()
             // Error logs get captured as messages and do not have a stacktrace attached by default. This is an opt-in feature.
             // Note: That stack traces generated for message events are provided without line numbers. See known limitations
             // https://docs.sentry.io/platforms/unity/troubleshooting/known-limitations/#line-numbers-missing-in-events-captured-through-debuglogerror-or-sentrysdkcapturemessage
-            Debug.LogError("Debug.LogError() called");
+            Debug.LogError("This is a 'Debug.LogError()' message.");
         }
     }
 

samples/unity-of-bugs/Assets/Scripts/ThreadingSamples.cs

@@ -81,7 +81,7 @@ public void LogError()
                 // Error logs get captured as messages and do not have a stacktrace attached by default. This is an opt-in feature.
                 // Note: That stack traces generated for message events are provided without line numbers. See known limitations
                 // https://docs.sentry.io/platforms/unity/troubleshooting/known-limitations/#line-numbers-missing-in-events-captured-through-debuglogerror-or-sentrysdkcapturemessage
-                Debug.LogError("Debug.LogError() called");
+                Debug.LogError("This is a 'Debug.LogError()' message.");
             }
         });
     }

src/Sentry.Unity.Editor/ConfigurationWindow/LoggingTab.cs

@@ -9,31 +9,35 @@ internal static class LoggingTab
     internal static void Display(ScriptableSentryUnityOptions options)
     {
         {
-            options.EnableLogDebouncing = EditorGUILayout.BeginToggleGroup(
-                new GUIContent("Enable Log Debouncing", "The SDK debounces log messages of the " +
-                                                        "same type if they are more frequent than once per second."),
-                options.EnableLogDebouncing);
+            GUILayout.Label("Structured Logging - Experimental", EditorStyles.boldLabel);
+
+            options.EnableStructuredLogging = EditorGUILayout.BeginToggleGroup(
+                new GUIContent("Send Logs for:", "Enables the SDK to forward log messages to Sentry " +
+                                                 "based on the log level."),
+                options.EnableStructuredLogging);
 
             EditorGUI.indentLevel++;
 
-            options.DebounceTimeLog = EditorGUILayout.IntField(
-                new GUIContent("Log Debounce [ms]", "The time that has to pass between events of " +
-                                                    "LogType.Log before the SDK sends it again."),
-                options.DebounceTimeLog);
-            options.DebounceTimeLog = Math.Max(0, options.DebounceTimeLog);
-
-            options.DebounceTimeWarning = EditorGUILayout.IntField(
-                new GUIContent("Warning Debounce [ms]", "The time that has to pass between events of " +
-                                                        "LogType.Warning before the SDK sends it again."),
-                options.DebounceTimeWarning);
-            options.DebounceTimeWarning = Math.Max(0, options.DebounceTimeWarning);
-
-            options.DebounceTimeError = EditorGUILayout.IntField(
-                new GUIContent("Error Debounce [ms]", "The time that has to pass between events of " +
-                                                      "LogType.Assert, LogType.Exception and LogType.Error before " +
-                                                      "the SDK sends it again."),
-                options.DebounceTimeError);
-            options.DebounceTimeError = Math.Max(0, options.DebounceTimeError);
+            options.OnDebugLog = EditorGUILayout.Toggle(
+                new GUIContent("Debug.Log",
+                    "Whether the SDK should forward Debug.Log messages to Sentry structured logging"),
+                options.OnDebugLog);
+            options.OnDebugLogWarning = EditorGUILayout.Toggle(
+                new GUIContent("Debug.LogWarning",
+                    "Whether the SDK should forward Debug.LogWarning messages to Sentry structured logging"),
+                options.OnDebugLogWarning);
+            options.OnDebugLogAssertion = EditorGUILayout.Toggle(
+                new GUIContent("Debug.LogAssertion",
+                    "Whether the SDK should forward Debug.LogAssertion messages to Sentry structured logging"),
+                options.OnDebugLogAssertion);
+            options.OnDebugLogError = EditorGUILayout.Toggle(
+                new GUIContent("Debug.LogError",
+                    "Whether the SDK should forward Debug.LogError messages to Sentry structured logging"),
+                options.OnDebugLogError);
+            options.OnDebugLogException = EditorGUILayout.Toggle(
+                new GUIContent("Debug.LogException",
+                    "Whether the SDK should forward Debug.LogException messages to Sentry structured logging"),
+                options.OnDebugLogException);
 
             EditorGUI.indentLevel--;
             EditorGUILayout.EndToggleGroup();
@@ -44,65 +48,109 @@ internal static void Display(ScriptableSentryUnityOptions options)
         EditorGUILayout.Space();
 
         {
-            GUILayout.Label("Automatically capture and send events for:", EditorStyles.boldLabel);
-            EditorGUI.indentLevel++;
+            GUILayout.Label("Breadcrumbs", EditorStyles.boldLabel);
 
-            options.CaptureLogErrorEvents = EditorGUILayout.Toggle(
-                new GUIContent("Debug.LogError", "Whether the SDK automatically captures events for 'Debug.LogError'."),
-                options.CaptureLogErrorEvents);
+            if (options.EnableStructuredLogging)
+            {
+                options.AttachBreadcrumbsToEvents = EditorGUILayout.BeginToggleGroup(
+                    new GUIContent("Attach logs as breadcrumbs in addition to sending them as structured logs", "Whether the SDK should attach breadcrumbs to events in addition to structured logging."),
+                    options.AttachBreadcrumbsToEvents);
 
-            EditorGUILayout.Space();
-            GUILayout.Label("Automatically add breadcrumbs for:", EditorStyles.boldLabel);
+                GUILayout.Label("Note: With sending structured logs enabled you have to opt-into adding breadcrumbs to events.", EditorStyles.boldLabel);
+            }
+
+            EditorGUI.indentLevel++;
 
             options.BreadcrumbsForLogs = EditorGUILayout.Toggle(
                 new GUIContent("Debug.Log", "Whether the SDK automatically adds breadcrumbs 'Debug.Log'."),
                 options.BreadcrumbsForLogs);
             options.BreadcrumbsForWarnings = EditorGUILayout.Toggle(
-                new GUIContent("Debug.Warning", "Whether the SDK automatically adds breadcrumbs for 'Debug.LogWarning'."),
+                new GUIContent("Debug.LogWarning", "Whether the SDK automatically adds breadcrumbs for 'Debug.LogWarning'."),
                 options.BreadcrumbsForWarnings);
             options.BreadcrumbsForAsserts = EditorGUILayout.Toggle(
-                new GUIContent("Debug.Assert", "Whether the SDK automatically adds breadcrumbs for 'Debug.Assert'."),
+                new GUIContent("Debug.LogAssertion", "Whether the SDK automatically adds breadcrumbs for 'Debug.LogAssertion'."),
                 options.BreadcrumbsForAsserts);
             options.BreadcrumbsForErrors = EditorGUILayout.Toggle(
-                new GUIContent("Debug.Error", "Whether the SDK automatically adds breadcrumbs for 'Debug.LogError'."),
+                new GUIContent("Debug.LogError", "Whether the SDK automatically adds breadcrumbs for 'Debug.LogError'."),
                 options.BreadcrumbsForErrors);
 
-            EditorGUI.indentLevel--;
-        }
-
-        EditorGUILayout.Space();
-        EditorGUI.DrawRect(EditorGUILayout.GetControlRect(false, 1), Color.gray);
-        EditorGUILayout.Space();
+            EditorGUILayout.Space();
 
-        {
             options.MaxBreadcrumbs = EditorGUILayout.IntField(
                 new GUIContent("Max Breadcrumbs", "Maximum number of breadcrumbs that get captured." +
                                                   "\nDefault: 100"),
                 options.MaxBreadcrumbs);
             options.MaxBreadcrumbs = Math.Max(0, options.MaxBreadcrumbs);
+
+            EditorGUI.indentLevel--;
+            if (options.EnableStructuredLogging)
+            {
+                EditorGUILayout.EndToggleGroup();
+            }
         }
 
         EditorGUILayout.Space();
         EditorGUI.DrawRect(EditorGUILayout.GetControlRect(false, 1), Color.gray);
         EditorGUILayout.Space();
 
         {
-            GUILayout.Label("Attach the stack trace when capturing log messages. NOTE: These will not contain line numbers.", EditorStyles.boldLabel);
+            GUILayout.Label("CaptureMessage Settings", EditorStyles.boldLabel);
             EditorGUI.indentLevel++;
 
+            options.CaptureLogErrorEvents = EditorGUILayout.Toggle(
+                new GUIContent("Capture LogError", "Whether the SDK automatically captures events for 'Debug.LogError'."),
+                options.CaptureLogErrorEvents);
+
             options.AttachStacktrace = EditorGUILayout.Toggle(
-                new GUIContent("Attach Stack Trace", "Whether to include a stack trace for non " +
-                                                      "error events like logs. Even when Unity didn't include and no " +
-                                                      "exception was thrown. Refer to AttachStacktrace on sentry docs."),
+                new GUIContent("Attach Stack Trace", "Whether the SDK should include a stack trace for CaptureMessage " +
+                                                     "events. Refer to AttachStacktrace on sentry docs."),
                 options.AttachStacktrace);
 
-            EditorGUI.indentLevel--;
+            GUILayout.Label("Note: The stack trace quality will depend on the IL2CPP line number setting and might not contain line numbers.", EditorStyles.boldLabel);
+
             // Enhanced not supported on IL2CPP so not displaying this for the time being:
             // Options.StackTraceMode = (StackTraceMode) EditorGUILayout.EnumPopup(
             //     new GUIContent("Stacktrace Mode", "Enhanced is the default." +
             //                                       "\n - Enhanced: Include async, return type, args,..." +
             //                                       "\n - Original - Default .NET stack trace format."),
             //     Options.StackTraceMode);
+
+            EditorGUI.indentLevel--;
+        }
+
+        EditorGUILayout.Space();
+        EditorGUI.DrawRect(EditorGUILayout.GetControlRect(false, 1), Color.gray);
+        EditorGUILayout.Space();
+
+        {
+            options.EnableLogDebouncing = EditorGUILayout.BeginToggleGroup(
+                new GUIContent("Enable Log Debouncing", "The SDK debounces log messages of the " +
+                                                        "same type if they are more frequent than once per second."),
+                options.EnableLogDebouncing);
+
+            EditorGUI.indentLevel++;
+
+            options.DebounceTimeLog = EditorGUILayout.IntField(
+                new GUIContent("Log Debounce [ms]", "The time that has to pass between events of " +
+                                                    "LogType.Log before the SDK sends it again."),
+                options.DebounceTimeLog);
+            options.DebounceTimeLog = Math.Max(0, options.DebounceTimeLog);
+
+            options.DebounceTimeWarning = EditorGUILayout.IntField(
+                new GUIContent("Warning Debounce [ms]", "The time that has to pass between events of " +
+                                                        "LogType.Warning before the SDK sends it again."),
+                options.DebounceTimeWarning);
+            options.DebounceTimeWarning = Math.Max(0, options.DebounceTimeWarning);
+
+            options.DebounceTimeError = EditorGUILayout.IntField(
+                new GUIContent("Error Debounce [ms]", "The time that has to pass between events of " +
+                                                      "LogType.Assert, LogType.Exception and LogType.Error before " +
+                                                      "the SDK sends it again."),
+                options.DebounceTimeError);
+            options.DebounceTimeError = Math.Max(0, options.DebounceTimeError);
+
+            EditorGUI.indentLevel--;
+            EditorGUILayout.EndToggleGroup();
         }
     }
 }