feat: Added instruction_addr_adjustment attribute

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Features
+
+- Added `instruction_addr_adjustment` attribute to SentryStackTrace ([#2151](https://github.com/getsentry/sentry-dotnet/pull/2151))
+
 ### Fixes
 
 - Workaround Visual Studio "Pair to Mac" issue (on Windows), and Update bundled Cocoa SDK to version 7.31.5 ([#2164](https://github.com/getsentry/sentry-dotnet/pull/2164))

src/Sentry/SentryStackTrace.cs

@@ -3,6 +3,35 @@
 
 namespace Sentry;
 
+/// <summary>
+/// Instruction Address Adjustments
+/// </summary>
+public enum InstructionAddressAdjustment
+{
+    /// <summary>
+    /// Symbolicator will use the `"all_but_first"` strategy **unless** the event has a crashing `signal`
+    /// attribute and the Stack Trace has a `registers` map, and the instruction pointer register (`rip` / `pc`)
+    /// does not match the first frame. In that case, `"all"` frames will be adjusted.
+    /// </summary>
+    Auto,
+
+    /// <summary>
+    /// All frames of the stack trace will be adjusted, subtracting one instruction with (or `1`) from the
+    /// incoming `instruction_addr` before symbolication.
+    /// </summary>
+    All,
+
+    /// <summary>
+    /// All frames but the first (in callee to caller / child to parent direction) should be adjusted.
+    /// </summary>
+    AllButFirst,
+
+    /// <summary>
+    /// No adjustment will be applied whatsoever.
+    /// </summary>
+    None
+}
+
 /// <summary>
 /// Sentry Stacktrace interface.
 /// </summary>
@@ -27,13 +56,35 @@ public IList<SentryStackFrame> Frames
         set => InternalFrames = value;
     }
 
+    /// <summary>
+    /// The optional instruction address adjustment.
+    /// </summary>
+    /// <remarks>
+    /// Tells the symbolicator if and what adjustment for is needed.
+    /// </remarks>
+    public InstructionAddressAdjustment? AddressAdjustment { get; set; }
+
     /// <inheritdoc />
     public void WriteTo(Utf8JsonWriter writer, IDiagnosticLogger? logger)
     {
         writer.WriteStartObject();
 
         writer.WriteArrayIfNotEmpty("frames", InternalFrames, logger);
 
+        if (AddressAdjustment is { } instructionAddressAdjustment)
+        {
+            var adjustmentType = instructionAddressAdjustment switch
+            {
+                InstructionAddressAdjustment.Auto => "auto",
+                InstructionAddressAdjustment.All => "all",
+                InstructionAddressAdjustment.AllButFirst => "all_but_first",
+                InstructionAddressAdjustment.None => "none",
+                _ => "auto"
+            };
+
+            writer.WriteString("instruction_addr_adjustment", adjustmentType);
+        }
+
         writer.WriteEndObject();
     }
 
@@ -48,9 +99,15 @@ public static SentryStackTrace FromJson(JsonElement json)
             .Select(SentryStackFrame.FromJson)
             .ToArray();
 
+        var instructionAddressAdjustment = json
+            .GetPropertyOrNull("instruction_addr_adjustment")
+            ?.ToString()
+            ?.ParseEnum<InstructionAddressAdjustment>();
+
         return new SentryStackTrace
         {
-            InternalFrames = frames
+            InternalFrames = frames,
+            AddressAdjustment = instructionAddressAdjustment
         };
     }
 }

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

@@ -277,6 +277,13 @@ namespace Sentry
         string Name { get; }
     }
     public interface ITransactionData : Sentry.IEventLike, Sentry.IHasBreadcrumbs, Sentry.IHasExtra, Sentry.IHasTags, Sentry.ISpanContext, Sentry.ISpanData, Sentry.ITransactionContext, Sentry.Protocol.ITraceContext { }
+    public enum InstructionAddressAdjustment
+    {
+        Auto = 0,
+        All = 1,
+        AllButFirst = 2,
+        None = 3,
+    }
     public static class MeasurementExtensions
     {
         public static void SetMeasurement(this Sentry.ITransactionData transaction, string name, double value, Sentry.MeasurementUnit unit = default) { }
@@ -699,6 +706,7 @@ namespace Sentry
     public class SentryStackTrace : Sentry.IJsonSerializable
     {
         public SentryStackTrace() { }
+        public Sentry.InstructionAddressAdjustment? AddressAdjustment { get; set; }
         public System.Collections.Generic.IList<Sentry.SentryStackFrame> Frames { get; set; }
         public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
         public static Sentry.SentryStackTrace FromJson(System.Text.Json.JsonElement json) { }

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

@@ -276,6 +276,13 @@ namespace Sentry
         string Name { get; }
     }
     public interface ITransactionData : Sentry.IEventLike, Sentry.IHasBreadcrumbs, Sentry.IHasExtra, Sentry.IHasTags, Sentry.ISpanContext, Sentry.ISpanData, Sentry.ITransactionContext, Sentry.Protocol.ITraceContext { }
+    public enum InstructionAddressAdjustment
+    {
+        Auto = 0,
+        All = 1,
+        AllButFirst = 2,
+        None = 3,
+    }
     public static class MeasurementExtensions
     {
         public static void SetMeasurement(this Sentry.ITransactionData transaction, string name, double value, Sentry.MeasurementUnit unit = default) { }
@@ -698,6 +705,7 @@ namespace Sentry
     public class SentryStackTrace : Sentry.IJsonSerializable
     {
         public SentryStackTrace() { }
+        public Sentry.InstructionAddressAdjustment? AddressAdjustment { get; set; }
         public System.Collections.Generic.IList<Sentry.SentryStackFrame> Frames { get; set; }
         public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
         public static Sentry.SentryStackTrace FromJson(System.Text.Json.JsonElement json) { }

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

@@ -277,6 +277,13 @@ namespace Sentry
         string Name { get; }
     }
     public interface ITransactionData : Sentry.IEventLike, Sentry.IHasBreadcrumbs, Sentry.IHasExtra, Sentry.IHasTags, Sentry.ISpanContext, Sentry.ISpanData, Sentry.ITransactionContext, Sentry.Protocol.ITraceContext { }
+    public enum InstructionAddressAdjustment
+    {
+        Auto = 0,
+        All = 1,
+        AllButFirst = 2,
+        None = 3,
+    }
     public static class MeasurementExtensions
     {
         public static void SetMeasurement(this Sentry.ITransactionData transaction, string name, double value, Sentry.MeasurementUnit unit = default) { }
@@ -699,6 +706,7 @@ namespace Sentry
     public class SentryStackTrace : Sentry.IJsonSerializable
     {
         public SentryStackTrace() { }
+        public Sentry.InstructionAddressAdjustment? AddressAdjustment { get; set; }
         public System.Collections.Generic.IList<Sentry.SentryStackFrame> Frames { get; set; }
         public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
         public static Sentry.SentryStackTrace FromJson(System.Text.Json.JsonElement json) { }

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

@@ -277,6 +277,13 @@ namespace Sentry
         string Name { get; }
     }
     public interface ITransactionData : Sentry.IEventLike, Sentry.IHasBreadcrumbs, Sentry.IHasExtra, Sentry.IHasTags, Sentry.ISpanContext, Sentry.ISpanData, Sentry.ITransactionContext, Sentry.Protocol.ITraceContext { }
+    public enum InstructionAddressAdjustment
+    {
+        Auto = 0,
+        All = 1,
+        AllButFirst = 2,
+        None = 3,
+    }
     public static class MeasurementExtensions
     {
         public static void SetMeasurement(this Sentry.ITransactionData transaction, string name, double value, Sentry.MeasurementUnit unit = default) { }
@@ -699,6 +706,7 @@ namespace Sentry
     public class SentryStackTrace : Sentry.IJsonSerializable
     {
         public SentryStackTrace() { }
+        public Sentry.InstructionAddressAdjustment? AddressAdjustment { get; set; }
         public System.Collections.Generic.IList<Sentry.SentryStackFrame> Frames { get; set; }
         public void WriteTo(System.Text.Json.Utf8JsonWriter writer, Sentry.Extensibility.IDiagnosticLogger? logger) { }
         public static Sentry.SentryStackTrace FromJson(System.Text.Json.JsonElement json) { }