Skip to content

feat: emit regionCacheHit('epoch_not_match_refresh') for a successful EpochNotMatch cache refresh (#858) - #1047

Open
IG-ABHINAV wants to merge 1 commit into
crazy-goat:masterfrom
IG-ABHINAV:fix/epoch-metric-858
Open

IG-ABHINAV wants to merge 1 commit into
crazy-goat:masterfrom
IG-ABHINAV:fix/epoch-metric-858

Conversation

@IG-ABHINAV

Copy link
Copy Markdown

Fixes #858.

What

A successful EpochNotMatch cache refresh (RetryExecutor::refreshRegionCacheFromEpochNotMatch(), the #246 current_regions path) now emits one positive counter, regionCacheHit('epoch_not_match_refresh'), on the success path only. The fallback keeps emitting retry_region_error:epoch_not_match and emits nothing under the new tag, so a dashboard can finally separate "refreshed from TiKV's payload" (PD round trip saved) from "fell back to PD".

  • src/Client/Retry/RetryExecutor.php — the counter is emitted after the superseding put() loop, immediately before the success log, so it fires exactly once per usable payload; no regionInvalidated() reason is added (the refresh stays a put(), not an error-driven drop).
  • src/Client/Observability/MetricsInterface.php — docblock of regionCacheHit() documents the new operation tag. No interface method was added and no signature changed.
  • docs/configuration.md — the tag is documented where the issue asked: the regionCacheHit() row of Metrics and Observability lists 'epoch_not_match_refresh' with its meaning, and the regionInvalidated() row points at the counter instead of leaving the "emits no regionInvalidated()" statement bare.
  • docs/advanced.md, docs/error-handling.md, docs/helpers/faq.md — the three places that stated "a successful refresh emits nothing" now name the counter next to that statement.
  • CHANGELOG.md — entry under ## [Unreleased] → ### Added.
  • tests/Unit/Retry/RetryExecutorEpochNotMatchTest.php — regression assertions (see below).

Why

Issue #858: the refresh path is observability-silent while the invalidation that precedes it is counted (region_error:epoch_not_match from RegionErrorHandler::check() at TxnKV call sites), so (a) a dashboard cannot tell a payload refresh from a PD fallback, and (b) the PD calls #246 saves are unmeasurable.

How / judgment calls

  • The issue offered regionCacheRefreshed() or a documented regionCacheHit('epoch_not_match_refresh'). I chose the tag:
    • MetricsInterface is explicitly frozen ("adding those signals never breaks an existing implementation" — the extension point is DetailedMetricsInterface, probed with instanceof). A new base method would be a breaking change for every custom backend, and a DetailedMetricsInterface-only method would emit nothing for base-only backends, failing "success emits one positive counter" for them.
    • The issue's DoD says "document the tag", which only exists in the tag variant, and one tag on the existing tikv_client_region_cache_hits_total counter adds no new Prometheus series and needs no change in PrometheusMetrics/InMemoryMetrics.
  • Emission placement: inside refreshRegionCacheFromEpochNotMatch() right after the put() loop — the only success exit — so exactly one counter per refresh regardless of call site (RawKV and TxnKV, including after check() already dropped the stale entry).
  • No extra invalidation anywhere: the refresh still returns true, so the caller's invalidation block stays skipped; region_error:epoch_not_match from check() remains the only invalidation on the TxnKV success shape.

Verification

Run on this branch with PHP 8.3.36 (composer install --ignore-platform-req=ext-grpc, unit suite needs no ext-grpc):

D:/gptmp/php/php.exe -l src/Client/Retry/RetryExecutor.php
D:/gptmp/php/php.exe -l src/Client/Observability/MetricsInterface.php
D:/gptmp/php/php.exe -l tests/Unit/Retry/RetryExecutorEpochNotMatchTest.php

→ No syntax errors detected ×3

D:/gptmp/php/php.exe vendor/bin/phpunit tests/Unit/Retry/RetryExecutorEpochNotMatchTest.php

→ OK (10 tests, 62 assertions)

Mutation check (the regression must fail without the fix): commenting out the $this->metrics->regionCacheHit('epoch_not_match_refresh'); line and re-running the same file gives Tests: 10, Assertions: 54, Failures: 3 — the three success-shape assertions fail; restoring the line returns OK (10 tests, 62 assertions).

D:/gptmp/php/php.exe vendor/bin/phpunit tests/Unit/Retry tests/Unit/Observability tests/Unit/Docs

→ Tests: 509, Assertions: 58031, Failures: 19, Warnings: 1

Those 19 failures are pre-existing and unrelated: git stash of this branch and re-running the identical command on the clean tree gives Tests: 509, Assertions: 58008, Failures: 19, Warnings: 1 with a byte-identical set of failing tests (all tests/Unit/Docs/* guards, failing on this Windows checkout with file_get_contents(D:\…/D:\…\README.md) path-concatenation warnings). The only delta between the two runs is the +23 assertions this PR adds.

Duplicate check before pushing:

git fetch origin && git log origin/master --oneline -20 | grep -F '#858'

→ no match (exit 1).

Test coverage added

RetryExecutorEpochNotMatchTest now asserts, in the repo's existing style:

  • one getCacheHits('epoch_not_match_refresh') on the fresh-split success, the same-ID-newer-epoch success, and the post-RegionErrorHandler::check() TxnKV success (which also asserts region_error:epoch_not_match stays at exactly 1 — no extra invalidation);
  • zero under the tag on all four fallbacks (empty payload, non-covering payload, older epoch, boundary-ending region), each of which still asserts retry_region_error:epoch_not_match === 1.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[OBS] A successful EpochNotMatch cache refresh emits no metric while the preceding invalidation does

1 participant