Skip to content

Commit f685a7d

Browse files
avitenzerclaude
authored andcommitted
docs(reference): PodID on /debug/sticky-claims, and what adopted does not prove (MAG-3860)
The route now names the process that answered, because the debug port is reached through a Service that balances across replicas. And adopted also counts a replica reading back its own claim after it dropped its local copy, so the section says how to tell that from a peer's claim. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent a06afb7 commit f685a7d

1 file changed

Lines changed: 17 additions & 5 deletions

File tree

‎docs/reference/metrics.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -455,23 +455,35 @@ across every replica through a shared claim. Each resolution is counted by how i
455455

456456
| Metric | Type | Labels | Description |
457457
| --- | --- | --- | --- |
458-
| `smartrouter_csm_sticky_claims_total` | Counter | `spec`, `apiInterface`, `outcome` | Claim resolutions. `outcome`: `local_hit` (answered from this replica's confirmed claim), `adopted` (took a claim another replica had made), `claimed` (this replica made the claim), `lost_race` (a peer's claim naming a different upstream won), `error` (the claim could not be read or written, so the request failed), `no_candidate` (this replica had no upstream to offer), `invalidated` (a claim was dropped because its upstream could not serve here). |
458+
| `smartrouter_csm_sticky_claims_total` | Counter | `spec`, `apiInterface`, `outcome` | Claim resolutions. `outcome`: `local_hit` (answered from this replica's confirmed claim), `adopted` (routed by a live claim read from the shared registry rather than one held in memory — usually a peer's, see below), `claimed` (this replica made the claim), `lost_race` (a peer's claim naming a different upstream won), `error` (the claim could not be read or written, so the request failed), `no_candidate` (this replica had no upstream to offer), `invalidated` (a claim was dropped because its upstream could not serve here). |
459459

460-
`adopted` is the outcome that proves a session crossed replicas. The `Lava-Provider-Address`
461-
reply header reads the same whether a replica used its own claim or a peer's.
460+
`adopted` is how a session that crossed replicas shows up. The `Lava-Provider-Address` reply
461+
header reads the same whether a replica used its own claim or a peer's. `adopted` is not proof on
462+
its own, though. A replica that drops its local copy of a claim (`invalidated`) leaves the shared
463+
claim in place, so its next request reads its own claim back and counts `adopted` too. So does a
464+
replica after `/debug/reset-all` clears its local table, if the shared claim outlived the reset. A
465+
rise in `adopted` on a replica whose `invalidated` count did not move, with no reset in between, is
466+
a peer's claim.
462467

463468
The same counts are readable without the metrics port at `GET /debug/sticky-claims` on the
464469
debug server (`--debug-address`), one row per endpoint:
465470

466471
```json
467-
[{"ChainID": "ETH1", "ApiInterface": "jsonrpc", "SharedSticky": true,
472+
[{"ChainID": "ETH1", "ApiInterface": "jsonrpc", "PodID": "eth-router-7d9f8b6c5-x2kqp/3fa9c1d2",
473+
"SharedSticky": true,
468474
"Outcomes": {"local_hit": 1, "adopted": 1, "claimed": 0, "lost_race": 0,
469475
"error": 0, "no_candidate": 0, "invalidated": 0}}]
470476
```
471477

472478
`SharedSticky` is `false` on a router without `--shared-state` and a cache backend, where every
473479
count stays `0`, so it tells "off" from "never fired". The counts are cumulative since the
474-
replica started; read them before and after the requests you send.
480+
router process started; read them before and after the requests you send.
481+
482+
`PodID` names the process that answered: the pod name, a slash, and a suffix that changes when the
483+
process restarts. The debug port is reached through a Service that balances across the router's
484+
replicas, so two readings in a row can come from different replicas. Compare two readings only when
485+
their `PodID` matches. A new suffix on the same pod name means the process restarted and its
486+
counts began again from `0`.
475487

476488
---
477489

0 commit comments

Comments
 (0)