feat: Add new Protocol for DebugImages and AddressMode (#1513)

Co-authored-by: Simon Cropp <simon.cropp@gmail.com> Co-authored-by: Bruno Garcia <bruno@brunogarcia.com>
getsentry · Mar 30, 2022 · 1bcfc3f · 1bcfc3f
1 parent 982f223
commit 1bcfc3f
Show file tree

Hide file tree

Showing 16 changed files with 317 additions and 5 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,7 @@
 ### Features
 
 - Use a default value of 60 seconds if a `Retry-After` header is not present. ([#1537](https://github.com/getsentry/sentry-dotnet/pull/1537))
+- Add new Protocol definitions for DebugImages and AddressMode ([#1513](https://github.com/getsentry/sentry-dotnet/pull/1513))
 
 ### Fixes
 

diff --git a/src/Sentry/DebugImage.cs b/src/Sentry/DebugImage.cs
@@ -0,0 +1,92 @@
+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 DebugImage : 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 DebugImage FromJson(JsonElement json)
+        {
+            var type = json.GetPropertyOrNull("type")?.GetString();
+            var imageAddress = json.GetPropertyOrNull("image_addr")?.GetString();
+            var imageSize = json.GetPropertyOrNull("image_size")?.GetInt64();
+            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 DebugImage
+            {
+                Type = type,
+                ImageAddress = imageAddress,
+                ImageSize = imageSize,
+                DebugId = debugId,
+                DebugFile = debugFile,
+                CodeId = codeId,
+                CodeFile = codeFile,
+            };
+        }
+    }
+}
diff --git a/src/Sentry/Exceptions/SentryStackFrame.cs b/src/Sentry/Exceptions/SentryStackFrame.cs
@@ -134,6 +134,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)
         {
@@ -157,6 +165,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();
         }
@@ -207,6 +216,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
             {
@@ -227,7 +237,8 @@ public static SentryStackFrame FromJson(JsonElement json)
                 ImageAddress = imageAddress,
                 SymbolAddress = symbolAddress,
                 InstructionAddress = instructionAddress,
-                InstructionOffset = instructionOffset
+                InstructionOffset = instructionOffset,
+                AddressMode = addressMode,
             };
         }
     }

diff --git a/src/Sentry/SentryEvent.cs b/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<DebugImage>? DebugImages { 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 (DebugImages?.Count > 0)
+            {
+                writer.WritePropertyName("debug_meta");
+                writer.WriteStartObject();
+
+                writer.WriteArray("images", DebugImages.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(DebugImage.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,
+                DebugImages = images,
                 Level = level,
                 TransactionName = transaction,
                 _request = request,

diff --git a/test/Sentry.DiagnosticSource.Tests/ApiApprovalTests.Run.Core3_1.verified.txt b/test/Sentry.DiagnosticSource.Tests/ApiApprovalTests.Run.Core3_1.verified.txt
@@ -70,6 +70,19 @@ namespace Sentry
         public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
         public static Sentry.Contexts FromJson(System.Text.Json.JsonElement json) { }
     }
+    public sealed class DebugImage : Sentry.IJsonSerializable
+    {
+        public DebugImage() { }
+        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.DebugImage FromJson(System.Text.Json.JsonElement json) { }
+    }
     [System.Flags]
     public enum DeduplicateMode
     {
@@ -362,6 +375,7 @@ namespace Sentry
         public SentryEvent(System.Exception? exception) { }
         public System.Collections.Generic.IReadOnlyCollection<Sentry.Breadcrumb> Breadcrumbs { get; }
         public Sentry.Contexts Contexts { get; set; }
+        public System.Collections.Generic.List<Sentry.DebugImage>? DebugImages { get; set; }
         public string? Environment { get; set; }
         public Sentry.SentryId EventId { get; }
         public System.Exception? Exception { get; }
@@ -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; }

diff --git a/test/Sentry.DiagnosticSource.Tests/ApiApprovalTests.Run.DotNet5_0.verified.txt b/test/Sentry.DiagnosticSource.Tests/ApiApprovalTests.Run.DotNet5_0.verified.txt
@@ -70,6 +70,19 @@ namespace Sentry
         public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
         public static Sentry.Contexts FromJson(System.Text.Json.JsonElement json) { }
     }
+    public sealed class DebugImage : Sentry.IJsonSerializable
+    {
+        public DebugImage() { }
+        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.DebugImage FromJson(System.Text.Json.JsonElement json) { }
+    }
     [System.Flags]
     public enum DeduplicateMode
     {
@@ -362,6 +375,7 @@ namespace Sentry
         public SentryEvent(System.Exception? exception) { }
         public System.Collections.Generic.IReadOnlyCollection<Sentry.Breadcrumb> Breadcrumbs { get; }
         public Sentry.Contexts Contexts { get; set; }
+        public System.Collections.Generic.List<Sentry.DebugImage>? DebugImages { get; set; }
         public string? Environment { get; set; }
         public Sentry.SentryId EventId { get; }
         public System.Exception? Exception { get; }
@@ -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; }

diff --git a/test/Sentry.DiagnosticSource.Tests/ApiApprovalTests.Run.DotNet6_0.verified.txt b/test/Sentry.DiagnosticSource.Tests/ApiApprovalTests.Run.DotNet6_0.verified.txt
@@ -70,6 +70,19 @@ namespace Sentry
         public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
         public static Sentry.Contexts FromJson(System.Text.Json.JsonElement json) { }
     }
+    public sealed class DebugImage : Sentry.IJsonSerializable
+    {
+        public DebugImage() { }
+        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.DebugImage FromJson(System.Text.Json.JsonElement json) { }
+    }
     [System.Flags]
     public enum DeduplicateMode
     {
@@ -362,6 +375,7 @@ namespace Sentry
         public SentryEvent(System.Exception? exception) { }
         public System.Collections.Generic.IReadOnlyCollection<Sentry.Breadcrumb> Breadcrumbs { get; }
         public Sentry.Contexts Contexts { get; set; }
+        public System.Collections.Generic.List<Sentry.DebugImage>? DebugImages { get; set; }
         public string? Environment { get; set; }
         public Sentry.SentryId EventId { get; }
         public System.Exception? Exception { get; }
@@ -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; }

diff --git a/test/Sentry.Tests/ApiApprovalTests.Run.Core2_1.verified.txt b/test/Sentry.Tests/ApiApprovalTests.Run.Core2_1.verified.txt
@@ -70,6 +70,19 @@ namespace Sentry
         public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
         public static Sentry.Contexts FromJson(System.Text.Json.JsonElement json) { }
     }
+    public sealed class DebugImage : Sentry.IJsonSerializable
+    {
+        public DebugImage() { }
+        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.DebugImage FromJson(System.Text.Json.JsonElement json) { }
+    }
     [System.Flags]
     public enum DeduplicateMode
     {
@@ -362,6 +375,7 @@ namespace Sentry
         public SentryEvent(System.Exception? exception) { }
         public System.Collections.Generic.IReadOnlyCollection<Sentry.Breadcrumb> Breadcrumbs { get; }
         public Sentry.Contexts Contexts { get; set; }
+        public System.Collections.Generic.List<Sentry.DebugImage>? DebugImages { get; set; }
         public string? Environment { get; set; }
         public Sentry.SentryId EventId { get; }
         public System.Exception? Exception { get; }
@@ -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; }

diff --git a/test/Sentry.Tests/ApiApprovalTests.Run.Core3_0.verified.txt b/test/Sentry.Tests/ApiApprovalTests.Run.Core3_0.verified.txt
@@ -70,6 +70,19 @@ namespace Sentry
         public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
         public static Sentry.Contexts FromJson(System.Text.Json.JsonElement json) { }
     }
+    public sealed class DebugImage : Sentry.IJsonSerializable
+    {
+        public DebugImage() { }
+        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.DebugImage FromJson(System.Text.Json.JsonElement json) { }
+    }
     [System.Flags]
     public enum DeduplicateMode
     {
@@ -362,6 +375,7 @@ namespace Sentry
         public SentryEvent(System.Exception? exception) { }
         public System.Collections.Generic.IReadOnlyCollection<Sentry.Breadcrumb> Breadcrumbs { get; }
         public Sentry.Contexts Contexts { get; set; }
+        public System.Collections.Generic.List<Sentry.DebugImage>? DebugImages { get; set; }
         public string? Environment { get; set; }
         public Sentry.SentryId EventId { get; }
         public System.Exception? Exception { get; }
@@ -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; }