API Proposal: GetGCInfo

Maoni0 commented 4 years ago

API to monitor per GC Info. This is meant to be used in situations where folks used to use the .NET Memory counters and provides much richer info than the counters used to provide.

Rationale

We'd like to provide the flexibility for folks who monitor the GC heap on a more detailed level. Previously we had the GetGCMemoryInfo API that provides high level memory info including total available/in use memory, high mem threshold, total heap size and fragmentation. Folks have requested to provide more detailed info in this fashion for monitoring purpose. The difference between this and eventing (ETW, eventpipe) is

This only provides info that is obtained with very low overhead . Eventing will still provide richer info when you enabled more heavyweight events so if you need to do deeper diagnostics you will still need events.
Since this is a managed API, it's easier to use than eventing. Users can get it whenever they want and don't need to deal with problems collecting traces.

At the end of the day, it's a tradeoff between simplicity and the amount of info you can get.

Proposed APIs

public readonly struct GCGenerationInfo
{
    public long SizeBytes;
    public long FragmentationBytes;
}

public sealed class GCInfo
{
    public long HighMemoryLoadThresholdBytes { get; }
    public long MemoryLoadBytes { get; }
    public long TotalAvailableMemoryBytes { get; }
    public long HeapSizeBytes { get; }
    public long FragmentedBytes { get; }

    // The index of this GC
    public long Index { get; }
    // The generation this GC collected
    public int Generation { get; }
    // Did it compact
    public bool Compacted { get; }
    // Was it concurrent
    public bool Concurrent { get; }
    // Total committed bytes
    public long CommittedBytes { get; }

    // How much this GC promoted
    public long PromotedBytes { get; }
    // # of pinned handles this GC encountered
    public long PinnedHandlesCount { get; }
    // # of ready for finalization objects this
    // GC encountered
    public long FinalizeObjectCount { get; }

    // This is the STW pause times for this GC
    // For BGC there are 2 STW pauses.
    public TimeSpan[] PauseDurations { get; }
    // This is the running counter for % pause time
    // in GC, calculated based on the pause durations
    // and total elapsed time.
    public double PauseTimePercentage { get; }

    public GCGenerationInfo[] genInfo { get; }
}

class GC
{
    public static GCInfo GetGCInfo();
}

Comments on the API

All the info provided via this API should be low cost to get.

We might want to add more in the future so suggestions to keep the API extensible are very welcome.

CC @terrajobst @mjsabby

stephentoub commented 4 years ago

@Maoni0, can this issue be closed now, or is it still tracking something?

Maoni0 commented 4 years ago

yes, closing now, thanks for the reminder!

dotnet / runtime