Shard introspection
Esta página aún no está disponible en tu idioma.
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.
Listing the shards
Section titled “Listing the shards”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.
What it costs
Section titled “What it costs”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.
How long a query waits
Section titled “How long a query waits”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.
A ref to one shard
Section titled “A ref to one shard”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"}.
A ref to one entity
Section titled “A ref to one entity”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
extractEntityIdhas to dig the id back out of your message, so every message type has to have one. The handle names its entity outright, soextractEntityIdis 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.
Following the map
Section titled “Following the map”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”.
The last map, without a query
Section titled “The last map, without a query”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.
Is the region ready to route?
Section titled “Is the region ready to route?”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,registrationRefusalisnulland 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
truewhile 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 oneheartbeat-intervaland 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);When the coordinator refuses a region
Section titled “When the coordinator refuses a region”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.
Where to next
Section titled “Where to next”- 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.
