Interface IMetricSource

Namespace

Typhon.Engine

Assembly

Typhon.Engine.dll

Implemented by resources that expose measurable metrics.

public interface IMetricSource

Examples

public class PageCache : IResource, IMetricSource
{
    private long _cacheHits;
    private long _cacheMisses;
    private long _peakBytes;
    private long _currentBytes;

    public void ReadMetrics(IMetricWriter writer)
    {
        writer.WriteMemory(_currentBytes, _peakBytes);
        writer.WriteThroughput("CacheHits", _cacheHits);
        writer.WriteThroughput("CacheMisses", _cacheMisses);
    }

    public void ResetPeaks()
    {
        _peakBytes = _currentBytes;
    }
}

Remarks

Not all IResource nodes implement IMetricSource — only those with meaningful state to measure. The graph uses runtime is checks during tree traversal to discover metric sources.

This separation follows the Interface Segregation Principle: pure grouping nodes (like "Root" or "Storage") exist only to organize the tree and have no counters of their own. Their metrics are aggregates of their children, computed by the snapshot system.

Thread safety: ReadMetrics(IMetricWriter) is called from the snapshot thread while other threads may update the same fields. This is acceptable because reads of primitive types are atomic on x64, and approximate values are acceptable for diagnostics.

Methods

ReadMetrics(IMetricWriter)

Writes current metric values to the provided writer.

void ReadMetrics(IMetricWriter writer)

Parameters

writer IMetricWriter

The writer to report metrics to. Call one or more Write* methods.

Remarks

Called during snapshot collection (every 1-5 seconds). Implementations should:

• Read fields and write to writer quickly (target < 100ns)
• Not allocate (no new objects, no LINQ, no string formatting)
• Not acquire locks (read fields directly, accept slight inconsistency)
• Not call other IMetricSource.ReadMetrics() — the graph handles recursion

Only report metric kinds that are relevant to this resource. For example, a TransactionPool might only report Capacity and Throughput, not Memory or DiskIO.

ResetPeaks()

Resets all high-water mark metrics (PeakBytes, MaxWaitUs, MaxUs, etc.) to current values.

void ResetPeaks()

Remarks

Called by ResetAllPeaks() to enable windowed peak measurements. After displaying or exporting peak values, this method resets them so subsequent peaks represent new maxima since the last reset.

If this node has no high-water marks, implement as an empty method. Plain writes are sufficient — snapshots are taken every 1-5 seconds, so eventual visibility is acceptable.