Diagnostics

DsmRuntime exposes an immutable snapshot-oriented diagnostics API. This is the fastest entry point when a node is running but DSM behavior looks wrong.

What To Read First

RuntimeDiagnostics

The runtime snapshot contains:

• runtime identity info
• lifecycle state
• cluster view
• total local entry count
• collection diagnostics for all registered collections
• lease-specific diagnostics for registered lease collections

RuntimeDiagnostics diagnostics = runtime.diagnostics();

RuntimeInfo info = diagnostics.info();
DsmRuntimeState state = diagnostics.state();
ClusterView clusterView = diagnostics.clusterView();
int totalEntries = diagnostics.totalEntries();
List<CollectionDiagnostics> collections = diagnostics.collections();
List<LeaseCollectionDiagnostics> leaseCollections = diagnostics.leaseCollections();

Recommended Read Order

1. Check Runtime State

First answer: is the runtime alive and ready?

If state() is not what the deployment expects, check whether the runtime was never started, is still moving through lifecycle readiness, or has already entered shutdown.

If the runtime is not ready, do not start with collection-level debugging.

2. Check Cluster View

clusterView() answers whether the node sees the peers you expect.

ClusterView clusterView = diagnostics.clusterView();

String clusterId = clusterView.clusterId();
String serviceId = clusterView.serviceId();
NodeInfo self = clusterView.self();
List<NodeInfo> activeMembers = clusterView.activeMembers();

Interpretation:

• no peers: membership or isolation boundary issue
• unexpected peers: clusterId or serviceId boundary issue
• self present but others absent: discovery, network, or service-family mismatch

Example healthy cluster view: clusterId=prod-eu-west, serviceId=gateway-service, self=node-a, and active nodes [node-a, node-b, node-c].

3. Check Collection Diagnostics

collections() tells you what is actually registered and how many entries the local runtime currently knows.

for (CollectionDiagnostics collection : diagnostics.collections()) {
	System.out.println(collection.locator());
	System.out.println(collection.schemaId());
	System.out.println(collection.consistencyTier());
	System.out.println(collection.entryCount());
}

Use it to answer:

• is the expected locator registered?
• is the schema ID what this deployment expects?
• is the consistency tier aligned with the intended collection type?
• is the local entry count clearly wrong?

4. Check Lease Diagnostics

For lease collections, leaseCollections() is where ownership churn and rejection patterns become visible.

Important fields include:

• activeHolders
• acquireSuccessCount
• acquireRejectCount
• uncertainAcquireCount
• renewSuccessCount
• renewRejectCount
• transferSuccessCount
• transferRejectCount
• releaseSuccessCount
• releaseRejectCount
• observedFencingRejectCount
• lastExpiredHolderCleanupLatencyMs

Lease signal shape	Interpretation
activeHolders tracks the expected shard-owner count, renewSuccessCount grows steadily, and renewRejectCount stays low.	Lease collection is probably healthy.
activeHolders flaps while acquireRejectCount, uncertainAcquireCount, or renewRejectCount grows.	Ownership is churning or membership visibility is unstable.
observedFencingRejectCount rises or cleanup latency is high.	Downstream fencing or expiry cleanup needs immediate review.

Practical Diagnostic Workflow

Use the same order during incident triage: inspect state() first, then clusterView(), then collections(), then lease-specific counters. Do not start with lease tuning if the runtime is not ready or the node is in the wrong membership fabric.

What Diagnostics Does Not Replace

Diagnostics is a point-in-time snapshot. It does not replace metrics, logs, or long-window trend analysis. Use it as the first structured read, then correlate with observability signals.

Read Next

• Observability
• Troubleshooting