Document that HttpClient, by default, creates a new Activity

[noahfalk]

Some of our developers are surprised by the behavior of DiagnosticHandler (part of HttpClient) when it creates an Activity by default. We should document this. See this thread for more background.

[mikedoug]

Please make sure to cover the complexity of the cases properly. I posted about it here, but will repeat it here with increased specificity.

THE FIRST STATEMENT WHICH MATCHES WINS:

• If there are ZERO listeners on System.Net.Http.DiagnosticsHandler, a new Activity is created (and thus a new span).
• If there is AT LEAST ONE listener on System.Net.Http.DiagnosticsHandler and ANY listener returns True for handling System.Net.Http.HttpRequestOut, a new Activity is created (and thus a new span).
• If there is AT LEAST ONE listener on System.Net.Http.DiagnosticsHandler and ALL listeners returns False for handling System.Net.Http.HttpRequestOut, there is NO new Activity created (and thus NO new span).

As stated in my previous post, this is incredibly unstable because I can have my application happily working in the third case where I don't get these extraneous Activities and then I incorporate some third party SDK that listens on System.Net.Http.DiagnosticsHandler and returns true for System.Net.Http.HttpRequestOut and the behavior of my HTTP calls changes instantly to creating these intermediate Activities. The Documentation should be really clear around the brittle nature of these code paths.

[BillWagner]

adding @scottaddie

Where should this fix be made?

[scottaddie]

@BillWagner There's an IHttpClientFactory doc over in the ASP.NET Core docs. See https://docs.microsoft.com/aspnet/core/fundamentals/http-requests. We could add some details there; however, this detail is probably better off in a dedicated HttpClient doc. I say that because IHttpClientFactory simply creates HttpClient instances. I'd expect the proposed HttpClient doc to exist in the .NET docs.

[BillWagner]

Adding @gewarren @tdykstra

Should this be in our conceptual docs for fundamentals, or in the API reference for HttpClient?

[tdykstra]

I would put it in API reference for HttpClient.

[J-Yen]

I found it very confusing that running two instances (a client project that makes a call to an API service) with 'Visual Studio Multiple startup projects' or without debugger results in the creation of a new Activity (because no listeners) but when running the client with debugger separately/standalone results in not creating a new Activity (listener that returns false for System.Net.Http.HttpRequestOut).

1. Running client project with debugger (separately/standalone):
   

2. Running client project and API project with 'Visual Studio Multiple startup projects' or without debugger:
   

Also confusing that you need to create your own activity in order to make the DiagnosticHandler to create it's own System.Net.Http.HttpRequestOut activity (internal DiagnosticsHandler.IsEnabled is checking Activity.Current != null) so removing the creation of my own custom activity and depending on the activity created by DiagnosticHandler is also not an option to avoid duplicate activity creations. All these different cases exists without documentation or logging which is very difficult to understand what's happening and how I should use it.

[tdykstra]

@scottaddie Does my suggestion to put this content in the API ref make sense to you? If so, we should transfer this issue to the API docs repo.

[scottaddie]

I support Tom's suggestion to put the content in the API ref page.

[nosalan]

I'm surprised that is going to be fixed by documentation. I would expect to be the default behavior that HttpClient propagates existing activity (span). Can't see why HttpClient creates a new span by default. There are workarounds like this but I'd prefer it to be default behavior.