feat: Capture Debug Images and StackFrame fields for Portable PDB symbolication

src/Sentry/DebugImage.cs

@@ -32,6 +32,11 @@ public sealed class DebugImage : IJsonSerializable
     /// </summary>
     public string? DebugId { get; set; }
 
+    /// <summary>
+    /// Checksum of the companion debug file.
+    /// </summary>
+    public string? DebugChecksum { get; set; }
+
     /// <summary>
     /// Path and name of the debug companion file.
     /// </summary>
@@ -57,6 +62,7 @@ public void WriteTo(Utf8JsonWriter writer, IDiagnosticLogger? logger)
         writer.WriteStringIfNotWhiteSpace("image_addr", ImageAddress);
         writer.WriteNumberIfNotNull("image_size", ImageSize);
         writer.WriteStringIfNotWhiteSpace("debug_id", DebugId);
+        writer.WriteStringIfNotWhiteSpace("debug_checksum", DebugChecksum);
         writer.WriteStringIfNotWhiteSpace("debug_file", DebugFile);
         writer.WriteStringIfNotWhiteSpace("code_id", CodeId);
         writer.WriteStringIfNotWhiteSpace("code_file", CodeFile);
@@ -73,6 +79,7 @@ public static DebugImage FromJson(JsonElement json)
         var imageAddress = json.GetPropertyOrNull("image_addr")?.GetString();
         var imageSize = json.GetPropertyOrNull("image_size")?.GetInt64();
         var debugId = json.GetPropertyOrNull("debug_id")?.GetString();
+        var debugChecksum = json.GetPropertyOrNull("debug_checksum")?.GetString();
         var debugFile = json.GetPropertyOrNull("debug_file")?.GetString();
         var codeId = json.GetPropertyOrNull("code_id")?.GetString();
         var codeFile = json.GetPropertyOrNull("code_file")?.GetString();
@@ -83,6 +90,7 @@ public static DebugImage FromJson(JsonElement json)
             ImageAddress = imageAddress,
             ImageSize = imageSize,
             DebugId = debugId,
+            DebugChecksum = debugChecksum,
             DebugFile = debugFile,
             CodeId = codeId,
             CodeFile = codeFile,

src/Sentry/Extensibility/ISentryStackTraceFactory.cs

@@ -1,3 +1,5 @@
+using System.Collections.Generic;
+
 namespace Sentry.Extensibility;
 
 /// <summary>
@@ -11,4 +13,10 @@ public interface ISentryStackTraceFactory
     /// <param name="exception">The exception to create the stacktrace from.</param>
     /// <returns>A Sentry stack trace.</returns>
     SentryStackTrace? Create(Exception? exception = null);
+
+    /// <summary>
+    /// Returns a list of <see cref="DebugImage" />s referenced from the previously processed <see cref="Exception" />s.
+    /// </summary>
+    /// <returns>A list of referenced debug images.</returns>
+    List<DebugImage>? DebugImages() { return null; }
 }

src/Sentry/Extensibility/SentryStackTraceFactory.cs

@@ -1,5 +1,9 @@
 using System.Diagnostics;
+using System.IO;
+using System.Linq;
 using System.Reflection;
+using System.Reflection.Metadata;
+using System.Reflection.PortableExecutable;
 using System.Text;
 using System.Text.RegularExpressions;
 using Sentry.Internal.Extensions;
@@ -13,6 +17,9 @@ public class SentryStackTraceFactory : ISentryStackTraceFactory
 {
     private readonly SentryOptions _options;
 
+    private Dictionary<Guid, Int32> _debugImageIndexByModule = new Dictionary<Guid, Int32>();
+    private List<DebugImage> _debugImages = new List<DebugImage>();
+
     /*
      *  NOTE: While we could improve these regexes, doing so might break exception grouping on the backend.
      *        Specifically, RegexAsyncFunctionName would be better as:  @"^(.*)\+<(\w*|<\w*>b__\d*)>d(?:__\d*)?$"
@@ -33,6 +40,16 @@ public class SentryStackTraceFactory : ISentryStackTraceFactory
     /// </summary>
     public SentryStackTraceFactory(SentryOptions options) => _options = options;
 
+    /// <summary>
+    /// Returns a list of <see cref="DebugImage" />s referenced from the previously processed <see cref="Exception" />s.
+    /// </summary>
+    /// <returns>A list of referenced debug images.</returns>
+    public virtual List<DebugImage>? DebugImages()
+    {
+        // create a shallow copy, as we want to still mutate our local copy
+        return _debugImages.ToList();
+    }
+
     /// <summary>
     /// Creates a <see cref="SentryStackTrace" /> from the optional <see cref="Exception" />.
     /// </summary>
@@ -96,7 +113,7 @@ internal IEnumerable<SentryStackFrame> CreateFrames(StackTrace stackTrace, bool
         {
             StackTraceMode.Enhanced => EnhancedStackTrace.GetFrames(stackTrace).Select(p => p as StackFrame),
             _ => stackTrace.GetFrames()
-                // error CS8619: Nullability of reference types in value of type 'StackFrame?[]' doesn't match target type 'IEnumerable<StackFrame>'.
+            // error CS8619: Nullability of reference types in value of type 'StackFrame?[]' doesn't match target type 'IEnumerable<StackFrame>'.
 #if NETCOREAPP3_0
                 .Where(f => f is not null)
 #endif
@@ -184,6 +201,23 @@ protected SentryStackFrame InternalCreateFrame(StackFrame stackFrame, bool deman
             }
 
             AttributeReader.TryGetProjectDirectory(method.Module.Assembly, out projectPath);
+
+            var moduleIdx = GetModuleIndex(method.Module);
+            if (moduleIdx != null)
+            {
+                frame.AddressMode = String.Format("rel:{0}", moduleIdx);
+            }
+
+            var token = method.MetadataToken;
+            // The top byte is the token type, the lower three bytes are the record id.
+            // See: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms404456(v=vs.100)#metadata-token-structure
+            var tokenType = token & 0xff000000;
+            // See https://docs.microsoft.com/en-us/dotnet/framework/unmanaged-api/metadata/cortokentype-enumeration
+            if (tokenType == 0x06000000)
+            {
+                var recordId = token & 0x00ffffff;
+                frame.FunctionId = String.Format("0x{0:x}", recordId);
+            }
         }
 
         frame.ConfigureAppFrame(_options);
@@ -203,7 +237,7 @@ protected SentryStackFrame InternalCreateFrame(StackFrame stackFrame, bool deman
         var ilOffset = stackFrame.GetILOffset();
         if (ilOffset != StackFrame.OFFSET_UNKNOWN)
         {
-            frame.InstructionOffset = ilOffset;
+            frame.InstructionAddress = String.Format("0x{0:x}", ilOffset);
         }
 
         var lineNo = stackFrame.GetFileLineNumber();
@@ -236,6 +270,84 @@ protected SentryStackFrame InternalCreateFrame(StackFrame stackFrame, bool deman
         return frame;
     }
 
+
+    private Int32? GetModuleIndex(Module module)
+    {
+        var id = module.ModuleVersionId;
+        Int32 idx = 0;
+
+        if (_debugImageIndexByModule.TryGetValue(id, out idx))
+        {
+            return idx;
+        }
+        idx = _debugImages.Count;
+
+        var codeFile = module.FullyQualifiedName;
+        if (!File.Exists(codeFile))
+        {
+            return null;
+        }
+        using var stream = File.OpenRead(codeFile);
+        var peReader = new PEReader(stream);
+
+
+        var headers = peReader.PEHeaders;
+        var peHeader = headers.PEHeader;
+
+        String? codeId = null;
+        if (peHeader != null)
+        {
+            codeId = String.Format("{0:X8}{1:x}", headers.CoffHeader.TimeDateStamp, peHeader.SizeOfImage);
+        }
+
+        String? debugId = null;
+        String? debugFile = null;
+        String? debugChecksum = null;
+
+        var debugDirs = peReader.ReadDebugDirectory();
+        foreach (var entry in debugDirs)
+        {
+            if (entry.Type == DebugDirectoryEntryType.PdbChecksum)
+            {
+                var checksum = peReader.ReadPdbChecksumDebugDirectoryData(entry);
+                var checksumHex = string.Concat(checksum.Checksum.Select(b => b.ToString("x2")));
+                debugChecksum = String.Format("{0}:{1:x}", checksum.AlgorithmName, checksumHex);
+            }
+            if (!entry.IsPortableCodeView)
+            {
+                continue;
+            }
+            var codeView = peReader.ReadCodeViewDebugDirectoryData(entry);
+
+            // Together 16B of the Guid concatenated with 4B of the TimeDateStamp field of the entry form a PDB ID that
+            // should be used to match the PE/COFF image with the associated PDB (instead of Guid and Age).
+            // Matching PDB ID is stored in the #Pdb stream of the .pdb file.
+            // See https://github.com/dotnet/runtime/blob/main/docs/design/specs/PE-COFF.md#codeview-debug-directory-entry-type-2
+            debugId = String.Format("{0}-{1:x}", codeView.Guid, entry.Stamp);
+            debugFile = codeView.Path;
+        }
+
+
+        // well, we are out of luck :-(
+        if (debugId == null)
+        {
+            return null;
+        }
+
+        _debugImages.Add(new DebugImage
+        {
+            Type = "pe_dotnet",
+            CodeId = codeId,
+            CodeFile = codeFile,
+            DebugId = debugId,
+            DebugChecksum = debugChecksum,
+            DebugFile = debugFile,
+        });
+        _debugImageIndexByModule.Add(id, idx);
+
+        return idx;
+    }
+
     /// <summary>
     /// Get a <see cref="MethodBase"/> from <see cref="StackFrame"/>.
     /// </summary>

src/Sentry/Internal/MainExceptionProcessor.cs

@@ -27,6 +27,7 @@ public void Process(Exception exception, SentryEvent sentryEvent)
         MoveExceptionExtrasToEvent(sentryEvent, sentryExceptions);
 
         sentryEvent.SentryExceptions = sentryExceptions;
+        sentryEvent.DebugImages = SentryStackTraceFactoryAccessor().DebugImages();
     }
 
     // SentryException.Extra is not supported by Sentry yet.

src/Sentry/Internal/MainSentryEventProcessor.cs

@@ -106,6 +106,24 @@ public SentryEvent Process(SentryEvent @event)
             }
         }
 
+        // Add all the Debug Images that were referenced from stack traces
+        // to the Event
+        // XXX: Ideally the StackTraceFactory would write these directly when
+        // creating the StackTrace, but that interface does not work that way.
+        // As we need our indices to work, we add these images to the *beginning*,
+        // shifting any existing image to the end.
+        // This should work for example with the Unity il2cpp processor.
+        // However if any other processor is adding (or rather, referencing)
+        // indexed images, things *will* break. Whatever code is creating/adding
+        // stack traces needs to modify the list of debug images at the same
+        // time!
+        var debugImages = SentryStackTraceFactoryAccessor().DebugImages() ?? new List<DebugImage>();
+        if (@event.DebugImages != null && !debugImages.SequenceEqual(@event.DebugImages))
+        {
+            debugImages.AddRange(@event.DebugImages);
+        }
+        @event.DebugImages = debugImages;
+
         if (_options.ReportAssembliesMode != ReportAssembliesMode.None)
         {
             foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())

src/Sentry/SentryStackFrame.cs

@@ -139,6 +139,14 @@ public sealed class SentryStackFrame : IJsonSerializable
     /// </summary>
     public string? AddressMode { get; set; }
 
+    /// <summary>
+    /// The optional Function Id.<br/>
+    /// This is derived from the `MetadataToken`, and should be the record id
+    /// of a `MethodDef`.<br/>
+    /// This should be a string with a hexadecimal number that includes a <b>0x</b> prefix.<br/>
+    /// </summary>
+    public string? FunctionId { get; set; }
+
     /// <inheritdoc />
     public void WriteTo(Utf8JsonWriter writer, IDiagnosticLogger? logger)
     {
@@ -163,6 +171,7 @@ public void WriteTo(Utf8JsonWriter writer, IDiagnosticLogger? logger)
         writer.WriteStringIfNotWhiteSpace("instruction_addr", InstructionAddress);
         writer.WriteNumberIfNotNull("instruction_offset", InstructionOffset);
         writer.WriteStringIfNotWhiteSpace("addr_mode", AddressMode);
+        writer.WriteStringIfNotWhiteSpace("function_id", FunctionId);
 
         writer.WriteEndObject();
     }
@@ -214,6 +223,7 @@ public static SentryStackFrame FromJson(JsonElement json)
         var instructionAddress = json.GetPropertyOrNull("instruction_addr")?.GetString();
         var instructionOffset = json.GetPropertyOrNull("instruction_offset")?.GetInt64();
         var addressMode = json.GetPropertyOrNull("addr_mode")?.GetString();
+        var functionId = json.GetPropertyOrNull("function_id")?.GetString();
 
         return new SentryStackFrame
         {
@@ -236,6 +246,7 @@ public static SentryStackFrame FromJson(JsonElement json)
             InstructionAddress = instructionAddress,
             InstructionOffset = instructionOffset,
             AddressMode = addressMode,
+            FunctionId = functionId,
         };
     }
 }