[Dynamic Instrumentation] DEBUG-5101 line probe two segment fallback (#8543)

## Summary of changes

- Update `LineProbeResolver` to support line probe source-file fallback
matches when only the last 2 path segments match (down from 4).
- Keep the existing strict-top-score binding rule, so fallback only
binds when a single qualified candidate has the strictly highest
matching-trailing-segment score across all currently loaded symbolicated
assemblies.
- Preserve bound diagnostics for fallback resolutions by reporting
`FallbackTrailingSuffixMatch` together with the matched trailing-segment
count.
- Extend `LineProbeResolverTest` coverage for 2-segment fallback binding
and for picking the highest-scoring candidate when incidental
low-scoring matches exist.

## Reason for change

- `DEBUG-5101` requires line probes to resolve when the configured
source path differs from the PDB path except for the trailing directory
and filename (for example `unknown-prefix/Controllers/HomeController.cs`
against a PDB path ending in `Controllers/HomeController.cs`).
- Raising the matching reach without weakening safety is the goal: the
existing top-score ambiguity check (across assemblies and within each
assembly) is sufficient to keep wrong-assembly binding out, so we don't
need to add a new uniqueness restriction on top of it.

## Implementation details

- Lower `MinTrailingSegmentsForFallbackMatch` from 4 to 2 so resolver
fallback can match scenarios like `unknown-prefix/Controllers/File.cs`
against a loaded symbolicated assembly path ending in
`Controllers/File.cs`.
- Encapsulate the cross-assembly qualified-candidate counter inside
`BestFallbackMatchSelection` (replacing the standalone `ref int
qualifiedFallbackMatchCount` parameter on `TrackClosestPathMatch`) and
expose it as `QualifiedMatchCount` so the diagnostics path keeps the
same information.
- Preserve the binding rule: bind to the candidate with the strictly
highest matching-trailing-segment score, reject when the top score is
tied across assemblies or when the top-scoring assembly is itself
internally ambiguous (`HasAmbiguousBestMatch`).
- Keep diagnostics explicit for successful fallback binds by continuing
to emit `LineProbePathMatchType.FallbackTrailingSuffixMatch` together
with the trailing-segment count used to resolve the probe.
- The resolver change stays in warm-path debugger resolution logic and
only adds integer bookkeeping on top of the existing assembly scan; no
new allocations on this path.

## Test coverage

- Ran:
  - `LineProbeResolverTest`
- Added coverage for:
- 2-segment fallback binding
(`FallbackMatchBindsWhenOnlyTwoTrailingSegmentsMatch`)
- binding to the highest-scoring qualified candidate when incidental
lower-scoring matches exist
(`BestFallbackMatchSelectionBindsHighestScoreOverIncidentalLowScoringCandidates`)
- binding when a single qualified candidate is tracked
(`BestFallbackMatchSelectionBindsWhenSingleQualifiedCandidateIsTracked`)

Author: dudikeleti

tracer/src/Datadog.Trace/Debugger/LineProbeResolver.cs

@@ -22,7 +22,7 @@ namespace Datadog.Trace.Debugger
 {
     internal sealed class LineProbeResolver : ILineProbeResolver
     {
-        private const int MinTrailingSegmentsForFallbackMatch = 4;
+        private const int MinTrailingSegmentsForFallbackMatch = 2;
         private const int MaxSameFileNameExamples = 3;
         private static readonly IDatadogLogger Log = DatadogLogging.GetLoggerFor<LineProbeResolver>();
         private readonly ImmutableHashSet<string> _thirdPartyDetectionExcludes;
@@ -101,7 +101,6 @@ private static void TrackClosestPathMatch(
             bool includeExamplePaths,
             ref int sameFileNameMatchCount,
             ref int bestMatchingTrailingSegments,
-            ref int qualifiedFallbackMatchCount,
             ref List<string>? sameFileNameMatches)
         {
             if (result.ExampleSameFileNamePath is null)
@@ -120,8 +119,6 @@ private static void TrackClosestPathMatch(
             {
                 bestMatchingTrailingSegments = result.BestMatchingTrailingSegments;
             }
-
-            qualifiedFallbackMatchCount += result.QualifiedMatchCount;
         }
 
         private static LineProbeResolutionDiagnostics BuildMinimalDiagnostics(string probeFile, int? probeLine, string probeId)
@@ -210,7 +207,6 @@ private bool TryFindAssemblyContainingFile(string probeFilePath, LineProbeDiagno
                 var symbolicatedAssemblyCount = 0;
                 var sameFileNameMatchCount = 0;
                 var bestMatchingTrailingSegments = 0;
-                var qualifiedFallbackMatchCount = 0;
 
                 foreach (var candidateAssembly in AppDomain.CurrentDomain.GetAssemblies())
                 {
@@ -237,10 +233,9 @@ private bool TryFindAssemblyContainingFile(string probeFilePath, LineProbeDiagno
                         includeDetailedDiagnostics,
                         ref sameFileNameMatchCount,
                         ref bestMatchingTrailingSegments,
-                        ref qualifiedFallbackMatchCount,
                         ref sameFileNameMatches);
 
-                    // Only bind when a single global fallback candidate has the best score.
+                    // Only bind when a single global fallback candidate has the strictly best score.
                     // Assemblies with internally ambiguous fallback matches must still participate in that global tie.
                     bestFallbackMatchSelection.Track(candidateAssembly, in closestPathMatch);
                 }
@@ -257,7 +252,7 @@ private bool TryFindAssemblyContainingFile(string probeFilePath, LineProbeDiagno
                     symbolicatedAssemblyCount,
                     sameFileNameMatchCount,
                     bestMatchingTrailingSegments,
-                    qualifiedFallbackMatchCount,
+                    bestFallbackMatchSelection.QualifiedMatchCount,
                     bestFallbackMatchSelection.HasAmbiguousBestMatch,
                     includeDetailedDiagnostics ? sameFileNameMatches?.ToArray() ?? [] : []);
                 return false;
@@ -376,18 +371,22 @@ internal struct BestFallbackMatchSelection
         {
             private BestFallbackMatch? _bestMatch;
             private int _bestMatchingTrailingSegments;
+            private int _qualifiedMatchCount;
 
             public BestFallbackMatch? BestMatch => HasAmbiguousBestMatch ? null : _bestMatch;
 
             public bool HasAmbiguousBestMatch { get; private set; }
 
+            public int QualifiedMatchCount => _qualifiedMatchCount;
+
             public void Track(Assembly assembly, in ClosestPathBySuffixResult result)
             {
                 if (result.QualifiedMatchCount == 0)
                 {
                     return;
                 }
 
+                _qualifiedMatchCount += result.QualifiedMatchCount;
                 var candidateScore = result.BestQualifiedMatchingTrailingSegments;
                 if (candidateScore > _bestMatchingTrailingSegments)
                 {

tracer/test/Datadog.Trace.Debugger.IntegrationTests/LineProbeResolverTest.cs

@@ -3,6 +3,7 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
 // </copyright>
 
+using System;
 using System.Linq;
 using Datadog.Trace.Debugger.Configurations.Models;
 using Datadog.Trace.Debugger.IntegrationTests.Helpers;
@@ -158,6 +159,19 @@ public void FallbackMatchBindsWhenOnlyLeadingSegmentsDiffer()
         loc.Should().NotBeNull();
     }
 
+    [Fact]
+    public void FallbackMatchBindsWhenOnlyTwoTrailingSegmentsMatch()
+    {
+        _probeDefinition.Where.SourceFile = BuildProbePathWithUnknownPrefix(_probeDefinition.Where.SourceFile, trailingSegmentCount: 2);
+
+        var result = _lineProbeResolver.TryResolveLineProbe(_probeDefinition, out var loc);
+
+        result.Status.Should().Be(LiveProbeResolveStatus.Bound);
+        result.Diagnostics.PathMatchType.Should().Be(LineProbePathMatchType.FallbackTrailingSuffixMatch);
+        result.Diagnostics.MatchingTrailingSegments.Should().Be(2);
+        loc.Should().NotBeNull();
+    }
+
     [Fact]
     public void FilePathLookupFindsClosestUniqueSuffixMatchForLinuxPaths()
     {
@@ -262,6 +276,19 @@ public void BestFallbackMatchSelectionRejectsTieWhenHighestScoreIsAlreadyAmbiguo
         selection.BestMatch.Should().BeNull();
     }
 
+    [Fact]
+    public void BestFallbackMatchSelectionBindsWhenSingleQualifiedCandidateIsTracked()
+    {
+        var selection = new LineProbeResolver.BestFallbackMatchSelection();
+
+        selection.Track(typeof(LineProbeResolverTest).Assembly, CreateClosestPathBySuffixResult(@"/b/src/One/Shared/Feature/MyFile.cs", matchingTrailingSegments: 5, isAmbiguous: false));
+
+        selection.QualifiedMatchCount.Should().Be(1);
+        selection.BestMatch.Should().NotBeNull();
+        selection.BestMatch!.Value.Path.Should().Be(@"/b/src/One/Shared/Feature/MyFile.cs");
+        selection.BestMatch!.Value.MatchingTrailingSegments.Should().Be(5);
+    }
+
     [Fact]
     public void BestFallbackMatchSelectionAllowsHigherUniqueScoreToOverrideEarlierAmbiguity()
     {
@@ -271,11 +298,27 @@ public void BestFallbackMatchSelectionAllowsHigherUniqueScoreToOverrideEarlierAm
         selection.Track(typeof(LineProbeResolverTest).Assembly, CreateClosestPathBySuffixResult(@"/b/src/One/Shared/Feature/MyFile.cs", matchingTrailingSegments: 5, isAmbiguous: false));
 
         selection.HasAmbiguousBestMatch.Should().BeFalse();
+        selection.QualifiedMatchCount.Should().Be(3);
         selection.BestMatch.Should().NotBeNull();
         selection.BestMatch!.Value.Path.Should().Be(@"/b/src/One/Shared/Feature/MyFile.cs");
         selection.BestMatch!.Value.MatchingTrailingSegments.Should().Be(5);
     }
 
+    [Fact]
+    public void BestFallbackMatchSelectionBindsHighestScoreOverIncidentalLowScoringCandidates()
+    {
+        var selection = new LineProbeResolver.BestFallbackMatchSelection();
+
+        selection.Track(typeof(LineProbeResolverTest).Assembly, CreateClosestPathBySuffixResult(@"/a/src/MyProject/Controllers/HomeController.cs", matchingTrailingSegments: 6, isAmbiguous: false));
+        selection.Track(typeof(string).Assembly, CreateClosestPathBySuffixResult(@"/vendor/Controllers/HomeController.cs", matchingTrailingSegments: 2, isAmbiguous: false));
+
+        selection.HasAmbiguousBestMatch.Should().BeFalse();
+        selection.QualifiedMatchCount.Should().Be(2);
+        selection.BestMatch.Should().NotBeNull();
+        selection.BestMatch!.Value.Path.Should().Be(@"/a/src/MyProject/Controllers/HomeController.cs");
+        selection.BestMatch!.Value.MatchingTrailingSegments.Should().Be(6);
+    }
+
     [Fact]
     public void OutOfBoundsLineProbeReturnsAnError()
     {
@@ -433,6 +476,17 @@ public void MinimalDiagnosticsOnUnboundResolutionKeepReasonButSkipDetailedFields
         loc.Should().BeNull();
     }
 
+    private static string BuildProbePathWithUnknownPrefix(string sourceFile, int trailingSegmentCount)
+    {
+        var segments = sourceFile.Split(new[] { '\\', '/' }, StringSplitOptions.RemoveEmptyEntries);
+        if (segments.Length < trailingSegmentCount)
+        {
+            throw new InvalidOperationException($"Expected at least {trailingSegmentCount} path segments.");
+        }
+
+        return $@"UnknownPrefix\{string.Join(@"\", segments.Skip(segments.Length - trailingSegmentCount))}";
+    }
+
     private static LineProbeResolver.ClosestPathBySuffixResult CreateClosestPathBySuffixResult(string path, int matchingTrailingSegments, bool isAmbiguous)
     {
         return new LineProbeResolver.ClosestPathBySuffixResult(