Async support in .NET

The agent instruments these HttpClient async methods:

• SendAsync
• GetAsync
• PostAsync
• PutAsync
• DeleteAsync
• GetStringAsync
• GetStreamAsync
• GetByteArrayAsync

The agent instruments these RestClient async methods:

• ExecuteTaskAsync
• ExecuteGetTaskAsync
• ExecutePostTaskAsync

The agent instruments these SqlCommand async methods:

• ExecuteReaderAsync
• ExecuteNonQueryAsync
• ExecuteScalarAsync
• ExecuteXmlReaderAsync

The agent instruments these SqlDataReader async methods:

• NextResultAsync
• ReadAsync

The agent instruments these NpgsqlCommand async methods (Postgres):

• ExecuteReaderAsync
• ExecuteNonQueryAsync
• ExecuteScalarAsync

The .NET agent supports custom instrumentation of your own async methods.

It is expected for response time to be less than the total time spent in async-await usage scenerios. Consider the following code example for a web endpoint:

async Task<string> WebEndpointExample() 
{
    await DoSomethingForSomeSecondsAsync(5); //kick off a 5-second-work to be done.
    return "Complete";
}

[Trace]
[MethodImpl(MethodImplOptions.NoInlining)]
private static async Task DoSomethingForSomeSecondsAsync(int seconds)
{
    await Task.Delay(TimeSpan.FromSeconds(seconds));
}

In this code example, it takes approximately 5 seconds for the WebEndpointExample to complete, so the response time for the transaction that represents the request to the WebEndpointExample endpoint will be approximately 5 seconds.

The agent also captures the "busy" time (the time that the instrumented method is actually executing) of each individual segment that constitutes the transaction. They are WebEndpointExample and DoSomethingForSomeSecondsAsync. Ideally, the total execution time of the two segments is equal to the response time (approximately 5 seconds).

It is easy to see that the execution time of DoSomethingForSomeSecondsAsync is 5 seconds. However, the execution time of the WebEndpointExample should be close to 0 seconds. (It doesn't do any work; it awaits for the DoSomethingForSomeSecondsAsync to complete.)

However, the agent still measures its execution time as approximately 5 seconds. This is due to the agent's inability to detect blocked time (not CPU time) when a method is awaiting for another. Hence the total time is reported as 10 seconds, which is greater than the response time (approximately 5 seconds).

At the same time, the agent cannot assume calling to async methods would always block the caller for the entire time. The next example demonstrates this:

async Task<string> WebEndpointExample()
{
    var task = DoSomethingForSomeSecondsAsync(5); //kick off a 5-second-work to be done.

    //Do something less than 5 seconds here.

    await task;
    return "Complete";
}

[Trace]
[MethodImpl(MethodImplOptions.NoInlining)]
private static async Task DoSomethingForSomeSecondsAsync(int seconds)
{
    await Task.Delay(TimeSpan.FromSeconds(seconds));
}

In this example, the response time is still approximately 5 seconds, but the actual execution time of the WebEndpointExample is no longer approximately 0.

The .NET agent will not instrument async methods if the legacy ASP pipeline is present. Since Microsoft replaced the legacy ASP pipeline well before async methods were introduced, this issue typically only affects applications created under .NET Framework 4.0 or lower, then migrated to .NET Framework 4.5 or higher.

To see if this issue affects your application, and how to resolve it if it does, review the troubleshooting procedures.

The .NET agent does not support instrumentation of async methods that have return type of anything other than Task or Task<T>. The agent does not support async void methods.

For more information, refer to the Microsoft documentation about async return types:

• Task<TResult> return type
• Async void
• Generalized async return types

The .NET agent does not instrument any .NET methods that use the begin* and end* style, except for WCF applications. Outside of this exception, if your application calls these types of methods, the agent will not create segments for them. However, the rest of your transactions and segments will be created correctly.

The .NET agent does not capture scoped metrics or segments within threads that are manually created by your application.

If your application calls instrumented async methods, use await rather than Task related methods like Task.Result() to wait for the results. Otherwise, instrumentation may not work properly.

In general, avoid using Task.Result() when calling async methods. It can lead to deadlocks.

If you add your own ContinueWith({}) block to the promise returned by an instrumented async method, it may affect timing measurements reported by the instrumentation. For example, the time may include the time your ContinueWith takes to execute.

IIS-hosted WCF services do not properly nest the WCF segment under the ExecuteRequestHandler segment. The two segments will appear to be siblings within a transaction trace, even though their reported total time will be accurate.

Segments in a transaction trace will not generate stack traces automatically, even if they run longer than transaction_tracer.stack_trace_threshold.