Skip to content

indexer: count and log decoder fallbacks to unknown/raw_topics - #62

Merged
priscaenoch merged 1 commit into
octraban:mainfrom
samuel2926i39-art:fix/decode-fallback-metrics-issue-51
Aug 24, 2026
Merged

indexer: count and log decoder fallbacks to unknown/raw_topics#62
priscaenoch merged 1 commit into
octraban:mainfrom
samuel2926i39-art:fix/decode-fallback-metrics-issue-51

Conversation

@samuel2926i39-art

Copy link
Copy Markdown
Contributor

Summary

decode() in indexer/src/decoder.js silently falls back to function: "unknown" (with only raw_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 (in indexer/src/metrics.js), incremented via a new recordDecodeFallback() helper every time decode() hits the fnName === "unknown" path.
  • A structured debug log per fallback (component: "decoder", event: "decode_fallback", contract_id, ledger, tx_hash) for sampling/investigation.
  • A ## Decode Fallback Metric section in README.md documenting what a rising rate indicates.

The counter registers into the indexer's existing shared prom-client Registry, so it's automatically exposed at the indexer's existing GET /metrics (indexer/src/api.js) — no additional wiring needed there.

Context / before-after

  • Before: an unrecognized event decoded with no observable signal — you'd only notice via a support ticket or a manual DB query for function = 'unknown'.
  • After: soroban_decode_fallback_total shows up per-contract in the indexer's metrics scrape, and each occurrence is logged with enough context (contract, ledger, tx) to investigate immediately.
  • No behavior change to what gets stored or returned for any event — this is purely additive observability.

Testing

  • Added 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() increments soroban_decode_fallback_total labeled by contract_id.
    • Counters for different contracts stay isolated (per-contract labeling).
    • A known event never reaches recordDecodeFallback (gate mirrors the real decode() check).
    • recordDecodeFallback() emits the expected structured debug log shape.
  • Ran locally: node --test tests/decodeFallback.test.js → 6/6 passing.
  • Regression-checked the existing decoder suites for this change: node --test tests/decoder.test.js tests/decoder-parity.test.js tests/scval.test.js (102/102 passing) and node --test test/decoder.sep41.test.js test/sac.test.js (23/23 passing).
  • npm run typecheck (indexer) — clean.

Closes #51

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
@priscaenoch
priscaenoch merged commit 6169659 into octraban:main Aug 24, 2026
7 checks passed
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.

Add metrics for indexer decode failures

2 participants