Table of Contents

Class ResourceSnapshot

Namespace
Typhon.Engine
Assembly
Typhon.Engine.dll

Immutable snapshot of all resource metrics at a point in time.

public sealed class ResourceSnapshot
Inheritance
ResourceSnapshot
Inherited Members

Remarks

A snapshot provides a consistent-enough reading of all metric values across the resource tree.

  • Per-node atomic: Each node's ReadMetrics() reads all fields together
  • Cross-node approximate: Different nodes may be read microseconds apart
  • No global lock: Tree traversal doesn't block other threads

Query methods operate on the frozen data, making them safe to call from any thread.

Constructors

ResourceSnapshot() 

public ResourceSnapshot()

Fields

DefaultHighUtilizationThreshold

Default threshold for high utilization detection in cascade analysis. Components above this threshold are considered "under pressure".

public const double DefaultHighUtilizationThreshold = 0.8

Field Value

double

Properties

Nodes

All nodes with their metric values, keyed by node path.

public IReadOnlyDictionary<string, NodeSnapshot> Nodes { get; init; }

Property Value

IReadOnlyDictionary<string, NodeSnapshot>

Examples

var utilization = snapshot.Nodes["Storage/PageCache"].Capacity?.Utilization;

Rates

Throughput rates (ops/sec) computed from the previous snapshot. Null for the first snapshot (no previous to compare against).

public ThroughputRates Rates { get; init; }

Property Value

ThroughputRates

Examples

var hitRate = snapshot.Rates?["Storage/PageCache"]["CacheHits"];

Timestamp

When this snapshot was taken.

public DateTime Timestamp { get; init; }

Property Value

DateTime

Methods

FindByType(ResourceType)

Find all nodes of a specific type.

public IEnumerable<NodeSnapshot> FindByType(ResourceType type)

Parameters

type ResourceType

The resource type to find.

Returns

IEnumerable<NodeSnapshot>

All nodes of the specified type.

FindMostUtilized()

Find the node with highest Utilization in the tree.

public NodeSnapshot FindMostUtilized()

Returns

NodeSnapshot

The most utilized node, or null if no nodes have Capacity metrics.

Remarks

Useful for finding the bottleneck: "Which resource is about to run out?"

FindMostUtilized(double)

Find the node with highest Utilization above a threshold.

public IEnumerable<NodeSnapshot> FindMostUtilized(double threshold)

Parameters

threshold double

Minimum utilization (0.0 to 1.0) to include in results.

Returns

IEnumerable<NodeSnapshot>

Nodes above the threshold, sorted by utilization descending.

FindRootCause(string, double)

Traces back from a symptomatic node to find the root cause of resource pressure.

public NodeSnapshot FindRootCause(string symptomPath, double highUtilizationThreshold = 0.8)

Parameters

symptomPath string

Path to the node showing symptoms (e.g., "DataEngine/TransactionPool" or "Root/DataEngine/TransactionPool").

highUtilizationThreshold double

Utilization threshold (0.0-1.0) above which a node is considered "under pressure". Defaults to DefaultHighUtilizationThreshold (0.8).

Returns

NodeSnapshot

The node at the end of the high-utilization chain (the root cause), or the symptom node itself if no dependencies are found or the node doesn't exist.

Remarks

This method uses hardcoded wait dependencies based on architectural knowledge to follow the causal chain. It is a heuristic, not runtime tracking.

Algorithm:

  1. Start at the symptom node
  2. If utilization > threshold and has known dependencies, follow to most utilized dependency
  3. Repeat until no further high-utilization dependencies found
  4. Return the final node (the root cause)
// Symptom: TransactionPool shows high utilization (0.95)
var rootCause = snapshot.FindRootCause("DataEngine/TransactionPool");
// Returns: WALRingBuffer (if it's the end of the high-utilization chain)

GetNode(string)

Get a specific node by path.

public NodeSnapshot GetNode(string nodePath)

Parameters

nodePath string

Path to the node.

Returns

NodeSnapshot

The node snapshot, or null if not found.

GetSubtree(string)

Get all nodes under a subtree path.

public IEnumerable<NodeSnapshot> GetSubtree(string nodePath)

Parameters

nodePath string

Path to the subtree root.

Returns

IEnumerable<NodeSnapshot>

All nodes under the path, including the root itself.

GetSubtreeMemory(string)

Sum AllocatedBytes across all descendants of the given node.

public long GetSubtreeMemory(string nodePath)

Parameters

nodePath string

Path to the subtree root (e.g., "DataEngine").

Returns

long

Total bytes allocated by all nodes under the path.

Remarks

Useful for memory attribution: "How much does each subsystem use?" 

var dataEngineMemory = snapshot.GetSubtreeMemory("DataEngine");
var storageMemory = snapshot.GetSubtreeMemory("Storage");