Skip to content

Commit a06afb7

Browse files
avitenzerclaude
authored andcommitted
docs(reference): name GET /debug/sticky-claims and the sticky-claims counter (MAG-3860)
The metrics reference listed the sticky-sessions gauge but not smartrouter_csm_sticky_claims_total, the counter that says whether a lava-stickiness id crossed replicas. It now does, with what each outcome means, and names GET /debug/sticky-claims (Magma-Devs/smart-router#442): the same counts per endpoint on the debug server, readable without the metrics port, with SharedSticky telling "off" from "never fired". The --debug-address row in the CLI reference links to it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 56a683c commit a06afb7

2 files changed

Lines changed: 26 additions & 1 deletion

File tree

‎docs/reference/cli.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -230,7 +230,7 @@ See [Metrics](metrics.md).
230230
| `--debug-relays` | `false` | Add debug info to relay response metadata (pairs with the `lava-debug-relay` header). |
231231
| `--debug-probes` | `false` | Add debug info to probe responses. |
232232
| `--enable-selection-stats` | `false` | Emit the `lava-selection-stats` response header. |
233-
| `--debug-address` | — | Debug HTTP server (integration tests) — exposes `/debug/*`. |
233+
| `--debug-address` | — | Debug HTTP server (integration tests) — exposes `/debug/*`, among them [`/debug/sticky-claims`](metrics.md#cross-pod-sticky-sessions). |
234234
| `--test-mode` | `false` | Send dummy data and print all listener metadata. |
235235
| `--allow-insecure-provider-dialing` | `false` | Allow non-TLS upstream connections. Dev/test only. |
236236
| `--pprof-address` | — | pprof server address (e.g. `localhost:6060`). |

‎docs/reference/metrics.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -448,6 +448,31 @@ assert `/debug/reset-all` emptied each store. All drop to `0` after a reset.
448448
| `smartrouter_csm_sticky_sessions` | Gauge | `spec`, `apiInterface` | Live sticky-session affinities. |
449449
| `smartrouter_csm_reported_providers` | Gauge | `spec`, `apiInterface` | Size of the reported-providers register. |
450450

451+
#### Cross-pod sticky sessions
452+
453+
With `--shared-state` and a cache backend, a `lava-stickiness` id resolves to one upstream
454+
across every replica through a shared claim. Each resolution is counted by how it went:
455+
456+
| Metric | Type | Labels | Description |
457+
| --- | --- | --- | --- |
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). |
459+
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.
462+
463+
The same counts are readable without the metrics port at `GET /debug/sticky-claims` on the
464+
debug server (`--debug-address`), one row per endpoint:
465+
466+
```json
467+
[{"ChainID": "ETH1", "ApiInterface": "jsonrpc", "SharedSticky": true,
468+
"Outcomes": {"local_hit": 1, "adopted": 1, "claimed": 0, "lost_race": 0,
469+
"error": 0, "no_candidate": 0, "invalidated": 0}}]
470+
```
471+
472+
`SharedSticky` is `false` on a router without `--shared-state` and a cache backend, where every
473+
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.
475+
451476
---
452477

453478
## Shared metrics

0 commit comments

Comments
 (0)