indexer: count and log decoder fallbacks to unknown/raw_topics - #62
Merged
priscaenoch merged 1 commit intoAug 24, 2026
Merged
Conversation
Add soroban_decode_fallback_total, a Prometheus counter labeled by contract_id, incremented whenever decode() cannot attribute an event to a recognised function and falls back to function: "unknown". Each fallback also emits a structured debug log (component, event, contract_id, ledger, tx_hash) for sampling. The counter registers into the indexer's existing shared prom-client registry, so it's already exposed at GET /metrics (indexer/src/api.js) with no further wiring. Documents the metric and what a rising rate indicates in README.md. Closes octraban#51
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.
Summary
decode()inindexer/src/decoder.jssilently falls back tofunction: "unknown"(with onlyraw_topics) whenever it can't recognize an event's function. There was no signal — counter or log — when this happens, so decoding coverage regressions (an unregistered ABI, an unrecognized event signature, a decoder bug) could go unnoticed indefinitely.This adds:
soroban_decode_fallback_total{contract_id="..."}— a Prometheus counter (inindexer/src/metrics.js), incremented via a newrecordDecodeFallback()helper every timedecode()hits thefnName === "unknown"path.component: "decoder",event: "decode_fallback",contract_id,ledger,tx_hash) for sampling/investigation.## Decode Fallback Metricsection inREADME.mddocumenting what a rising rate indicates.The counter registers into the indexer's existing shared
prom-clientRegistry, so it's automatically exposed at the indexer's existingGET /metrics(indexer/src/api.js) — no additional wiring needed there.Context / before-after
function = 'unknown'.soroban_decode_fallback_totalshows up per-contract in the indexer's metrics scrape, and each occurrence is logged with enough context (contract, ledger, tx) to investigate immediately.Testing
indexer/tests/decodeFallback.test.js(Node's built-in test runner, matching this repo's existing decoder test conventions):isDecodeFallback("unknown")is true;isDecodeFallback("transfer")is false.recordDecodeFallback()incrementssoroban_decode_fallback_totallabeled bycontract_id.recordDecodeFallback(gate mirrors the realdecode()check).recordDecodeFallback()emits the expected structured debug log shape.node --test tests/decodeFallback.test.js→ 6/6 passing.node --test tests/decoder.test.js tests/decoder-parity.test.js tests/scval.test.js(102/102 passing) andnode --test test/decoder.sep41.test.js test/sac.test.js(23/23 passing).npm run typecheck(indexer) — clean.Closes #51