Document HTTP Client Errors (enableCaptureFailedRequests) (#6987)

Author: jamescrosswell

src/platforms/common/configuration/options.mdx

@@ -577,7 +577,7 @@ _(New in version 6.6.0)_
 
 </ConfigKey>
 
-<ConfigKey name="capture-failed-requests" supported={["apple"]}>
+<ConfigKey name="capture-failed-requests" supported={["apple","dotnet"]}>
 
 Once enabled, this feature automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry.
 

src/platforms/dotnet/common/configuration/http-client-errors.mdx

@@ -0,0 +1,109 @@
+---
+title: HTTP Client Errors
+sidebar_order: 25
+description: "This feature, once enabled, automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry"
+---
+
+Once enabled, this feature automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry. The error event will contain information from the HTTP request and response, such as `url`, `status_code`, and so on.
+
+To enable it:
+
+```csharp
+// Add this to the SDK initialization callback
+options.CaptureFailedRequests = true;
+```
+
+```fsharp
+// Add this to the SDK initialization callback
+options.CaptureFailedRequests <- true
+```
+
+HTTP client errors will then be captured for any requests from the Sentry SDK. To capture HTTP client errors for outbound requests from your own application, pass `SentryHttpMessageHandler` as the inner handler when creating your `HttpClient`:
+
+```csharp
+using var httpClient = new HttpClient(new SentryHttpMessageHandler());
+```
+
+```fsharp
+let httpClient = new HttpClient(new SentryHttpMessageHandler())
+```
+
+<Alert title="Tip">
+
+You can skip the above step when using any of the Sentry .NET SDKs that are registered via dependency injection (`Senry.AspNetCore`, `Sentry.Maui`, `Sentry.Extensions.Logging`, etc.).
+
+Instead, create your `HttpClient` using the `IHttpClientFactory` pattern, as described in [the documentation from Microsoft](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests). The `SentryHttpMessageHandler` will automatically be added to the factory during initialization, so no additional wire-up is needed.
+
+</Alert>
+
+By default, only HTTP client errors with a response code between `500` and `599` are captured as error events, but you can change this behavior by modifying the `FailedRequestStatusCodes` option:
+
+```csharp
+options.FailedRequestStatusCodes.Add((400, 499));
+```
+
+```fsharp
+options.FailedRequestStatusCodes.Add(HttpStatusCodeRange(400, 599))
+```
+
+HTTP client errors from every target (`.*` regular expression) are automatically captured, but you can change this behavior by updating the `FailedRequestTargets` option with either regular expressions or plain strings. A plain string must contain at least one of the items from the list. Plain strings don't have to be full matches, meaning the URL of a request is matched when it contains a substring provided through the option:
+
+```csharp
+options.FailedRequestTargets.Add("foo");      // substring
+options.FailedRequestTargets.Add("foo.*bar"); // regex
+```
+
+```fsharp
+options.FailedRequestTargets.Add("foo")      // substring
+options.FailedRequestTargets.Add("foo.*bar") // regex
+```
+
+When the `SendDefaultPii` option is enabled, error events may contain PII data such as `Headers` and `Cookies`. Sentry already does data scrubbing by default, but you can also scrub any data before it is sent. Learn more in [Scrubbing Sensitive Data](/platforms/dotnet/data-management/sensitive-data/).
+
+These events are searchable and you can set alerts on them if you use the `http.url` and `http.status_code` properties. Learn more in our full [Searchable Properties](/product/sentry-basics/search/searchable-properties/) documentation.
+
+### Customize or Drop the Error Event
+
+The captured error event can be customized or dropped with a `beforeSend`:
+
+```csharp
+options.SetBeforeSend((@event, hint) =>
+{
+    if (hint.Items.TryGetValue(HintTypes.HttpResponseMessage, out var responseHint))
+    {
+        var response = (HttpResponseMessage)responseHint!;
+        var request = response.RequestMessage!;
+
+        // Do something with the request and/or response... for example, you could add
+        // some custom context to the event for specific scenarios
+        var statusCode = response.StatusCode;
+        if (statusCode == HttpStatusCode.Unauthorized)
+        {
+            @event.Contexts["Unauthorized"] = request.RequestUri.GetComponents(
+                UriComponents.HttpRequestUrl, UriFormat.SafeUnescaped
+                );
+        }
+    }
+
+    // return the modified event
+    return @event;
+});
+```
+
+```fsharp
+options.SetBeforeSend(fun event hint ->
+    let (isHint, responseHint) = hint.Items.TryGetValue(HintTypes.HttpResponseMessage)
+    if isHint then
+        let response = responseHint :?> HttpResponseMessage
+        let request = response.RequestMessage :> HttpRequestMessage
+
+        // Do something with the request and/or response... for example, you could add
+        // some custom context to the event for specific scenarios
+        let statusCode = response.StatusCode
+        if statusCode = HttpStatusCode.Unauthorized then
+            event.Contexts.["Unauthorized"] <- request.RequestUri.GetComponents(UriComponents.HttpRequestUrl, UriFormat.SafeUnescaped)
+
+    // return the modified event
+    event
+)
+```