跳转到内容
简体中文

Shard introspection

此内容尚不支持你的语言。

Starting a region hands you one ref — the region’s — and that used to be the whole story. You could send messages through sharding, but you could not ask it anything: not “which shards exist”, not “where does shard 7 live”, not “give me a handle on entity user-42”.

Four APIs on ClusterSharding close that, plus one cluster event for the push side.

shards(typeName) answers cluster-wide, from any node:

const shards = await cluster.sharding.shards<CounterCommand>('counter');
for (const shard of shards) {
console.log(
`shard ${shard.shardId} on ${shard.node}`,
`— ${shard.entityCount} entities`,
shard.local ? '(here)' : '',
);
}

Each entry is a ShardInfo:

type ShardInfo<TMessage = unknown> = {
readonly shardId: number;
readonly node: NodeAddress; // node currently hosting the shard
readonly regionPath: string; // region on that node
readonly entityCount: number; // live entities when its region answered
readonly resident: boolean; // shard actor materialised at that moment
readonly local: boolean; // hosted by the node that asked
readonly ref: ActorRef<ShardMessage<TMessage>>;
};

resident is what separates a shard that is running and happens to be empty from one that passivated while empty — entityCount: 0 reports both. It does not affect whether you can talk to the shard: ref works either way. Read it when you are tuning shardPassivationIdleMs, or counting the actors a node is really holding.

The entry carries a live ref, not just placement data, so one query answers both “what is out there” and “how do I talk to it”. The trade-off is that ShardInfo is not JSON-serialisable — if you need a serialisable view, use shardMap(typeName) or the GET /cluster/shards management endpoint, which serialises exactly that.

Shards with no home yet are absent from the list. Nothing has asked for them, so the coordinator has had no reason to place them; a 64-shard type that has seen three entity ids reports one to three shards, not 64.

The coordinator owns the shard map but not the entity counts — only the region hosting a shard knows those — so the call fans out to every registered region and joins the answers against the allocation map. One extra round trip, in other words.

The fan-out deadline is a partial-answer deadline: a region that is slow, or that left between the map snapshot and the fan-out, contributes entityCount: 0 rather than failing the whole call. You get a complete shard list with one conservative count, not an exception.

shards() and shardRefFor() wait actor-ts.sharding.shard-region-query-timeout (5 s), or what withShardRegionQueryTimeoutMs gave the type, or a timeoutMs you pass as the last argument. The region keeps a waiting query for a minute, or for actor-ts.actor.ask-timeout or the type’s query timeout when either is longer — it cannot see a per-call timeoutMs. So a timeoutMs above that lifetime is not waited out in full: an answer that arrives after it reaches nobody, and the call fails with AskTimeoutError when its own timeoutMs runs out. For shards() that includes the coordinator’s partial answer, which comes after 0.6 × timeoutMs when a region is slow. To wait longer than a minute, raise the type’s query timeout rather than the argument; the lifetime rises with it.

const shard = await cluster.sharding.shardRefFor<CounterCommand>('counter', 7);

If shard 7 has no home yet, this places it — exactly what a first message for it would have done — and answers once the coordinator has decided.

An id that cannot be a shard of the type — anything but an integer from 0 to numShards - 1 — is refused at once with a RangeError naming the range. No coordinator would ever place it, so waiting would only end in a timeout that says nothing about why.

A shard that passivated while empty needs no special handling: the ref stays valid across the gap and the shard is re-created when something arrives for it. Locally that happens as soon as you ask, because a handle to an actor that is not running would be a handle to nothing; for a shard on another node the ref delivers through that node’s region, which materialises the shard before forwarding. So shardRefFor() on a local shard wakes it, and on a remote one the first tell does. The exceptions are a local shard backing off after a failure and one caught mid-stop, handing off or passivating: the ref then relays through the region, which holds what arrives until the shard can take it, or sends it on to wherever a hand-off moved the shard.

The ref is the real thing. A shard is an actor (/system/cluster/sharding/region-counter/shard-7), and the ref carries that path as its identity whichever node you asked from — what changes is the route: directly to the actor when this node hosts it, through the owning region when it does not. tell therefore works from anywhere:

// Bring an entity up without sending it a message.
shard.tell({ kind: 'sharding.StartEntity', entityId: 'user-42' });
// Address one entity through the shard.
shard.tell({
kind: 'sharding.EntityEnvelope',
entityId: 'user-42',
message: { id: 'user-42', kind: 'increment' },
});

And to ask what a shard is holding:

const stats = await shard.ask<ShardStats>({ kind: 'sharding.GetShardStats' });
// { shardId: 7, entityCount: 2, entityIds: ['user-42', 'user-99'] }

StartEntity and GetShardStats are shard messages: told to the region rather than to a shard ref, they are not forwarded but declined — a dead letter naming the region, counted in actor_unhandled_total{class="ShardRegion"}.

entityRefFor is the counterpart to the region ref — a handle on a single entity, wherever it currently lives:

const entity = cluster.sharding.entityRefFor<CounterCommand>('counter', 'user-42');
entity.tell({ kind: 'increment', by: 1 });
const value = await entity.ask<number>({ kind: 'get' });

Two things are different from talking to the region:

  • The message no longer carries its own routing key. Sending to a region means extractEntityId has to dig the id back out of your message, so every message type has to have one. The handle names its entity outright, so extractEntityId is never consulted.
  • It is synchronous to obtain. The shard is hash(entityId) % numShards, so nothing needs looking up. A message for a shard whose home is not known yet is buffered by the region, exactly as it always was.

It is location-transparent because it routes through the local region, which already knows how to reach any node. A proxy region (startProxy) is enough to hand one out — the node does not have to host anything.

ask works on an entity ref regardless of where the entity lives: the region forwards your sender to the entity, so the reply comes straight back to you.

For the push side, subscribe to ShardMapChanged:

import { match, P } from 'ts-pattern';
import { ShardMapChanged } from 'actor-ts/cluster';
cluster.subscribe((event) =>
match(event)
.with(P.instanceOf(ShardMapChanged), (e) => onShardMapChanged(e))
.otherwise(() => onOtherEvent()));
function onShardMapChanged(event: ShardMapChanged): void {
// event.type — the sharded type name
// event.shards — ReadonlyMap<shardId, regionKey>
// event.regions — the region table, with per-region shard counts
// event.version — increments once per broadcast
}

The event fires on every node, not just the leader: the coordinator broadcasts to each region and the region publishes locally. That is what makes it usable from an application listener or a per-node dashboard.

Broadcasts are coalesced. Allocation changes arrive one shard at a time and a fresh cluster places every shard at once, so version counts broadcasts rather than individual assignments — do not read it as “how many shards moved”.

Because the event reaches every node, ClusterSharding can simply remember the last one — which is what shardMap(typeName) returns, as plain JSON:

const map = cluster.sharding.shardMap('cart');
if (map !== null) {
// map.regions — one entry per region, with its shard ids
// map.shardHome — [{ shard, regionKey }], one per placed shard
// map.version — the coordinator's broadcast counter
// map.leader, map.takenAt — who published it, and when it arrived here
}

Synchronous and free: no round trip, no DistributedData, no coordinatorStateStore. It is what the GET /cluster/shards endpoint serialises.

It returns null until the coordinator has published once for the type — which includes every node that started neither a region nor a proxy for it, since the coordinator broadcasts only to regions that registered. And shardHome stays empty until a shard is actually placed, while regions fills on registration: read regions for “who is participating”, shardHome for “what is placed”.

Reach for shards() instead when you need entity counts or live refs, and for ShardMapChanged when you need the changes rather than the latest state.

A region registers with the coordinator that runs on the leader, over a retry timer of its own. That is a separate step from joining the cluster, and membership convergence is not a proxy for it: a fully converged cluster can still hold a region that has not registered.

if (cluster.sharding.isRegistered('cart')) { /* the coordinator acknowledged this node's region */ }

Synchronous and free, like shardMap, and fed the same way — from a ShardRegionRegistered event this node’s region publishes once the coordinator acknowledges it. false for a type this node never started; for one whose registration was refused over a numShards mismatch; for one whose region was told it had been evicted for going silent, until its new registration is acknowledged; and for one whose region has stopped. In each of those the coordinator places no shard of the type on this node, so a readiness probe built on this signal takes the node out of rotation rather than reporting it ready.

It is this node’s account of its registration, built from what its region was told, and two situations are worth knowing exactly:

  • A leader change does not turn it false. Every region registers again with the new leader’s coordinator, and the node keeps reading as registered while it does, so an election does not take every node out of rotation at once. That holds even when the new leader runs no coordinator for the type at all: the reading cannot tell that apart from a re-registration still in flight. A refusal the old leader issued lapses with it — from the leader change until the new coordinator answers, registrationRefusal is null and the type reads as not registered: waiting, not refused.
  • An eviction is learnt from the coordinator’s notice, a single, unacknowledged frame. If it is lost, the region keeps its shards and this keeps reading true while the coordinator holds no entry for the region — until the region’s next beat reaches the coordinator, which answers a beat from a region it does not know with a request to register. The window is one heartbeat-interval and a round trip, and registering again takes the region’s stale copies of the re-homed shards down. Without stale-region detection nothing is evicted, so there is no such window.

That probe ships with the framework. Name the type, and Cluster.join installs a shard-region:cart readiness check for it, whose detail says which of those cases is keeping it red:

actor-ts.sharding.healthcheck.names = ["cart"]

For a type only the code knows about, register shardRegionRegistered(cluster, 'cart') from actor-ts/management yourself — see gating on a shard region.

cluster.subscribe((event) => {
if (event instanceof ShardRegionRegistered) console.log(event.type, 'can route');
});

The event is node-local, like every cluster event: it says something about this node’s region. To watch every node’s registrations from one place, bridge it — it originates on a single node, which makes it a sound thing to bridge:

cluster.eventStream.bridge(ShardRegionRegistered);

A coordinator refuses a region whose numShards disagrees with the count it governs the type with. That is the shape of a rolling deploy that changed the setting on some nodes and not others, and it is the one sharding failure that gets worse the longer it goes unnoticed: the refused region keeps running and keeps accepting traffic for the type, and everything it accepts buffers. The end state is a node out of memory.

const refusal = cluster.sharding.registrationRefusal('cart');
if (refusal) {
console.error(
`refused: this node has ${refusal.regionNumShards},`
+ ` the coordinator governs ${refusal.coordinatorNumShards}`,
);
}

null when there is no refusal, and cleared once a later registration is accepted — so a deploy that fixes the mismatch stops reporting one — and when the leader moves: a refusal is the verdict of the coordinator that issued it, and until the new leader’s coordinator answers there is none to report. The same refusal is published as a ShardRegionRegistrationRefused cluster event, for code that wants to react rather than poll.

The thing to alert on is the counter, which needs no code of yours:

cluster_sharding_registrations_refused_total{type="cart",reason="num-shards-mismatch"}

Any non-zero value is worth paging on — a refusal is never transient and never resolves on its own. It follows the label shape of cluster_gossip_records_refused_total, and like every metric here it is only recorded when metrics are enabled on the system.

  • Sharding overview — the region, shard and entity actors these APIs hand you refs to.
  • Rebalance — why placement moves, and what happens to a shard ref when it does.
  • HTTP management endpoints — GET /cluster/shards, the serialisable view of the same map.