Add near-miss diagnostics and request count/unmatched endpoints to the admin API (#1521)

* Add near-miss diagnostics and request count/unmatched admin endpoints (#171)

Add IWireMockServer.FindUnmatchedLogEntries, FindNearMisses and
FindNearMissesForUnmatchedRequests, which rank the mappings that
partially match a request by score.

Expose them through the admin API (POST requests/count,
GET requests/unmatched, GET requests/unmatched/near-misses and
GET requests/{guid}/near-misses), the RestClient and the OpenAPI document.

* Make scenario delay tests independent of server warm-up time

The two *_StateTransitions_BeforeDelayCompletes tests waited a fixed
100 ms for the scenario state to change, which fails on a cold server.
Poll server.Scenarios until the expected state is reached instead.

---------

Co-authored-by: Mattias <13809209+Quattordici@users.noreply.github.com>

src/WireMock.Net.Abstractions/Admin/Requests/NearMissModel.cs

@@ -0,0 +1,34 @@
+// Copyright © WireMock.Net
+
+namespace WireMock.Admin.Requests;
+
+/// <summary>
+/// NearMiss Model: a mapping which did not (fully) match a request.
+/// </summary>
+public class NearMissModel
+{
+    /// <summary>
+    /// The unique identifier of the log entry for the request. [Optional]
+    /// </summary>
+    public Guid? LogEntryGuid { get; set; }
+
+    /// <summary>
+    /// The request.
+    /// </summary>
+    public LogRequestModel? Request { get; set; }
+
+    /// <summary>
+    /// The unique identifier of the mapping.
+    /// </summary>
+    public Guid MappingGuid { get; set; }
+
+    /// <summary>
+    /// The title of the mapping.
+    /// </summary>
+    public string? MappingTitle { get; set; }
+
+    /// <summary>
+    /// The request match result, containing the score per matcher.
+    /// </summary>
+    public LogRequestMatchModel? RequestMatchResult { get; set; }
+}

src/WireMock.Net.Abstractions/Admin/Requests/RequestCountModel.cs

@@ -0,0 +1,14 @@
+// Copyright © WireMock.Net
+
+namespace WireMock.Admin.Requests;
+
+/// <summary>
+/// RequestCount Model
+/// </summary>
+public class RequestCountModel
+{
+    /// <summary>
+    /// The number of requests which match the criteria.
+    /// </summary>
+    public int Count { get; set; }
+}

src/WireMock.Net.Abstractions/Matchers/Request/NearMiss.cs

@@ -0,0 +1,34 @@
+// Copyright © WireMock.Net
+
+namespace WireMock.Matchers.Request;
+
+/// <summary>
+/// A mapping which did not (fully) match a request, together with the match result explaining why.
+/// </summary>
+public class NearMiss
+{
+    /// <summary>
+    /// The request which was evaluated against the mapping.
+    /// </summary>
+    public required IRequestMessage RequestMessage { get; init; }
+
+    /// <summary>
+    /// The unique identifier of the log entry for the request. [Optional]
+    /// </summary>
+    public Guid? LogEntryGuid { get; init; }
+
+    /// <summary>
+    /// The unique identifier of the mapping.
+    /// </summary>
+    public required Guid MappingGuid { get; init; }
+
+    /// <summary>
+    /// The title of the mapping. [Optional]
+    /// </summary>
+    public string? MappingTitle { get; init; }
+
+    /// <summary>
+    /// The match result, containing the score per matcher.
+    /// </summary>
+    public required IRequestMatchResult RequestMatchResult { get; init; }
+}

src/WireMock.Net.Abstractions/Server/IWireMockServer.cs

@@ -107,6 +107,39 @@ public interface IWireMockServer : IDisposable
     /// <returns>The <see cref="IReadOnlyList{ILogEntry}"/>.</returns>
     IReadOnlyList<ILogEntry> FindLogEntries(params IRequestMatcher[] matchers);
 
+    /// <summary>
+    /// Get the log-entries for the requests which did not fully match any mapping.
+    /// This includes the requests which were served by a partial match when AllowPartialMapping is enabled.
+    /// </summary>
+    /// <returns>The <see cref="IReadOnlyList{ILogEntry}"/>.</returns>
+    IReadOnlyList<ILogEntry> FindUnmatchedLogEntries();
+
+    /// <summary>
+    /// Find the mappings which partially match the request (the near misses), ordered by best match first.
+    /// Perfect matches and mappings which do not match at all are excluded.
+    /// Use this to find out why a request did not match the expected mapping.
+    /// </summary>
+    /// <param name="requestMessage">The request to evaluate.</param>
+    /// <param name="maxResults">The maximum number of near misses to return. Default is 3.</param>
+    /// <returns>The <see cref="IReadOnlyList{NearMiss}"/>.</returns>
+    IReadOnlyList<NearMiss> FindNearMisses(IRequestMessage requestMessage, int maxResults = 3);
+
+    /// <summary>
+    /// Find the mappings which partially match the request of a log-entry (the near misses), ordered by best match first.
+    /// Perfect matches and mappings which do not match at all are excluded.
+    /// </summary>
+    /// <param name="logEntry">The log-entry for which to evaluate the request.</param>
+    /// <param name="maxResults">The maximum number of near misses to return. Default is 3.</param>
+    /// <returns>The <see cref="IReadOnlyList{NearMiss}"/>.</returns>
+    IReadOnlyList<NearMiss> FindNearMisses(ILogEntry logEntry, int maxResults = 3);
+
+    /// <summary>
+    /// Find the near misses for all requests which did not fully match any mapping.
+    /// </summary>
+    /// <param name="maxResultsPerRequest">The maximum number of near misses to return per request. Default is 3.</param>
+    /// <returns>The <see cref="IReadOnlyList{NearMiss}"/>.</returns>
+    IReadOnlyList<NearMiss> FindNearMissesForUnmatchedRequests(int maxResultsPerRequest = 3);
+
     /// <summary>
     /// Reads a static mapping file and adds or updates a single mapping.
     /// 

src/WireMock.Net.Minimal/Owin/AdminPaths.cs

@@ -43,6 +43,8 @@ internal sealed class AdminPaths(string? adminPath) : IAdminPaths
 
     public RegexMatcher RequestsGuidPathMatcher => new($@"^{PrefixRegexEscaped}\/requests\/([0-9A-Fa-f]{{8}}[-][0-9A-Fa-f]{{4}}[-][0-9A-Fa-f]{{4}}[-][0-9A-Fa-f]{{4}}[-][0-9A-Fa-f]{{12}})$");
 
+    public RegexMatcher RequestsGuidNearMissesPathMatcher => new($@"^{PrefixRegexEscaped}\/requests\/([0-9A-Fa-f]{{8}}[-][0-9A-Fa-f]{{4}}[-][0-9A-Fa-f]{{4}}[-][0-9A-Fa-f]{{4}}[-][0-9A-Fa-f]{{12}})\/near-misses$");
+
     public RegexMatcher ScenariosNameMatcher => new($@"^{PrefixRegexEscaped}\/scenarios\/.+$");
 
     public RegexMatcher ScenariosNameWithStateMatcher => new($@"^{PrefixRegexEscaped}\/scenarios\/.+\/state$");

src/WireMock.Net.Minimal/Owin/IAdminPaths.cs

@@ -24,6 +24,8 @@ internal interface IAdminPaths
 
     RegexMatcher RequestsGuidPathMatcher { get; }
 
+    RegexMatcher RequestsGuidNearMissesPathMatcher { get; }
+
     RegexMatcher ScenariosNameMatcher { get; }
 
     RegexMatcher ScenariosNameWithStateMatcher { get; }

src/WireMock.Net.Minimal/Owin/IMappingMatcher.cs

@@ -5,4 +5,6 @@ namespace WireMock.Owin;
 internal interface IMappingMatcher
 {
     (MappingMatcherResult? Match, MappingMatcherResult? Partial) FindBestMatch(RequestMessage request);
+
+    IReadOnlyList<MappingMatcherResult> FindNearMisses(IRequestMessage request, int maxResults);
 }

src/WireMock.Net.Minimal/Owin/MappingMatcher.cs

@@ -83,6 +83,39 @@ internal class MappingMatcher(IWireMockMiddlewareOptions options, IRandomizerDou
         return (match, partialMatch);
     }
 
+    public IReadOnlyList<MappingMatcherResult> FindNearMisses(IRequestMessage request, int maxResults)
+    {
+        Guard.NotNull(request);
+
+        var nearMisses = new List<MappingMatcherResult>();
+
+        // Probability is not taken into account here: a mapping which was skipped based on probability can still be a near miss.
+        foreach (var mapping in _options.Mappings.Values.Where(m => !m.IsAdminInterface && !m.IsDisabled && m.TimeSettings.IsValid()))
+        {
+            try
+            {
+                var requestMatchResult = mapping.GetRequestMatchResult(request, GetNextState(mapping));
+                if (requestMatchResult.MatchDetails.All(md => md.Exception == null))
+                {
+                    nearMisses.Add(new MappingMatcherResult(mapping, requestMatchResult));
+                }
+            }
+            catch (Exception ex)
+            {
+                LogException(mapping, ex);
+            }
+        }
+
+        // A near miss is a mapping which matches the request partially: perfect matches and complete mismatches are excluded.
+        return nearMisses
+            .Where(nm => !nm.RequestMatchResult.IsPerfectMatch && nm.RequestMatchResult.AverageTotalScore > 0.0)
+            .OrderBy(nm => nm.RequestMatchResult)
+                .ThenBy(nm => nm.Mapping.Priority)
+                .ThenByDescending(nm => nm.Mapping.UpdatedAt)
+            .Take(maxResults)
+            .ToArray();
+    }
+
     private void LogException(IMapping mapping, Exception ex)
     {
         _options.Logger.Error($"Getting a Request MatchResult for Mapping '{mapping.Guid}' failed. This mapping will not be evaluated. Exception: {ex}");

src/WireMock.Net.Minimal/Serialization/LogEntryMapper.cs

@@ -14,60 +14,7 @@ internal class LogEntryMapper(IWireMockMiddlewareOptions options)
 {
     public LogEntryModel Map(ILogEntry logEntry)
     {
-        LogRequestModel? logRequestModel = null;
-        if (logEntry.RequestMessage != null)
-        {
-            logRequestModel = new LogRequestModel
-            {
-                DateTime = logEntry.RequestMessage.DateTime,
-                ClientIP = logEntry.RequestMessage.ClientIP,
-                Path = logEntry.RequestMessage.Path,
-                AbsolutePath = logEntry.RequestMessage.AbsolutePath,
-                Url = logEntry.RequestMessage.Url,
-                AbsoluteUrl = logEntry.RequestMessage.AbsoluteUrl,
-                ProxyUrl = logEntry.RequestMessage.ProxyUrl,
-                Query = logEntry.RequestMessage.Query,
-                Method = logEntry.RequestMessage.Method,
-                HttpVersion = logEntry.RequestMessage.HttpVersion,
-                Headers = logEntry.RequestMessage.Headers,
-                Cookies = logEntry.RequestMessage.Cookies
-            };
-
-            if (logEntry.RequestMessage.BodyData != null)
-            {
-                logRequestModel.DetectedBodyType = logEntry.RequestMessage.BodyData.DetectedBodyType?.ToString();
-                logRequestModel.DetectedBodyTypeFromContentType = logEntry.RequestMessage.BodyData.DetectedBodyTypeFromContentType?.ToString();
-
-                switch (logEntry.RequestMessage.BodyData.DetectedBodyType)
-                {
-                    case BodyType.String:
-                    case BodyType.FormUrlEncoded:
-                    case BodyType.WebSocketText:
-                    case BodyType.WebSocketClose:
-                        logRequestModel.Body = logEntry.RequestMessage.BodyData.BodyAsString;
-                        break;
-
-                    case BodyType.Json:
-                        logRequestModel.Body = logEntry.RequestMessage.BodyData.BodyAsString; // In case of Json, do also save the Body as string (backwards compatible)
-                        logRequestModel.BodyAsJson = logEntry.RequestMessage.BodyData.BodyAsJson;
-                        break;
-
-                    case BodyType.Bytes:
-                    case BodyType.WebSocketBinary:
-                        logRequestModel.BodyAsBytes = logEntry.RequestMessage.BodyData.BodyAsBytes;
-                        break;
-                }
-
-                logRequestModel.BodyEncoding = logEntry.RequestMessage.BodyData.Encoding != null
-                    ? new EncodingModel
-                    {
-                        EncodingName = logEntry.RequestMessage.BodyData.Encoding.EncodingName,
-                        CodePage = logEntry.RequestMessage.BodyData.Encoding.CodePage,
-                        WebName = logEntry.RequestMessage.BodyData.Encoding.WebName
-                    }
-                    : null;
-            }
-        }
+        var logRequestModel = logEntry.RequestMessage != null ? MapRequest(logEntry.RequestMessage) : null;
 
         LogResponseModel? logResponseModel = null;
         if (logEntry.ResponseMessage != null)
@@ -123,6 +70,74 @@ internal class LogEntryMapper(IWireMockMiddlewareOptions options)
         };
     }
 
+    public NearMissModel Map(NearMiss nearMiss)
+    {
+        return new NearMissModel
+        {
+            LogEntryGuid = nearMiss.LogEntryGuid,
+            Request = MapRequest(nearMiss.RequestMessage),
+            MappingGuid = nearMiss.MappingGuid,
+            MappingTitle = nearMiss.MappingTitle,
+            RequestMatchResult = Map(nearMiss.RequestMatchResult)
+        };
+    }
+
+    private static LogRequestModel MapRequest(IRequestMessage requestMessage)
+    {
+        var logRequestModel = new LogRequestModel
+        {
+            DateTime = requestMessage.DateTime,
+            ClientIP = requestMessage.ClientIP,
+            Path = requestMessage.Path,
+            AbsolutePath = requestMessage.AbsolutePath,
+            Url = requestMessage.Url,
+            AbsoluteUrl = requestMessage.AbsoluteUrl,
+            ProxyUrl = requestMessage.ProxyUrl,
+            Query = requestMessage.Query,
+            Method = requestMessage.Method,
+            HttpVersion = requestMessage.HttpVersion,
+            Headers = requestMessage.Headers,
+            Cookies = requestMessage.Cookies
+        };
+
+        if (requestMessage.BodyData != null)
+        {
+            logRequestModel.DetectedBodyType = requestMessage.BodyData.DetectedBodyType?.ToString();
+            logRequestModel.DetectedBodyTypeFromContentType = requestMessage.BodyData.DetectedBodyTypeFromContentType?.ToString();
+
+            switch (requestMessage.BodyData.DetectedBodyType)
+            {
+                case BodyType.String:
+                case BodyType.FormUrlEncoded:
+                case BodyType.WebSocketText:
+                case BodyType.WebSocketClose:
+                    logRequestModel.Body = requestMessage.BodyData.BodyAsString;
+                    break;
+
+                case BodyType.Json:
+                    logRequestModel.Body = requestMessage.BodyData.BodyAsString; // In case of Json, do also save the Body as string (backwards compatible)
+                    logRequestModel.BodyAsJson = requestMessage.BodyData.BodyAsJson;
+                    break;
+
+                case BodyType.Bytes:
+                case BodyType.WebSocketBinary:
+                    logRequestModel.BodyAsBytes = requestMessage.BodyData.BodyAsBytes;
+                    break;
+            }
+
+            logRequestModel.BodyEncoding = requestMessage.BodyData.Encoding != null
+                ? new EncodingModel
+                {
+                    EncodingName = requestMessage.BodyData.Encoding.EncodingName,
+                    CodePage = requestMessage.BodyData.Encoding.CodePage,
+                    WebName = requestMessage.BodyData.Encoding.WebName
+                }
+                : null;
+        }
+
+        return logRequestModel;
+    }
+
     private void MapBody(ILogEntry logEntry, LogResponseModel logResponseModel)
     {
         switch (logEntry.ResponseMessage?.BodyData?.DetectedBodyType)

src/WireMock.Net.Minimal/Server/WireMockServer.Admin.cs

@@ -8,6 +8,7 @@ using Microsoft.AspNetCore.Http;
 using Newtonsoft.Json.Linq;
 using Stef.Validation;
 using WireMock.Admin.Mappings;
+using WireMock.Admin.Requests;
 using WireMock.Admin.Scenarios;
 using WireMock.Admin.Settings;
 using WireMock.Constants;
@@ -93,6 +94,18 @@ public partial class WireMockServer
         Given(Request.Create().WithPath(_adminPaths.RequestsGuidPathMatcher).UsingGet()).AtPriority(WireMockConstants.AdminPriority).RespondWith(new DynamicResponseProvider(RequestGet));
         Given(Request.Create().WithPath(_adminPaths.RequestsGuidPathMatcher).UsingDelete()).AtPriority(WireMockConstants.AdminPriority).RespondWith(new DynamicResponseProvider(RequestDelete));
 
+        // __admin/requests/{guid}/near-misses
+        Given(Request.Create().WithPath(_adminPaths.RequestsGuidNearMissesPathMatcher).UsingGet()).AtPriority(WireMockConstants.AdminPriority).RespondWith(new DynamicResponseProvider(RequestNearMissesGet));
+
+        // __admin/requests/count
+        Given(Request.Create().WithPath(_adminPaths.Requests + "/count").UsingPost()).AtPriority(WireMockConstants.AdminPriority).RespondWith(new DynamicResponseProvider(RequestsCount));
+
+        // __admin/requests/unmatched
+        Given(Request.Create().WithPath(_adminPaths.Requests + "/unmatched").UsingGet()).AtPriority(WireMockConstants.AdminPriority).RespondWith(new DynamicResponseProvider(RequestsUnmatchedGet));
+
+        // __admin/requests/unmatched/near-misses
+        Given(Request.Create().WithPath(_adminPaths.Requests + "/unmatched/near-misses").UsingGet()).AtPriority(WireMockConstants.AdminPriority).RespondWith(new DynamicResponseProvider(RequestsUnmatchedNearMissesGet));
+
         // __admin/requests/find
         Given(Request.Create().WithPath(_adminPaths.Requests + "/find").UsingPost()).AtPriority(WireMockConstants.AdminPriority).RespondWith(new DynamicResponseProvider(RequestsFind));
         Given(Request.Create().WithPath(_adminPaths.Requests + "/find").UsingGet().WithParam("mappingGuid", new NotNullOrEmptyMatcher())).AtPriority(WireMockConstants.AdminPriority).RespondWith(new DynamicResponseProvider(RequestsFindByMappingGuid));
@@ -641,6 +654,22 @@ public partial class WireMockServer
 
     #region Requests/find
     private IResponseMessage RequestsFind(HttpContext _, IRequestMessage requestMessage)
+    {
+        var logEntryMapper = new LogEntryMapper(_options);
+        var result = FindLogEntriesByRequestModel(requestMessage)
+            .OrderBy(x => x.Value.AverageTotalScore)
+            .Select(x => x.Key)
+            .Select(logEntryMapper.Map);
+
+        return ToJson(result);
+    }
+
+    private IResponseMessage RequestsCount(HttpContext _, IRequestMessage requestMessage)
+    {
+        return ToJson(new RequestCountModel { Count = FindLogEntriesByRequestModel(requestMessage).Count });
+    }
+
+    private Dictionary<ILogEntry, RequestMatchResult> FindLogEntriesByRequestModel(IRequestMessage requestMessage)
     {
         var requestModel = DeserializeObject<RequestModel>(requestMessage);
 
@@ -656,10 +685,7 @@ public partial class WireMockServer
             }
         }
 
-        var logEntryMapper = new LogEntryMapper(_options);
-        var result = dict.OrderBy(x => x.Value.AverageTotalScore).Select(x => x.Key).Select(logEntryMapper.Map);
-
-        return ToJson(result);
+        return dict;
     }
 
     private IResponseMessage RequestsFindByMappingGuid(HttpContext _, IRequestMessage requestMessage)
@@ -679,6 +705,65 @@ public partial class WireMockServer
     }
     #endregion Requests/find
 
+    #region Requests/unmatched
+    private IResponseMessage RequestsUnmatchedGet(HttpContext _, IRequestMessage requestMessage)
+    {
+        var logEntryMapper = new LogEntryMapper(_options);
+        var result = FindUnmatchedLogEntries().Select(logEntryMapper.Map);
+
+        return ToJson(result);
+    }
+
+    private IResponseMessage RequestsUnmatchedNearMissesGet(HttpContext _, IRequestMessage requestMessage)
+    {
+        if (!TryGetMaxResultsFromQuery(requestMessage, out var maxResults))
+        {
+            return _responseMessageBuilder.Create(HttpStatusCode.BadRequest, "Query parameter 'maxResults' must be a positive integer");
+        }
+
+        var logEntryMapper = new LogEntryMapper(_options);
+        var result = FindNearMissesForUnmatchedRequests(maxResults).Select(logEntryMapper.Map);
+
+        return ToJson(result);
+    }
+    #endregion Requests/unmatched
+
+    #region Requests/{guid}/near-misses
+    private IResponseMessage RequestNearMissesGet(HttpContext _, IRequestMessage requestMessage)
+    {
+        if (!TryGetMaxResultsFromQuery(requestMessage, out var maxResults))
+        {
+            return _responseMessageBuilder.Create(HttpStatusCode.BadRequest, "Query parameter 'maxResults' must be a positive integer");
+        }
+
+        if (TryParseGuidFromSecondToLastSegment(requestMessage, out var guid))
+        {
+            var entry = LogEntries.SingleOrDefault(r => !_adminPaths!.Includes(r.RequestMessage?.Path) && r.Guid == guid);
+            if (entry is not null)
+            {
+                var logEntryMapper = new LogEntryMapper(_options);
+                var result = FindNearMisses(entry, maxResults).Select(logEntryMapper.Map);
+
+                return ToJson(result);
+            }
+        }
+
+        _settings.Logger.Warn("HttpStatusCode set to 404 : Request not found");
+        return _responseMessageBuilder.Create(HttpStatusCode.NotFound, "Request not found");
+    }
+
+    private static bool TryGetMaxResultsFromQuery(IRequestMessage requestMessage, out int maxResults)
+    {
+        maxResults = DefaultMaxNearMisses;
+        if (requestMessage.Query == null || !requestMessage.Query.TryGetValue("maxResults", out var value))
+        {
+            return true;
+        }
+
+        return int.TryParse(value.ToString(), out maxResults) && maxResults > 0;
+    }
+    #endregion Requests/{guid}/near-misses
+
     #region Scenarios
     private IResponseMessage ScenariosGet(HttpContext _, IRequestMessage requestMessage)
     {

src/WireMock.Net.Minimal/Server/WireMockServer.LogEntries.cs

@@ -7,6 +7,8 @@ using Stef.Validation;
 using WireMock.Logging;
 using WireMock.Matchers;
 using WireMock.Matchers.Request;
+using WireMock.Owin;
+using WireMock.Services;
 
 namespace WireMock.Server;
 
@@ -57,6 +59,68 @@ public partial class WireMockServer
             .ToArray();
     }
 
+    /// <inheritdoc />
+    [PublicAPI]
+    public IReadOnlyList<ILogEntry> FindUnmatchedLogEntries()
+    {
+        return LogEntries
+            .Where(le => le.RequestMessage != null && !_options.AdminPaths.Includes(le.RequestMessage.Path))
+            .Where(le => le.RequestMatchResult is not { IsPerfectMatch: true })
+            .ToArray();
+    }
+
+    /// <inheritdoc />
+    [PublicAPI]
+    public IReadOnlyList<NearMiss> FindNearMisses(IRequestMessage requestMessage, int maxResults = DefaultMaxNearMisses)
+    {
+        Guard.NotNull(requestMessage);
+        Guard.Condition(maxResults, m => m > 0);
+
+        return FindNearMisses(requestMessage, null, maxResults);
+    }
+
+    /// <inheritdoc />
+    [PublicAPI]
+    public IReadOnlyList<NearMiss> FindNearMisses(ILogEntry logEntry, int maxResults = DefaultMaxNearMisses)
+    {
+        Guard.NotNull(logEntry);
+        Guard.Condition(maxResults, m => m > 0);
+
+        return logEntry.RequestMessage is null ? [] : FindNearMisses(logEntry.RequestMessage, logEntry.Guid, maxResults);
+    }
+
+    /// <inheritdoc />
+    [PublicAPI]
+    public IReadOnlyList<NearMiss> FindNearMissesForUnmatchedRequests(int maxResultsPerRequest = DefaultMaxNearMisses)
+    {
+        Guard.Condition(maxResultsPerRequest, m => m > 0);
+
+        return FindUnmatchedLogEntries()
+            .SelectMany(le => FindNearMisses(le, maxResultsPerRequest))
+            .ToArray();
+    }
+
+    private const int DefaultMaxNearMisses = 3;
+
+    private IMappingMatcher? _nearMissMappingMatcher;
+
+    private IReadOnlyList<NearMiss> FindNearMisses(IRequestMessage requestMessage, Guid? logEntryGuid, int maxResults)
+    {
+        _nearMissMappingMatcher ??= new MappingMatcher(_options, new RandomizerDoubleBetween0And1());
+
+        return _nearMissMappingMatcher
+            .FindNearMisses(requestMessage, maxResults)
+            .Select(nm => new NearMiss
+            {
+                RequestMessage = requestMessage,
+                LogEntryGuid = logEntryGuid,
+                MappingGuid = nm.Mapping.Guid,
+                MappingTitle = nm.Mapping.Title,
+                RequestMatchResult = nm.RequestMatchResult
+            })
+            .ToArray();
+    }
+
     /// <inheritdoc cref="IWireMockServer.ResetLogEntries" />
     [PublicAPI]
     public void ResetLogEntries()

src/WireMock.Net.Minimal/Server/wiremock.net-openapi.yml

@@ -421,6 +421,105 @@ paths:
               schema:
                 $ref: '#/components/schemas/StatusModel'
 
+  /__admin/requests/{guid}/near-misses:
+    get:
+      summary: Get the near misses (mappings which partially match) for a logged request
+      parameters:
+        - name: guid
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - name: maxResults
+          in: query
+          required: false
+          description: The maximum number of near misses per request (default 3).
+          schema:
+            type: integer
+            format: int32
+            minimum: 1
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/NearMissModel'
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StatusModel'
+        '404':
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StatusModel'
+
+  /__admin/requests/count:
+    post:
+      summary: Count logged requests matching a request filter
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RequestModel'
+        required: true
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RequestCountModel'
+      x-codegen-request-body-name: requestFilter
+
+  /__admin/requests/unmatched:
+    get:
+      summary: Get logged requests which did not fully match any mapping
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/LogEntryModel'
+
+  /__admin/requests/unmatched/near-misses:
+    get:
+      summary: Get the near misses (mappings which partially match) for each logged request which did not fully match any mapping
+      parameters:
+        - name: maxResults
+          in: query
+          required: false
+          description: The maximum number of near misses per request (default 3).
+          schema:
+            type: integer
+            format: int32
+            minimum: 1
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/NearMissModel'
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StatusModel'
+
   /__admin/requests/find:
     post:
       summary: Find logged requests matching a request filter
@@ -895,6 +994,35 @@ components:
             additionalProperties: true
       description: Log Request Match Model
 
+    NearMissModel:
+      type: object
+      properties:
+        LogEntryGuid:
+          type: string
+          description: The unique identifier of the log entry for the request.
+          format: uuid
+        Request:
+          $ref: '#/components/schemas/LogRequestModel'
+        MappingGuid:
+          type: string
+          description: The unique identifier of the mapping.
+          format: uuid
+        MappingTitle:
+          type: string
+          description: The title of the mapping.
+        RequestMatchResult:
+          $ref: '#/components/schemas/LogRequestMatchModel'
+      description: Near Miss Model, a mapping which did not (fully) match a request
+
+    RequestCountModel:
+      type: object
+      properties:
+        Count:
+          type: integer
+          description: The number of requests which match the criteria.
+          format: int32
+      description: Request Count Model
+
     LogRequestModel:
       type: object
       properties:

src/WireMock.Net.RestClient/IWireMockAdminApi.cs

@@ -250,6 +250,39 @@ public interface IWireMockAdminApi
     [Get("requests/find")]
     Task<IList<LogEntryModel>> FindRequestsByMappingGuidAsync([Query] Guid mappingGuid, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// Count the requests which match the criteria (<see cref="RequestModel"/>).
+    /// </summary>
+    /// <param name="model">The RequestModel</param>
+    /// <param name="cancellationToken">The optional cancellationToken.</param>
+    [Post("requests/count")]
+    [Header("Content-Type", "application/json")]
+    Task<RequestCountModel> CountRequestsAsync([Body] RequestModel model, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Get the requests which did not fully match any mapping.
+    /// </summary>
+    /// <param name="cancellationToken">The optional cancellationToken.</param>
+    [Get("requests/unmatched")]
+    Task<IList<LogEntryModel>> GetUnmatchedRequestsAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Get the near misses (the mappings which partially match) for all requests which did not fully match any mapping.
+    /// </summary>
+    /// <param name="maxResults">The maximum number of near misses per request. Default is 3.</param>
+    /// <param name="cancellationToken">The optional cancellationToken.</param>
+    [Get("requests/unmatched/near-misses")]
+    Task<IList<NearMissModel>> GetNearMissesForUnmatchedRequestsAsync([Query] int? maxResults = null, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Get the near misses (the mappings which partially match) for a request.
+    /// </summary>
+    /// <param name="guid">The Guid of the request</param>
+    /// <param name="maxResults">The maximum number of near misses. Default is 3.</param>
+    /// <param name="cancellationToken">The optional cancellationToken.</param>
+    [Get("requests/{guid}/near-misses")]
+    Task<IList<NearMissModel>> GetNearMissesForRequestAsync([Path] Guid guid, [Query] int? maxResults = null, CancellationToken cancellationToken = default);
+
     /// <summary>
     /// Get all scenarios
     /// </summary>