[API Proposal]: Exposing the total paused duration in GC.

[cshung]

Background and motivation

Today we have already exposed the total paused time as a percentage of the process time on the GetGCMemoryInfo API.

In particular, through the PauseTimePercentage field on the GCMemoryInfo struct.

This is useful, but what if I only want to numerator (i.e. the total amount of time paused in GC since the beginning of the process?). There is no way to get that value for now.

API Proposal

I am proposing to add an API on System.GC as follow:

TimeSpan System.GC.GetTotalPauseDuration()

This will return the total paused duration in the GC

API Usage

...
TimeSpan start = System.GC.GetTotalPauseDuration();
// ... Perform some work ...
TimeSpan end= System.GC.GetTotalPauseDuration();
Console.WriteLine(end - start + " was spent pausing in GC");
...

Alternative Designs

We have considered the alternative to add a field on the GetGCMemoryInfo API, this will also work, but if the only thing we wanted is just the total pause time, that API will carry a larger overhead than necessary.

Risks

No response

Tagging subscribers to this area: @dotnet/gc
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Today we have already exposed the total paused time as a percentage of the process time on the GetGCMemoryInfo API.

In particular, through the PauseTimePercentage field on the GCMemoryInfo struct.

This is useful, but what if I only want to numerator (i.e. the total amount of time paused in GC since the beginning of the process?). There is no way to get that value for now.

API Proposal

I am proposing to add an API on System.GC as follow:

TimeSpan System.GC.GetTotalPauseDuration()

This will return the total paused duration in the GC

API Usage

...
TimeSpan start = System.GC.GetTotalPauseDuration();
// ... Perform some work ...
TimeSpan end= System.GC.GetTotalPauseDuration();
Console.WriteLine(end - start + " was spent pausing in GC");
...

Alternative Designs

We have considered the alternative to add a field on the GetGCMemoryInfo API, this will also work, but if the only thing we wanted is just the total pause time, that API will carry a larger overhead than necessary.

Risks

No response

Author:	cshung
Assignees:	-
Labels:	api-suggestion, area-GC-coreclr, untriaged
Milestone:	-

[cshung]

@timmydo Hopefully, this can help with your performance analysis needs.

[timmydo]

Thanks! + @sudeepagarwal

[timmydo]

this looks good to me. can't wait to try it out.

[terrajobst]

How is System.GC.GetTotalPauseDuration() related to GCMemoryInfo.PauseDurations? Is the primary goal to make this cheaper? If so, does this mean we're going to expose more and more data from GCMemoryInfo?

[cshung]

GCMemoryInfo.PauseDurations are (*) the time spent pausing in the GC during the last GC.

GCMemoryInfo.PauseDurations are (*) the time spent pausing in the GC during the last GC.

System.GC.GetTotalPauseDuration() is the total time spent suspended in the GC since the process starts.

(*) Plurals - because for background GC, we pause for a few disjoint brief periods.

[terrajobst]

So in other words, GetTotalPauseDuration() is <= Sum(GCMemoryInfo.PauseDurations) because those could have happened concurrently?

[Maoni0]

no, GetTotalPauseDuration() is always >= Sum(GCMemoryInfo.PauseDurations)

GCMemoryInfo.PauseDurations are durations for when the GC is NOT running concurrently, in other words, these are the durations that GC did work while the managed threads are paused. they are never for when GC is doing work concurrently. whether there's one or multiple durations per GC is not really relevant here (yes, BGCs will report 2 durations while blocking GCs will report one per GC but that's an implementation detail).

the reason why GetTotalPauseDuration() is always >= Sum(GCMemoryInfo.PauseDurations) is because GetGCMemoryInfo is a sampling API. so assuming you called it early enough and frequent enough to catch every single GC that happened, it means what you get from GetTotalPauseDuration will be exactly the same as the sum of what you get from every GC's PauseDurations. but if you don't sample frequent enough to get every single GC, what you get from GetTotalPauseDuration will be > Sum(GCMemoryInfo.PauseDurations).

and yes, the reason why we wanted to provide the accumulated pause duration in its own API is to make it cheaper. this does not mean we will want to expose the accumulated version of all the data you get right now in GCMemoryInfo - most data simply does not make sense to be presented in an accumulated form. there are a couple of things that may make some sense to expose as accumulated, but no strong justification.

[terrajobst]

Video

• Looks good as proposed

namespace System;

public partial class GC
{
    public static TimeSpan GetTotalPauseDuration();
}