feat: Add new Protocol for DebugImages and AddressMode

src/Sentry/Exceptions/SentryDebugImage.cs

@@ -0,0 +1,94 @@
+using System.Collections.Generic;
+using System.Linq;
+using System.Text.Json;
+using Sentry.Extensibility;
+using Sentry.Internal.Extensions;
+
+namespace Sentry
+{
+    /// <summary>
+    /// The Sentry Debug Meta Images interface.
+    /// </summary>
+    /// <see href="https://develop.sentry.dev/sdk/event-payloads/debugmeta#debug-images"/>
+    public sealed class SentryDebugImage : IJsonSerializable
+    {
+        /// <summary>
+        /// Type of the debug image.
+        /// </summary>
+        public string? Type { get; set; }
+
+        /// <summary>
+        /// Memory address, at which the image is mounted in the virtual address space of the process.
+        /// Should be a string in hex representation prefixed with "0x".
+        /// </summary>
+        public string? ImageAddress { get; set; }
+
+        /// <summary>
+        /// The size of the image in virtual memory.
+        /// If missing, Sentry will assume that the image spans up to the next image, which might lead to invalid stack traces.
+        /// </summary>
+        public long ImageSize { get; set; }
+
+        /// <summary>
+        /// Unique debug identifier of the image.
+        /// </summary>
+        public string? DebugId { get; set; }
+
+        /// <summary>
+        /// Path and name of the debug companion file.
+        /// </summary>
+        public string? DebugFile { get; set; }
+
+        /// <summary>
+        /// Optional identifier of the code file.
+        /// </summary>
+        public string? CodeId { get; set; }
+
+        /// <summary>
+        /// The absolute path to the dynamic library or executable.
+        /// This helps to locate the file if it is missing on Sentry.
+        /// </summary>
+        public string? CodeFile { get; set; }
+
+        /// <inheritdoc />
+        public void WriteTo(Utf8JsonWriter writer, IDiagnosticLogger? logger)
+        {
+            writer.WriteStartObject();
+
+            writer.WriteStringIfNotWhiteSpace("type", Type);
+            writer.WriteStringIfNotWhiteSpace("image_addr", ImageAddress);
+            writer.WriteNumberIfNotNull("image_size", ImageSize);
+            writer.WriteStringIfNotWhiteSpace("debug_id", DebugId);
+            writer.WriteStringIfNotWhiteSpace("debug_file", DebugFile);
+            writer.WriteStringIfNotWhiteSpace("code_id", CodeId);
+            writer.WriteStringIfNotWhiteSpace("code_file", CodeFile);
+
+            writer.WriteEndObject();
+        }
+
+        /// <summary>
+        /// Parses from JSON.
+        /// </summary>
+        public static SentryDebugImage FromJson(JsonElement json)
+        {
+            var type = json.GetPropertyOrNull("type")?.GetString();
+            var imageAddress = json.GetPropertyOrNull("image_addr")?.GetString();
+            var imageSize = json.GetPropertyOrNull("image_size")?.GetInt64() ?? 0;
+            var debugId = json.GetPropertyOrNull("debug_id")?.GetString();
+            var debugFile = json.GetPropertyOrNull("debug_file")?.GetString();
+            var codeId = json.GetPropertyOrNull("code_id")?.GetString();
+            var codeFile = json.GetPropertyOrNull("code_file")?.GetString();
+
+            return new SentryDebugImage
+            {
+                Type = type,
+                ImageAddress = imageAddress,
+                ImageSize = imageSize,
+                DebugId = debugId,
+                DebugFile = debugFile,
+                CodeId = codeId,
+                CodeFile = codeFile,
+            };
+        }
+    }
+}

src/Sentry/Exceptions/SentryStackFrame.cs

@@ -133,6 +133,14 @@ public sealed class SentryStackFrame : IJsonSerializable
         /// </remarks>
         public long? InstructionOffset { get; set; }
 
+        /// <summary>
+        /// Optionally changes the addressing mode. The default value is the same as
+        /// `"abs"` which means absolute referencing. This can also be set to
+        /// `"rel:DEBUG_ID"` or `"rel:IMAGE_INDEX"` to make addresses relative to an
+        /// object referenced by debug id or index.
+        /// </summary>
+        public string? AddressMode { get; set; }
+
         /// <inheritdoc />
         public void WriteTo(Utf8JsonWriter writer, IDiagnosticLogger? logger)
         {
@@ -156,6 +164,7 @@ public void WriteTo(Utf8JsonWriter writer, IDiagnosticLogger? logger)
             writer.WriteNumberIfNotNull("symbol_addr", SymbolAddress);
             writer.WriteStringIfNotWhiteSpace("instruction_addr", InstructionAddress);
             writer.WriteNumberIfNotNull("instruction_offset", InstructionOffset);
+            writer.WriteStringIfNotWhiteSpace("addr_mode", AddressMode);
 
             writer.WriteEndObject();
         }
@@ -183,6 +192,7 @@ public static SentryStackFrame FromJson(JsonElement json)
             var symbolAddress = json.GetPropertyOrNull("symbol_addr")?.GetInt64();
             var instructionAddress = json.GetPropertyOrNull("instruction_addr")?.GetString();
             var instructionOffset = json.GetPropertyOrNull("instruction_offset")?.GetInt64();
+            var addressMode = json.GetPropertyOrNull("addr_mode")?.GetString();
 
             return new SentryStackFrame
             {
@@ -203,7 +213,8 @@ public static SentryStackFrame FromJson(JsonElement json)
                 ImageAddress = imageAddress,
                 SymbolAddress = symbolAddress,
                 InstructionAddress = instructionAddress,
-                InstructionOffset = instructionOffset
+                InstructionOffset = instructionOffset,
+                AddressMode = addressMode,
             };
         }
     }

src/Sentry/SentryEvent.cs

@@ -96,6 +96,12 @@ public IEnumerable<SentryThread>? SentryThreads
             set => SentryThreadValues = value != null ? new SentryValues<SentryThread>(value) : null;
         }
 
+        /// <summary>
+        /// The Sentry Debug Meta Images interface.
+        /// </summary>
+        /// <see href="https://develop.sentry.dev/sdk/event-payloads/debugmeta#debug-images"/>
+        public List<SentryDebugImage>? SentryDebugImages { get; set; }
+
         /// <summary>
         /// A list of relevant modules and their versions.
         /// </summary>
@@ -242,6 +248,16 @@ public void WriteTo(Utf8JsonWriter writer, IDiagnosticLogger? logger)
             writer.WriteDictionaryIfNotEmpty("extra", _extra, logger);
             writer.WriteStringDictionaryIfNotEmpty("tags", _tags!);
 
+            if (SentryDebugImages != null && SentryDebugImages.Count > 0)
+            {
+                writer.WritePropertyName("debug_meta");
+                writer.WriteStartObject();
+
+                writer.WriteArray("images", SentryDebugImages.ToArray(), logger);
+
+                writer.WriteEndObject();
+            }
+
             writer.WriteEndObject();
         }
 
@@ -272,6 +288,9 @@ public static SentryEvent FromJson(JsonElement json)
             var extra = json.GetPropertyOrNull("extra")?.GetDictionaryOrNull();
             var tags = json.GetPropertyOrNull("tags")?.GetStringDictionaryOrNull();
 
+            var debugMeta = json.GetPropertyOrNull("debug_meta");
+            var images = debugMeta?.GetPropertyOrNull("images")?.EnumerateArray().Select(SentryDebugImage.FromJson).ToList();
+
             return new SentryEvent(null, timestamp, eventId)
             {
                 _modules = modules?.WhereNotNullValue().ToDictionary(),
@@ -282,6 +301,7 @@ public static SentryEvent FromJson(JsonElement json)
                 Release = release,
                 SentryExceptionValues = exceptionValues,
                 SentryThreadValues = threadValues,
+                SentryDebugImages = images,
                 Level = level,
                 TransactionName = transaction,
                 _request = request,

test/Sentry.DiagnosticSource.Tests/ApiApprovalTests.Run.Core3_1.verified.txt

@@ -355,6 +355,19 @@ namespace Sentry
         public static Sentry.SentryId CaptureMessage(this Sentry.ISentryClient client, string message, Sentry.SentryLevel level = 1) { }
         public static void CaptureUserFeedback(this Sentry.ISentryClient client, Sentry.SentryId eventId, string email, string comments, string? name = null) { }
     }
+    public sealed class SentryDebugImage : Sentry.IJsonSerializable
+    {
+        public SentryDebugImage() { }
+        public string? CodeFile { get; set; }
+        public string? CodeId { get; set; }
+        public string? DebugFile { get; set; }
+        public string? DebugId { get; set; }
+        public string? ImageAddress { get; set; }
+        public long ImageSize { get; set; }
+        public string? Type { get; set; }
+        public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
+        public static Sentry.SentryDebugImage FromJson(System.Text.Json.JsonElement json) { }
+    }
     [System.Diagnostics.DebuggerDisplay("{GetType().Name,nq}: {EventId,nq}")]
     public sealed class SentryEvent : Sentry.IEventLike, Sentry.IHasBreadcrumbs, Sentry.IHasExtra, Sentry.IHasTags, Sentry.IJsonSerializable
     {
@@ -375,6 +388,7 @@ namespace Sentry
         public string? Release { get; set; }
         public Sentry.Request Request { get; set; }
         public Sentry.SdkVersion Sdk { get; }
+        public System.Collections.Generic.List<Sentry.SentryDebugImage>? SentryDebugImages { get; set; }
         public System.Collections.Generic.IEnumerable<Sentry.Protocol.SentryException>? SentryExceptions { get; set; }
         public System.Collections.Generic.IEnumerable<Sentry.SentryThread>? SentryThreads { get; set; }
         public string? ServerName { get; set; }
@@ -556,6 +570,7 @@ namespace Sentry
     {
         public SentryStackFrame() { }
         public string? AbsolutePath { get; set; }
+        public string? AddressMode { get; set; }
         public int? ColumnNumber { get; set; }
         public string? ContextLine { get; set; }
         public string? FileName { get; set; }

test/Sentry.DiagnosticSource.Tests/ApiApprovalTests.Run.DotNet5_0.verified.txt

@@ -355,6 +355,19 @@ namespace Sentry
         public static Sentry.SentryId CaptureMessage(this Sentry.ISentryClient client, string message, Sentry.SentryLevel level = 1) { }
         public static void CaptureUserFeedback(this Sentry.ISentryClient client, Sentry.SentryId eventId, string email, string comments, string? name = null) { }
     }
+    public sealed class SentryDebugImage : Sentry.IJsonSerializable
+    {
+        public SentryDebugImage() { }
+        public string? CodeFile { get; set; }
+        public string? CodeId { get; set; }
+        public string? DebugFile { get; set; }
+        public string? DebugId { get; set; }
+        public string? ImageAddress { get; set; }
+        public long ImageSize { get; set; }
+        public string? Type { get; set; }
+        public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
+        public static Sentry.SentryDebugImage FromJson(System.Text.Json.JsonElement json) { }
+    }
     [System.Diagnostics.DebuggerDisplay("{GetType().Name,nq}: {EventId,nq}")]
     public sealed class SentryEvent : Sentry.IEventLike, Sentry.IHasBreadcrumbs, Sentry.IHasExtra, Sentry.IHasTags, Sentry.IJsonSerializable
     {
@@ -375,6 +388,7 @@ namespace Sentry
         public string? Release { get; set; }
         public Sentry.Request Request { get; set; }
         public Sentry.SdkVersion Sdk { get; }
+        public System.Collections.Generic.List<Sentry.SentryDebugImage>? SentryDebugImages { get; set; }
         public System.Collections.Generic.IEnumerable<Sentry.Protocol.SentryException>? SentryExceptions { get; set; }
         public System.Collections.Generic.IEnumerable<Sentry.SentryThread>? SentryThreads { get; set; }
         public string? ServerName { get; set; }
@@ -556,6 +570,7 @@ namespace Sentry
     {
         public SentryStackFrame() { }
         public string? AbsolutePath { get; set; }
+        public string? AddressMode { get; set; }
         public int? ColumnNumber { get; set; }
         public string? ContextLine { get; set; }
         public string? FileName { get; set; }

test/Sentry.DiagnosticSource.Tests/ApiApprovalTests.Run.DotNet6_0.verified.txt

@@ -355,6 +355,19 @@ namespace Sentry
         public static Sentry.SentryId CaptureMessage(this Sentry.ISentryClient client, string message, Sentry.SentryLevel level = 1) { }
         public static void CaptureUserFeedback(this Sentry.ISentryClient client, Sentry.SentryId eventId, string email, string comments, string? name = null) { }
     }
+    public sealed class SentryDebugImage : Sentry.IJsonSerializable
+    {
+        public SentryDebugImage() { }
+        public string? CodeFile { get; set; }
+        public string? CodeId { get; set; }
+        public string? DebugFile { get; set; }
+        public string? DebugId { get; set; }
+        public string? ImageAddress { get; set; }
+        public long ImageSize { get; set; }
+        public string? Type { get; set; }
+        public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
+        public static Sentry.SentryDebugImage FromJson(System.Text.Json.JsonElement json) { }
+    }
     [System.Diagnostics.DebuggerDisplay("{GetType().Name,nq}: {EventId,nq}")]
     public sealed class SentryEvent : Sentry.IEventLike, Sentry.IHasBreadcrumbs, Sentry.IHasExtra, Sentry.IHasTags, Sentry.IJsonSerializable
     {
@@ -375,6 +388,7 @@ namespace Sentry
         public string? Release { get; set; }
         public Sentry.Request Request { get; set; }
         public Sentry.SdkVersion Sdk { get; }
+        public System.Collections.Generic.List<Sentry.SentryDebugImage>? SentryDebugImages { get; set; }
         public System.Collections.Generic.IEnumerable<Sentry.Protocol.SentryException>? SentryExceptions { get; set; }
         public System.Collections.Generic.IEnumerable<Sentry.SentryThread>? SentryThreads { get; set; }
         public string? ServerName { get; set; }
@@ -556,6 +570,7 @@ namespace Sentry
     {
         public SentryStackFrame() { }
         public string? AbsolutePath { get; set; }
+        public string? AddressMode { get; set; }
         public int? ColumnNumber { get; set; }
         public string? ContextLine { get; set; }
         public string? FileName { get; set; }

test/Sentry.Tests/ApiApprovalTests.Run.Core2_1.verified.txt

@@ -355,6 +355,19 @@ namespace Sentry
         public static Sentry.SentryId CaptureMessage(this Sentry.ISentryClient client, string message, Sentry.SentryLevel level = 1) { }
         public static void CaptureUserFeedback(this Sentry.ISentryClient client, Sentry.SentryId eventId, string email, string comments, string? name = null) { }
     }
+    public sealed class SentryDebugImage : Sentry.IJsonSerializable
+    {
+        public SentryDebugImage() { }
+        public string? CodeFile { get; set; }
+        public string? CodeId { get; set; }
+        public string? DebugFile { get; set; }
+        public string? DebugId { get; set; }
+        public string? ImageAddress { get; set; }
+        public long ImageSize { get; set; }
+        public string? Type { get; set; }
+        public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
+        public static Sentry.SentryDebugImage FromJson(System.Text.Json.JsonElement json) { }
+    }
     [System.Diagnostics.DebuggerDisplay("{GetType().Name,nq}: {EventId,nq}")]
     public sealed class SentryEvent : Sentry.IEventLike, Sentry.IHasBreadcrumbs, Sentry.IHasExtra, Sentry.IHasTags, Sentry.IJsonSerializable
     {
@@ -375,6 +388,7 @@ namespace Sentry
         public string? Release { get; set; }
         public Sentry.Request Request { get; set; }
         public Sentry.SdkVersion Sdk { get; }
+        public System.Collections.Generic.List<Sentry.SentryDebugImage>? SentryDebugImages { get; set; }
         public System.Collections.Generic.IEnumerable<Sentry.Protocol.SentryException>? SentryExceptions { get; set; }
         public System.Collections.Generic.IEnumerable<Sentry.SentryThread>? SentryThreads { get; set; }
         public string? ServerName { get; set; }
@@ -555,6 +569,7 @@ namespace Sentry
     {
         public SentryStackFrame() { }
         public string? AbsolutePath { get; set; }
+        public string? AddressMode { get; set; }
         public int? ColumnNumber { get; set; }
         public string? ContextLine { get; set; }
         public string? FileName { get; set; }

test/Sentry.Tests/ApiApprovalTests.Run.Core3_0.verified.txt

@@ -355,6 +355,19 @@ namespace Sentry
         public static Sentry.SentryId CaptureMessage(this Sentry.ISentryClient client, string message, Sentry.SentryLevel level = 1) { }
         public static void CaptureUserFeedback(this Sentry.ISentryClient client, Sentry.SentryId eventId, string email, string comments, string? name = null) { }
     }
+    public sealed class SentryDebugImage : Sentry.IJsonSerializable
+    {
+        public SentryDebugImage() { }
+        public string? CodeFile { get; set; }
+        public string? CodeId { get; set; }
+        public string? DebugFile { get; set; }
+        public string? DebugId { get; set; }
+        public string? ImageAddress { get; set; }
+        public long ImageSize { get; set; }
+        public string? Type { get; set; }
+        public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
+        public static Sentry.SentryDebugImage FromJson(System.Text.Json.JsonElement json) { }
+    }
     [System.Diagnostics.DebuggerDisplay("{GetType().Name,nq}: {EventId,nq}")]
     public sealed class SentryEvent : Sentry.IEventLike, Sentry.IHasBreadcrumbs, Sentry.IHasExtra, Sentry.IHasTags, Sentry.IJsonSerializable
     {
@@ -375,6 +388,7 @@ namespace Sentry
         public string? Release { get; set; }
         public Sentry.Request Request { get; set; }
         public Sentry.SdkVersion Sdk { get; }
+        public System.Collections.Generic.List<Sentry.SentryDebugImage>? SentryDebugImages { get; set; }
         public System.Collections.Generic.IEnumerable<Sentry.Protocol.SentryException>? SentryExceptions { get; set; }
         public System.Collections.Generic.IEnumerable<Sentry.SentryThread>? SentryThreads { get; set; }
         public string? ServerName { get; set; }
@@ -555,6 +569,7 @@ namespace Sentry
     {
         public SentryStackFrame() { }
         public string? AbsolutePath { get; set; }
+        public string? AddressMode { get; set; }
         public int? ColumnNumber { get; set; }
         public string? ContextLine { get; set; }
         public string? FileName { get; set; }