Skip to content

vector-store: add FTS metrics#519

Merged
ewienik merged 6 commits into
scylladb:masterfrom
QuerthDP:add-fts-metrics
Jul 15, 2026
Merged

vector-store: add FTS metrics#519
ewienik merged 6 commits into
scylladb:masterfrom
QuerthDP:add-fts-metrics

Conversation

@QuerthDP

@QuerthDP QuerthDP commented Jul 14, 2026

Copy link
Copy Markdown
Member

Adds Prometheus metrics for full-text search (FTS) indexes, exposed via the existing /metrics endpoint.

New gauges, refreshed on scrape for indexes with pending writes:

  • fts_index_size_bytes - in-memory size of a Tantivy index.
  • fts_segment_count - number of tantivy segments in a Tantivy index.

Reused existing, index-type-agnostic instruments instead of duplicating them under an fts_ prefix:

  • fts_query_latency_seconds -> request_latency_seconds (now also timed around the bm25 query handler)
  • fts_query_count_total -> request_latency_seconds_count (comes for free with the histogram)
  • fts_index_doc_count -> index_size
  • fts_indexing_rate -> index_modified (raw counter; apply rate() in PromQL)
  • fts_indexing_lag_seconds -> indexing_lag_seconds (only recorded for CDC-sourced writes, not full-scan indexing)

Deferred to a follow-up: fts_merge_duration_seconds. Tantivy has no completion hook for automatic background merges, so measuring it requires disabling auto-merge and driving/timing merges manually - a bigger, separate
change.

Fixes: VECTOR-629
Follow-up: VECTOR-743

@QuerthDP QuerthDP changed the title Add FTS metrics vector-store: add FTS metrics Jul 14, 2026
@QuerthDP
QuerthDP force-pushed the add-fts-metrics branch 4 times, most recently from 8c9d2af to 1addba0 Compare July 14, 2026 13:30
@QuerthDP
QuerthDP requested review from Copilot and ewienik and removed request for Copilot July 14, 2026 13:31
@QuerthDP

Copy link
Copy Markdown
Member Author

This PR is ready for review. Waiting for #515 and #503 to get in to rebase on them and open.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR extends the vector-store Prometheus metrics surface by adding FTS-specific index stats (size/segments) and wiring a shared Metrics instance through initialization so /metrics can refresh per-index stats on scrape. It also introduces new CDC reader instrumentation and refactors CDC handling into a dedicated db_cdc module.

Changes:

  • Add new Prometheus series for FTS index size (bytes) and segment count, and refresh them during /metrics scrape via a new stats() request to the Tantivy FTS actor.
  • Introduce CDC reader metrics (up/errors/restarts/last processed timestamp) and new db_cdc module components (consumer + checkpoint saver).
  • Plumb a shared Arc<Metrics> through main/lib/db initialization and time BM25 requests via the existing latency histogram.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
crates/vector-store/tests/integration/db_basic.rs Updates pattern matching for an expanded Db::GetDbIndex message.
crates/vector-store/src/metrics.rs Adds new CDC + FTS metric vectors, registration, label cleanup helpers, and export tests.
crates/vector-store/src/main.rs Creates a shared metrics instance and passes it into DB and HTTP server startup.
crates/vector-store/src/lib.rs Adds run_with_metrics() / new_metrics() and threads metrics into new_db().
crates/vector-store/src/httproutes.rs Refreshes FTS metrics on scrape and adds BM25 request timing via request_latency_seconds.
crates/vector-store/src/fts_index/tantivy.rs Implements stats() to expose Tantivy doc/segment/space usage and adds tests.
crates/vector-store/src/fts_index/actor.rs Adds FtsStats and a Stats actor message + sender extension method.
crates/vector-store/src/db.rs Threads Arc<Metrics> into statement/index construction to support CDC/lag metrics.
crates/vector-store/src/db_index.rs Passes metrics into CDC reader creation for each index.
crates/vector-store/src/db_cdc/mod.rs Introduces the CDC module and standardizes reader names (wide/fine).
crates/vector-store/src/db_cdc/consumer.rs Moves CDC row consumption/parsing into a dedicated consumer implementation.
crates/vector-store/src/db_cdc/checkpoint_saver.rs Adds a checkpoint saver that updates cdc_last_processed_timestamp_seconds.
crates/vector-store/src/db_cdc/actor.rs Adds CDC reader lifecycle metrics, restart counters, and checkpoint saver wiring.
Comments suppressed due to low confidence (1)

crates/vector-store/src/db_cdc/actor.rs:271

  • The CDC reader restart logic claims to preserve the last checkpoint, but stop() sets self.start from the handler task result, and the handler task currently returns cdc_now(). If the reader is behind (non-zero indexing_lag_seconds), restarting from wall-clock time can skip unconsumed CDC entries and cause data loss. The restart timestamp should come from the CDC checkpoint/progress (e.g., the minimum checkpoint timestamp tracked by the checkpoint saver), not from cdc_now().

Comment thread crates/vector-store/src/metrics.rs
Comment thread crates/vector-store/src/fts_index/tantivy.rs
@QuerthDP
QuerthDP marked this pull request as ready for review July 15, 2026 07:12
@QuerthDP

Copy link
Copy Markdown
Member Author

@ewienik please review

@QuerthDP
QuerthDP requested a review from knowack1 July 15, 2026 10:20
ewienik
ewienik previously approved these changes Jul 15, 2026

@ewienik ewienik left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@knowack1 Do you have any comments?

Comment thread crates/vector-store/src/httproutes.rs Outdated
Comment thread crates/vector-store/src/metrics.rs Outdated
Comment thread crates/vector-store/src/metrics.rs Outdated
Comment thread crates/vector-store/src/httproutes.rs
Comment thread crates/vector-store/src/httproutes.rs Outdated
Comment thread crates/vector-store/src/httproutes.rs Outdated
Comment thread crates/vector-store/src/httproutes.rs
QuerthDP added 3 commits July 15, 2026 15:20
Introduce two new Prometheus gauges to track the in-memory footprint
and segment count of each full-text search index. These lay the groundwork
for exposing FTS-specific index stats via the existing `/metrics` endpoint.
Add a new actor message and `FtsIndexExt::stats()` method that reports
document count, in-memory size, and segment count for an FTS index,
computed from the underlying Tantivy engine.
Time the `post_index_bm25` handler with the existing `request_latency_seconds`
histogram on every return path, mirroring how `post_index_ann` is already
instrumented, so BM25 query latency becomes visible in `/metrics`.
@QuerthDP

Copy link
Copy Markdown
Member Author

Changelog:

  • moved refreshing index metrics to a separate function
  • added fts metrics integration test
  • changed metrics description to not expose the Tantivy backend internals
  • added get_fts_index

@QuerthDP
QuerthDP requested review from ewienik and knowack1 July 15, 2026 13:27
Add a new actor message and `EngineExt::get_fts_index()` method that
resolves the FTS index and DB index senders for a given key, mirroring
the existing `get_vs_index`. This lets FTS index lookups go through
the engine actor consistently with VS indexes.
QuerthDP added 2 commits July 15, 2026 15:39
Wire the new FTS `stats()` query into the `/metrics` handler
so that `index_size`, `fts_index_size_bytes`, and `fts_segment_count`
are refreshed for FTS indexes that received writes since the last scrape.
Remove the `#[allow(dead_code)]` macros from `FtsIndex` and `FtsIndexExt`
which were probably left for removal in the future and forgotten.
Comment thread crates/vector-store/src/engine.rs
@QuerthDP

Copy link
Copy Markdown
Member Author

Changelog:

  • split get_fts_index addition into separate commit

@ewienik
ewienik added this pull request to the merge queue Jul 15, 2026
Merged via the queue into scylladb:master with commit 016b09d Jul 15, 2026
40 checks passed
@QuerthDP
QuerthDP deleted the add-fts-metrics branch July 16, 2026 07:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants