Repository navigation
feat: emit regionCacheHit('epoch_not_match_refresh') for a successful EpochNotMatch cache refresh (#858) - #1047
Open
IG-ABHINAV wants to merge 1 commit into
Open
IG-ABHINAV wants to merge 1 commit into
IG-ABHINAV wants to merge 1 commit into
Conversation
IG-ABHINAV
force-pushed
the
fix/epoch-metric-858
branch
from
November 10, 2026 15:24
5df71c9 to
d55e6a5
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #858.
What
A successful
EpochNotMatchcache refresh (RetryExecutor::refreshRegionCacheFromEpochNotMatch(), the #246current_regionspath) now emits one positive counter,regionCacheHit('epoch_not_match_refresh'), on the success path only. The fallback keeps emittingretry_region_error:epoch_not_matchand 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 supersedingput()loop, immediately before the success log, so it fires exactly once per usable payload; noregionInvalidated()reason is added (the refresh stays aput(), not an error-driven drop).src/Client/Observability/MetricsInterface.php— docblock ofregionCacheHit()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: theregionCacheHit()row of Metrics and Observability lists'epoch_not_match_refresh'with its meaning, and theregionInvalidated()row points at the counter instead of leaving the "emits noregionInvalidated()" 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_matchfromRegionErrorHandler::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
regionCacheRefreshed()or a documentedregionCacheHit('epoch_not_match_refresh'). I chose the tag:MetricsInterfaceis explicitly frozen ("adding those signals never breaks an existing implementation" — the extension point isDetailedMetricsInterface, probed withinstanceof). A new base method would be a breaking change for every custom backend, and aDetailedMetricsInterface-only method would emit nothing for base-only backends, failing "success emits one positive counter" for them.tikv_client_region_cache_hits_totalcounter adds no new Prometheus series and needs no change inPrometheusMetrics/InMemoryMetrics.refreshRegionCacheFromEpochNotMatch()right after theput()loop — the only success exit — so exactly one counter per refresh regardless of call site (RawKV and TxnKV, including aftercheck()already dropped the stale entry).true, so the caller's invalidation block stays skipped;region_error:epoch_not_matchfromcheck()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 noext-grpc):→
No syntax errors detected×3→
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 givesTests: 10, Assertions: 54, Failures: 3— the three success-shape assertions fail; restoring the line returnsOK (10 tests, 62 assertions).→
Tests: 509, Assertions: 58031, Failures: 19, Warnings: 1Those 19 failures are pre-existing and unrelated:
git stashof this branch and re-running the identical command on the clean tree givesTests: 509, Assertions: 58008, Failures: 19, Warnings: 1with a byte-identical set of failing tests (alltests/Unit/Docs/*guards, failing on this Windows checkout withfile_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:
→ no match (exit 1).
Test coverage added
RetryExecutorEpochNotMatchTestnow asserts, in the repo's existing style: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 assertsregion_error:epoch_not_matchstays at exactly 1 — no extra invalidation);retry_region_error:epoch_not_match === 1.