Indexer Probes

Purpose

Indexer Probes address the critical need to monitor the health and synchronization status of Blockbook-based blockchain indexers. These indexers continuously process blockchain data to maintain an up-to-date and queryable cache of blocks, transactions, and addresses. Ensuring that the indexer is fully synchronized with the blockchain is essential for reliable API responses and real-time event subscriptions.

This subtopic specifically implements readiness checks that determine whether a Blockbook indexer instance has caught up with the blockchain tip and is thus ready to serve accurate data. Unlike daemon probes that check node-level synchronization and connectivity, indexer probes focus on the indexer's internal sync state by querying its local API endpoints.

Functionality

The core workflow of indexer probes involves executing a lightweight shell script that:

1. Checks if readiness probing is explicitly disabled by the presence of a sentinel file (e.g., /data/disable_readiness).

2. Sends an HTTP GET request to the local Blockbook API endpoint (usually http://localhost:8001/api/v2).

3. Parses the JSON response to extract the .blockbook.inSync boolean flag.

4. Determines readiness based on the inSync flag:

   • If true, the indexer is fully synced, and the probe exits successfully (exit code 0).

   • If false, the indexer is still catching up, and the probe signals failure (exit code 1).

This probe script is run repeatedly by Kubernetes as a readiness check, controlling traffic routing to the pod. If the probe fails, the pod is marked "not ready," preventing API requests from hitting an out-of-date indexer.

Key Code Snippet

STATUS=$(curl -sf http://localhost:8001/api/v2) || exit 1
IN_SYNC=$(echo $STATUS | jq -r '.blockbook.inSync')

if [[ $IN_SYNC == "true" ]]; then
    echo "blockbook is synced"
    exit 0
fi

echo "blockbook is still syncing"
exit 1

This concise logic ensures that the indexer's sync status directly influences Kubernetes service readiness.

Relationship to Parent Topic and Other Subtopics

Indexer Probes complement the broader health and readiness probe framework by focusing on the indexer layer, while the sibling Daemon Probes target the blockchain node daemons themselves. Both probe types are essential for end-to-end health monitoring:

• Daemon Probes verify that the blockchain node is operational, connected to peers, and advancing blocks.

• Indexer Probes confirm that the indexer has processed these blocks and is ready to serve consistent indexed data.

Together, they provide a layered health-check strategy ensuring that the entire blockchain data stack—from node to indexer to API—is synchronized and available.

This subtopic introduces the unique approach of querying the Blockbook API's own sync state endpoint, which is not part of daemon monitoring. It leverages the indexer's built-in health indicators rather than relying solely on external metrics or logs, enabling more precise readiness decisions.

Diagram

flowchart TD
    Start[Start Readiness Probe]
    CheckDisable[Check if readiness probe disabled file exists]
    Disabled[Probe Disabled - Exit 0]
    QueryAPI[Query Blockbook API /api/v2]
    ParseSync[Parse .blockbook.inSync Flag]
    InSyncTrue{Is inSync == true?}
    Ready[Indexer Ready - Exit 0]
    NotReady[Indexer Syncing - Exit 1]

    Start --> CheckDisable
    CheckDisable -->|Exists| Disabled
    CheckDisable -->|Not exists| QueryAPI
    QueryAPI --> ParseSync
    ParseSync --> InSyncTrue
    InSyncTrue -->|Yes| Ready
    InSyncTrue -->|No| NotReady

This flowchart visualizes the decision process of the indexer readiness probe script, emphasizing its simplicity and reliability in confirming indexer sync status.