QRun-IO/qbit-quick-search
3
0 Fork 0
Code Issues 2 Pull Requests 4 Actions Packages Projects Releases 14 Wiki Activity

feat(#35): search admin tooling (playground, validation, record tools, analyzer, failure diagnostics) #39

Merged
KofTwentyTwo merged 5 commits from feature/GH-35-search-admin-tooling into develop 2026-10-12 12:37:58 +00:00
Conversation 1 Commits 5 Files Changed 41
+8595 -31
41 changed files with 8595 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CHANGELOG.md
+6
View File
@@ -15,6 +15,12 @@ Requires QQQ 4.1.0-RC.2 or later, the first release that carries the record-sear
- `serveCoreRecordSearch` (default `true`): registers the provider and gives indexed tables core `searchFields` (visible string and integer searchable fields) when they have none. Host `searchFields` and a host-registered provider are never replaced.
- `recordSearchTimeoutMillis` (default 2500): wall-clock limit on the OpenSearch request; on timeout or any failure core falls back to its own search, and the provider claims no tables for 30 seconds.
- `QuickSearchOpenSearchClient.searchRecordIdsPerTable`.
- Diagnostic tools (#35), on by default (`enableDiagnosticTools`): Search Playground, Validate Search Index (schedulable with `validationCronExpression`; reports kept in the new `quickSearchValidationRun` table), Test Search Analyzer, and on every indexed table and on `quickSearchFailedEvent` rows the record actions Inspect Search Document (database vs index, and why a record does or does not match a term) and Reindex in Search. All are table or record actions, gated by the new `debugPermissionRules` (`quickSearchDebug.hasAccess`; Reindex in Search uses `adminPermissionRules`), rate-limited per user (`diagnosticRunsPerMinute`), and recorded in the new `quickSearchDiagnosticEvent` table. Settings: `enableRecordDiagnosticActions`, `validationCronExpression`, `validationCronTimeZoneId`, `validationSampleSize`.
- Search failure diagnostics: a failed or timed-out OpenSearch request behind core record search or `QuickSearchAction` is recorded as a `SEARCH_FAILED` diagnostic event (tables, duration, error, server; never the term); the runtime counts failures and backoff fallbacks. The Search Diagnostics widget (`quickSearchDiagnostics`, on the admin app home) shows the provider's state, recent failures and the latest validation.
- `QuickSearchDiagnosticsOperations`: read-only probe search (named clauses, field highlights, request and response JSON), explain, document reads, `_analyze`, document sampling, and raw cluster, mapping and settings reads.
### Changed
- Run history purging also purges `quickSearchDiagnosticEvent` and `quickSearchValidationRun` rows older than `runHistoryRetentionDays`.
### Security
- Fields of type `PASSWORD` are no longer indexed (as hidden fields already were). Reconcile or fully reindex once to remove values a 1.0 index may hold.
README.md
+26 -1
View File
@@ -160,6 +160,23 @@ config.withSchedulerName("quartz")
.withReconcileCronTimeZoneId("America/Chicago");
```
### Diagnostic tools
With `enableDiagnosticTools` (default `true`) the QBit adds tools to validate the search and debug it from the admin UI. They are table and record actions (never left-nav entries), gated by permissions, recorded in `quickSearchDiagnosticEvent`, limited to `diagnosticRunsPerMinute` runs per user and tool, and read-only except Reindex in Search.
| Tool | Where | What it does |
|---|---|---|
| Search Playground | Quick Search Index, Actions (select rows to pre-fill their tables) | Runs a term the way the global search does, as you: the path each table takes (OpenSearch provider, core database search, or not searched) and why; the provider's own request, timed; the global search results you would see; per indexed table, the production query with scores, highlights, matched fields, which hits you can read and which the global search shows, the query DSL and the raw response (hits you cannot read are redacted); the term's tokens; and `explain` for a hit (`table:id`). The form stays open, so you can change the term and run again. |
| Validate Search Index | Quick Search Index, Actions; also scheduled by `validationCronExpression` | Cluster and index health, the alias, leftover physical indexes from interrupted rebuilds, the live mapping (version, field types, analyzers, the `fieldValues` template) and analysis settings, then per table: database rows vs documents, a sample of records checked present and current in the index, a random sample of documents checked to still have a record, the index row's status and last run, and waiting failed events. Each finding is OK, INFO, WARN or FAIL with what to do. The report is saved as a `quickSearchValidationRun` row (HTML for the record view, JSON for tools). Database reads run as the system user so counts compare like with like; the report holds counts, ids and field names, never record values. One validation runs at a time per server. |
| Test Search Analyzer | Quick Search Index, Actions | `_analyze` on the live index: the tokens of a text as indexed (edge n-grams of 2 to 20 characters) and as a query, and, given a term, whether every term token is among the text's indexed tokens. |
| Inspect Search Document | Every indexed table's records (Actions), and Quick Search Failed Event rows | The record's document in the index next to the document indexing would write from the database now, field by field (current, stale or missing), with versions and the raw document. Enter a term to see why the record does or does not match it: term length, table enabled, read permission, document present and current, each term token found or not (and why: one character, longer than 20, not in the text, or only in the database's newer values), `explain`, and the record's rank against the number of ids the global search takes. |
| Reindex in Search | Every indexed table's records, and Quick Search Failed Event rows | Rebuild the selected records' documents from the database now (versioned writes, so a newer document is never overwritten); a record that no longer exists has its document removed; a record you cannot read is skipped. Asks to confirm. Needs the admin permission. |
| Search Diagnostics widget | The Quick Search Admin app home (hosts with their own home add `quickSearchDiagnostics`) | Whether the global search is served by OpenSearch on this server or backing off (and why), failure and fallback counts, the latest search failures from every server, and the latest validation run. |
Search failures are recorded too: when the provider's OpenSearch request fails or times out (and core falls back to its own search), or `QuickSearchAction`'s search fails, a `SEARCH_FAILED` event keeps the tables, duration, error class and message, and the server. The user's term is never stored, only its length. At most 120 events are written per server per minute.
Permissions: the read-only tools and the widget use `debugPermissionRules` (default `quickSearchDebug.hasAccess`); Reindex in Search uses `adminPermissionRules` (`quickSearchAdmin.hasAccess`); the two history tables use `tablePermissionRules` (grant `.read` only: rows are written by the QBit). Impersonation ("search as user X") is deliberately not offered: a fabricated session would not carry the real user's security key values, so its results would mislead.
## Configuration reference
| Field | Default | Description |
@@ -188,7 +205,13 @@ config.withSchedulerName("quartz")
| `applyRecordSecurityLocks` | `true` | Re-read hits through `QueryAction` |
| `serveCoreRecordSearch` | `true` | Register `QuickSearchRecordSearchProvider` so core `POST /qqq/v1/search` uses OpenSearch for indexed tables, and give those tables `searchFields` when they have none |
| `recordSearchTimeoutMillis` | 2500 | Wall-clock limit on the OpenSearch request behind a core search; past it, core falls back to its own search |
| `adminPermissionRules` | `HAS_ACCESS_PERMISSION`, base name `quickSearchAdmin` | Rules for the app and processes |
| `enableDiagnosticTools` | `true` | Add the diagnostic tools, the `quickSearchDiagnosticEvent` and `quickSearchValidationRun` tables and the diagnostics widget |
| `enableRecordDiagnosticActions` | `true` | With the tools on, add Inspect Search Document and Reindex in Search to every indexed table |
| `validationCronExpression`, `validationCronTimeZoneId` | none | Schedule Validate Search Index; same rules as the reconcile schedule (a cron-capable scheduler such as Quartz, a valid Quartz expression, a time zone ID) |
| `validationSampleSize` | 50 | Records and documents sampled per table by validation (at most 1000) |
| `diagnosticRunsPerMinute` | 30 | Per-user, per-tool limit on diagnostic runs |
| `debugPermissionRules` | `HAS_ACCESS_PERMISSION`, base name `quickSearchDebug` | Rules for the read-only diagnostic tools and the widget |
| `adminPermissionRules` | `HAS_ACCESS_PERMISSION`, base name `quickSearchAdmin` | Rules for the app, the maintenance processes and Reindex in Search |
| `tablePermissionRules` | `READ_WRITE_PERMISSIONS` | Rules for the operational tables |
| `tableMetaDataCustomizer` | | Applied to every produced table (backend details, for example) |
| `searchableEntityClasses`, `searchableTables` | at least one | What to index |
@@ -200,6 +223,8 @@ config.withSchedulerName("quartz")
- `quickSearchIndex`: one row per table with `enabled` (honoured by indexing and search, cached for one minute), `basepullIntervalMinutes`, `lastBasepullTime`, `lastReconcileTime`, `lastFullReindexTime`, `lastRunStatus`, `lastErrorMessage`, `recordCount`, `documentCount`, `realTimeErrorCount`, `status` (`ACTIVE`, `NEEDS_REINDEX` when the configured fields changed since the row was created, or `REBUILDING` while a full reindex of all tables runs). Unique on `tableName`.
- `quickSearchIndexRun`: `runType` (`BASEPULL`, `RECONCILE`, `FULL_REINDEX`), `status`, counts, `errorMessage`.
- `quickSearchDiagnosticEvent` (with `enableDiagnosticTools`): `eventType` (`SEARCH_FAILED`, `TOOL_RUN`, `REINDEX`, `RATE_LIMITED`), `source`, `outcome`, `userName`, `tableNames`, `searchTerm` (tool runs only), `durationMillis`, `errorClass`, `errorMessage` (text), `detail` (text), `hostName`, `createDate`. Purged after `runHistoryRetentionDays`.
- `quickSearchValidationRun` (with `enableDiagnosticTools`): `status` (`PASS`, `WARN`, `FAIL`), `triggerType` (`MANUAL`, `SCHEDULED`), `userName`, `tableNames`, `sampleSize`, `tablesChecked`, `failCount`, `warnCount`, `summary`, `reportHtml` (HTML), `reportJson` (text), `startTime`, `endTime`, `createDate`. Purged after `runHistoryRetentionDays`.
- `quickSearchFailedEvent`: real-time events that could not be applied; `status` `PENDING` or `EXHAUSTED` after 10 attempts. Deletes made while a full reindex of all tables runs are also recorded here with status `AWAITING_REINDEX`: the reindex applies them to the new index after the alias swap (basepull does not replay them). While a table is `REBUILDING`, drift detection is suspended for it. Only one full reindex runs at a time: starting one while another is running fails. A full reindex shows it is running through its `FULL_REINDEX` run records, which stay `RUNNING` with `modifyDate` refreshed after every page. If it is killed mid-run (pod restart, OOM, deploy), recovery is automatic once its run records have shown no sign of life for `fullReindexStaleMinutes` (30 by default): the next basepull, or the next full reindex, marks those run records `FAILED`, returns the tables to `ACTIVE` with `lastBasepullTime` moved back to the run's start, and turns the `AWAITING_REINDEX` rows `PENDING` so basepull replays the deletes. No data is lost. A run that was only slow and is judged stopped notices before its alias swap and fails without swapping, or, after its swap, stops applying its captured deletes; basepull skips a replayed delete whose record exists again.
## Extending
docs/MIGRATION-1.1.md
+9
View File
@@ -28,3 +28,12 @@ new QuickSearchQBitConfig()
```
restores 1.0 behaviour: no provider, no `searchFields` changes.
## Diagnostic tools (1.1.0-RC.2)
The QBit now adds admin tools to validate and debug search (see the README, "Diagnostic tools"). They are on by default.
- **Two new operational tables**, on `backendName` like the others: `quickSearchDiagnosticEvent` and `quickSearchValidationRun` (columns in the README, "Operational tables"). Create them in the host's schema, with the naming the host applies to the other operational tables (`tableMetaDataCustomizer` applies to them too). Until they exist, writing events and saving reports fails quietly (logged at warn) and the tools still run.
- **Permissions.** Grant `quickSearchDebug.hasAccess` to the people who may use the read-only tools and see the widget, `quickSearchAdmin.hasAccess` for Reindex in Search, and `.read` on the two new tables (the QBit writes them; users never do).
- **New processes** have a `tableName` (Quick Search Index, Quick Search Failed Event, and each indexed table), so they appear as table and record actions. They are not added to the admin app's children; a host that strips processes from its nav needs no change.
- **Opting out.** `withEnableDiagnosticTools(false)` adds none of it; `withEnableRecordDiagnosticActions(false)` keeps the tools on Quick Search Index but adds nothing to the indexed tables.
src/main/java/com/kingsrook/qbits/quicksearch/QuickSearchQBitConfig.java
+268 -9
View File
@@ -71,6 +71,10 @@ public class QuickSearchQBitConfig implements QBitConfig
public static final String DEFAULT_ADMIN_PERMISSION_BASE_NAME = "quickSearchAdmin";
public static final String DEFAULT_BASEPULL_TIMESTAMP_FIELD = "modifyDate";
public static final int DEFAULT_RECORD_SEARCH_TIMEOUT_MILLIS = 2500;
public static final String DEFAULT_DEBUG_PERMISSION_BASE_NAME = "quickSearchDebug";
public static final int DEFAULT_VALIDATION_SAMPLE_SIZE = 50;
public static final int MAX_VALIDATION_SAMPLE_SIZE = 1000;
public static final int DEFAULT_DIAGNOSTIC_RUNS_PER_MINUTE = 30;
///////////////////////////////////////////////////////////////////////////////
// a live full reindex refreshes its run record after every page; a page is //
@@ -123,12 +127,19 @@ public class QuickSearchQBitConfig implements QBitConfig
private Boolean applyRecordSecurityLocks = true;
private Boolean serveCoreRecordSearch = true;
private Integer recordSearchTimeoutMillis = DEFAULT_RECORD_SEARCH_TIMEOUT_MILLIS;
private Boolean enableDiagnosticTools = true;
private Boolean enableRecordDiagnosticActions = true;
private String validationCronExpression;
private String validationCronTimeZoneId;
private Integer validationSampleSize = DEFAULT_VALIDATION_SAMPLE_SIZE;
private Integer diagnosticRunsPerMinute = DEFAULT_DIAGNOSTIC_RUNS_PER_MINUTE;
private List<Class<?>> searchableEntityClasses;
private List<SearchableTableConfig> searchableTables;
private transient IndexEventPublisher indexEventPublisher;
private transient QPermissionRules adminPermissionRules = new QPermissionRules().withLevel(PermissionLevel.HAS_ACCESS_PERMISSION).withPermissionBaseName(DEFAULT_ADMIN_PERMISSION_BASE_NAME);
private transient QPermissionRules tablePermissionRules = new QPermissionRules().withLevel(PermissionLevel.READ_WRITE_PERMISSIONS);
private transient QPermissionRules debugPermissionRules = new QPermissionRules().withLevel(PermissionLevel.HAS_ACCESS_PERMISSION).withPermissionBaseName(DEFAULT_DEBUG_PERMISSION_BASE_NAME);
private transient MetaDataCustomizerInterface<QTableMetaData> tableMetaDataCustomizer;
private transient QuickSearchRuntime runtime;
@@ -414,6 +425,13 @@ public class QuickSearchQBitConfig implements QBitConfig
requirePositive(maxFieldLength, "maxFieldLength", errors);
requirePositive(runHistoryRetentionDays, "runHistoryRetentionDays", errors);
requirePositive(fullReindexStaleMinutes, "fullReindexStaleMinutes", errors);
requirePositive(validationSampleSize, "validationSampleSize", errors);
requirePositive(diagnosticRunsPerMinute, "diagnosticRunsPerMinute", errors);
if(validationSampleSize != null && validationSampleSize > MAX_VALIDATION_SAMPLE_SIZE)
{
errors.add("validationSampleSize must be at most " + MAX_VALIDATION_SAMPLE_SIZE + " for QuickSearchQBit");
}
if(basepullOverlapSeconds != null && basepullOverlapSeconds < 0)
{
@@ -455,35 +473,53 @@ public class QuickSearchQBitConfig implements QBitConfig
}
}
if(StringUtils.hasContent(reconcileCronExpression))
validateCron("reconcile", reconcileCronExpression, reconcileCronTimeZoneId, scheduler, errors);
validateCron("validation", validationCronExpression, validationCronTimeZoneId, scheduler, errors);
if(StringUtils.hasContent(validationCronExpression) && !Boolean.TRUE.equals(enableDiagnosticTools))
{
errors.add("validationCronExpression requires enableDiagnosticTools");
}
}
/*******************************************************************************
** A cron schedule (prefix "reconcile" or "validation"): needs schedulerName
** on a scheduler that supports cron, a valid Quartz expression and a
** recognized time zone ID.
*******************************************************************************/
private void validateCron(String prefix, String cronExpression, String cronTimeZoneId, QSchedulerMetaData scheduler, List<String> errors)
{
if(StringUtils.hasContent(cronExpression))
{
if(!StringUtils.hasContent(schedulerName))
{
errors.add("reconcileCronExpression requires schedulerName");
errors.add(prefix + "CronExpression requires schedulerName");
}
else if(scheduler != null && !scheduler.supportsCronSchedules())
{
errors.add("reconcileCronExpression requires a scheduler that supports cron schedules, such as a QuartzSchedulerMetaData; scheduler [" + schedulerName + "] is of type " + scheduler.getType());
errors.add(prefix + "CronExpression requires a scheduler that supports cron schedules, such as a QuartzSchedulerMetaData; scheduler [" + schedulerName + "] is of type " + scheduler.getType());
}
try
{
CronExpression.validateExpression(reconcileCronExpression);
CronExpression.validateExpression(cronExpression);
}
catch(ParseException e)
{
errors.add("reconcileCronExpression [" + reconcileCronExpression + "] is not a valid Quartz cron expression: " + e.getMessage());
errors.add(prefix + "CronExpression [" + cronExpression + "] is not a valid Quartz cron expression: " + e.getMessage());
}
if(!StringUtils.hasContent(reconcileCronTimeZoneId))
if(!StringUtils.hasContent(cronTimeZoneId))
{
errors.add("reconcileCronExpression requires reconcileCronTimeZoneId (a time zone ID such as UTC or America/Chicago)");
errors.add(prefix + "CronExpression requires " + prefix + "CronTimeZoneId (a time zone ID such as UTC or America/Chicago)");
}
}
if(StringUtils.hasContent(reconcileCronTimeZoneId) && !Arrays.asList(TimeZone.getAvailableIDs()).contains(reconcileCronTimeZoneId))
if(StringUtils.hasContent(cronTimeZoneId) && !Arrays.asList(TimeZone.getAvailableIDs()).contains(cronTimeZoneId))
{
errors.add("reconcileCronTimeZoneId [" + reconcileCronTimeZoneId + "] is not a recognized time zone ID");
errors.add(prefix + "CronTimeZoneId [" + cronTimeZoneId + "] is not a recognized time zone ID");
}
}
@@ -2229,6 +2265,229 @@ public class QuickSearchQBitConfig implements QBitConfig
/*******************************************************************************
** Getter for enableDiagnosticTools: add the admin diagnostic tools (search playground, index validation, analyzer tester, diagnostic event and validation run tables, diagnostics widget); default true
*******************************************************************************/
public Boolean getEnableDiagnosticTools()
{
return (this.enableDiagnosticTools);
}
/*******************************************************************************
** Setter for enableDiagnosticTools
*******************************************************************************/
public void setEnableDiagnosticTools(Boolean enableDiagnosticTools)
{
this.enableDiagnosticTools = enableDiagnosticTools;
}
/*******************************************************************************
** Fluent setter for enableDiagnosticTools
*******************************************************************************/
public QuickSearchQBitConfig withEnableDiagnosticTools(Boolean enableDiagnosticTools)
{
this.enableDiagnosticTools = enableDiagnosticTools;
return (this);
}
/*******************************************************************************
** Getter for enableRecordDiagnosticActions: with enableDiagnosticTools, also add the per-table record actions (inspect search document, reindex records) to every indexed table; default true
*******************************************************************************/
public Boolean getEnableRecordDiagnosticActions()
{
return (this.enableRecordDiagnosticActions);
}
/*******************************************************************************
** Setter for enableRecordDiagnosticActions
*******************************************************************************/
public void setEnableRecordDiagnosticActions(Boolean enableRecordDiagnosticActions)
{
this.enableRecordDiagnosticActions = enableRecordDiagnosticActions;
}
/*******************************************************************************
** Fluent setter for enableRecordDiagnosticActions
*******************************************************************************/
public QuickSearchQBitConfig withEnableRecordDiagnosticActions(Boolean enableRecordDiagnosticActions)
{
this.enableRecordDiagnosticActions = enableRecordDiagnosticActions;
return (this);
}
/*******************************************************************************
** Getter for validationCronExpression: cron schedule for the index validation process (needs schedulerName); none by default
*******************************************************************************/
public String getValidationCronExpression()
{
return (this.validationCronExpression);
}
/*******************************************************************************
** Setter for validationCronExpression
*******************************************************************************/
public void setValidationCronExpression(String validationCronExpression)
{
this.validationCronExpression = validationCronExpression;
}
/*******************************************************************************
** Fluent setter for validationCronExpression
*******************************************************************************/
public QuickSearchQBitConfig withValidationCronExpression(String validationCronExpression)
{
this.validationCronExpression = validationCronExpression;
return (this);
}
/*******************************************************************************
** Getter for validationCronTimeZoneId: time zone for validationCronExpression
*******************************************************************************/
public String getValidationCronTimeZoneId()
{
return (this.validationCronTimeZoneId);
}
/*******************************************************************************
** Setter for validationCronTimeZoneId
*******************************************************************************/
public void setValidationCronTimeZoneId(String validationCronTimeZoneId)
{
this.validationCronTimeZoneId = validationCronTimeZoneId;
}
/*******************************************************************************
** Fluent setter for validationCronTimeZoneId
*******************************************************************************/
public QuickSearchQBitConfig withValidationCronTimeZoneId(String validationCronTimeZoneId)
{
this.validationCronTimeZoneId = validationCronTimeZoneId;
return (this);
}
/*******************************************************************************
** Getter for validationSampleSize: records sampled per table by index validation (default 50, at most 1000)
*******************************************************************************/
public Integer getValidationSampleSize()
{
return (this.validationSampleSize);
}
/*******************************************************************************
** Setter for validationSampleSize
*******************************************************************************/
public void setValidationSampleSize(Integer validationSampleSize)
{
this.validationSampleSize = validationSampleSize;
}
/*******************************************************************************
** Fluent setter for validationSampleSize
*******************************************************************************/
public QuickSearchQBitConfig withValidationSampleSize(Integer validationSampleSize)
{
this.validationSampleSize = validationSampleSize;
return (this);
}
/*******************************************************************************
** Getter for diagnosticRunsPerMinute: per-user limit on diagnostic tool runs per minute (default 30)
*******************************************************************************/
public Integer getDiagnosticRunsPerMinute()
{
return (this.diagnosticRunsPerMinute);
}
/*******************************************************************************
** Setter for diagnosticRunsPerMinute
*******************************************************************************/
public void setDiagnosticRunsPerMinute(Integer diagnosticRunsPerMinute)
{
this.diagnosticRunsPerMinute = diagnosticRunsPerMinute;
}
/*******************************************************************************
** Fluent setter for diagnosticRunsPerMinute
*******************************************************************************/
public QuickSearchQBitConfig withDiagnosticRunsPerMinute(Integer diagnosticRunsPerMinute)
{
this.diagnosticRunsPerMinute = diagnosticRunsPerMinute;
return (this);
}
/*******************************************************************************
** Getter for debugPermissionRules: permission rules for the read-only diagnostic tools and the diagnostics widget (default: quickSearchDebug.hasAccess)
*******************************************************************************/
public QPermissionRules getDebugPermissionRules()
{
return (this.debugPermissionRules);
}
/*******************************************************************************
** Setter for debugPermissionRules
*******************************************************************************/
public void setDebugPermissionRules(QPermissionRules debugPermissionRules)
{
this.debugPermissionRules = debugPermissionRules;
}
/*******************************************************************************
** Fluent setter for debugPermissionRules
*******************************************************************************/
public QuickSearchQBitConfig withDebugPermissionRules(QPermissionRules debugPermissionRules)
{
this.debugPermissionRules = debugPermissionRules;
return (this);
}
/*******************************************************************************
** Getter for runtime: live state once produced (client, publisher, discovered tables)
*******************************************************************************/
src/main/java/com/kingsrook/qbits/quicksearch/QuickSearchQBitProducer.java
+38
View File
@@ -32,6 +32,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaDataProducer;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
@@ -42,6 +43,7 @@ import com.kingsrook.qbits.quicksearch.annotations.QuickSearchField;
import com.kingsrook.qbits.quicksearch.annotations.QuickSearchable;
import com.kingsrook.qbits.quicksearch.listeners.QuickSearchRecordChangeListener;
import com.kingsrook.qbits.quicksearch.metadata.QuickSearchAdminAppMetaDataProducer;
import com.kingsrook.qbits.quicksearch.metadata.QuickSearchDiagnosticsProcessMetaDataHelper;
import com.kingsrook.qbits.quicksearch.metadata.QuickSearchProcessMetaDataHelper;
import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
@@ -260,6 +262,8 @@ public class QuickSearchQBitProducer implements QBitMetaDataProducer<QuickSearch
qInstance.withRuntimeService(new QCodeReference(QuickSearchRuntimeService.class));
addRecordDiagnosticActions(output, qInstance, discoveredTables);
if(Boolean.TRUE.equals(qBitConfig.getServeCoreRecordSearch()))
{
registerRecordSearchProvider(qInstance);
@@ -282,6 +286,40 @@ public class QuickSearchQBitProducer implements QBitMetaDataProducer<QuickSearch
/*******************************************************************************
** Give every indexed table in the instance the Inspect Search Document and
** Reindex in Search record actions (when enableDiagnosticTools and
** enableRecordDiagnosticActions are on). A process the host already
** defined with the same name is kept.
*******************************************************************************/
void addRecordDiagnosticActions(MetaDataProducerMultiOutput output, QInstance qInstance, List<QuickSearchableTableConfig> tableConfigs)
{
if(!Boolean.TRUE.equals(qBitConfig.getEnableDiagnosticTools()) || !Boolean.TRUE.equals(qBitConfig.getEnableRecordDiagnosticActions()))
{
return;
}
for(QuickSearchableTableConfig tableConfig : tableConfigs)
{
if(qInstance.getTable(tableConfig.getTableName()) == null)
{
continue;
}
for(QProcessMetaData process : List.of(
QuickSearchDiagnosticsProcessMetaDataHelper.buildInspectProcess(qBitConfig, tableConfig.getTableName()),
QuickSearchDiagnosticsProcessMetaDataHelper.buildReindexRecordsProcess(qBitConfig, tableConfig.getTableName())))
{
if(qInstance.getProcess(process.getName()) == null && output.get(QProcessMetaData.class, process.getName()) == null)
{
process.setSourceQBitName(getQBitMetaData().getName());
output.add(process);
}
}
}
}
/*******************************************************************************
** Register QuickSearchRecordSearchProvider as the instance's core record
** search provider. An instance holds one provider; a different one the host
src/main/java/com/kingsrook/qbits/quicksearch/QuickSearchRuntime.java
+158
View File
@@ -17,12 +17,15 @@
package com.kingsrook.qbits.quicksearch;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicLong;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
@@ -34,6 +37,8 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticEventRecorder;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsRateLimiter;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchOpenSearchClient;
import com.kingsrook.qbits.quicksearch.publisher.IndexEventPublisher;
import com.kingsrook.qbits.quicksearch.publisher.SynchronousIndexEventPublisher;
@@ -72,6 +77,15 @@ public class QuickSearchRuntime
private final Map<String, CachedFlag> enabledCache = new ConcurrentHashMap<>();
private volatile DiagnosticEventRecorder diagnosticEventRecorder;
private final DiagnosticsRateLimiter diagnosticsRateLimiter = new DiagnosticsRateLimiter();
private final AtomicBoolean validationRunning = new AtomicBoolean(false);
private final AtomicLong recordSearchFailures = new AtomicLong();
private final AtomicLong backoffDeclinedClaims = new AtomicLong();
private final Instant startedAt = Instant.now();
private volatile Instant lastRecordSearchFailureTime;
private volatile String lastRecordSearchFailureMessage;
/*******************************************************************************
@@ -312,8 +326,147 @@ public class QuickSearchRuntime
** timeout on every search while OpenSearch is down.
*******************************************************************************/
public void markRecordSearchFailed()
{
markRecordSearchFailed(null);
}
/*******************************************************************************
** As markRecordSearchFailed(), also counting the failure and keeping its
** message and time for the diagnostics.
*******************************************************************************/
public void markRecordSearchFailed(String message)
{
recordSearchBackoffUntilMillis = System.currentTimeMillis() + RECORD_SEARCH_BACKOFF_MILLIS;
recordSearchFailures.incrementAndGet();
lastRecordSearchFailureTime = Instant.now();
lastRecordSearchFailureMessage = message;
}
/*******************************************************************************
** Milliseconds left in the current record-search backoff (0 when none).
*******************************************************************************/
public long getRecordSearchBackoffRemainingMillis()
{
return (Math.max(0L, recordSearchBackoffUntilMillis - System.currentTimeMillis()));
}
/*******************************************************************************
** Count a table the provider declined because of a backoff (core searched
** it with its own search instead).
*******************************************************************************/
public void countBackoffDeclinedClaim()
{
backoffDeclinedClaims.incrementAndGet();
}
/*******************************************************************************
** Record searches through OpenSearch that failed since this runtime started.
*******************************************************************************/
public long getRecordSearchFailureCount()
{
return (recordSearchFailures.get());
}
/*******************************************************************************
** Table searches core ran itself because the provider was backing off,
** since this runtime started.
*******************************************************************************/
public long getBackoffDeclinedClaimCount()
{
return (backoffDeclinedClaims.get());
}
/*******************************************************************************
** When the last record search through OpenSearch failed (null when none).
*******************************************************************************/
public Instant getLastRecordSearchFailureTime()
{
return (lastRecordSearchFailureTime);
}
/*******************************************************************************
** The last record-search failure's message (null when none).
*******************************************************************************/
public String getLastRecordSearchFailureMessage()
{
return (lastRecordSearchFailureMessage);
}
/*******************************************************************************
** When this runtime was created.
*******************************************************************************/
public Instant getStartedAt()
{
return (startedAt);
}
/*******************************************************************************
** The diagnostic event recorder, built on first use.
*******************************************************************************/
public DiagnosticEventRecorder getDiagnosticEventRecorder()
{
DiagnosticEventRecorder existing = diagnosticEventRecorder;
if(existing != null)
{
return (existing);
}
synchronized(this)
{
if(diagnosticEventRecorder == null)
{
diagnosticEventRecorder = new DiagnosticEventRecorder(config);
}
return (diagnosticEventRecorder);
}
}
/*******************************************************************************
** The per-user rate limiter of the diagnostic tools.
*******************************************************************************/
public DiagnosticsRateLimiter getDiagnosticsRateLimiter()
{
return (diagnosticsRateLimiter);
}
/*******************************************************************************
** Claim the single validation slot of this JVM; false when a validation is
** already running. Release with endValidation().
*******************************************************************************/
public boolean beginValidation()
{
return (validationRunning.compareAndSet(false, true));
}
/*******************************************************************************
** Release the validation slot.
*******************************************************************************/
public void endValidation()
{
validationRunning.set(false);
}
@@ -437,6 +590,11 @@ public class QuickSearchRuntime
}
}
if(diagnosticEventRecorder != null)
{
diagnosticEventRecorder.close();
}
if(client != null)
{
client.close();
src/main/java/com/kingsrook/qbits/quicksearch/actions/QuickSearchAction.java
+23 -1
View File
@@ -46,6 +46,8 @@ import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitContext;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.QuickSearchableTableConfig;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsSupport;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
import com.kingsrook.qbits.quicksearch.opensearch.OpenSearchDocument;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchOpenSearchClient;
import com.kingsrook.qbits.quicksearch.processes.IndexingUtils;
@@ -453,14 +455,34 @@ public class QuickSearchAction
*******************************************************************************/
private static SearchResponse<OpenSearchDocument> runSearch(QuickSearchOpenSearchClient client, String term, List<String> tables, int fetchSize, int offset, List<QuickSearchableTableConfig> tableConfigs, String preference) throws QException
{
long start = System.currentTimeMillis();
try
{
return (client.search(term, tables, fetchSize, offset, tableConfigs, preference));
}
catch(OpenSearchException e)
{
throw (new QException("Quick search failed: " + (e.error() != null && e.error().reason() != null ? e.error().reason() : e.getMessage()), e));
QException wrapped = new QException("Quick search failed: " + (e.error() != null && e.error().reason() != null ? e.error().reason() : e.getMessage()), e);
recordFailure(tables, term, start, wrapped);
throw (wrapped);
}
catch(QException e)
{
recordFailure(tables, term, start, e);
throw (e);
}
}
/*******************************************************************************
** Record a failed search as a diagnostic event (the term's length only,
** never the term).
*******************************************************************************/
private static void recordFailure(List<String> tables, String term, long start, Exception e)
{
DiagnosticsSupport.recordSearchFailure(QuickSearchRuntime.get(), QuickSearchDiagnosticEvent.SOURCE_QUICK_SEARCH_ACTION, tables, term,
System.currentTimeMillis() - start, e, "term length " + (term == null ? 0 : term.length()));
}
src/main/java/com/kingsrook/qbits/quicksearch/actions/QuickSearchRecordSearchProvider.java
+18 -2
View File
@@ -32,6 +32,8 @@ import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsSupport;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
import com.kingsrook.qbits.quicksearch.processes.IndexingUtils;
import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
@@ -83,11 +85,17 @@ public class QuickSearchRecordSearchProvider implements RecordSearchProviderInte
return (false);
}
if(runtime.getTableConfig(table.getName()) == null || runtime.isRecordSearchBackingOff())
if(runtime.getTableConfig(table.getName()) == null)
{
return (false);
}
if(runtime.isRecordSearchBackingOff())
{
runtime.countBackoffDeclinedClaim();
return (false);
}
return (runtime.isTableEnabled(table.getName()));
}
@@ -127,13 +135,21 @@ public class QuickSearchRecordSearchProvider implements RecordSearchProviderInte
int timeoutMillis = config.getRecordSearchTimeoutMillis() == null ? QuickSearchQBitConfig.DEFAULT_RECORD_SEARCH_TIMEOUT_MILLIS : config.getRecordSearchTimeoutMillis();
Map<String, List<String>> idsByTable;
long start = System.currentTimeMillis();
try
{
idsByTable = runtime.getClient().searchRecordIdsPerTable(term, tableNames, idsPerTable, runtime.getDiscoveredTables(), timeoutMillis);
}
catch(QException | RuntimeException e)
{
runtime.markRecordSearchFailed();
runtime.markRecordSearchFailed(e.getMessage());
//////////////////////////////////////////////////////////////////////
// the user's term is not recorded (it may hold personal data); its //
// length is, so a length-related failure is still visible //
//////////////////////////////////////////////////////////////////////
DiagnosticsSupport.recordSearchFailure(runtime, QuickSearchDiagnosticEvent.SOURCE_CORE_RECORD_SEARCH, tableNames, term, System.currentTimeMillis() - start, e,
"term length " + term.length() + ", " + idsPerTable + " ids per table, timeout " + timeoutMillis + " ms; core searched these tables itself");
LOG.info("Quick Search record search failed; core searches these tables itself, and Quick Search claims none for a while", logPair("tables", tableNames),
logPair("backoffMillis", QuickSearchRuntime.RECORD_SEARCH_BACKOFF_MILLIS), logPair("error", e.getMessage()));
throw (e instanceof QException qe ? qe : new QException("Quick Search record search failed: " + e.getMessage(), e));
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/AnalyzerTester.java
+134
View File
@@ -0,0 +1,134 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.utils.StringUtils;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml.Level;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations.AnalyzedToken;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchOpenSearchClient;
/*******************************************************************************
** The analyzer tester: run _analyze on the live index with its two
** analyzers. The text is analyzed as it would be indexed (standard
** tokenizer, lowercase, edge n-grams of 2 to 20 characters) and as a query
** (standard tokenizer, lowercase); with a query, each query token is marked
** found or not among the text's indexed tokens, which is how matching works
** (every query token must be found). Read-only.
*******************************************************************************/
public class AnalyzerTester
{
/*******************************************************************************
** The tokens of the text (both analyzers) and of the query.
*******************************************************************************/
public record Result(String text, String query, List<AnalyzedToken> indexTokens, List<AnalyzedToken> textAsQueryTokens, List<AnalyzedToken> queryTokens)
{
}
/*******************************************************************************
** Analyze text (and an optional query) with the index's analyzers.
*******************************************************************************/
public Result analyze(QuickSearchRuntime runtime, String text, String query) throws QException
{
QuickSearchDiagnosticsOperations ops = new QuickSearchDiagnosticsOperations(runtime.getClient());
String safeText = text == null ? "" : text;
return (new Result(safeText, query,
ops.analyze(QuickSearchOpenSearchClient.INDEX_ANALYZER, safeText),
ops.analyze(QuickSearchOpenSearchClient.SEARCH_ANALYZER, safeText),
StringUtils.hasContent(query) ? ops.analyze(QuickSearchOpenSearchClient.SEARCH_ANALYZER, query) : null));
}
/*******************************************************************************
** Render a result as HTML.
*******************************************************************************/
public static String render(Result result)
{
DiagnosticsHtml html = new DiagnosticsHtml().open();
html.heading("Analyzer tokens");
if(result.text().length() > QuickSearchDiagnosticsOperations.MAX_ANALYZE_TEXT_LENGTH)
{
html.status(Level.WARN, "Only the first " + QuickSearchDiagnosticsOperations.MAX_ANALYZE_TEXT_LENGTH + " characters were analyzed.");
}
Set<String> indexed = new LinkedHashSet<>();
result.indexTokens().forEach(t -> indexed.add(t.token()));
if(result.queryTokens() != null)
{
html.subheading("Does the query match this text?");
List<DiagnosticsHtml.Check> checks = new ArrayList<>();
boolean all = !result.queryTokens().isEmpty();
for(AnalyzedToken token : result.queryTokens())
{
boolean found = indexed.contains(token.token());
all &= found;
String why = found ? "found among the indexed tokens"
: token.token().length() < 2 ? "one character: never indexed (n-grams start at 2)"
: token.token().length() > 20 ? "longer than 20 characters: never indexed (n-grams stop at 20)"
: "no word in the text starts with it";
checks.add(new DiagnosticsHtml.Check("\"" + token.token() + "\"", found ? Level.OK : Level.FAIL, why));
}
html.status(all ? Level.OK : Level.FAIL, all ? "Every query token is found: the searchable-text clause matches."
: "At least one query token is missing: with AND semantics, a document with only this text does not match.");
html.checks(checks);
}
html.subheading("As indexed (" + QuickSearchOpenSearchClient.INDEX_ANALYZER + "): " + result.indexTokens().size() + " token(s)");
html.paragraph(join(result.indexTokens()));
html.subheading("As a query (" + QuickSearchOpenSearchClient.SEARCH_ANALYZER + "): " + result.textAsQueryTokens().size() + " token(s)");
html.paragraph(join(result.textAsQueryTokens()));
if(result.queryTokens() != null)
{
html.subheading("Query tokens: " + result.queryTokens().size());
html.paragraph(join(result.queryTokens()));
}
return (html.close().toString());
}
/*******************************************************************************
** Tokens as "token (position)" separated by commas.
*******************************************************************************/
static String join(List<AnalyzedToken> tokens)
{
if(tokens == null || tokens.isEmpty())
{
return ("(none)");
}
List<String> parts = new ArrayList<>();
for(AnalyzedToken token : tokens)
{
parts.add(token.token() + " @" + token.position());
}
return (String.join(", ", parts));
}
}
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/DiagnosticEventRecorder.java
+259
View File
@@ -0,0 +1,259 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.net.InetAddress;
import java.time.Instant;
import java.util.concurrent.ArrayBlockingQueue;
import java.util.concurrent.ThreadPoolExecutor;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicLong;
import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.logging.QLogger;
import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.session.QSession;
import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
/*******************************************************************************
** Writes quickSearchDiagnosticEvent rows: failed searches, diagnostic tool
** runs (the audit trail) and refused runs.
** Best effort and off the caller's thread: events are queued (at most
** QUEUE_CAPACITY) and inserted by one daemon thread as the system user, so
** a slow or failing database never slows or fails a search. At most
** MAX_EVENTS_PER_MINUTE events are written per JVM per minute; the rest are
** counted as dropped (see getDroppedCount), so a search outage cannot flood
** the table. A no-op when the diagnostic tables are not configured.
*******************************************************************************/
public class DiagnosticEventRecorder implements AutoCloseable
{
private static final QLogger LOG = QLogger.getLogger(DiagnosticEventRecorder.class);
public static final int MAX_EVENTS_PER_MINUTE = 120;
public static final int QUEUE_CAPACITY = 500;
private final QuickSearchQBitConfig config;
private final ThreadPoolExecutor executor;
private final AtomicLong droppedCount = new AtomicLong();
private final AtomicLong failedCount = new AtomicLong();
private final String hostName;
private long windowStartMillis = 0L;
private int windowCount = 0;
/*******************************************************************************
** Constructor
*******************************************************************************/
public DiagnosticEventRecorder(QuickSearchQBitConfig config)
{
this.config = config;
this.hostName = resolveHostName();
this.executor = new ThreadPoolExecutor(1, 1, 0L, TimeUnit.MILLISECONDS, new ArrayBlockingQueue<>(QUEUE_CAPACITY), runnable ->
{
Thread thread = new Thread(runnable, "quick-search-diagnostic-events");
thread.setDaemon(true);
return (thread);
}, (runnable, pool) -> droppedCount.incrementAndGet());
}
/*******************************************************************************
** Queue an event for insert. Fills in host name and create date, bounds
** string lengths, and uses the current session's user when none is set.
*******************************************************************************/
public void record(QuickSearchDiagnosticEvent event)
{
QInstance qInstance = QContext.getQInstance();
String tableName = config.applyPrefix(QuickSearchDiagnosticEvent.TABLE_NAME);
if(event == null || qInstance == null || !Boolean.TRUE.equals(config.getEnableDiagnosticTools()) || qInstance.getTable(tableName) == null)
{
return;
}
if(!admit())
{
droppedCount.incrementAndGet();
return;
}
if(event.getUserName() == null)
{
event.setUserName(DiagnosticsSupport.currentUserName());
}
event.withHostName(truncate(hostName, 100))
.withCreateDate(Instant.now())
.withSource(truncate(event.getSource(), 50))
.withUserName(truncate(event.getUserName(), 250))
.withTableNames(truncate(event.getTableNames(), 1000))
.withSearchTerm(truncate(event.getSearchTerm(), 100))
.withErrorClass(truncate(event.getErrorClass(), 250))
.withErrorMessage(truncate(event.getErrorMessage(), 4000))
.withDetail(truncate(event.getDetail(), 4000));
executor.execute(() -> insert(qInstance, tableName, event));
}
/*******************************************************************************
** Insert one event as the system user. Failures are logged and counted.
*******************************************************************************/
private void insert(QInstance qInstance, String tableName, QuickSearchDiagnosticEvent event)
{
QSession session = new QSystemUserSession();
try
{
QContext.init(qInstance, session);
new InsertAction().execute(new InsertInput(tableName).withRecordEntity(event));
}
catch(Exception e)
{
failedCount.incrementAndGet();
LOG.warn("Could not record a Quick Search diagnostic event", e, logPair("eventType", event.getEventType()), logPair("source", event.getSource()));
}
finally
{
QContext.clear();
}
}
/*******************************************************************************
** Whether one more event fits in the current minute's budget.
*******************************************************************************/
private synchronized boolean admit()
{
long now = System.currentTimeMillis();
if(now - windowStartMillis >= 60_000L)
{
windowStartMillis = now;
windowCount = 0;
}
if(windowCount >= MAX_EVENTS_PER_MINUTE)
{
return (false);
}
windowCount++;
return (true);
}
/*******************************************************************************
** Wait (up to timeoutMillis) until every queued event has been written.
** For tests and orderly shutdown.
*******************************************************************************/
public void flush(long timeoutMillis)
{
try
{
executor.submit(() ->
{
}).get(timeoutMillis, TimeUnit.MILLISECONDS);
}
catch(Exception e)
{
LOG.debug("Diagnostic event flush did not complete", e);
}
}
/*******************************************************************************
** Events not written because the queue or the per-minute budget was full.
*******************************************************************************/
public long getDroppedCount()
{
return (droppedCount.get());
}
/*******************************************************************************
** Events whose insert failed.
*******************************************************************************/
public long getFailedCount()
{
return (failedCount.get());
}
/*******************************************************************************
** Stop the writer after the queued events (up to 2 seconds).
*******************************************************************************/
@Override
public void close()
{
executor.shutdown();
try
{
if(!executor.awaitTermination(2, TimeUnit.SECONDS))
{
executor.shutdownNow();
}
}
catch(InterruptedException e)
{
executor.shutdownNow();
Thread.currentThread().interrupt();
}
}
/*******************************************************************************
** This JVM's host name (the pod name in Kubernetes).
*******************************************************************************/
static String resolveHostName()
{
String fromEnv = System.getenv("HOSTNAME");
if(fromEnv != null && !fromEnv.isBlank())
{
return (fromEnv);
}
try
{
return (InetAddress.getLocalHost().getHostName());
}
catch(Exception e)
{
return ("unknown");
}
}
/*******************************************************************************
*******************************************************************************/
static String truncate(String value, int max)
{
return (value == null || value.length() <= max ? value : value.substring(0, max));
}
}
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/DiagnosticRecordReads.java
+192
View File
@@ -0,0 +1,192 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collection;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import com.kingsrook.qqq.backend.core.actions.tables.CountAction;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
import com.kingsrook.qqq.backend.core.utils.ValueUtils;
/*******************************************************************************
** Source-table reads for the diagnostics, in the current session (so table
** permissions and record security locks apply, as for any query the user
** runs). Records are read the way indexing reads them: display values
** generated and possible values translated, so a document built from them
** is exactly the document indexing would write.
*******************************************************************************/
public final class DiagnosticRecordReads
{
public static final int MAX_IDS_PER_QUERY = 1_000;
/*******************************************************************************
** Utility class - no instances.
*******************************************************************************/
private DiagnosticRecordReads()
{
}
/*******************************************************************************
** Records of a table by primary key (as strings), keyed by primary key
** string, read as indexing reads them. Ids that do not exist or that the
** session cannot read are absent. Ids that do not convert to the key's
** type are skipped.
*******************************************************************************/
public static Map<String, QRecord> loadForIndexing(String tableName, Collection<String> recordIds) throws QException
{
QTableMetaData table = requireTable(tableName);
String pk = table.getPrimaryKeyField();
Map<String, QRecord> records = new LinkedHashMap<>();
List<Serializable> ids = typedIds(table, recordIds);
for(int start = 0; start < ids.size(); start += MAX_IDS_PER_QUERY)
{
QueryInput queryInput = new QueryInput();
queryInput.setTableName(tableName);
queryInput.setFilter(new QQueryFilter(new QFilterCriteria(pk, QCriteriaOperator.IN, ids.subList(start, Math.min(ids.size(), start + MAX_IDS_PER_QUERY)))));
queryInput.setShouldGenerateDisplayValues(true);
queryInput.setShouldTranslatePossibleValues(true);
for(QRecord record : CollectionUtils.nonNullList(new QueryAction().execute(queryInput).getRecords()))
{
records.put(record.getValueString(pk), record);
}
}
return (records);
}
/*******************************************************************************
** Up to limit records of a table ordered by primary key (ascending or
** descending), read as indexing reads them.
*******************************************************************************/
public static List<QRecord> loadEdge(String tableName, boolean ascending, int limit) throws QException
{
QTableMetaData table = requireTable(tableName);
QueryInput queryInput = new QueryInput();
queryInput.setTableName(tableName);
queryInput.setFilter(new QQueryFilter().withOrderBy(new QFilterOrderBy(table.getPrimaryKeyField(), ascending)).withLimit(limit));
queryInput.setShouldGenerateDisplayValues(true);
queryInput.setShouldTranslatePossibleValues(true);
return (CollectionUtils.nonNullList(new QueryAction().execute(queryInput).getRecords()));
}
/*******************************************************************************
** The primary keys (as strings) among recordIds that exist and that the
** session can read.
*******************************************************************************/
public static List<String> existingIds(String tableName, Collection<String> recordIds) throws QException
{
QTableMetaData table = requireTable(tableName);
String pk = table.getPrimaryKeyField();
List<String> found = new ArrayList<>();
List<Serializable> ids = typedIds(table, recordIds);
for(int start = 0; start < ids.size(); start += MAX_IDS_PER_QUERY)
{
QueryInput queryInput = new QueryInput();
queryInput.setTableName(tableName);
queryInput.setFilter(new QQueryFilter(new QFilterCriteria(pk, QCriteriaOperator.IN, ids.subList(start, Math.min(ids.size(), start + MAX_IDS_PER_QUERY)))));
for(QRecord record : CollectionUtils.nonNullList(new QueryAction().execute(queryInput).getRecords()))
{
found.add(record.getValueString(pk));
}
}
return (found);
}
/*******************************************************************************
** Row count of a table in the current session.
*******************************************************************************/
public static Integer count(String tableName) throws QException
{
CountInput countInput = new CountInput();
countInput.setTableName(tableName);
return (new CountAction().execute(countInput).getCount());
}
/*******************************************************************************
** Ids converted to the primary key's type; ids that do not convert are
** skipped (they cannot exist).
*******************************************************************************/
static List<Serializable> typedIds(QTableMetaData table, Collection<String> recordIds)
{
QFieldMetaData pkField = table.getField(table.getPrimaryKeyField());
List<Serializable> ids = new ArrayList<>();
for(String recordId : CollectionUtils.nonNullCollection(recordIds))
{
try
{
Serializable id = ValueUtils.getValueAsFieldType(pkField.getType(), recordId);
if(id != null && !ids.contains(id))
{
ids.add(id);
}
}
catch(Exception e)
{
//////////////////////////////////////////////////////////
// e.g. "abc" for an integer key: no such record exists //
//////////////////////////////////////////////////////////
}
}
return (ids);
}
/*******************************************************************************
*******************************************************************************/
private static QTableMetaData requireTable(String tableName) throws QException
{
QTableMetaData table = QContext.getQInstance() == null ? null : QContext.getQInstance().getTable(tableName);
if(table == null)
{
throw (new QException("Table [" + tableName + "] is not in the instance"));
}
return (table);
}
}
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/DiagnosticsHtml.java
+362
View File
@@ -0,0 +1,362 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.util.List;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
/*******************************************************************************
** A small HTML builder for the diagnostic screens (process HTML blocks, the
** validation report field and the diagnostics widget). Every text value is
** escaped. Layout rules: one column of blocks capped at a readable width,
** no fixed widths, and long values (JSON, ids, text) wrap instead of
** scrolling, so a screen reads from 360px to 3200px without an inner or
** horizontal scrollbar. Colours are mid-tone so they read in light and dark
** themes; status is always also spelled out in text.
*******************************************************************************/
public class DiagnosticsHtml
{
public static final int MAX_JSON_CHARS = 60_000;
private static final ObjectMapper PRETTY = new ObjectMapper().enable(SerializationFeature.INDENT_OUTPUT);
private static final String WRAP = "overflow-wrap:anywhere;word-break:break-word;";
private final StringBuilder html = new StringBuilder();
/*******************************************************************************
** Severity of a check or a line, rendered as a coloured label.
*******************************************************************************/
public enum Level
{
OK("OK", "#16a34a"),
INFO("INFO", "#2563eb"),
WARN("WARN", "#d97706"),
FAIL("FAIL", "#dc2626");
private final String label;
private final String color;
/*******************************************************************************
** Constructor
*******************************************************************************/
Level(String label, String color)
{
this.label = label;
this.color = color;
}
/*******************************************************************************
** Getter for label
*******************************************************************************/
public String getLabel()
{
return (label);
}
}
/*******************************************************************************
** Escape text for HTML element content and attribute values.
*******************************************************************************/
public static String escape(Object value)
{
if(value == null)
{
return ("");
}
String text = String.valueOf(value);
StringBuilder out = new StringBuilder(text.length() + 16);
for(int i = 0; i < text.length(); i++)
{
char c = text.charAt(i);
switch(c)
{
case '<' -> out.append("&lt;");
case '>' -> out.append("&gt;");
case '&' -> out.append("&amp;");
case '"' -> out.append("&quot;");
case '\'' -> out.append("&#39;");
default -> out.append(c);
}
}
return (out.toString());
}
/*******************************************************************************
** Escape text but keep OpenSearch highlight tags (em) as mark elements.
*******************************************************************************/
public static String highlight(String fragment)
{
return (escape(fragment).replace("&lt;em&gt;", "<mark>").replace("&lt;/em&gt;", "</mark>"));
}
/*******************************************************************************
** A coloured status label.
*******************************************************************************/
public static String badge(Level level)
{
return ("<strong style=\"color:" + level.color + "\">" + level.label + "</strong>");
}
/*******************************************************************************
** Open the root block.
*******************************************************************************/
public DiagnosticsHtml open()
{
html.append("<div style=\"max-width:72rem;").append(WRAP).append("\">");
return (this);
}
/*******************************************************************************
** Close the root block.
*******************************************************************************/
public DiagnosticsHtml close()
{
html.append("</div>");
return (this);
}
/*******************************************************************************
** A section heading.
*******************************************************************************/
public DiagnosticsHtml heading(String text)
{
html.append("<h3>").append(escape(text)).append("</h3>");
return (this);
}
/*******************************************************************************
** A sub-heading.
*******************************************************************************/
public DiagnosticsHtml subheading(String text)
{
html.append("<h4>").append(escape(text)).append("</h4>");
return (this);
}
/*******************************************************************************
** A paragraph of escaped text.
*******************************************************************************/
public DiagnosticsHtml paragraph(String text)
{
html.append("<p>").append(escape(text)).append("</p>");
return (this);
}
/*******************************************************************************
** A paragraph starting with a status label.
*******************************************************************************/
public DiagnosticsHtml status(Level level, String text)
{
html.append("<p>").append(badge(level)).append(" ").append(escape(text)).append("</p>");
return (this);
}
/*******************************************************************************
** A list of checks: each line a status label and text.
*******************************************************************************/
public DiagnosticsHtml checks(List<Check> checks)
{
if(checks == null || checks.isEmpty())
{
return (this);
}
html.append("<ul>");
for(Check check : checks)
{
html.append("<li>").append(badge(check.level())).append(" <strong>").append(escape(check.name())).append("</strong>");
if(check.message() != null)
{
html.append(": ").append(escape(check.message()));
}
html.append("</li>");
}
html.append("</ul>");
return (this);
}
/*******************************************************************************
** A list of label: value lines (values escaped). Null values show as
** "none".
*******************************************************************************/
public DiagnosticsHtml facts(List<String[]> facts)
{
html.append("<ul>");
for(String[] fact : facts)
{
html.append("<li><strong>").append(escape(fact[0])).append(":</strong> ")
.append(fact.length > 1 && fact[1] != null ? escape(fact[1]) : "<em>none</em>").append("</li>");
}
html.append("</ul>");
return (this);
}
/*******************************************************************************
** A bulleted list of pre-built HTML items (callers escape their parts).
*******************************************************************************/
public DiagnosticsHtml rawList(List<String> itemsHtml)
{
if(itemsHtml == null || itemsHtml.isEmpty())
{
return (this);
}
html.append("<ul>");
for(String item : itemsHtml)
{
html.append("<li>").append(item).append("</li>");
}
html.append("</ul>");
return (this);
}
/*******************************************************************************
** A preformatted block that wraps (no horizontal scrolling).
*******************************************************************************/
public DiagnosticsHtml pre(String text)
{
html.append("<pre style=\"white-space:pre-wrap;").append(WRAP).append("\">").append(escape(text)).append("</pre>");
return (this);
}
/*******************************************************************************
** A collapsed block with a summary line and pretty-printed JSON inside.
*******************************************************************************/
public DiagnosticsHtml jsonDetails(String summary, String json)
{
html.append("<details><summary>").append(escape(summary)).append("</summary>");
pre(prettyJson(json));
html.append("</details>");
return (this);
}
/*******************************************************************************
** A collapsed block with a summary line and preformatted text inside.
*******************************************************************************/
public DiagnosticsHtml textDetails(String summary, String text)
{
html.append("<details><summary>").append(escape(summary)).append("</summary>");
pre(text);
html.append("</details>");
return (this);
}
/*******************************************************************************
** Append pre-built HTML (callers escape their parts).
*******************************************************************************/
public DiagnosticsHtml raw(String rawHtml)
{
html.append(rawHtml);
return (this);
}
/*******************************************************************************
** Pretty-print JSON (or return the text as-is when it is not JSON),
** truncated to MAX_JSON_CHARS.
*******************************************************************************/
public static String prettyJson(String json)
{
if(json == null)
{
return ("");
}
String pretty;
try
{
pretty = PRETTY.writeValueAsString(PRETTY.readTree(json));
}
catch(Exception e)
{
pretty = json;
}
return (pretty.length() > MAX_JSON_CHARS ? pretty.substring(0, MAX_JSON_CHARS) + "\n... (truncated at " + MAX_JSON_CHARS + " characters)" : pretty);
}
/*******************************************************************************
** Pretty-print a JSON node.
*******************************************************************************/
public static String prettyJson(JsonNode node)
{
return (node == null ? "" : prettyJson(node.toString()));
}
/*******************************************************************************
** The built HTML.
*******************************************************************************/
@Override
public String toString()
{
return (html.toString());
}
/*******************************************************************************
** One check: name, level and message.
*******************************************************************************/
public record Check(String name, Level level, String message)
{
}
}
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/DiagnosticsRateLimiter.java
+89
View File
@@ -0,0 +1,89 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.util.ArrayDeque;
import java.util.Deque;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.function.LongSupplier;
/*******************************************************************************
** Sliding one-minute window of diagnostic tool runs per key (user and
** tool), per JVM. tryAcquire admits a run when fewer than the limit ran in
** the last 60 seconds.
*******************************************************************************/
public class DiagnosticsRateLimiter
{
private static final long WINDOW_MILLIS = 60_000L;
private final Map<String, Deque<Long>> runsByKey = new ConcurrentHashMap<>();
private final LongSupplier clock;
/*******************************************************************************
** Constructor (system clock)
*******************************************************************************/
public DiagnosticsRateLimiter()
{
this(System::currentTimeMillis);
}
/*******************************************************************************
** Constructor with a clock (tests)
*******************************************************************************/
public DiagnosticsRateLimiter(LongSupplier clock)
{
this.clock = clock;
}
/*******************************************************************************
** Admit one run for the key when fewer than perMinute ran in the last
** minute; a null or non-positive limit admits everything.
*******************************************************************************/
public boolean tryAcquire(String key, Integer perMinute)
{
if(perMinute == null || perMinute <= 0)
{
return (true);
}
long now = clock.getAsLong();
Deque<Long> runs = runsByKey.computeIfAbsent(key, k -> new ArrayDeque<>());
synchronized(runs)
{
while(!runs.isEmpty() && now - runs.peekFirst() >= WINDOW_MILLIS)
{
runs.pollFirst();
}
if(runs.size() >= perMinute)
{
return (false);
}
runs.addLast(now);
return (true);
}
}
}
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/DiagnosticsSupport.java
+222
View File
@@ -0,0 +1,222 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.util.Collection;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
import com.kingsrook.qqq.backend.core.logging.QLogger;
import com.kingsrook.qqq.backend.core.model.session.QSession;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
/*******************************************************************************
** Shared pieces of the diagnostic tools: tool names, the current user, the
** per-user rate limit, and recording tool runs and search failures as
** quickSearchDiagnosticEvent rows (the audit trail).
*******************************************************************************/
public final class DiagnosticsSupport
{
private static final QLogger LOG = QLogger.getLogger(DiagnosticsSupport.class);
public static final String TOOL_PLAYGROUND = "SEARCH_PLAYGROUND";
public static final String TOOL_INSPECT_RECORD = "INSPECT_RECORD";
public static final String TOOL_REINDEX_RECORDS = "REINDEX_RECORDS";
public static final String TOOL_VALIDATE_INDEX = "VALIDATE_INDEX";
public static final String TOOL_ANALYZE_TEXT = "ANALYZE_TEXT";
/*******************************************************************************
** Utility class - no instances.
*******************************************************************************/
private DiagnosticsSupport()
{
}
/*******************************************************************************
** The session's user id reference (else full name), or null.
*******************************************************************************/
public static String currentUserName()
{
QSession session = QContext.getQSession();
if(session == null || session.getUser() == null)
{
return (null);
}
return (session.getUser().getIdReference() != null ? session.getUser().getIdReference() : session.getUser().getFullName());
}
/*******************************************************************************
** The runtime of the Quick Search QBit, or a user-facing error saying the
** tool is unavailable.
*******************************************************************************/
public static QuickSearchRuntime requireRuntime() throws QUserFacingException
{
QuickSearchRuntime runtime = QuickSearchRuntime.get();
if(runtime == null)
{
throw (new QUserFacingException("Quick Search is not configured in this application, so its diagnostic tools are unavailable."));
}
return (runtime);
}
/*******************************************************************************
** Admit one run of a tool for the current user, or refuse it (recording
** the refusal) when the user ran diagnosticRunsPerMinute tools in the last
** minute.
*******************************************************************************/
public static void checkRateLimit(QuickSearchRuntime runtime, String tool) throws QUserFacingException
{
String user = currentUserName();
if(runtime.getDiagnosticsRateLimiter().tryAcquire((user == null ? "anonymous" : user) + "|" + tool, runtime.getConfig().getDiagnosticRunsPerMinute()))
{
return;
}
runtime.getDiagnosticEventRecorder().record(new QuickSearchDiagnosticEvent()
.withEventType(QuickSearchDiagnosticEvent.TYPE_RATE_LIMITED)
.withSource(tool)
.withOutcome(QuickSearchDiagnosticEvent.OUTCOME_REFUSED));
throw (new QUserFacingException("Too many Quick Search diagnostic runs in the last minute (limit " + runtime.getConfig().getDiagnosticRunsPerMinute()
+ " per tool). Wait a minute and try again."));
}
/*******************************************************************************
** Record a tool run (audit): who ran which tool on which tables with which
** term, how long it took, and its outcome.
*******************************************************************************/
public static void recordToolRun(QuickSearchRuntime runtime, String tool, String eventType, Collection<String> tableNames, String term, long startMillis, Throwable error, String detail)
{
try
{
runtime.getDiagnosticEventRecorder().record(new QuickSearchDiagnosticEvent()
.withEventType(eventType)
.withSource(tool)
.withOutcome(error == null ? QuickSearchDiagnosticEvent.OUTCOME_OK : QuickSearchDiagnosticEvent.OUTCOME_ERROR)
.withTableNames(tableNames == null || tableNames.isEmpty() ? null : String.join(",", tableNames))
.withSearchTerm(term)
.withDurationMillis((int) Math.min(Integer.MAX_VALUE, System.currentTimeMillis() - startMillis))
.withErrorClass(error == null ? null : error.getClass().getName())
.withErrorMessage(error == null ? null : error.getMessage())
.withDetail(detail));
}
catch(Exception e)
{
LOG.debug("Could not queue a diagnostic event", e);
}
LOG.info("Quick Search diagnostic tool run", logPair("tool", tool), logPair("user", currentUserName()), logPair("tables", tableNames),
logPair("millis", System.currentTimeMillis() - startMillis), logPair("error", error == null ? null : error.getMessage()));
}
/*******************************************************************************
** Record a failed search (OpenSearch error or timeout). userTerm is the
** user's term: never stored, and redacted from the message and detail.
*******************************************************************************/
public static void recordSearchFailure(QuickSearchRuntime runtime, String source, Collection<String> tableNames, String userTerm, long durationMillis, Throwable error, String detail)
{
if(runtime == null)
{
return;
}
try
{
Throwable cause = rootCause(error);
runtime.getDiagnosticEventRecorder().record(new QuickSearchDiagnosticEvent()
.withEventType(QuickSearchDiagnosticEvent.TYPE_SEARCH_FAILED)
.withSource(source)
.withOutcome(QuickSearchDiagnosticEvent.OUTCOME_ERROR)
.withTableNames(tableNames == null || tableNames.isEmpty() ? null : String.join(",", tableNames))
.withDurationMillis((int) Math.min(Integer.MAX_VALUE, durationMillis))
.withErrorClass(cause == null ? null : cause.getClass().getName())
.withErrorMessage(redactTerm(error == null ? null : error.getMessage(), userTerm))
.withDetail(redactTerm(detail, userTerm)));
}
catch(Exception e)
{
LOG.debug("Could not queue a search failure event", e);
}
}
/*******************************************************************************
** The text with the user's search term, and each of its words of three or
** more characters, replaced by a marker (case-insensitive): error messages
** (ours and OpenSearch's) can echo the term, which may hold personal data.
*******************************************************************************/
public static String redactTerm(String text, String userTerm)
{
if(text == null || userTerm == null || userTerm.isBlank())
{
return (text);
}
String redacted = text.replaceAll("(?i)" + java.util.regex.Pattern.quote(userTerm.trim()), "[search term]");
for(String word : userTerm.trim().split("\\s+"))
{
if(word.length() >= 3)
{
redacted = redacted.replaceAll("(?i)" + java.util.regex.Pattern.quote(word), "[search term]");
}
}
return (redacted);
}
/*******************************************************************************
** The innermost cause of a throwable (the one that names the real error
** class: timeout, connection refused, OpenSearch error).
*******************************************************************************/
public static Throwable rootCause(Throwable error)
{
Throwable cause = error;
int depth = 0;
while(cause != null && cause.getCause() != null && cause.getCause() != cause && depth++ < 20)
{
cause = cause.getCause();
}
return (cause);
}
/*******************************************************************************
** A user-facing error for a tool whose OpenSearch call failed: the tool
** reports the failure honestly instead of showing partial data.
*******************************************************************************/
public static QUserFacingException unavailable(String what, QException e)
{
return (new QUserFacingException(what + " is unavailable: " + e.getMessage(), e));
}
}
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/IndexValidator.java
+782
View File
@@ -0,0 +1,782 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.time.Instant;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import com.kingsrook.qqq.backend.core.actions.tables.CountAction;
import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.context.CapturedContext;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.logging.QLogger;
import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertOutput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession;
import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.QuickSearchableTableConfig;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml.Level;
import com.kingsrook.qbits.quicksearch.model.QuickSearchFailedEvent;
import com.kingsrook.qbits.quicksearch.model.QuickSearchValidationRun;
import com.kingsrook.qbits.quicksearch.opensearch.OpenSearchDocument;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations.RawResponse;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchOpenSearchClient;
import com.kingsrook.qbits.quicksearch.processes.AbstractIndexingStep;
import com.kingsrook.qbits.quicksearch.processes.IndexingUtils;
import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
/*******************************************************************************
** Validate the Quick Search index against the database and its expected
** shape, and report every finding with a level (OK, INFO, WARN, FAIL):
** - cluster: reachable, cluster and index health, the alias pointing at one
** physical index, leftover physical indexes from interrupted rebuilds;
** - mapping and settings: mapping version, field types and analyzers of the
** fixed fields, the fieldValues dynamic template and every fieldValues.*
** field mapped as text, the two analyzers and the edge n-gram filter;
** - per table: database rows vs indexed documents, a sample of records
** (the lowest and highest primary keys) checked present and current in
** the index, a random sample of documents checked to still have a record,
** the quickSearchIndex row's status and last run, failed events waiting.
** Database reads run as the system user, so counts compare like with like
** (the index holds every row whatever the record locks). The report holds
** counts, ids and field names, never record values. Read-only, except that
** persist() saves the report as a quickSearchValidationRun row.
*******************************************************************************/
public class IndexValidator
{
private static final QLogger LOG = QLogger.getLogger(IndexValidator.class);
private static final ObjectMapper MAPPER = new ObjectMapper().registerModule(new JavaTimeModule());
public static final String SCOPE_CLUSTER = "cluster";
public static final String SCOPE_MAPPING = "mapping";
private static final int MAX_LISTED_IDS = 25;
/*******************************************************************************
** One finding.
*******************************************************************************/
public record Finding(String scope, String check, Level level, String message)
{
}
/*******************************************************************************
** Per-table numbers.
*******************************************************************************/
public record TableStats(String tableName, Integer databaseCount, Long indexCount, Integer sampled, List<String> missingIds, Map<String, List<String>> staleFields,
Integer documentsSampled, List<String> extraIds)
{
}
/*******************************************************************************
** A validation report.
*******************************************************************************/
public record Report(String status, Instant startTime, Instant endTime, Integer sampleSize, List<String> tableNames, List<Finding> findings, List<TableStats> tableStats)
{
/*******************************************************************************
** Count of findings at a level.
*******************************************************************************/
public int count(Level level)
{
return ((int) findings.stream().filter(f -> f.level() == level).count());
}
}
/*******************************************************************************
** Validate the named tables (empty for every indexed table) with the given
** sample size per table.
*******************************************************************************/
public Report validate(QuickSearchRuntime runtime, List<String> requestedTables, int sampleSize) throws QException
{
Instant start = Instant.now();
List<Finding> findings = new ArrayList<>();
List<TableStats> stats = new ArrayList<>();
List<String> tables = resolveTables(runtime, requestedTables, findings);
int boundedN = Math.max(1, Math.min(sampleSize, QuickSearchQBitConfig.MAX_VALIDATION_SAMPLE_SIZE));
QInstance qInstance = QContext.getQInstance();
QContext.withTemporaryContext(new CapturedContext(qInstance, new QSystemUserSession()), () ->
{
QuickSearchDiagnosticsOperations ops;
try
{
ops = new QuickSearchDiagnosticsOperations(runtime.getClient());
}
catch(QException e)
{
findings.add(new Finding(SCOPE_CLUSTER, "Client", Level.FAIL, "The OpenSearch client could not be built: " + e.getMessage()));
return;
}
if(!checkCluster(runtime, ops, findings))
{
return;
}
checkMapping(ops, findings);
checkSettings(ops, findings);
for(String tableName : tables)
{
stats.add(checkTable(runtime, ops, runtime.getTableConfig(tableName), boundedN, findings));
}
});
String status = findings.stream().anyMatch(f -> f.level() == Level.FAIL) ? QuickSearchValidationRun.STATUS_FAIL
: findings.stream().anyMatch(f -> f.level() == Level.WARN) ? QuickSearchValidationRun.STATUS_WARN : QuickSearchValidationRun.STATUS_PASS;
return (new Report(status, start, Instant.now(), boundedN, tables, findings, stats));
}
/*******************************************************************************
** The requested indexed tables (unknown ones reported), else every indexed
** table.
*******************************************************************************/
private static List<String> resolveTables(QuickSearchRuntime runtime, List<String> requested, List<Finding> findings)
{
List<String> tables = new ArrayList<>();
if(CollectionUtils.nullSafeIsEmpty(requested))
{
runtime.getDiscoveredTables().forEach(t -> tables.add(t.getTableName()));
return (tables);
}
for(String tableName : requested)
{
if(runtime.getTableConfig(tableName) == null)
{
findings.add(new Finding(tableName, "Configured", Level.WARN, "Quick Search does not index this table; skipped."));
}
else if(!tables.contains(tableName))
{
tables.add(tableName);
}
}
return (tables);
}
/*******************************************************************************
** Cluster health, alias and physical indexes. Returns false when the index
** cannot be reached (the other checks are then skipped).
*******************************************************************************/
boolean checkCluster(QuickSearchRuntime runtime, QuickSearchDiagnosticsOperations ops, List<Finding> findings)
{
RawResponse health;
try
{
health = ops.clusterHealth();
}
catch(QException e)
{
findings.add(new Finding(SCOPE_CLUSTER, "Reachable", Level.FAIL, "OpenSearch did not answer: " + e.getMessage()));
return (false);
}
if(health.status() == 404)
{
findings.add(new Finding(SCOPE_CLUSTER, "Index", Level.FAIL, "The index alias [" + ops.getIndexName() + "] does not exist. Run the full reindex to create it."));
return (false);
}
if(!health.isOk())
{
findings.add(new Finding(SCOPE_CLUSTER, "Reachable", Level.FAIL, "Cluster health returned status " + health.status() + ": " + QuickSearchDiagnosticsOperations.errorReason(health.body())));
return (false);
}
findings.add(new Finding(SCOPE_CLUSTER, "Reachable", Level.OK, "OpenSearch answered (" + health.body().path("cluster_name").asText("cluster") + ", "
+ health.body().path("number_of_nodes").asInt() + " node(s))."));
findings.add(healthFinding("Cluster health", health.body().path("status").asText("unknown")));
Iterator<Map.Entry<String, JsonNode>> indexes = health.body().path("indices").fields();
while(indexes.hasNext())
{
Map.Entry<String, JsonNode> index = indexes.next();
findings.add(healthFinding("Index health " + index.getKey(), index.getValue().path("status").asText("unknown")));
}
try
{
Set<String> physical = runtime.getClient().getPhysicalIndexes();
if(physical.isEmpty())
{
findings.add(new Finding(SCOPE_CLUSTER, "Alias", Level.WARN, "[" + ops.getIndexName() + "] is a concrete index, not an alias (created before 1.0). The next full reindex replaces it with an alias."));
}
else if(physical.size() > 1)
{
findings.add(new Finding(SCOPE_CLUSTER, "Alias", Level.FAIL, "The alias points at " + physical.size() + " physical indexes " + physical + "; searches and counts see documents twice. Run the full reindex."));
}
else
{
findings.add(new Finding(SCOPE_CLUSTER, "Alias", Level.OK, "The alias points at " + physical.iterator().next() + "."));
}
RawResponse cat = ops.physicalIndexes();
if(cat.isOk() && cat.body() != null)
{
for(JsonNode row : cat.body())
{
String name = row.path("index").asText();
if(!physical.contains(name))
{
findings.add(new Finding(SCOPE_CLUSTER, "Leftover index", Level.WARN, "Physical index " + name + " (" + row.path("docs.count").asText("?") + " docs, "
+ row.path("store.size").asText("?") + ") is not behind the alias: left by an interrupted rebuild. Delete it to free space."));
}
}
}
}
catch(QException e)
{
findings.add(new Finding(SCOPE_CLUSTER, "Alias", Level.FAIL, "Could not read the alias: " + e.getMessage()));
}
return (true);
}
/*******************************************************************************
*******************************************************************************/
private static Finding healthFinding(String check, String status)
{
return (switch(status)
{
case "green" -> new Finding(SCOPE_CLUSTER, check, Level.OK, "green.");
case "yellow" -> new Finding(SCOPE_CLUSTER, check, Level.WARN, "yellow: replica shards are unassigned (expected on a single-node cluster when the index asks for replicas).");
default -> new Finding(SCOPE_CLUSTER, check, Level.FAIL, status + ": primary shards are unassigned; searches and writes may fail.");
});
}
/*******************************************************************************
** The live mapping against the mapping this version creates.
*******************************************************************************/
void checkMapping(QuickSearchDiagnosticsOperations ops, List<Finding> findings)
{
RawResponse response;
try
{
response = ops.mapping();
QuickSearchDiagnosticsOperations.requireOk(response, "Mapping read failed");
}
catch(QException e)
{
findings.add(new Finding(SCOPE_MAPPING, "Mapping", Level.FAIL, e.getMessage()));
return;
}
Iterator<Map.Entry<String, JsonNode>> indexes = response.body().fields();
while(indexes.hasNext())
{
Map.Entry<String, JsonNode> index = indexes.next();
JsonNode mappings = index.getValue().path("mappings");
String prefix = index.getKey() + ": ";
int version = mappings.path("_meta").path(QuickSearchOpenSearchClient.META_MAPPING_VERSION).asInt(1);
findings.add(version >= QuickSearchOpenSearchClient.MAPPING_VERSION
? new Finding(SCOPE_MAPPING, "Mapping version", Level.OK, prefix + "version " + version + ".")
: new Finding(SCOPE_MAPPING, "Mapping version", Level.FAIL, prefix + "version " + version + ", this release writes " + QuickSearchOpenSearchClient.MAPPING_VERSION + ". Run the full reindex."));
JsonNode properties = mappings.path("properties");
List<String> problems = new ArrayList<>();
expectType(properties, "sourceTable", "keyword", problems);
expectType(properties, "recordId", "keyword", problems);
expectType(properties, "indexedAt", "date", problems);
expectText(properties.path("searchableText"), "searchableText", problems);
expectText(properties.path("recordLabel"), "recordLabel", problems);
boolean template = false;
for(JsonNode entry : mappings.path("dynamic_templates"))
{
template |= entry.has("fieldValuesAsText");
}
if(!template)
{
problems.add("the fieldValuesAsText dynamic template is missing, so new fields may be mapped as numbers or dates");
}
if(mappings.path("date_detection").asBoolean(true) || mappings.path("numeric_detection").asBoolean(false))
{
problems.add("date or numeric detection is on");
}
Iterator<Map.Entry<String, JsonNode>> fields = properties.path("fieldValues").path("properties").fields();
int count = 0;
while(fields.hasNext())
{
Map.Entry<String, JsonNode> field = fields.next();
expectText(field.getValue(), "fieldValues." + field.getKey(), problems);
count++;
}
findings.add(problems.isEmpty()
? new Finding(SCOPE_MAPPING, "Field mappings", Level.OK, prefix + "fixed fields and " + count + " fieldValues field(s) mapped as expected.")
: new Finding(SCOPE_MAPPING, "Field mappings", Level.FAIL, prefix + String.join("; ", problems) + ". Run the full reindex to rebuild the mapping."));
}
}
/*******************************************************************************
*******************************************************************************/
private static void expectType(JsonNode properties, String field, String type, List<String> problems)
{
String actual = properties.path(field).path("type").asText(null);
if(!type.equals(actual))
{
problems.add(field + " is " + (actual == null ? "not mapped" : "mapped as " + actual) + ", expected " + type);
}
}
/*******************************************************************************
*******************************************************************************/
private static void expectText(JsonNode mapping, String field, List<String> problems)
{
String type = mapping.path("type").asText(null);
String analyzer = mapping.path("analyzer").asText(null);
String search = mapping.path("search_analyzer").asText(null);
if(!"text".equals(type))
{
problems.add(field + " is " + (type == null ? "not mapped" : "mapped as " + type) + ", expected text");
}
else if(!QuickSearchOpenSearchClient.INDEX_ANALYZER.equals(analyzer) || !QuickSearchOpenSearchClient.SEARCH_ANALYZER.equals(search))
{
problems.add(field + " uses analyzer " + analyzer + " / search analyzer " + search + ", expected " + QuickSearchOpenSearchClient.INDEX_ANALYZER + " / " + QuickSearchOpenSearchClient.SEARCH_ANALYZER);
}
}
/*******************************************************************************
** The live analysis settings against the ones this version creates.
*******************************************************************************/
void checkSettings(QuickSearchDiagnosticsOperations ops, List<Finding> findings)
{
RawResponse response;
try
{
response = ops.settings();
QuickSearchDiagnosticsOperations.requireOk(response, "Settings read failed");
}
catch(QException e)
{
findings.add(new Finding(SCOPE_MAPPING, "Analysis settings", Level.FAIL, e.getMessage()));
return;
}
Iterator<Map.Entry<String, JsonNode>> indexes = response.body().fields();
while(indexes.hasNext())
{
Map.Entry<String, JsonNode> index = indexes.next();
JsonNode settings = index.getValue().path("settings").path("index");
JsonNode analysis = settings.path("analysis");
List<String> problems = new ArrayList<>();
JsonNode indexAnalyzer = analysis.path("analyzer").path(QuickSearchOpenSearchClient.INDEX_ANALYZER);
JsonNode searchAnalyzer = analysis.path("analyzer").path(QuickSearchOpenSearchClient.SEARCH_ANALYZER);
JsonNode ngram = analysis.path("filter").path("edge_ngram_filter");
if(!"standard".equals(indexAnalyzer.path("tokenizer").asText()) || !List.of("lowercase", "edge_ngram_filter").equals(textList(indexAnalyzer.path("filter"))))
{
problems.add(QuickSearchOpenSearchClient.INDEX_ANALYZER + " is " + (indexAnalyzer.isMissingNode() ? "missing" : indexAnalyzer.toString()));
}
if(!"standard".equals(searchAnalyzer.path("tokenizer").asText()) || !List.of("lowercase").equals(textList(searchAnalyzer.path("filter"))))
{
problems.add(QuickSearchOpenSearchClient.SEARCH_ANALYZER + " is " + (searchAnalyzer.isMissingNode() ? "missing" : searchAnalyzer.toString()));
}
if(!"edge_ngram".equals(ngram.path("type").asText()) || ngram.path("min_gram").asInt() != 2 || ngram.path("max_gram").asInt() != 20)
{
problems.add("edge_ngram_filter is " + (ngram.isMissingNode() ? "missing" : ngram.toString()));
}
findings.add(problems.isEmpty()
? new Finding(SCOPE_MAPPING, "Analysis settings", Level.OK, index.getKey() + ": analyzers and edge n-grams (2 to 20) as expected; "
+ settings.path("number_of_shards").asText("?") + " shard(s), " + settings.path("number_of_replicas").asText("?") + " replica(s).")
: new Finding(SCOPE_MAPPING, "Analysis settings", Level.FAIL, index.getKey() + ": " + String.join("; ", problems) + ". Run the full reindex."));
}
}
/*******************************************************************************
*******************************************************************************/
private static List<String> textList(JsonNode array)
{
List<String> values = new ArrayList<>();
array.forEach(v -> values.add(v.asText()));
return (values);
}
/*******************************************************************************
** Counts, sampled freshness and orphans of one table, plus its index row
** and failed events.
*******************************************************************************/
TableStats checkTable(QuickSearchRuntime runtime, QuickSearchDiagnosticsOperations ops, QuickSearchableTableConfig tableConfig, int sampleSize, List<Finding> findings)
{
String tableName = tableConfig.getTableName();
Integer databaseCount = null;
Long indexCount = null;
try
{
databaseCount = DiagnosticRecordReads.count(tableName);
indexCount = runtime.getClient().countDocumentsForTable(tableName);
long difference = indexCount - databaseCount;
long tolerance = Math.max(5, databaseCount / 100);
Level level = difference == 0 ? Level.OK : (Math.abs(difference) <= tolerance ? Level.WARN : Level.FAIL);
findings.add(new Finding(tableName, "Counts", level, "database " + databaseCount + ", index " + indexCount
+ (difference == 0 ? "." : " (" + (difference > 0 ? difference + " more in the index" : (-difference) + " missing from the index") + "). Reconcile fixes counts.")));
}
catch(QException e)
{
findings.add(new Finding(tableName, "Counts", Level.FAIL, e.getMessage()));
}
List<String> missing = new ArrayList<>();
Map<String, List<String>> staleFields = new LinkedHashMap<>();
int sampled = 0;
try
{
Map<String, QRecord> sample = new LinkedHashMap<>();
for(QRecord record : DiagnosticRecordReads.loadEdge(tableName, true, (sampleSize + 1) / 2))
{
sample.put(record.getValueString(tableConfig.getPrimaryKeyField()), record);
}
for(QRecord record : DiagnosticRecordReads.loadEdge(tableName, false, sampleSize / 2))
{
sample.putIfAbsent(record.getValueString(tableConfig.getPrimaryKeyField()), record);
}
sampled = sample.size();
Map<String, JsonNode> indexed = ops.getDocuments(tableName, sample.keySet());
for(Map.Entry<String, QRecord> entry : sample.entrySet())
{
JsonNode source = indexed.get(entry.getKey());
if(source == null)
{
missing.add(entry.getKey());
continue;
}
List<String> differing = differingFields(tableConfig, IndexingUtils.buildDocument(entry.getValue(), tableConfig), source);
if(!differing.isEmpty())
{
staleFields.put(entry.getKey(), differing);
}
}
findings.add(missing.isEmpty() && staleFields.isEmpty()
? new Finding(tableName, "Sampled records", Level.OK, sampled + " record(s) checked: all indexed and current.")
: new Finding(tableName, "Sampled records", Level.FAIL, sampled + " record(s) checked: " + missing.size() + " missing" + listIds(missing) + ", "
+ staleFields.size() + " stale" + listIds(new ArrayList<>(staleFields.keySet())) + ". Reindex those records, or run reconcile for the table."));
}
catch(QException e)
{
findings.add(new Finding(tableName, "Sampled records", Level.FAIL, e.getMessage()));
}
List<String> extra = new ArrayList<>();
int documentsSampled = 0;
try
{
List<String> documentIds = ops.sampleRecordIds(tableName, sampleSize);
documentsSampled = documentIds.size();
Set<String> existing = new HashSet<>(DiagnosticRecordReads.existingIds(tableName, documentIds));
for(String recordId : documentIds)
{
if(!existing.contains(recordId))
{
extra.add(recordId);
}
}
findings.add(extra.isEmpty()
? new Finding(tableName, "Sampled documents", Level.OK, documentsSampled + " random document(s) checked: every one has its record.")
: new Finding(tableName, "Sampled documents", Level.FAIL, documentsSampled + " random document(s) checked: " + extra.size() + " have no record (orphans)"
+ listIds(extra) + ". Reconcile removes them."));
}
catch(QException e)
{
findings.add(new Finding(tableName, "Sampled documents", Level.FAIL, e.getMessage()));
}
checkIndexRow(runtime, tableName, findings);
checkFailedEvents(runtime, tableName, findings);
return (new TableStats(tableName, databaseCount, indexCount, sampled, missing, staleFields, documentsSampled, extra));
}
/*******************************************************************************
** Names of the values that differ between an expected document and an
** indexed source (recordLabel, searchableText, fieldValues.x).
*******************************************************************************/
static List<String> differingFields(QuickSearchableTableConfig tableConfig, OpenSearchDocument expected, JsonNode source)
{
return (RecordInspector.diff(tableConfig, expected, new QuickSearchDiagnosticsOperations.DocumentView(true, null, null, source)).stream()
.filter(d -> !d.isSame())
.map(RecordInspector.FieldDiff::name)
.toList());
}
/*******************************************************************************
*******************************************************************************/
private static void checkIndexRow(QuickSearchRuntime runtime, String tableName, List<Finding> findings)
{
try
{
String indexTable = runtime.getConfig().getQuickSearchIndexTableName();
if(QContext.getQInstance().getTable(indexTable) == null)
{
return;
}
QueryInput queryInput = new QueryInput();
queryInput.setTableName(indexTable);
queryInput.setFilter(new QQueryFilter(new QFilterCriteria("tableName", QCriteriaOperator.EQUALS, tableName)));
List<QRecord> rows = CollectionUtils.nonNullList(new QueryAction().execute(queryInput).getRecords());
if(rows.isEmpty())
{
findings.add(new Finding(tableName, "Index row", Level.WARN, "No Quick Search Index row yet: no basepull, reconcile or reindex has run for this table."));
return;
}
QRecord row = rows.get(0);
String status = row.getValueString("status");
String lastRun = row.getValueString("lastRunStatus");
if(Boolean.FALSE.equals(row.getValueBoolean("enabled")))
{
findings.add(new Finding(tableName, "Index row", Level.INFO, "Disabled: Quick Search neither indexes nor searches this table, so differences are expected."));
}
if(AbstractIndexingStep.STATUS_NEEDS_REINDEX.equals(status))
{
findings.add(new Finding(tableName, "Index row", Level.WARN, "Status NEEDS_REINDEX: the configured fields changed since the last reindex. Rebuild the table."));
}
else if(AbstractIndexingStep.STATUS_REBUILDING.equals(status))
{
findings.add(new Finding(tableName, "Index row", Level.WARN, "Status REBUILDING: a full reindex is running. If it was killed, basepull returns the table to ACTIVE once its run records show no sign of life for fullReindexStaleMinutes."));
}
if(AbstractIndexingStep.RUN_FAILED.equals(lastRun))
{
findings.add(new Finding(tableName, "Last run", Level.WARN, "The last indexing run failed: " + row.getValueString("lastErrorMessage")));
}
}
catch(Exception e)
{
LOG.info("Could not read the Quick Search Index row during validation", e, logPair("tableName", tableName));
}
}
/*******************************************************************************
*******************************************************************************/
private static void checkFailedEvents(QuickSearchRuntime runtime, String tableName, List<Finding> findings)
{
try
{
String failedTable = runtime.getConfig().applyPrefix(QuickSearchFailedEvent.TABLE_NAME);
if(QContext.getQInstance().getTable(failedTable) == null)
{
return;
}
CountInput countInput = new CountInput();
countInput.setTableName(failedTable);
countInput.setFilter(new QQueryFilter(new QFilterCriteria("tableName", QCriteriaOperator.EQUALS, tableName),
new QFilterCriteria("status", QCriteriaOperator.IN, List.of(QuickSearchFailedEvent.STATUS_PENDING, QuickSearchFailedEvent.STATUS_EXHAUSTED))));
Integer count = new CountAction().execute(countInput).getCount();
if(count != null && count > 0)
{
findings.add(new Finding(tableName, "Failed events", Level.WARN, count + " real-time index event(s) failed and wait for replay (or are exhausted). See Quick Search Failed Event."));
}
}
catch(Exception e)
{
LOG.info("Could not count failed events during validation", e, logPair("tableName", tableName));
}
}
/*******************************************************************************
** Save a report as a quickSearchValidationRun row (as the system user);
** returns its id, or null when the table is not configured or the insert
** fails (logged).
*******************************************************************************/
public Integer persist(QuickSearchRuntime runtime, Report report, String triggerType, String userName)
{
String tableName = runtime.getConfig().applyPrefix(QuickSearchValidationRun.TABLE_NAME);
if(QContext.getQInstance() == null || QContext.getQInstance().getTable(tableName) == null)
{
return (null);
}
QuickSearchValidationRun run = new QuickSearchValidationRun()
.withStatus(report.status())
.withTriggerType(triggerType)
.withUserName(userName)
.withTableNames(DiagnosticEventRecorder.truncate(String.join(",", report.tableNames()), 1000))
.withSampleSize(report.sampleSize())
.withTablesChecked(report.tableStats().size())
.withFailCount(report.count(Level.FAIL))
.withWarnCount(report.count(Level.WARN))
.withSummary(DiagnosticEventRecorder.truncate(summary(report), 250))
.withReportHtml(render(report))
.withReportJson(toJson(report))
.withStartTime(report.startTime())
.withEndTime(report.endTime())
.withCreateDate(Instant.now());
Integer[] id = new Integer[1];
try
{
QContext.withTemporaryContext(new CapturedContext(QContext.getQInstance(), new QSystemUserSession()), () ->
{
InsertOutput output = new InsertAction().execute(new InsertInput(tableName).withRecordEntity(run));
id[0] = output.getRecords().get(0).getValueInteger("id");
});
}
catch(Exception e)
{
LOG.warn("Could not save the Quick Search validation report", e);
}
return (id[0]);
}
/*******************************************************************************
** One line: status and counts.
*******************************************************************************/
public static String summary(Report report)
{
return (report.status() + ": " + report.tableStats().size() + " table(s), " + report.count(Level.FAIL) + " failed check(s), " + report.count(Level.WARN) + " warning(s).");
}
/*******************************************************************************
** The report as JSON.
*******************************************************************************/
public static String toJson(Report report)
{
try
{
return (MAPPER.writeValueAsString(report));
}
catch(Exception e)
{
return ("{\"error\":\"report could not be serialized\"}");
}
}
/*******************************************************************************
** The report as HTML: summary, then the findings grouped by scope.
*******************************************************************************/
public static String render(Report report)
{
DiagnosticsHtml html = new DiagnosticsHtml().open();
Level overall = switch(report.status())
{
case QuickSearchValidationRun.STATUS_PASS -> Level.OK;
case QuickSearchValidationRun.STATUS_WARN -> Level.WARN;
default -> Level.FAIL;
};
html.heading("Index validation");
html.status(overall, summary(report));
html.paragraph("Ran " + report.startTime() + " to " + report.endTime() + ", " + report.sampleSize() + " sampled record(s) and document(s) per table. Database reads ran as the system user.");
Map<String, List<DiagnosticsHtml.Check>> byScope = new LinkedHashMap<>();
for(Finding finding : report.findings())
{
byScope.computeIfAbsent(finding.scope(), k -> new ArrayList<>()).add(new DiagnosticsHtml.Check(finding.check(), finding.level(), finding.message()));
}
for(Map.Entry<String, List<DiagnosticsHtml.Check>> scope : byScope.entrySet())
{
String heading = switch(scope.getKey())
{
case SCOPE_CLUSTER -> "Cluster and index";
case SCOPE_MAPPING -> "Mapping and analyzers";
default -> "Table " + scope.getKey();
};
html.subheading(heading);
html.checks(scope.getValue());
}
for(TableStats stats : report.tableStats())
{
if(!stats.staleFields().isEmpty())
{
List<String> items = new ArrayList<>();
stats.staleFields().entrySet().stream().limit(MAX_LISTED_IDS).forEach(e ->
items.add("#" + DiagnosticsHtml.escape(e.getKey()) + ": " + DiagnosticsHtml.escape(String.join(", ", e.getValue()))));
html.subheading("Stale fields in " + stats.tableName());
html.rawList(items);
}
}
return (html.close().toString());
}
/*******************************************************************************
*******************************************************************************/
private static String listIds(List<String> ids)
{
if(ids.isEmpty())
{
return ("");
}
return (" (" + String.join(", ", ids.subList(0, Math.min(MAX_LISTED_IDS, ids.size()))) + (ids.size() > MAX_LISTED_IDS ? ", ..." : "") + ")");
}
}
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/QuickSearchDiagnosticsWidgetRenderer.java
+217
View File
@@ -0,0 +1,217 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.util.ArrayList;
import java.util.List;
import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.AbstractWidgetRenderer;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.logging.QLogger;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetOutput;
import com.kingsrook.qqq.backend.core.model.dashboard.widgets.RawHTML;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml.Level;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
import com.kingsrook.qbits.quicksearch.model.QuickSearchValidationRun;
/*******************************************************************************
** The Search Diagnostics widget: the record-search provider's state on the
** server that renders it, the most recent search failures (from every
** server, via Quick Search Diagnostic Event), the latest validation run,
** and where the tools are. Every part says plainly when it has nothing to
** show or cannot be read.
*******************************************************************************/
public class QuickSearchDiagnosticsWidgetRenderer extends AbstractWidgetRenderer
{
private static final QLogger LOG = QLogger.getLogger(QuickSearchDiagnosticsWidgetRenderer.class);
public static final int RECENT_FAILURES = 10;
/*******************************************************************************
*******************************************************************************/
@Override
public RenderWidgetOutput render(RenderWidgetInput input) throws QException
{
QuickSearchRuntime runtime = QuickSearchRuntime.get();
if(runtime == null)
{
return (new RenderWidgetOutput(new RawHTML("Search Diagnostics", "<p>Quick Search is not configured in this application.</p>")));
}
return (new RenderWidgetOutput(new RawHTML("Search Diagnostics", renderHtml(runtime))));
}
/*******************************************************************************
** The widget's HTML.
*******************************************************************************/
static String renderHtml(QuickSearchRuntime runtime)
{
QuickSearchQBitConfig config = runtime.getConfig();
DiagnosticsHtml html = new DiagnosticsHtml().open();
SearchPathDiagnosis.ProviderState state = SearchPathDiagnosis.providerState(QContext.getQInstance(), runtime);
html.subheading("Global search on this server");
if(!Boolean.TRUE.equals(state.quickSearchProvider()) || !Boolean.TRUE.equals(state.serveCoreRecordSearch()))
{
html.status(Level.INFO, "Quick Search does not serve the global search here (" + (state.registeredProvider() == null ? "no provider registered" : "provider " + state.registeredProvider())
+ "); core searches every table itself.");
}
else if(state.backoffRemainingMillis() > 0)
{
html.status(Level.FAIL, "Backing off for " + (state.backoffRemainingMillis() / 1000) + " s after an OpenSearch failure: the global search uses core's database search meanwhile. Last error: "
+ state.lastFailureMessage());
}
else
{
html.status(Level.OK, "Served by OpenSearch through Quick Search (timeout " + state.timeoutMillis() + " ms).");
}
html.facts(List.of(
new String[] { "Failed OpenSearch searches since " + state.runtimeStartedAt(), String.valueOf(state.failureCount()) },
new String[] { "Table searches core ran itself during backoffs", String.valueOf(state.backoffDeclinedClaims()) },
new String[] { "Last failure", state.lastFailureTime() == null ? null : state.lastFailureTime() + ": " + state.lastFailureMessage() }));
renderRecentFailures(html, config);
renderLastValidation(html, config);
html.subheading("Tools");
html.paragraph("On Quick Search Index (Actions): Search Playground, Validate Search Index, Test Search Analyzer. "
+ "On any indexed record and on Quick Search Failed Event rows: Inspect Search Document and Reindex in Search. "
+ "Every run is recorded in Quick Search Diagnostic Event.");
return (html.close().toString());
}
/*******************************************************************************
*******************************************************************************/
private static void renderRecentFailures(DiagnosticsHtml html, QuickSearchQBitConfig config)
{
String tableName = config.applyPrefix(QuickSearchDiagnosticEvent.TABLE_NAME);
html.subheading("Recent search failures (all servers)");
if(QContext.getQInstance().getTable(tableName) == null)
{
html.paragraph("Not recorded: the diagnostic event table is not configured.");
return;
}
try
{
QueryInput queryInput = new QueryInput();
queryInput.setTableName(tableName);
queryInput.setFilter(new QQueryFilter(new QFilterCriteria("eventType", QCriteriaOperator.EQUALS, QuickSearchDiagnosticEvent.TYPE_SEARCH_FAILED))
.withOrderBy(new QFilterOrderBy("id", false))
.withLimit(RECENT_FAILURES));
List<QRecord> rows = CollectionUtils.nonNullList(new QueryAction().execute(queryInput).getRecords());
if(rows.isEmpty())
{
html.status(Level.OK, "None recorded (failures are kept for " + config.getRunHistoryRetentionDays() + " days).");
return;
}
List<String> items = new ArrayList<>();
for(QRecord row : rows)
{
items.add("<a href=\"/app/" + DiagnosticsHtml.escape(tableName) + "/" + DiagnosticsHtml.escape(row.getValueString("id")) + "\">"
+ DiagnosticsHtml.escape(row.getValueString("createDate")) + "</a> on " + DiagnosticsHtml.escape(row.getValueString("hostName"))
+ ": " + DiagnosticsHtml.escape(row.getValueString("source")) + ", " + DiagnosticsHtml.escape(row.getValueString("durationMillis")) + " ms, "
+ DiagnosticsHtml.escape(shortClass(row.getValueString("errorClass"))) + ": " + DiagnosticsHtml.escape(abbreviate(row.getValueString("errorMessage"), 240)));
}
html.rawList(items);
}
catch(Exception e)
{
LOG.info("Could not read recent search failures for the diagnostics widget", e);
html.status(Level.WARN, "Could not read the diagnostic events: " + e.getMessage());
}
}
/*******************************************************************************
*******************************************************************************/
private static void renderLastValidation(DiagnosticsHtml html, QuickSearchQBitConfig config)
{
String tableName = config.applyPrefix(QuickSearchValidationRun.TABLE_NAME);
html.subheading("Latest index validation");
if(QContext.getQInstance().getTable(tableName) == null)
{
html.paragraph("Not kept: the validation run table is not configured.");
return;
}
try
{
QueryInput queryInput = new QueryInput();
queryInput.setTableName(tableName);
queryInput.setFilter(new QQueryFilter().withOrderBy(new QFilterOrderBy("id", false)).withLimit(1));
List<QRecord> rows = CollectionUtils.nonNullList(new QueryAction().execute(queryInput).getRecords());
if(rows.isEmpty())
{
html.paragraph("None yet. Run Validate Search Index from Quick Search Index (Actions)"
+ (config.getValidationCronExpression() == null ? "." : "; it is also scheduled (" + config.getValidationCronExpression() + ")."));
return;
}
QRecord row = rows.get(0);
String status = row.getValueString("status");
Level level = QuickSearchValidationRun.STATUS_PASS.equals(status) ? Level.OK : (QuickSearchValidationRun.STATUS_WARN.equals(status) ? Level.WARN : Level.FAIL);
html.raw("<p>" + DiagnosticsHtml.badge(level) + " <a href=\"/app/" + DiagnosticsHtml.escape(tableName) + "/" + DiagnosticsHtml.escape(row.getValueString("id")) + "\">"
+ DiagnosticsHtml.escape(row.getValueString("startTime")) + "</a> (" + DiagnosticsHtml.escape(row.getValueString("triggerType")) + "): "
+ DiagnosticsHtml.escape(row.getValueString("summary")) + "</p>");
}
catch(Exception e)
{
LOG.info("Could not read the latest validation run for the diagnostics widget", e);
html.status(Level.WARN, "Could not read the validation runs: " + e.getMessage());
}
}
/*******************************************************************************
*******************************************************************************/
private static String shortClass(String className)
{
return (className == null ? "error" : className.substring(className.lastIndexOf('.') + 1));
}
/*******************************************************************************
*******************************************************************************/
private static String abbreviate(String text, int max)
{
return (text == null ? "" : (text.length() > max ? text.substring(0, max) + "..." : text));
}
}
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/RecordInspector.java
+410
View File
@@ -0,0 +1,410 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
import com.fasterxml.jackson.databind.JsonNode;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
import com.kingsrook.qqq.backend.core.actions.permissions.TablePermissionSubType;
import com.kingsrook.qqq.backend.core.actions.tables.RecordSearchAction;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
import com.kingsrook.qqq.backend.core.utils.StringUtils;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.QuickSearchableTableConfig;
import com.kingsrook.qbits.quicksearch.actions.QuickSearchAction;
import com.kingsrook.qbits.quicksearch.actions.QuickSearchRecordSearchProvider;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml.Check;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml.Level;
import com.kingsrook.qbits.quicksearch.opensearch.OpenSearchDocument;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations.AnalyzedToken;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations.DocumentView;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations.ExplainResult;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations.ProbeHit;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations.SearchProbe;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchOpenSearchClient;
import com.kingsrook.qbits.quicksearch.processes.IndexingUtils;
/*******************************************************************************
** Inspect one record's search document: the document as indexed next to the
** document indexing would write from the database now (field by field),
** and, given a term, why the record does or does not match it.
** The match analysis walks the same gates as the global search: term
** length, table indexed and enabled, read permission, record readable,
** document present and current, every query token present among the
** document's indexed tokens (edge n-grams of 2 to 20 characters, AND
** semantics), explain, and the record's rank against the provider's
** per-table id window. Read-only.
*******************************************************************************/
public class RecordInspector
{
public static final String VERDICT_CURRENT = "CURRENT";
public static final String VERDICT_STALE = "STALE";
public static final String VERDICT_MISSING = "MISSING";
public static final String VERDICT_NOT_INDEXED = "NOT_INDEXED";
public static final String VERDICT_NO_RECORD = "NO_RECORD";
private static final int RANK_WINDOW = RecordSearchAction.MAX_PROVIDER_IDS_PER_TABLE;
/*******************************************************************************
** One compared value: name, value from the database, value in the index.
*******************************************************************************/
public record FieldDiff(String name, String databaseValue, String indexValue)
{
/*******************************************************************************
** Whether the two values are equal.
*******************************************************************************/
public boolean isSame()
{
return (Objects.equals(databaseValue, indexValue));
}
}
/*******************************************************************************
** The inspection of one record.
*******************************************************************************/
public record Inspection(String tableName, String recordId, String verdict, List<FieldDiff> diffs, DocumentView indexed, OpenSearchDocument expected,
List<Check> matchChecks, ExplainResult explain, String error)
{
}
/*******************************************************************************
** Inspect one record, with an optional term to analyze.
*******************************************************************************/
public Inspection inspect(QuickSearchRuntime runtime, String tableName, String recordId, String term, AbstractActionInput permissionInput) throws QException
{
QuickSearchableTableConfig tableConfig = runtime.getTableConfig(tableName);
if(tableConfig == null)
{
return (new Inspection(tableName, recordId, VERDICT_NOT_INDEXED, List.of(), null, null, List.of(), null, "Quick Search does not index table [" + tableName + "]."));
}
Map<String, QRecord> records = DiagnosticRecordReads.loadForIndexing(tableName, List.of(recordId));
QRecord record = records.get(recordId);
if(record == null && !records.isEmpty())
{
record = records.values().iterator().next();
}
if(record == null)
{
return (new Inspection(tableName, recordId, VERDICT_NO_RECORD, List.of(), null, null, List.of(), null,
"Record " + recordId + " does not exist, or you cannot read it."));
}
QuickSearchDiagnosticsOperations ops = new QuickSearchDiagnosticsOperations(runtime.getClient());
OpenSearchDocument expected = IndexingUtils.buildDocument(record, tableConfig);
DocumentView indexed = ops.getDocument(tableName, recordId);
List<FieldDiff> diffs = diff(tableConfig, expected, indexed);
String verdict = !Boolean.TRUE.equals(indexed.found()) ? VERDICT_MISSING : (diffs.stream().allMatch(FieldDiff::isSame) ? VERDICT_CURRENT : VERDICT_STALE);
List<Check> checks = new ArrayList<>();
ExplainResult explain = null;
String cleaned = IndexingUtils.normalizeSearchText(term);
if(StringUtils.hasContent(cleaned))
{
explain = analyzeMatch(runtime, ops, tableConfig, recordId, cleaned, verdict, expected, indexed, checks, permissionInput);
}
return (new Inspection(tableName, recordId, verdict, diffs, indexed, expected, checks, explain, null));
}
/*******************************************************************************
** Compare the expected document with the indexed one: label, searchable
** text, then each configured field (in configuration order) and any extra
** field only the index holds.
*******************************************************************************/
static List<FieldDiff> diff(QuickSearchableTableConfig tableConfig, OpenSearchDocument expected, DocumentView indexed)
{
JsonNode source = indexed == null || indexed.source() == null ? null : indexed.source();
List<FieldDiff> diffs = new ArrayList<>();
diffs.add(new FieldDiff("recordLabel", expected == null ? null : blankToNull(expected.getRecordLabel()), text(source, "recordLabel")));
diffs.add(new FieldDiff("searchableText", expected == null ? null : blankToNull(expected.getSearchableText()), text(source, "searchableText")));
Set<String> fieldNames = new LinkedHashSet<>(CollectionUtils.nonNullList(tableConfig.getSearchableFields()));
if(source != null && source.has("fieldValues"))
{
source.get("fieldValues").fieldNames().forEachRemaining(fieldNames::add);
}
for(String field : fieldNames)
{
Object expectedValue = expected == null || expected.getFieldValues() == null ? null : expected.getFieldValues().get(field);
diffs.add(new FieldDiff("fieldValues." + field, expectedValue == null ? null : String.valueOf(expectedValue),
source == null ? null : text(source.path("fieldValues"), field)));
}
return (diffs);
}
/*******************************************************************************
** Walk the global search's gates for this record and term, adding a check
** per gate; returns the explain result when the document exists.
*******************************************************************************/
private ExplainResult analyzeMatch(QuickSearchRuntime runtime, QuickSearchDiagnosticsOperations ops, QuickSearchableTableConfig tableConfig, String recordId, String term, String verdict,
OpenSearchDocument expected, DocumentView indexed, List<Check> checks, AbstractActionInput permissionInput) throws QException
{
String tableName = tableConfig.getTableName();
checks.add(term.length() < QuickSearchAction.MIN_TERM_LENGTH
? new Check("Term length", Level.FAIL, "Terms shorter than " + QuickSearchAction.MIN_TERM_LENGTH + " characters never reach OpenSearch.")
: new Check("Term length", Level.OK, term.length() + " characters."));
boolean enabled = runtime.isTableEnabled(tableName);
checks.add(enabled
? new Check("Table enabled", Level.OK, "The table is enabled in Quick Search Index.")
: new Check("Table enabled", Level.FAIL, "The table is disabled in Quick Search Index, so Quick Search does not search it (core searches it with its own database search)."));
boolean readable = PermissionsHelper.hasTablePermission(permissionInput, tableName, TablePermissionSubType.READ);
checks.add(readable
? new Check("Table permission", Level.OK, "You can read this table.")
: new Check("Table permission", Level.FAIL, "You cannot read this table, so the global search skips it for you."));
checks.add(new Check("Record access", Level.OK, "You can read this record (record security locks allow it)."));
switch(verdict)
{
case VERDICT_MISSING -> checks.add(new Check("Indexed document", Level.FAIL,
"The record has no document in the index, so OpenSearch cannot return it. Use Reindex in Search on the record (or wait for the next basepull / reconcile)."));
case VERDICT_STALE -> checks.add(new Check("Indexed document", Level.WARN,
"The indexed document differs from the database (see the comparison); the search matches the indexed values. Reindex the record to refresh it."));
default -> checks.add(new Check("Indexed document", Level.OK, "The indexed document matches the database."));
}
List<AnalyzedToken> queryTokens = ops.analyze(QuickSearchOpenSearchClient.SEARCH_ANALYZER, term);
Set<String> indexedGrams = Boolean.TRUE.equals(indexed.found()) ? tokenSet(ops.analyze(QuickSearchOpenSearchClient.INDEX_ANALYZER, text(indexed.source(), "searchableText")))
: Set.of();
Set<String> expectedGrams = expected == null ? Set.of() : tokenSet(ops.analyze(QuickSearchOpenSearchClient.INDEX_ANALYZER, expected.getSearchableText()));
if(queryTokens.isEmpty())
{
checks.add(new Check("Term tokens", Level.FAIL, "The term has no searchable characters after analysis."));
}
for(AnalyzedToken token : queryTokens)
{
String value = token.token();
if(value.length() < 2)
{
checks.add(new Check("Token \"" + value + "\"", Level.FAIL, "One character: the index holds edge n-grams of 2 to 20 characters, so a single character never matches, and every token must match."));
}
else if(value.length() > 20)
{
checks.add(new Check("Token \"" + value + "\"", Level.FAIL, "Longer than 20 characters: the index holds edge n-grams of at most 20 characters, so this token never matches. Search a shorter prefix."));
}
else if(indexedGrams.contains(value))
{
checks.add(new Check("Token \"" + value + "\"", Level.OK, "Found in the indexed text (as a word or a word prefix)."));
}
else if(expectedGrams.contains(value))
{
checks.add(new Check("Token \"" + value + "\"", Level.WARN, "Not in the indexed text, but in the database's current values: it will match once the record is reindexed."));
}
else
{
checks.add(new Check("Token \"" + value + "\"", Level.FAIL, "Not in this record's searchable text: no searchable field holds a word starting with it. Every token must match (AND)."));
}
}
ExplainResult explain = null;
if(Boolean.TRUE.equals(indexed.found()))
{
explain = ops.explain(term, tableName, recordId, runtime.getDiscoveredTables());
checks.add(Boolean.TRUE.equals(explain.matched())
? new Check("OpenSearch explain", Level.OK, "The search query matches this document with score " + String.format("%.4f", explain.score()) + ".")
: new Check("OpenSearch explain", Level.FAIL, "The search query does not match this document."));
if(Boolean.TRUE.equals(explain.matched()))
{
checks.add(rankCheck(runtime, ops, tableName, recordId, term));
}
}
return (explain);
}
/*******************************************************************************
** Where the record ranks among the table's matches, against the number of
** ids the provider asks for with the default per-table limit.
*******************************************************************************/
private Check rankCheck(QuickSearchRuntime runtime, QuickSearchDiagnosticsOperations ops, String tableName, String recordId, String term) throws QException
{
int window = Math.min(RecordSearchAction.MAX_PROVIDER_IDS_PER_TABLE, RecordSearchAction.DEFAULT_LIMIT_PER_TABLE * QuickSearchRecordSearchProvider.IDS_PER_LIMIT_MULTIPLIER);
SearchProbe probe = ops.probeSearch(term, tableName, RANK_WINDOW, runtime.getDiscoveredTables());
int rank = 0;
for(ProbeHit hit : probe.hits())
{
rank++;
if(recordId.equals(hit.recordId()))
{
if(rank <= RecordSearchAction.DEFAULT_LIMIT_PER_TABLE)
{
return (new Check("Rank", Level.OK, "#" + rank + " of " + probe.totalHits() + " matches in this table: within the global search's default " + RecordSearchAction.DEFAULT_LIMIT_PER_TABLE + " results."));
}
if(rank <= window)
{
return (new Check("Rank", Level.WARN, "#" + rank + " of " + probe.totalHits() + " matches: Quick Search returns it, but the global search shows only the first "
+ RecordSearchAction.DEFAULT_LIMIT_PER_TABLE + " readable results per table by default. A more specific term ranks it higher."));
}
return (new Check("Rank", Level.WARN, "#" + rank + " of " + probe.totalHits() + " matches: beyond the top " + window + " ids the provider requests per table, so the global search does not show it."));
}
}
return (new Check("Rank", Level.WARN, "Not in the top " + RANK_WINDOW + " of " + probe.totalHits() + " matches in this table, so the global search does not show it."));
}
/*******************************************************************************
** Render inspections as HTML.
*******************************************************************************/
public static String render(List<Inspection> inspections, String term)
{
DiagnosticsHtml html = new DiagnosticsHtml().open();
for(Inspection inspection : inspections)
{
html.heading("Search document for " + inspection.tableName() + " #" + inspection.recordId());
if(inspection.error() != null)
{
html.status(Level.FAIL, inspection.error());
continue;
}
switch(inspection.verdict())
{
case VERDICT_CURRENT -> html.status(Level.OK, "Indexed and current: the document matches the database.");
case VERDICT_STALE -> html.status(Level.WARN, "Indexed but stale: some values differ from the database. Reindex in Search refreshes it.");
default -> html.status(Level.FAIL, "Not in the index. Reindex in Search adds it.");
}
DocumentView indexed = inspection.indexed();
List<String[]> facts = new ArrayList<>();
facts.add(new String[] { "Document id", OpenSearchDocument.buildDocumentId(inspection.tableName(), inspection.recordId()) });
facts.add(new String[] { "Physical index", indexed == null ? null : indexed.physicalIndex() });
facts.add(new String[] { "Indexed version", indexed == null || indexed.version() == null ? null : indexed.version() + versionNote(indexed.version()) });
facts.add(new String[] { "Database version", inspection.expected() == null || inspection.expected().getVersion() == null ? "not versioned (no timestamp field)"
: inspection.expected().getVersion() + versionNote(inspection.expected().getVersion()) });
facts.add(new String[] { "Indexed at", indexed == null || indexed.source() == null ? null : indexed.source().path("indexedAt").asText(null) });
html.facts(facts);
html.subheading("Database vs index");
List<String> items = new ArrayList<>();
for(FieldDiff diff : inspection.diffs())
{
items.add(DiagnosticsHtml.badge(diff.isSame() ? Level.OK : Level.WARN) + " <strong>" + DiagnosticsHtml.escape(diff.name()) + "</strong>"
+ (diff.isSame() ? ": " + valueHtml(diff.databaseValue())
: "<br>database: " + valueHtml(diff.databaseValue()) + "<br>index: " + valueHtml(diff.indexValue())));
}
html.rawList(items);
if(!inspection.matchChecks().isEmpty())
{
html.subheading("Why does (or doesn't) this record match \"" + term + "\"?");
html.checks(inspection.matchChecks());
if(inspection.explain() != null && inspection.explain().explanationText() != null)
{
html.textDetails("Score explanation", inspection.explain().explanationText());
}
}
if(indexed != null && indexed.source() != null)
{
html.jsonDetails("Indexed document (JSON)", indexed.source().toString());
}
}
return (html.close().toString());
}
/*******************************************************************************
*******************************************************************************/
private static String valueHtml(String value)
{
if(value == null)
{
return ("<em>none</em>");
}
String shown = value.length() > 500 ? value.substring(0, 500) + "... (" + value.length() + " characters)" : value;
return ("<code>" + DiagnosticsHtml.escape(shown) + "</code>");
}
/*******************************************************************************
** " (time)" for a version that looks like epoch millis.
*******************************************************************************/
private static String versionNote(Long version)
{
return (version != null && version > 946_684_800_000L ? " (" + java.time.Instant.ofEpochMilli(version) + ")" : "");
}
/*******************************************************************************
*******************************************************************************/
private static Set<String> tokenSet(List<AnalyzedToken> tokens)
{
Set<String> set = new LinkedHashSet<>();
for(AnalyzedToken token : tokens)
{
set.add(token.token());
}
return (set);
}
/*******************************************************************************
*******************************************************************************/
private static String text(JsonNode node, String field)
{
if(node == null || !node.has(field) || node.get(field).isNull())
{
return (null);
}
return (blankToNull(node.get(field).isTextual() ? node.get(field).asText() : node.get(field).toString()));
}
/*******************************************************************************
*******************************************************************************/
private static String blankToNull(String value)
{
return (value == null || value.isEmpty() ? null : value);
}
}
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/RecordReindexer.java
+201
View File
@@ -0,0 +1,201 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import com.kingsrook.qqq.backend.core.context.CapturedContext;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.QuickSearchableTableConfig;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml.Level;
import com.kingsrook.qbits.quicksearch.opensearch.BulkIndexResult;
import com.kingsrook.qbits.quicksearch.opensearch.OpenSearchDocument;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchOpenSearchClient;
import com.kingsrook.qbits.quicksearch.processes.IndexingUtils;
/*******************************************************************************
** Reindex chosen records of one table now: each record the user can read is
** rebuilt from the database and written to the index (versioned, so a newer
** document is never overwritten); a record that no longer exists has its
** document removed; a record that exists but that the user cannot read is
** skipped. The one diagnostic tool that writes to the index; it never
** changes a record. A disabled table is refused.
*******************************************************************************/
public class RecordReindexer
{
public static final String OUTCOME_INDEXED = "INDEXED";
public static final String OUTCOME_DELETED = "DELETED";
public static final String OUTCOME_SKIPPED = "SKIPPED";
public static final String OUTCOME_FAILED = "FAILED";
/*******************************************************************************
** What happened to one record.
*******************************************************************************/
public record Outcome(String recordId, String outcome, String message)
{
}
/*******************************************************************************
** Reindex the records of a table by id.
*******************************************************************************/
public List<Outcome> reindex(QuickSearchRuntime runtime, String tableName, List<String> recordIds) throws QException
{
QuickSearchableTableConfig tableConfig = runtime.getTableConfig(tableName);
if(tableConfig == null)
{
throw (new QException("Quick Search does not index table [" + tableName + "]"));
}
if(!runtime.isTableEnabled(tableName))
{
throw (new QException("Table [" + tableName + "] is disabled in Quick Search Index; enable it before reindexing its records"));
}
Set<String> ids = new LinkedHashSet<>(recordIds);
Map<String, QRecord> readable = DiagnosticRecordReads.loadForIndexing(tableName, ids);
Set<String> validIds = new HashSet<>();
DiagnosticRecordReads.typedIds(QContext.getQInstance().getTable(tableName), ids).forEach(id -> validIds.add(String.valueOf(id)));
////////////////////////////////////////////////////////////////////
// ids the user cannot read: exists at all (system view)? if not, //
// the record is gone and its document should go too //
////////////////////////////////////////////////////////////////////
List<String> unreadable = ids.stream().filter(id -> !readable.containsKey(id)).toList();
Set<String> existing = new HashSet<>();
if(!unreadable.isEmpty())
{
List<String> found = new ArrayList<>();
QContext.withTemporaryContext(new CapturedContext(QContext.getQInstance(), new QSystemUserSession()), () ->
found.addAll(DiagnosticRecordReads.existingIds(tableName, unreadable)));
existing.addAll(found);
}
QuickSearchOpenSearchClient client = runtime.getClient();
List<Outcome> outcomes = new ArrayList<>();
List<OpenSearchDocument> docs = new ArrayList<>();
for(String id : ids)
{
QRecord record = readable.get(id);
if(record != null)
{
OpenSearchDocument doc = IndexingUtils.buildDocument(record, tableConfig);
if(doc != null)
{
docs.add(doc);
}
}
}
BulkIndexResult indexResult = client.indexDocuments(docs, Math.max(1, runtime.getConfig().getBulkBatchSize() == null ? 500 : runtime.getConfig().getBulkBatchSize()));
Set<String> failedIds = new HashSet<>();
for(String failure : indexResult.getErrors())
{
////////////////////////////////////////////////////
// failures read "table:recordId: reason" //
////////////////////////////////////////////////////
int reasonStart = failure.indexOf(": ");
String documentId = reasonStart < 0 ? failure : failure.substring(0, reasonStart);
failedIds.add(documentId.substring(documentId.indexOf(':') + 1));
}
List<String> toDelete = new ArrayList<>();
for(String id : ids)
{
if(readable.containsKey(id))
{
outcomes.add(failedIds.contains(id) ? new Outcome(id, OUTCOME_FAILED, "OpenSearch rejected the document; see the run's errors")
: new Outcome(id, OUTCOME_INDEXED, "Rebuilt from the database and written to the index."));
}
else if(!validIds.contains(id))
{
outcomes.add(new Outcome(id, OUTCOME_SKIPPED, "Not a valid id for this table."));
}
else if(existing.contains(id))
{
outcomes.add(new Outcome(id, OUTCOME_SKIPPED, "The record exists but you cannot read it, so it was not reindexed."));
}
else
{
toDelete.add(OpenSearchDocument.buildDocumentId(tableName, id));
outcomes.add(new Outcome(id, OUTCOME_DELETED, "The record no longer exists; its document (if any) was removed."));
}
}
if(!toDelete.isEmpty())
{
BulkIndexResult deleteResult = client.deleteDocuments(toDelete, 500);
if(!deleteResult.getErrors().isEmpty())
{
throw (new QException("Removing documents of deleted records failed: " + String.join("; ", deleteResult.getErrors())));
}
}
if(!indexResult.getErrors().isEmpty())
{
outcomes.add(new Outcome("-", OUTCOME_FAILED, "Index errors: " + String.join("; ", indexResult.getErrors())));
}
client.refreshIndex();
return (outcomes);
}
/*******************************************************************************
** Render outcomes as HTML.
*******************************************************************************/
public static String render(String tableName, List<Outcome> outcomes)
{
DiagnosticsHtml html = new DiagnosticsHtml().open();
html.heading("Reindex in search: " + tableName);
long indexed = outcomes.stream().filter(o -> OUTCOME_INDEXED.equals(o.outcome())).count();
long deleted = outcomes.stream().filter(o -> OUTCOME_DELETED.equals(o.outcome())).count();
long skipped = outcomes.stream().filter(o -> OUTCOME_SKIPPED.equals(o.outcome())).count();
long failed = outcomes.stream().filter(o -> OUTCOME_FAILED.equals(o.outcome())).count();
html.status(failed > 0 ? Level.FAIL : (skipped > 0 ? Level.WARN : Level.OK),
indexed + " reindexed, " + deleted + " removed (record gone), " + skipped + " skipped, " + failed + " failed. The documents are searchable now.");
List<String> items = new ArrayList<>();
for(Outcome outcome : outcomes)
{
Level level = switch(outcome.outcome())
{
case OUTCOME_INDEXED, OUTCOME_DELETED -> Level.OK;
case OUTCOME_SKIPPED -> Level.WARN;
default -> Level.FAIL;
};
items.add(DiagnosticsHtml.badge(level) + " #" + DiagnosticsHtml.escape(outcome.recordId()) + ": " + DiagnosticsHtml.escape(outcome.message()));
}
html.rawList(items);
return (html.close().toString());
}
}
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/SearchPathDiagnosis.java
+178
View File
@@ -0,0 +1,178 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
import com.kingsrook.qqq.backend.core.actions.permissions.TablePermissionSubType;
import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
import com.kingsrook.qqq.backend.core.model.metadata.tables.Capability;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.actions.QuickSearchRecordSearchProvider;
/*******************************************************************************
** Which path the global search (core RecordSearchAction, POST
** /qqq/v1/search) takes for each table, and why: OpenSearch through the
** Quick Search record-search provider, core's own database search, or not
** searched at all. Mirrors RecordSearchAction's table selection and
** QuickSearchRecordSearchProvider.claimsTable without calling them, so a
** diagnosis changes no state (no backoff, no counters).
*******************************************************************************/
public final class SearchPathDiagnosis
{
public static final String PATH_OPENSEARCH = "OpenSearch (Quick Search provider)";
public static final String PATH_CORE = "Core database search";
public static final String PATH_NONE = "Not searched";
/*******************************************************************************
** The record-search provider's state in this JVM.
*******************************************************************************/
public record ProviderState(String registeredProvider, Boolean quickSearchProvider, Boolean serveCoreRecordSearch, Long backoffRemainingMillis,
Long failureCount, Instant lastFailureTime, String lastFailureMessage, Long backoffDeclinedClaims, Integer timeoutMillis, Instant runtimeStartedAt)
{
}
/*******************************************************************************
** One table's path and the reason for it.
*******************************************************************************/
public record TablePath(String tableName, String tableLabel, Boolean indexed, Boolean enabled, Boolean readable, Boolean coreSearchable, String path, String reason)
{
}
/*******************************************************************************
** Utility class - no instances.
*******************************************************************************/
private SearchPathDiagnosis()
{
}
/*******************************************************************************
** The provider's state from the instance and the runtime.
*******************************************************************************/
public static ProviderState providerState(QInstance qInstance, QuickSearchRuntime runtime)
{
QCodeReference provider = qInstance.getRecordSearchProvider();
QuickSearchQBitConfig config = runtime.getConfig();
return (new ProviderState(
provider == null ? null : provider.getName(),
provider != null && QuickSearchRecordSearchProvider.class.getName().equals(provider.getName()),
Boolean.TRUE.equals(config.getServeCoreRecordSearch()),
runtime.getRecordSearchBackoffRemainingMillis(),
runtime.getRecordSearchFailureCount(),
runtime.getLastRecordSearchFailureTime(),
runtime.getLastRecordSearchFailureMessage(),
runtime.getBackoffDeclinedClaimCount(),
config.getRecordSearchTimeoutMillis() == null ? QuickSearchQBitConfig.DEFAULT_RECORD_SEARCH_TIMEOUT_MILLIS : config.getRecordSearchTimeoutMillis(),
runtime.getStartedAt()));
}
/*******************************************************************************
** The path of each named table (unknown names are reported as not
** searched), as seen by the session of permissionInput.
*******************************************************************************/
public static List<TablePath> diagnose(QInstance qInstance, QuickSearchRuntime runtime, List<String> tableNames, AbstractActionInput permissionInput)
{
ProviderState state = providerState(qInstance, runtime);
List<TablePath> paths = new ArrayList<>();
for(String tableName : CollectionUtils.nonNullList(tableNames))
{
paths.add(diagnoseTable(qInstance, runtime, state, tableName, permissionInput));
}
return (paths);
}
/*******************************************************************************
*******************************************************************************/
private static TablePath diagnoseTable(QInstance qInstance, QuickSearchRuntime runtime, ProviderState state, String tableName, AbstractActionInput permissionInput)
{
QTableMetaData table = qInstance.getTable(tableName);
if(table == null)
{
return (new TablePath(tableName, tableName, false, false, false, false, PATH_NONE, "There is no table with this name."));
}
boolean indexed = runtime.getTableConfig(tableName) != null;
boolean enabled = indexed && runtime.isTableEnabled(tableName);
boolean readable = PermissionsHelper.hasTablePermission(permissionInput, tableName, TablePermissionSubType.READ);
boolean coreSearchable = !CollectionUtils.nullSafeIsEmpty(table.getSearchFields()) && table.isCapabilityEnabled(qInstance.getBackendForTable(tableName), Capability.TABLE_QUERY);
String label = table.getLabel() == null ? tableName : table.getLabel();
if(!coreSearchable)
{
return (new TablePath(tableName, label, indexed, enabled, readable, false, PATH_NONE,
"Global search skips this table: it has no core searchFields (or does not support query)."));
}
if(!readable)
{
return (new TablePath(tableName, label, indexed, enabled, false, true, PATH_NONE,
"Global search skips this table for you: you do not have read permission on it."));
}
if(!indexed)
{
return (new TablePath(tableName, label, false, false, true, true, PATH_CORE, "Quick Search does not index this table."));
}
if(!Boolean.TRUE.equals(state.serveCoreRecordSearch()))
{
return (new TablePath(tableName, label, true, enabled, true, true, PATH_CORE, "serveCoreRecordSearch is off in the Quick Search configuration."));
}
if(!Boolean.TRUE.equals(state.quickSearchProvider()))
{
String reason = state.registeredProvider() == null
? "No record search provider is registered on the instance."
: "Another record search provider is registered (" + state.registeredProvider() + "), so Quick Search does not serve global search.";
return (new TablePath(tableName, label, true, enabled, true, true, PATH_CORE, reason));
}
if(!enabled)
{
return (new TablePath(tableName, label, true, false, true, true, PATH_CORE, "The table is disabled in Quick Search Index (enabled = false)."));
}
if(state.backoffRemainingMillis() != null && state.backoffRemainingMillis() > 0)
{
return (new TablePath(tableName, label, true, true, true, true, PATH_CORE,
"Quick Search is backing off for " + Math.max(1, state.backoffRemainingMillis() / 1000) + " more second(s) after an OpenSearch failure"
+ (state.lastFailureTime() == null ? "" : " at " + state.lastFailureTime())
+ (state.lastFailureMessage() == null ? "" : ": " + state.lastFailureMessage())));
}
return (new TablePath(tableName, label, true, true, true, true, PATH_OPENSEARCH,
"Claimed by the Quick Search provider. If OpenSearch fails or takes longer than " + state.timeoutMillis()
+ " ms, core searches this table itself for that request and Quick Search backs off for "
+ (QuickSearchRuntime.RECORD_SEARCH_BACKOFF_MILLIS / 1000) + " seconds."));
}
}
src/main/java/com/kingsrook/qbits/quicksearch/diagnostics/SearchPlayground.java
+654
View File
@@ -0,0 +1,654 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.time.Instant;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.kingsrook.qqq.backend.core.actions.tables.RecordSearchAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.search.RecordSearchInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.search.RecordSearchOutput;
import com.kingsrook.qqq.backend.core.model.actions.tables.search.RecordSearchResult;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
import com.kingsrook.qqq.backend.core.utils.StringUtils;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.QuickSearchableTableConfig;
import com.kingsrook.qbits.quicksearch.actions.QuickSearchAction;
import com.kingsrook.qbits.quicksearch.actions.QuickSearchRecordSearchProvider;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml.Level;
import com.kingsrook.qbits.quicksearch.opensearch.OpenSearchDocument;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations.AnalyzedToken;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations.ExplainResult;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations.ProbeHit;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations.SearchProbe;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchOpenSearchClient;
import com.kingsrook.qbits.quicksearch.processes.IndexingUtils;
/*******************************************************************************
** The search playground: runs a term the way the global search does, as the
** current user, and shows everything behind it.
** 1. Which path serves each table and why (SearchPathDiagnosis).
** 2. The provider's own OpenSearch request (_msearch of record ids), timed,
** without starting a backoff when it fails.
** 3. The real global search (core RecordSearchAction) as the current user:
** what users see, per table, timed. Like any user search, a provider
** failure here starts the provider's normal backoff.
** 4. Per indexed table, the production query with scores, highlights and
** matched clauses, which hits users can read (record locks), which ones
** the global search shows, the query DSL and the raw response (hits the
** user cannot read are redacted to their id).
** 5. Optionally, explain for one hit, and the term's tokens.
** Read-only: no index or record is changed.
*******************************************************************************/
public class SearchPlayground
{
private static final ObjectMapper MAPPER = new ObjectMapper();
/*******************************************************************************
** What to run: term, tables (empty for every searchable table), results per
** table as in the global search, and an optional hit to explain
** ("table:recordId").
*******************************************************************************/
public record Input(String term, List<String> tableNames, Integer limitPerTable, String explainDocumentId)
{
}
/*******************************************************************************
** One table's probe: the search, which hit ids the user can read, which
** the global search showed, and an error when the probe failed.
*******************************************************************************/
public record TableProbe(String tableName, SearchProbe probe, Set<String> readableIds, Set<String> shownIds, Integer hiddenCount, String error)
{
}
/*******************************************************************************
** Everything the playground found.
*******************************************************************************/
public record Report(String term, List<String> notices, List<AnalyzedToken> termTokens, String termTokensError,
SearchPathDiagnosis.ProviderState providerState, List<SearchPathDiagnosis.TablePath> paths,
Map<String, List<String>> providerIds, Map<String, Integer> providerHiddenCounts, Long providerMillis, String providerError,
Map<String, List<RecordSearchResult>> coreResults, Long coreMillis, String coreError,
List<TableProbe> probes, String explainDocumentId, ExplainResult explain, String explainError,
Integer limitPerTable, Integer idsPerTable)
{
}
/*******************************************************************************
** Run the playground for the input as the current session.
*******************************************************************************/
public Report run(QuickSearchRuntime runtime, Input input, AbstractActionInput permissionInput)
{
QInstance qInstance = QContext.getQInstance();
QuickSearchQBitConfig config = runtime.getConfig();
List<String> notices = new ArrayList<>();
String term = IndexingUtils.normalizeSearchText(input.term());
int limitPerTable = input.limitPerTable() == null || input.limitPerTable() <= 0 ? RecordSearchAction.DEFAULT_LIMIT_PER_TABLE : Math.min(input.limitPerTable(), RecordSearchAction.MAX_LIMIT_PER_TABLE);
int idsPerTable = Math.min(RecordSearchAction.MAX_PROVIDER_IDS_PER_TABLE, limitPerTable * QuickSearchRecordSearchProvider.IDS_PER_LIMIT_MULTIPLIER);
List<String> tables = resolveTables(qInstance, runtime, input.tableNames(), notices);
List<SearchPathDiagnosis.TablePath> paths = SearchPathDiagnosis.diagnose(qInstance, runtime, tables, permissionInput);
SearchPathDiagnosis.ProviderState state = SearchPathDiagnosis.providerState(qInstance, runtime);
if(term.length() < QuickSearchAction.MIN_TERM_LENGTH)
{
notices.add("The term is shorter than " + QuickSearchAction.MIN_TERM_LENGTH + " characters: the Quick Search provider returns nothing for it, so only core's own search can match.");
}
if(term.length() > RecordSearchAction.MAX_SEARCH_TERM_LENGTH)
{
notices.add("The term is longer than " + RecordSearchAction.MAX_SEARCH_TERM_LENGTH + " characters: the global search rejects it.");
}
QuickSearchDiagnosticsOperations ops = null;
String opsError = null;
try
{
ops = new QuickSearchDiagnosticsOperations(runtime.getClient());
}
catch(QException e)
{
opsError = e.getMessage();
notices.add("The OpenSearch client could not be built: " + e.getMessage());
}
////////////////////////
// term tokens //
////////////////////////
List<AnalyzedToken> termTokens = null;
String termTokensError = opsError;
if(ops != null && StringUtils.hasContent(term))
{
try
{
termTokens = ops.analyze(QuickSearchOpenSearchClient.SEARCH_ANALYZER, term);
}
catch(QException e)
{
termTokensError = e.getMessage();
}
}
///////////////////////////////////////////////////////////
// the provider's own request, for the tables it claims //
///////////////////////////////////////////////////////////
List<String> claimed = paths.stream().filter(p -> SearchPathDiagnosis.PATH_OPENSEARCH.equals(p.path())).map(SearchPathDiagnosis.TablePath::tableName).toList();
Map<String, List<String>> providerIds = null;
Map<String, Integer> providerHidden = new LinkedHashMap<>();
Long providerMillis = null;
String providerError = null;
if(!claimed.isEmpty() && ops != null && term.length() >= QuickSearchAction.MIN_TERM_LENGTH)
{
int timeout = state.timeoutMillis();
long start = System.currentTimeMillis();
try
{
providerIds = runtime.getClient().searchRecordIdsPerTable(term, claimed, idsPerTable, runtime.getDiscoveredTables(), timeout);
}
catch(QException | RuntimeException e)
{
providerError = e.getClass().getSimpleName() + ": " + e.getMessage();
}
providerMillis = System.currentTimeMillis() - start;
providerIds = providerIds == null ? null : readableOnly(providerIds, providerHidden);
}
///////////////////////////////////////////////////////
// the real global search, as the current user //
///////////////////////////////////////////////////////
Map<String, List<RecordSearchResult>> coreResults = new LinkedHashMap<>();
Long coreMillis = null;
String coreError = null;
List<String> searched = paths.stream().filter(p -> !SearchPathDiagnosis.PATH_NONE.equals(p.path())).map(SearchPathDiagnosis.TablePath::tableName).toList();
if(!searched.isEmpty() && StringUtils.hasContent(term))
{
long start = System.currentTimeMillis();
try
{
RecordSearchOutput output = new RecordSearchAction().execute(new RecordSearchInput().withSearchTerm(term).withTableNames(searched).withLimitPerTable(limitPerTable));
for(RecordSearchResult result : CollectionUtils.nonNullList(output.getResults()))
{
coreResults.computeIfAbsent(result.getTableName(), k -> new ArrayList<>()).add(result);
}
}
catch(Exception e)
{
coreError = e.getClass().getSimpleName() + ": " + e.getMessage();
}
coreMillis = System.currentTimeMillis() - start;
}
//////////////////////////////////////////
// per indexed table, the probe search //
//////////////////////////////////////////
List<TableProbe> probes = new ArrayList<>();
for(SearchPathDiagnosis.TablePath path : paths)
{
if(!Boolean.TRUE.equals(path.indexed()) || !Boolean.TRUE.equals(path.readable()) || term.length() < QuickSearchAction.MIN_TERM_LENGTH)
{
continue;
}
if(ops == null)
{
probes.add(new TableProbe(path.tableName(), null, Set.of(), Set.of(), 0, opsError));
continue;
}
probes.add(probeTable(ops, runtime, term, path.tableName(), idsPerTable, coreResults.get(path.tableName())));
}
//////////////////////
// explain one hit //
//////////////////////
ExplainResult explain = null;
String explainError = null;
String explainId = StringUtils.hasContent(input.explainDocumentId()) ? input.explainDocumentId().trim() : null;
if(explainId != null && ops != null)
{
try
{
explain = explainHit(ops, runtime, term, explainId);
}
catch(QException e)
{
explainError = e.getMessage();
}
}
return (new Report(term, notices, termTokens, termTokensError, state, paths, providerIds, providerHidden, providerMillis, providerError,
coreResults, coreMillis, coreError, probes, explainId, explain, explainError, limitPerTable, idsPerTable));
}
/*******************************************************************************
** The requested tables that exist (else every table with core searchFields
** or a Quick Search index), in instance order.
*******************************************************************************/
static List<String> resolveTables(QInstance qInstance, QuickSearchRuntime runtime, List<String> requested, List<String> notices)
{
List<String> tables = new ArrayList<>();
if(!CollectionUtils.nullSafeIsEmpty(requested))
{
for(String tableName : new LinkedHashSet<>(requested))
{
if(qInstance.getTable(tableName) == null)
{
notices.add("Ignored unknown table [" + tableName + "].");
}
else
{
tables.add(tableName);
}
}
return (tables);
}
for(QTableMetaData table : CollectionUtils.nonNullMap(qInstance.getTables()).values())
{
if(!CollectionUtils.nullSafeIsEmpty(table.getSearchFields()) || runtime.getTableConfig(table.getName()) != null)
{
tables.add(table.getName());
}
}
return (tables);
}
/*******************************************************************************
** Probe one table and mark which hits the user can read and which ones the
** global search showed.
*******************************************************************************/
private TableProbe probeTable(QuickSearchDiagnosticsOperations ops, QuickSearchRuntime runtime, String term, String tableName, int size, List<RecordSearchResult> shown)
{
try
{
SearchProbe probe = ops.probeSearch(term, tableName, size, runtime.getDiscoveredTables());
List<String> ids = probe.hits().stream().map(ProbeHit::recordId).toList();
Set<String> readable = new HashSet<>(DiagnosticRecordReads.existingIds(tableName, ids));
Set<String> shownIds = new HashSet<>();
for(RecordSearchResult result : CollectionUtils.nonNullList(shown))
{
shownIds.add(String.valueOf(result.getRecordId()));
}
List<ProbeHit> visible = probe.hits().stream().filter(h -> readable.contains(h.recordId())).toList();
int hidden = probe.hits().size() - visible.size();
SearchProbe redacted = new SearchProbe(probe.tableName(), probe.requestJson(), redactResponse(probe.responseJson(), readable),
probe.tookMillis(), probe.wallMillis(), hidden == 0 ? probe.totalHits() : null, probe.totalIsLowerBound(), visible);
return (new TableProbe(tableName, redacted, readable, shownIds, hidden, null));
}
catch(QException e)
{
return (new TableProbe(tableName, null, Set.of(), Set.of(), 0, e.getMessage()));
}
}
/*******************************************************************************
** The provider's ids per table, keeping only records the user can read;
** how many were dropped goes in hiddenCounts. Ids of records the user
** cannot read are never shown (they would reveal what a locked record
** contains).
*******************************************************************************/
static Map<String, List<String>> readableOnly(Map<String, List<String>> idsByTable, Map<String, Integer> hiddenCounts)
{
Map<String, List<String>> readable = new LinkedHashMap<>();
for(Map.Entry<String, List<String>> entry : idsByTable.entrySet())
{
List<String> ids = entry.getValue() == null ? List.of() : entry.getValue();
Set<String> ok;
try
{
ok = new HashSet<>(DiagnosticRecordReads.existingIds(entry.getKey(), ids));
}
catch(QException e)
{
ok = Set.of();
}
Set<String> finalOk = ok;
readable.put(entry.getKey(), ids.stream().filter(finalOk::contains).toList());
hiddenCounts.put(entry.getKey(), (int) ids.stream().filter(id -> !finalOk.contains(id)).count());
}
return (readable);
}
/*******************************************************************************
** The raw response without the hits the user cannot read: they are
** removed whole (id, score, source, highlights, matched queries), and
** when any was removed the total and max score are redacted too, so the
** response reveals nothing about records the user cannot read.
*******************************************************************************/
static String redactResponse(String responseJson, Set<String> readableIds)
{
try
{
JsonNode root = MAPPER.readTree(responseJson);
JsonNode hitList = root.path("hits").path("hits");
int removed = 0;
if(hitList.isArray())
{
ArrayNode array = (ArrayNode) hitList;
for(int i = array.size() - 1; i >= 0; i--)
{
String recordId = array.get(i).path("_source").path("recordId").asText(null);
if(recordId == null || !readableIds.contains(recordId))
{
array.remove(i);
removed++;
}
}
}
if(removed > 0 && root.path("hits") instanceof ObjectNode hits)
{
hits.put("total", "redacted: " + removed + " hit(s) you cannot read were removed");
hits.remove("max_score");
}
return (root.toString());
}
catch(Exception e)
{
return ("{\"redacted\":\"response could not be parsed for redaction\"}");
}
}
/*******************************************************************************
** Explain one hit ("table:recordId") when the table is indexed and the user
** can read the record.
*******************************************************************************/
private ExplainResult explainHit(QuickSearchDiagnosticsOperations ops, QuickSearchRuntime runtime, String term, String documentId) throws QException
{
int colon = documentId.indexOf(':');
if(colon <= 0 || colon == documentId.length() - 1)
{
throw (new QException("Give the hit as table:recordId (its document id), for example blogPost:42"));
}
String tableName = documentId.substring(0, colon);
String recordId = documentId.substring(colon + 1);
QuickSearchableTableConfig tableConfig = runtime.getTableConfig(tableName);
if(tableConfig == null)
{
throw (new QException("Table [" + tableName + "] is not indexed by Quick Search"));
}
if(DiagnosticRecordReads.existingIds(tableName, List.of(recordId)).isEmpty())
{
throw (new QException("Record " + recordId + " of [" + tableName + "] does not exist or you cannot read it"));
}
return (ops.explain(term, tableName, recordId, runtime.getDiscoveredTables()));
}
/*******************************************************************************
** Render a report as HTML.
*******************************************************************************/
public static String render(Report report)
{
DiagnosticsHtml html = new DiagnosticsHtml().open();
html.heading("Search playground: \"" + report.term() + "\"");
html.paragraph("Run as you, at " + Instant.now() + ". The global search shows up to " + report.limitPerTable() + " results per table; the Quick Search provider asks OpenSearch for the top "
+ report.idsPerTable() + " ids per table and core keeps the first " + report.limitPerTable() + " you can read.");
for(String notice : report.notices())
{
html.status(Level.WARN, notice);
}
renderProviderState(html, report.providerState());
html.subheading("Path per table");
List<String> pathItems = new ArrayList<>();
for(SearchPathDiagnosis.TablePath path : report.paths())
{
Level level = SearchPathDiagnosis.PATH_OPENSEARCH.equals(path.path()) ? Level.OK : (SearchPathDiagnosis.PATH_CORE.equals(path.path()) ? Level.INFO : Level.WARN);
pathItems.add(DiagnosticsHtml.badge(level) + " <strong>" + DiagnosticsHtml.escape(path.tableLabel()) + "</strong> (" + DiagnosticsHtml.escape(path.tableName()) + "): "
+ DiagnosticsHtml.escape(path.path()) + ". " + DiagnosticsHtml.escape(path.reason()));
}
if(pathItems.isEmpty())
{
html.paragraph("No table is searchable by the global search.");
}
html.rawList(pathItems);
html.subheading("Term tokens (search analyzer)");
if(report.termTokensError() != null)
{
html.status(Level.FAIL, "Could not analyze the term: " + report.termTokensError());
}
else if(report.termTokens() != null)
{
html.paragraph(tokenSummary(report.termTokens()));
for(AnalyzedToken token : report.termTokens())
{
if(token.token().length() < 2)
{
html.status(Level.WARN, "\"" + token.token() + "\" is one character: the index holds edge n-grams of 2 to 20 characters, so it can never match, and every term must match.");
}
else if(token.token().length() > 20)
{
html.status(Level.WARN, "\"" + token.token() + "\" is longer than 20 characters: the index holds edge n-grams of at most 20 characters, so it can never match.");
}
}
}
html.subheading("Quick Search provider request");
if(report.providerMillis() == null)
{
html.paragraph("Not run: the provider claims none of these tables (see the paths above), or the term is too short.");
}
else if(report.providerError() != null)
{
html.status(Level.FAIL, "Failed after " + report.providerMillis() + " ms: " + report.providerError() + ". A user search hitting this falls back to core's database search for these tables.");
}
else
{
html.status(Level.OK, "Answered in " + report.providerMillis() + " ms (wall clock, limit " + report.providerState().timeoutMillis() + " ms).");
List<String> items = new ArrayList<>();
for(Map.Entry<String, List<String>> entry : report.providerIds().entrySet())
{
Integer hidden = report.providerHiddenCounts().getOrDefault(entry.getKey(), 0);
items.add("<strong>" + DiagnosticsHtml.escape(entry.getKey()) + "</strong>: " + entry.getValue().size() + " id(s) you can read"
+ (hidden > 0 ? " (" + hidden + " more you cannot read, not shown)" : "")
+ (entry.getValue().isEmpty() ? "" : ": " + DiagnosticsHtml.escape(String.join(", ", entry.getValue().subList(0, Math.min(20, entry.getValue().size()))))
+ (entry.getValue().size() > 20 ? ", ..." : "")));
}
html.rawList(items);
}
html.subheading("Global search results (what you see)");
if(report.coreMillis() == null)
{
html.paragraph("Not run: no table is searchable, or the term is empty.");
}
else if(report.coreError() != null)
{
html.status(Level.FAIL, "The global search failed after " + report.coreMillis() + " ms: " + report.coreError());
}
else
{
int total = report.coreResults().values().stream().mapToInt(List::size).sum();
html.status(total == 0 ? Level.INFO : Level.OK, total + " result(s) in " + report.coreMillis() + " ms.");
List<String> items = new ArrayList<>();
for(Map.Entry<String, List<RecordSearchResult>> entry : report.coreResults().entrySet())
{
List<String> labels = new ArrayList<>();
for(RecordSearchResult result : entry.getValue())
{
labels.add(DiagnosticsHtml.escape(result.getRecordLabel() == null ? String.valueOf(result.getRecordId()) : result.getRecordLabel()) + " (#" + DiagnosticsHtml.escape(result.getRecordId()) + ")");
}
items.add("<strong>" + DiagnosticsHtml.escape(entry.getKey()) + "</strong>: " + String.join("; ", labels));
}
html.rawList(items);
}
html.subheading("OpenSearch detail per indexed table");
if(report.probes().isEmpty())
{
html.paragraph("No indexed table you can read was searched, or the term is too short.");
}
for(TableProbe tableProbe : report.probes())
{
renderProbe(html, tableProbe);
}
if(report.explainDocumentId() != null)
{
html.subheading("Explain " + report.explainDocumentId());
if(report.explainError() != null)
{
html.status(Level.FAIL, report.explainError());
}
else if(report.explain() != null && !Boolean.TRUE.equals(report.explain().documentFound()))
{
html.status(Level.FAIL, "There is no document " + report.explainDocumentId() + " in the index.");
}
else if(report.explain() != null)
{
html.status(Boolean.TRUE.equals(report.explain().matched()) ? Level.OK : Level.WARN,
Boolean.TRUE.equals(report.explain().matched()) ? "Matches with score " + report.explain().score() + "." : "Does not match this term.");
html.textDetails("Score explanation", report.explain().explanationText());
html.jsonDetails("Explain response (JSON)", report.explain().json());
}
}
return (html.close().toString());
}
/*******************************************************************************
*******************************************************************************/
private static void renderProviderState(DiagnosticsHtml html, SearchPathDiagnosis.ProviderState state)
{
html.subheading("Record search provider (this server)");
List<String[]> facts = new ArrayList<>();
facts.add(new String[] { "Registered provider", state.registeredProvider() == null ? null : state.registeredProvider() + (Boolean.TRUE.equals(state.quickSearchProvider()) ? " (Quick Search)" : " (not Quick Search)") });
facts.add(new String[] { "serveCoreRecordSearch", String.valueOf(state.serveCoreRecordSearch()) });
facts.add(new String[] { "Timeout", state.timeoutMillis() + " ms" });
facts.add(new String[] { "Backing off", state.backoffRemainingMillis() > 0 ? "yes, " + (state.backoffRemainingMillis() / 1000) + " s left" : "no" });
facts.add(new String[] { "Failures since " + state.runtimeStartedAt(), String.valueOf(state.failureCount()) });
facts.add(new String[] { "Table searches core ran itself during backoffs", String.valueOf(state.backoffDeclinedClaims()) });
facts.add(new String[] { "Last failure", state.lastFailureTime() == null ? null : state.lastFailureTime() + ": " + state.lastFailureMessage() });
html.facts(facts);
}
/*******************************************************************************
*******************************************************************************/
private static void renderProbe(DiagnosticsHtml html, TableProbe tableProbe)
{
html.raw("<h4>" + DiagnosticsHtml.escape(tableProbe.tableName()) + "</h4>");
if(tableProbe.error() != null)
{
html.status(Level.FAIL, "OpenSearch search failed: " + tableProbe.error());
return;
}
SearchProbe probe = tableProbe.probe();
html.paragraph((probe.totalHits() == null ? "Matching documents: not shown (some are records you cannot read)"
: probe.totalHits() + (Boolean.TRUE.equals(probe.totalIsLowerBound()) ? "+" : "") + " matching document(s)")
+ "; OpenSearch took " + probe.tookMillis() + " ms (" + probe.wallMillis() + " ms wall clock). Showing the " + probe.hits().size() + " top hit(s) you can read.");
if(tableProbe.hiddenCount() != null && tableProbe.hiddenCount() > 0)
{
html.status(Level.INFO, tableProbe.hiddenCount() + " of the top hits are records you cannot read (deleted, or hidden by a record security lock); they are not shown.");
}
List<String> items = new ArrayList<>();
int position = 0;
for(ProbeHit hit : probe.hits())
{
position++;
StringBuilder item = new StringBuilder();
item.append("#").append(position).append(" <strong>")
.append(DiagnosticsHtml.escape(hit.recordLabel() == null ? "(no label)" : hit.recordLabel()))
.append("</strong> &middot; document <code>").append(DiagnosticsHtml.escape(OpenSearchDocument.buildDocumentId(tableProbe.tableName(), hit.recordId()))).append("</code>")
.append(" &middot; score ").append(hit.score() == null ? "n/a" : String.format("%.3f", hit.score()))
.append(" &middot; ").append(tableProbe.shownIds().contains(hit.recordId()) ? "shown in global search" : "not shown (beyond the per-table limit)");
if(!hit.matchedClauses().isEmpty())
{
List<String> fields = hit.matchedClauses().stream().map(c -> c.startsWith(QuickSearchOpenSearchClient.FIELD_CLAUSE_PREFIX) ? c.substring(QuickSearchOpenSearchClient.FIELD_CLAUSE_PREFIX.length()) : c).toList();
item.append("<br>Matched: ").append(DiagnosticsHtml.escape(String.join(", ", fields)));
}
for(Map.Entry<String, List<String>> highlight : hit.highlights().entrySet())
{
item.append("<br><em>").append(DiagnosticsHtml.escape(highlight.getKey())).append(":</em> ")
.append(DiagnosticsHtml.highlight(String.join(" ... ", highlight.getValue())));
}
items.add(item.toString());
}
if(items.isEmpty())
{
html.paragraph("No document of this table that you can read matches every term.");
}
html.rawList(items);
html.jsonDetails("Query DSL", probe.requestJson());
html.jsonDetails("Raw response (hits you cannot read removed)", probe.responseJson());
}
/*******************************************************************************
** "a, b, c" of token strings.
*******************************************************************************/
static String tokenSummary(List<AnalyzedToken> tokens)
{
if(tokens.isEmpty())
{
return ("No tokens: the term has no searchable characters.");
}
List<String> parts = new ArrayList<>();
for(AnalyzedToken token : tokens)
{
parts.add("\"" + token.token() + "\"");
}
return (tokens.size() + " token(s), all of which must match: " + String.join(", ", parts));
}
}
src/main/java/com/kingsrook/qbits/quicksearch/metadata/QuickSearchAdminAppMetaDataProducer.java
+13 -1
View File
@@ -17,9 +17,12 @@
package com.kingsrook.qbits.quicksearch.metadata;
import java.util.ArrayList;
import java.util.List;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
@@ -27,9 +30,11 @@ import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitComponentMetaData
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitProductionContext;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
import com.kingsrook.qbits.quicksearch.model.QuickSearchFailedEvent;
import com.kingsrook.qbits.quicksearch.model.QuickSearchIndex;
import com.kingsrook.qbits.quicksearch.model.QuickSearchIndexRun;
import com.kingsrook.qbits.quicksearch.model.QuickSearchValidationRun;
/*******************************************************************************
@@ -62,7 +67,14 @@ public class QuickSearchAdminAppMetaDataProducer extends QBitComponentMetaDataPr
return (app);
}
for(String tableName : new String[] { QuickSearchIndex.TABLE_NAME, QuickSearchIndexRun.TABLE_NAME, QuickSearchFailedEvent.TABLE_NAME })
QWidgetMetaData diagnosticsWidget = produced.get(QWidgetMetaData.class, config.applyPrefix(QuickSearchDiagnosticsWidgetMetaDataProducer.WIDGET_NAME));
if(diagnosticsWidget != null)
{
app.withWidgets(new ArrayList<>(List.of(diagnosticsWidget.getName())));
}
for(String tableName : new String[] { QuickSearchIndex.TABLE_NAME, QuickSearchIndexRun.TABLE_NAME, QuickSearchFailedEvent.TABLE_NAME,
QuickSearchValidationRun.TABLE_NAME, QuickSearchDiagnosticEvent.TABLE_NAME })
{
QTableMetaData table = produced.get(QTableMetaData.class, config.applyPrefix(tableName));
if(table != null)
src/main/java/com/kingsrook/qbits/quicksearch/metadata/QuickSearchDiagnosticEventTableMetaDataProducer.java
+62
View File
@@ -0,0 +1,62 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.metadata;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitComponentMetaDataProducer;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
/*******************************************************************************
** Produces the quickSearchDiagnosticEvent table when enableDiagnosticTools is true.
*******************************************************************************/
public class QuickSearchDiagnosticEventTableMetaDataProducer extends QBitComponentMetaDataProducer<QTableMetaData, QuickSearchQBitConfig>
{
/*******************************************************************************
*******************************************************************************/
@Override
public QTableMetaData produce(QInstance qInstance) throws QException
{
return (QuickSearchTableMetaDataHelper.buildDiagnosticEventTable(getQBitConfig()));
}
/*******************************************************************************
*******************************************************************************/
@Override
public boolean isEnabled()
{
return (getQBitConfig() != null && Boolean.TRUE.equals(getQBitConfig().getEnableDiagnosticTools()));
}
/*******************************************************************************
** tables before processes and the app
*******************************************************************************/
@Override
public int getSortOrder()
{
return (100);
}
}
src/main/java/com/kingsrook/qbits/quicksearch/metadata/QuickSearchDiagnosticsProcessMetaDataHelper.java
+279
View File
@@ -0,0 +1,279 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.metadata;
import java.util.ArrayList;
import java.util.List;
import com.kingsrook.qqq.backend.core.actions.tables.RecordSearchAction;
import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
import com.kingsrook.qqq.backend.core.model.metadata.permissions.QPermissionRules;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QComponentType;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendComponentMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QFunctionInputMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QRecordListMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.scheduleing.QScheduleMetaData;
import com.kingsrook.qqq.backend.core.utils.StringUtils;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.model.QuickSearchFailedEvent;
import com.kingsrook.qbits.quicksearch.processes.diagnostics.AbstractDiagnosticToolStep;
import com.kingsrook.qbits.quicksearch.processes.diagnostics.AnalyzeTextStep;
import com.kingsrook.qbits.quicksearch.processes.diagnostics.InspectRecordStep;
import com.kingsrook.qbits.quicksearch.processes.diagnostics.ReindexRecordsStep;
import com.kingsrook.qbits.quicksearch.processes.diagnostics.SearchPlaygroundStep;
import com.kingsrook.qbits.quicksearch.processes.diagnostics.ValidateIndexStep;
/*******************************************************************************
** Builds the diagnostic tool processes. Every one is a table or record
** action (it has a tableName and is never added to an app's nav):
** - on Quick Search Index: Search Playground, Validate Search Index (also
** schedulable), Test Search Analyzer;
** - on every indexed table and on Quick Search Failed Event: Inspect Search
** Document and Reindex in Search.
** Read-only tools use debugPermissionRules; Reindex in Search uses
** adminPermissionRules.
*******************************************************************************/
public class QuickSearchDiagnosticsProcessMetaDataHelper
{
public static final String PLAYGROUND_PROCESS_NAME = "quickSearchPlayground";
public static final String VALIDATE_PROCESS_NAME = "quickSearchValidateIndex";
public static final String ANALYZE_PROCESS_NAME = "quickSearchAnalyzeText";
public static final String INSPECT_PROCESS_PREFIX = "quickSearchInspect";
public static final String REINDEX_RECORDS_PROCESS_PREFIX = "quickSearchReindexRecords";
/*******************************************************************************
** Name of the Inspect Search Document process of a table.
*******************************************************************************/
public static String inspectProcessName(QuickSearchQBitConfig config, String tableName)
{
return (config.applyPrefix(INSPECT_PROCESS_PREFIX) + "_" + tableName);
}
/*******************************************************************************
** Name of the Reindex in Search process of a table.
*******************************************************************************/
public static String reindexRecordsProcessName(QuickSearchQBitConfig config, String tableName)
{
return (config.applyPrefix(REINDEX_RECORDS_PROCESS_PREFIX) + "_" + tableName);
}
/*******************************************************************************
** Search Playground, a table action on Quick Search Index.
*******************************************************************************/
public static QProcessMetaData buildPlaygroundProcess(QuickSearchQBitConfig config)
{
return (new QProcessMetaData()
.withName(config.applyPrefix(PLAYGROUND_PROCESS_NAME))
.withLabel("Search Playground")
.withIcon(new QIcon("travel_explore"))
.withTableName(config.getQuickSearchIndexTableName())
.withMinInputRecords(0)
.withPermissionRules(clone(config.getDebugPermissionRules()))
.withStep(backend(SearchPlaygroundStep.class, AbstractDiagnosticToolStep.STEP_PREPARE, null))
.withStep(form("Search", List.of(
new QFieldMetaData(SearchPlaygroundStep.FIELD_TERM, QFieldType.STRING).withLabel("Search term").withIsRequired(true).withMaxLength(RecordSearchAction.MAX_SEARCH_TERM_LENGTH),
new QFieldMetaData(SearchPlaygroundStep.FIELD_TABLES, QFieldType.STRING).withLabel("Tables (optional; names separated by commas)"),
new QFieldMetaData(SearchPlaygroundStep.FIELD_LIMIT_PER_TABLE, QFieldType.INTEGER).withLabel("Results per table").withDefaultValue(RecordSearchAction.DEFAULT_LIMIT_PER_TABLE),
new QFieldMetaData(SearchPlaygroundStep.FIELD_EXPLAIN_HIT, QFieldType.STRING).withLabel("Explain hit (optional document id, e.g. blogPost:42)"))))
.withStep(backend(SearchPlaygroundStep.class, AbstractDiagnosticToolStep.STEP_RUN, null)));
}
/*******************************************************************************
** Test Search Analyzer, a table action on Quick Search Index.
*******************************************************************************/
public static QProcessMetaData buildAnalyzeProcess(QuickSearchQBitConfig config)
{
return (new QProcessMetaData()
.withName(config.applyPrefix(ANALYZE_PROCESS_NAME))
.withLabel("Test Search Analyzer")
.withIcon(new QIcon("text_fields"))
.withTableName(config.getQuickSearchIndexTableName())
.withMinInputRecords(0)
.withPermissionRules(clone(config.getDebugPermissionRules()))
.withStep(backend(AnalyzeTextStep.class, AbstractDiagnosticToolStep.STEP_PREPARE, null))
.withStep(form("Analyze", List.of(
new QFieldMetaData(AnalyzeTextStep.FIELD_TEXT, QFieldType.TEXT).withLabel("Text (as a field value)").withIsRequired(true),
new QFieldMetaData(AnalyzeTextStep.FIELD_QUERY, QFieldType.STRING).withLabel("Search term (optional)").withMaxLength(RecordSearchAction.MAX_SEARCH_TERM_LENGTH))))
.withStep(backend(AnalyzeTextStep.class, AbstractDiagnosticToolStep.STEP_RUN, null)));
}
/*******************************************************************************
** Validate Search Index, a table action on Quick Search Index; scheduled
** by cron when validationCronExpression and a schedulerName are set.
*******************************************************************************/
public static QProcessMetaData buildValidateProcess(QuickSearchQBitConfig config)
{
QProcessMetaData process = new QProcessMetaData()
.withName(config.applyPrefix(VALIDATE_PROCESS_NAME))
.withLabel("Validate Search Index")
.withIcon(new QIcon("fact_check"))
.withTableName(config.getQuickSearchIndexTableName())
.withMinInputRecords(0)
.withPermissionRules(clone(config.getDebugPermissionRules()))
.withStep(backend(ValidateIndexStep.class, AbstractDiagnosticToolStep.STEP_PREPARE, null))
.withStep(form("Validate", List.of(
new QFieldMetaData(ValidateIndexStep.FIELD_SAMPLE_SIZE, QFieldType.INTEGER).withLabel("Records and documents to sample per table")
.withDefaultValue(config.getValidationSampleSize()))))
.withStep(backend(ValidateIndexStep.class, AbstractDiagnosticToolStep.STEP_RUN, null))
.withStep(result(AbstractDiagnosticToolStep.STEP_RESULT, "Validation report"));
if(StringUtils.hasContent(config.getSchedulerName()) && StringUtils.hasContent(config.getValidationCronExpression()))
{
process.withSchedule(new QScheduleMetaData()
.withSchedulerName(config.getSchedulerName())
.withCronExpression(config.getValidationCronExpression())
.withCronTimeZoneId(config.getValidationCronTimeZoneId())
.withDescription("Quick Search index validation"));
}
return (process);
}
/*******************************************************************************
** Inspect Search Document, a record action on a table (an indexed table,
** or Quick Search Failed Event for the event's record).
*******************************************************************************/
public static QProcessMetaData buildInspectProcess(QuickSearchQBitConfig config, String tableName)
{
return (new QProcessMetaData()
.withName(inspectProcessName(config, tableName))
.withLabel("Inspect Search Document")
.withIcon(new QIcon("manage_search"))
.withTableName(tableName)
.withMinInputRecords(1)
.withMaxInputRecords(InspectRecordStep.MAX_RECORDS)
.withPermissionRules(clone(config.getDebugPermissionRules()))
.withStep(backend(InspectRecordStep.class, AbstractDiagnosticToolStep.STEP_PREPARE, tableName))
.withStep(form("Inspect", List.of(
new QFieldMetaData(InspectRecordStep.FIELD_TERM, QFieldType.STRING).withLabel("Why doesn't it match... (optional search term)")
.withMaxLength(RecordSearchAction.MAX_SEARCH_TERM_LENGTH))))
.withStep(backend(InspectRecordStep.class, AbstractDiagnosticToolStep.STEP_RUN, null)));
}
/*******************************************************************************
** Reindex in Search, a record action on a table (an indexed table, or
** Quick Search Failed Event for the event's record). Writes to the index,
** so it uses the admin permission rules.
*******************************************************************************/
public static QProcessMetaData buildReindexRecordsProcess(QuickSearchQBitConfig config, String tableName)
{
return (new QProcessMetaData()
.withName(reindexRecordsProcessName(config, tableName))
.withLabel("Reindex in Search")
.withIcon(new QIcon("sync"))
.withTableName(tableName)
.withMinInputRecords(1)
.withMaxInputRecords(ReindexRecordsStep.MAX_RECORDS)
.withPermissionRules(clone(config.getAdminPermissionRules()))
.withStep(backend(ReindexRecordsStep.class, AbstractDiagnosticToolStep.STEP_PREPARE, tableName))
.withStep(result(AbstractDiagnosticToolStep.STEP_CONFIRM, "Confirm"))
.withStep(backend(ReindexRecordsStep.class, AbstractDiagnosticToolStep.STEP_RUN, null))
.withStep(result(AbstractDiagnosticToolStep.STEP_RESULT, "Reindexed")));
}
/*******************************************************************************
** The fixed processes (on Quick Search Index and Quick Search Failed
** Event).
*******************************************************************************/
public static List<QProcessMetaData> buildFixedProcesses(QuickSearchQBitConfig config)
{
List<QProcessMetaData> processes = new ArrayList<>();
processes.add(buildPlaygroundProcess(config));
processes.add(buildValidateProcess(config));
processes.add(buildAnalyzeProcess(config));
processes.add(buildInspectProcess(config, config.applyPrefix(QuickSearchFailedEvent.TABLE_NAME)));
processes.add(buildReindexRecordsProcess(config, config.applyPrefix(QuickSearchFailedEvent.TABLE_NAME)));
return (processes);
}
/*******************************************************************************
** A backend step of a tool; with recordsTableName, the step receives the
** selected records of that table.
*******************************************************************************/
private static QBackendStepMetaData backend(Class<?> stepClass, String name, String recordsTableName)
{
QBackendStepMetaData step = new QBackendStepMetaData().withName(name).withCode(new QCodeReference(stepClass));
if(recordsTableName != null)
{
step.withInputData(new QFunctionInputMetaData().withRecordListMetaData(new QRecordListMetaData().withTableName(recordsTableName)));
}
return (step);
}
/*******************************************************************************
** The FORM step: fields above, the tool's HTML below.
*******************************************************************************/
private static QFrontendStepMetaData form(String label, List<QFieldMetaData> fields)
{
QFrontendStepMetaData step = new QFrontendStepMetaData()
.withName(AbstractDiagnosticToolStep.STEP_FORM)
.withLabel(label)
.withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM))
.withComponent(new QFrontendComponentMetaData().withType(QComponentType.HTML));
fields.forEach(step::withFormField);
return (step);
}
/*******************************************************************************
** An HTML-only frontend step.
*******************************************************************************/
private static QFrontendStepMetaData result(String name, String label)
{
return (new QFrontendStepMetaData()
.withName(name)
.withLabel(label)
.withComponent(new QFrontendComponentMetaData().withType(QComponentType.HTML)));
}
/*******************************************************************************
*******************************************************************************/
private static QPermissionRules clone(QPermissionRules rules)
{
return (rules == null ? null : rules.clone());
}
}
src/main/java/com/kingsrook/qbits/quicksearch/metadata/QuickSearchDiagnosticsProcessesMetaDataProducer.java
+72
View File
@@ -0,0 +1,72 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.metadata;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitComponentMetaDataProducer;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
/*******************************************************************************
** Produces the fixed diagnostic tool processes (Search Playground, Validate
** Search Index, Test Search Analyzer, and Inspect / Reindex on Quick Search
** Failed Event) when enableDiagnosticTools is true. The per-table record
** actions are added by QuickSearchQBitProducer once the indexed tables are
** known.
*******************************************************************************/
public class QuickSearchDiagnosticsProcessesMetaDataProducer extends QBitComponentMetaDataProducer<MetaDataProducerMultiOutput, QuickSearchQBitConfig>
{
/*******************************************************************************
*******************************************************************************/
@Override
public MetaDataProducerMultiOutput produce(QInstance qInstance) throws QException
{
MetaDataProducerMultiOutput output = new MetaDataProducerMultiOutput();
for(QProcessMetaData process : QuickSearchDiagnosticsProcessMetaDataHelper.buildFixedProcesses(getQBitConfig()))
{
output.add(process);
}
return (output);
}
/*******************************************************************************
*******************************************************************************/
@Override
public boolean isEnabled()
{
return (getQBitConfig() != null && Boolean.TRUE.equals(getQBitConfig().getEnableDiagnosticTools()));
}
/*******************************************************************************
** after tables, before the app
*******************************************************************************/
@Override
public int getSortOrder()
{
return (200);
}
}
src/main/java/com/kingsrook/qbits/quicksearch/metadata/QuickSearchDiagnosticsWidgetMetaDataProducer.java
+79
View File
@@ -0,0 +1,79 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.metadata;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.dashboard.widgets.WidgetType;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitComponentMetaDataProducer;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.diagnostics.QuickSearchDiagnosticsWidgetRenderer;
/*******************************************************************************
** Produces the Search Diagnostics widget (quickSearchDiagnostics) when
** enableDiagnosticTools is true. The admin app shows it on its home; a host
** with its own Quick Search home adds it there by name.
*******************************************************************************/
public class QuickSearchDiagnosticsWidgetMetaDataProducer extends QBitComponentMetaDataProducer<QWidgetMetaData, QuickSearchQBitConfig>
{
public static final String WIDGET_NAME = "quickSearchDiagnostics";
/*******************************************************************************
*******************************************************************************/
@Override
public QWidgetMetaData produce(QInstance qInstance) throws QException
{
QuickSearchQBitConfig config = getQBitConfig();
return (new QWidgetMetaData()
.withName(config.applyPrefix(WIDGET_NAME))
.withLabel("Search Diagnostics")
.withIcon("troubleshoot")
.withType(WidgetType.HTML.getType())
.withGridColumns(12)
.withIsCard(true)
.withCodeReference(new QCodeReference(QuickSearchDiagnosticsWidgetRenderer.class))
.withPermissionRules(config.getDebugPermissionRules() == null ? null : config.getDebugPermissionRules().clone()));
}
/*******************************************************************************
*******************************************************************************/
@Override
public boolean isEnabled()
{
return (getQBitConfig() != null && Boolean.TRUE.equals(getQBitConfig().getEnableDiagnosticTools()));
}
/*******************************************************************************
** after tables, before the app
*******************************************************************************/
@Override
public int getSortOrder()
{
return (300);
}
}
src/main/java/com/kingsrook/qbits/quicksearch/metadata/QuickSearchTableMetaDataHelper.java
+85
View File
@@ -17,16 +17,22 @@
package com.kingsrook.qbits.quicksearch.metadata;
import java.util.List;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
import com.kingsrook.qqq.backend.core.model.metadata.tables.Capability;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSection;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.tables.Tier;
import com.kingsrook.qqq.backend.core.model.metadata.tables.UniqueKey;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
import com.kingsrook.qbits.quicksearch.model.QuickSearchFailedEvent;
import com.kingsrook.qbits.quicksearch.model.QuickSearchIndex;
import com.kingsrook.qbits.quicksearch.model.QuickSearchIndexRun;
import com.kingsrook.qbits.quicksearch.model.QuickSearchValidationRun;
/*******************************************************************************
@@ -126,6 +132,85 @@ public class QuickSearchTableMetaDataHelper
/*******************************************************************************
** quickSearchDiagnosticEvent: failed searches, diagnostic tool runs (the
** audit trail) and refused runs. Written by the QBit only: insert, update
** and delete are disabled for users and the API (core actions, which the
** QBit uses, do not check capabilities).
*******************************************************************************/
public static QTableMetaData buildDiagnosticEventTable(QuickSearchQBitConfig config)
{
return (new QTableMetaData()
.withName(config.applyPrefix(QuickSearchDiagnosticEvent.TABLE_NAME))
.withLabel("Quick Search Diagnostic Event")
.withoutCapabilities(Capability.TABLE_INSERT, Capability.TABLE_UPDATE, Capability.TABLE_DELETE)
.withIcon(new QIcon("bug_report"))
.withBackendName(config.getBackendName())
.withPrimaryKeyField("id")
.withRecordLabelFormat("%s %s")
.withRecordLabelFields("eventType", "source")
.withPermissionRules(config.getTablePermissionRules() == null ? null : config.getTablePermissionRules().clone())
.withField(new QFieldMetaData("id", QFieldType.INTEGER).withIsEditable(false))
.withField(new QFieldMetaData("eventType", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("source", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("outcome", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("userName", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("tableNames", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("searchTerm", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("durationMillis", QFieldType.INTEGER).withIsEditable(false))
.withField(new QFieldMetaData("errorClass", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("errorMessage", QFieldType.TEXT).withIsEditable(false))
.withField(new QFieldMetaData("detail", QFieldType.TEXT).withIsEditable(false))
.withField(new QFieldMetaData("hostName", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("createDate", QFieldType.DATE_TIME).withIsEditable(false))
.withSection(new QFieldSection("identity", "Event", new QIcon("bug_report"), Tier.T1, List.of("id", "createDate", "eventType", "source", "outcome")))
.withSection(new QFieldSection("request", "Request", new QIcon("search"), Tier.T2, List.of("userName", "tableNames", "searchTerm", "durationMillis", "hostName")))
.withSection(new QFieldSection("error", "Error and detail", new QIcon("error_outline"), Tier.T2, List.of("errorClass", "errorMessage", "detail"))));
}
/*******************************************************************************
** quickSearchValidationRun: index validation reports (history). The
** report is an HTML field, shown in full on the record view; only the
** QBit writes rows (insert, update and delete are disabled for users and
** the API), so the HTML is always the QBit's escaped output.
*******************************************************************************/
public static QTableMetaData buildValidationRunTable(QuickSearchQBitConfig config)
{
return (new QTableMetaData()
.withName(config.applyPrefix(QuickSearchValidationRun.TABLE_NAME))
.withLabel("Quick Search Validation Run")
.withoutCapabilities(Capability.TABLE_INSERT, Capability.TABLE_UPDATE, Capability.TABLE_DELETE)
.withIcon(new QIcon("fact_check"))
.withBackendName(config.getBackendName())
.withPrimaryKeyField("id")
.withRecordLabelFormat("%s %s")
.withRecordLabelFields("status", "startTime")
.withPermissionRules(config.getTablePermissionRules() == null ? null : config.getTablePermissionRules().clone())
.withField(new QFieldMetaData("id", QFieldType.INTEGER).withIsEditable(false))
.withField(new QFieldMetaData("status", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("triggerType", QFieldType.STRING).withLabel("Trigger").withIsEditable(false))
.withField(new QFieldMetaData("userName", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("tableNames", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("sampleSize", QFieldType.INTEGER).withIsEditable(false))
.withField(new QFieldMetaData("tablesChecked", QFieldType.INTEGER).withIsEditable(false))
.withField(new QFieldMetaData("failCount", QFieldType.INTEGER).withLabel("Failed Checks").withIsEditable(false))
.withField(new QFieldMetaData("warnCount", QFieldType.INTEGER).withLabel("Warnings").withIsEditable(false))
.withField(new QFieldMetaData("summary", QFieldType.STRING).withIsEditable(false))
.withField(new QFieldMetaData("reportHtml", QFieldType.HTML).withLabel("Report").withIsEditable(false))
.withField(new QFieldMetaData("reportJson", QFieldType.TEXT).withLabel("Report JSON").withIsEditable(false))
.withField(new QFieldMetaData("startTime", QFieldType.DATE_TIME).withIsEditable(false))
.withField(new QFieldMetaData("endTime", QFieldType.DATE_TIME).withIsEditable(false))
.withField(new QFieldMetaData("createDate", QFieldType.DATE_TIME).withIsEditable(false))
.withSection(new QFieldSection("identity", "Run", new QIcon("fact_check"), Tier.T1, List.of("id", "status", "summary", "triggerType", "startTime", "endTime")))
.withSection(new QFieldSection("scope", "Scope", new QIcon("table_chart"), Tier.T2, List.of("userName", "tableNames", "sampleSize", "tablesChecked", "failCount", "warnCount", "createDate")))
.withSection(new QFieldSection("report", "Report", new QIcon("description"), Tier.T2, List.of("reportHtml")))
.withSection(new QFieldSection("data", "Report data (JSON)", new QIcon("data_object"), Tier.T3, List.of("reportJson"))));
}
/*******************************************************************************
** Possible value source over quickSearchIndex, so run rows show the table
** name instead of an id.
src/main/java/com/kingsrook/qbits/quicksearch/metadata/QuickSearchValidationRunTableMetaDataProducer.java
+62
View File
@@ -0,0 +1,62 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.metadata;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitComponentMetaDataProducer;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
/*******************************************************************************
** Produces the quickSearchValidationRun table when enableDiagnosticTools is true.
*******************************************************************************/
public class QuickSearchValidationRunTableMetaDataProducer extends QBitComponentMetaDataProducer<QTableMetaData, QuickSearchQBitConfig>
{
/*******************************************************************************
*******************************************************************************/
@Override
public QTableMetaData produce(QInstance qInstance) throws QException
{
return (QuickSearchTableMetaDataHelper.buildValidationRunTable(getQBitConfig()));
}
/*******************************************************************************
*******************************************************************************/
@Override
public boolean isEnabled()
{
return (getQBitConfig() != null && Boolean.TRUE.equals(getQBitConfig().getEnableDiagnosticTools()));
}
/*******************************************************************************
** tables before processes and the app
*******************************************************************************/
@Override
public int getSortOrder()
{
return (100);
}
}
src/main/java/com/kingsrook/qbits/quicksearch/model/QuickSearchDiagnosticEvent.java
+508
View File
@@ -0,0 +1,508 @@
/*
* Copyright 2024 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.model;
import java.time.Instant;
import com.kingsrook.qqq.backend.core.model.data.QField;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.model.data.QRecordEntity;
import com.kingsrook.qqq.backend.core.exceptions.QException;
/*******************************************************************************
** A Quick Search diagnostic event: a failed search (OpenSearch error or timeout,
** after which core record search falls back to its own search), a diagnostic
** tool run (the audit trail of the admin tools), or a refused run (rate limit).
** Written by DiagnosticEventRecorder; read-only for operators.
*******************************************************************************/
public class QuickSearchDiagnosticEvent extends QRecordEntity
{
public static final String TABLE_NAME = "quickSearchDiagnosticEvent";
public static final String TYPE_SEARCH_FAILED = "SEARCH_FAILED";
public static final String TYPE_TOOL_RUN = "TOOL_RUN";
public static final String TYPE_REINDEX = "REINDEX";
public static final String TYPE_RATE_LIMITED = "RATE_LIMITED";
public static final String SOURCE_CORE_RECORD_SEARCH = "CORE_RECORD_SEARCH";
public static final String SOURCE_QUICK_SEARCH_ACTION = "QUICK_SEARCH_ACTION";
public static final String OUTCOME_OK = "OK";
public static final String OUTCOME_ERROR = "ERROR";
public static final String OUTCOME_REFUSED = "REFUSED";
@QField()
private Integer id;
@QField()
private String eventType;
@QField()
private String source;
@QField()
private String outcome;
@QField()
private String userName;
@QField()
private String tableNames;
@QField()
private String searchTerm;
@QField()
private Integer durationMillis;
@QField()
private String errorClass;
@QField()
private String errorMessage;
@QField()
private String detail;
@QField()
private String hostName;
@QField()
private Instant createDate;
/*******************************************************************************
** Default constructor
*******************************************************************************/
public QuickSearchDiagnosticEvent()
{
}
/*******************************************************************************
** Constructor from a QRecord
*******************************************************************************/
public QuickSearchDiagnosticEvent(QRecord record) throws QException
{
populateFromQRecord(record);
}
/*******************************************************************************
** Getter for id
*******************************************************************************/
public Integer getId()
{
return (this.id);
}
/*******************************************************************************
** Setter for id
*******************************************************************************/
public void setId(Integer id)
{
this.id = id;
}
/*******************************************************************************
** Fluent setter for id
*******************************************************************************/
public QuickSearchDiagnosticEvent withId(Integer id)
{
this.id = id;
return (this);
}
/*******************************************************************************
** Getter for eventType
*******************************************************************************/
public String getEventType()
{
return (this.eventType);
}
/*******************************************************************************
** Setter for eventType
*******************************************************************************/
public void setEventType(String eventType)
{
this.eventType = eventType;
}
/*******************************************************************************
** Fluent setter for eventType
*******************************************************************************/
public QuickSearchDiagnosticEvent withEventType(String eventType)
{
this.eventType = eventType;
return (this);
}
/*******************************************************************************
** Getter for source
*******************************************************************************/
public String getSource()
{
return (this.source);
}
/*******************************************************************************
** Setter for source
*******************************************************************************/
public void setSource(String source)
{
this.source = source;
}
/*******************************************************************************
** Fluent setter for source
*******************************************************************************/
public QuickSearchDiagnosticEvent withSource(String source)
{
this.source = source;
return (this);
}
/*******************************************************************************
** Getter for outcome
*******************************************************************************/
public String getOutcome()
{
return (this.outcome);
}
/*******************************************************************************
** Setter for outcome
*******************************************************************************/
public void setOutcome(String outcome)
{
this.outcome = outcome;
}
/*******************************************************************************
** Fluent setter for outcome
*******************************************************************************/
public QuickSearchDiagnosticEvent withOutcome(String outcome)
{
this.outcome = outcome;
return (this);
}
/*******************************************************************************
** Getter for userName
*******************************************************************************/
public String getUserName()
{
return (this.userName);
}
/*******************************************************************************
** Setter for userName
*******************************************************************************/
public void setUserName(String userName)
{
this.userName = userName;
}
/*******************************************************************************
** Fluent setter for userName
*******************************************************************************/
public QuickSearchDiagnosticEvent withUserName(String userName)
{
this.userName = userName;
return (this);
}
/*******************************************************************************
** Getter for tableNames
*******************************************************************************/
public String getTableNames()
{
return (this.tableNames);
}
/*******************************************************************************
** Setter for tableNames
*******************************************************************************/
public void setTableNames(String tableNames)
{
this.tableNames = tableNames;
}
/*******************************************************************************
** Fluent setter for tableNames
*******************************************************************************/
public QuickSearchDiagnosticEvent withTableNames(String tableNames)
{
this.tableNames = tableNames;
return (this);
}
/*******************************************************************************
** Getter for searchTerm
*******************************************************************************/
public String getSearchTerm()
{
return (this.searchTerm);
}
/*******************************************************************************
** Setter for searchTerm
*******************************************************************************/
public void setSearchTerm(String searchTerm)
{
this.searchTerm = searchTerm;
}
/*******************************************************************************
** Fluent setter for searchTerm
*******************************************************************************/
public QuickSearchDiagnosticEvent withSearchTerm(String searchTerm)
{
this.searchTerm = searchTerm;
return (this);
}
/*******************************************************************************
** Getter for durationMillis
*******************************************************************************/
public Integer getDurationMillis()
{
return (this.durationMillis);
}
/*******************************************************************************
** Setter for durationMillis
*******************************************************************************/
public void setDurationMillis(Integer durationMillis)
{
this.durationMillis = durationMillis;
}
/*******************************************************************************
** Fluent setter for durationMillis
*******************************************************************************/
public QuickSearchDiagnosticEvent withDurationMillis(Integer durationMillis)
{
this.durationMillis = durationMillis;
return (this);
}
/*******************************************************************************
** Getter for errorClass
*******************************************************************************/
public String getErrorClass()
{
return (this.errorClass);
}
/*******************************************************************************
** Setter for errorClass
*******************************************************************************/
public void setErrorClass(String errorClass)
{
this.errorClass = errorClass;
}
/*******************************************************************************
** Fluent setter for errorClass
*******************************************************************************/
public QuickSearchDiagnosticEvent withErrorClass(String errorClass)
{
this.errorClass = errorClass;
return (this);
}
/*******************************************************************************
** Getter for errorMessage
*******************************************************************************/
public String getErrorMessage()
{
return (this.errorMessage);
}
/*******************************************************************************
** Setter for errorMessage
*******************************************************************************/
public void setErrorMessage(String errorMessage)
{
this.errorMessage = errorMessage;
}
/*******************************************************************************
** Fluent setter for errorMessage
*******************************************************************************/
public QuickSearchDiagnosticEvent withErrorMessage(String errorMessage)
{
this.errorMessage = errorMessage;
return (this);
}
/*******************************************************************************
** Getter for detail
*******************************************************************************/
public String getDetail()
{
return (this.detail);
}
/*******************************************************************************
** Setter for detail
*******************************************************************************/
public void setDetail(String detail)
{
this.detail = detail;
}
/*******************************************************************************
** Fluent setter for detail
*******************************************************************************/
public QuickSearchDiagnosticEvent withDetail(String detail)
{
this.detail = detail;
return (this);
}
/*******************************************************************************
** Getter for hostName
*******************************************************************************/
public String getHostName()
{
return (this.hostName);
}
/*******************************************************************************
** Setter for hostName
*******************************************************************************/
public void setHostName(String hostName)
{
this.hostName = hostName;
}
/*******************************************************************************
** Fluent setter for hostName
*******************************************************************************/
public QuickSearchDiagnosticEvent withHostName(String hostName)
{
this.hostName = hostName;
return (this);
}
/*******************************************************************************
** Getter for createDate
*******************************************************************************/
public Instant getCreateDate()
{
return (this.createDate);
}
/*******************************************************************************
** Setter for createDate
*******************************************************************************/
public void setCreateDate(Instant createDate)
{
this.createDate = createDate;
}
/*******************************************************************************
** Fluent setter for createDate
*******************************************************************************/
public QuickSearchDiagnosticEvent withCreateDate(Instant createDate)
{
this.createDate = createDate;
return (this);
}
}
src/main/java/com/kingsrook/qbits/quicksearch/model/QuickSearchValidationRun.java
+572
View File
@@ -0,0 +1,572 @@
/*
* Copyright 2024 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.model;
import java.time.Instant;
import com.kingsrook.qqq.backend.core.model.data.QField;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.model.data.QRecordEntity;
import com.kingsrook.qqq.backend.core.exceptions.QException;
/*******************************************************************************
** One run of the index validation: overall status, counts of failed and
** warning checks, and the full report (HTML for the record view, JSON for
** tools). Kept as history; purged after runHistoryRetentionDays.
*******************************************************************************/
public class QuickSearchValidationRun extends QRecordEntity
{
public static final String TABLE_NAME = "quickSearchValidationRun";
public static final String STATUS_PASS = "PASS";
public static final String STATUS_WARN = "WARN";
public static final String STATUS_FAIL = "FAIL";
public static final String STATUS_ERROR = "ERROR";
public static final String TRIGGER_MANUAL = "MANUAL";
public static final String TRIGGER_SCHEDULED = "SCHEDULED";
@QField()
private Integer id;
@QField()
private String status;
@QField()
private String triggerType;
@QField()
private String userName;
@QField()
private String tableNames;
@QField()
private Integer sampleSize;
@QField()
private Integer tablesChecked;
@QField()
private Integer failCount;
@QField()
private Integer warnCount;
@QField()
private String summary;
@QField()
private String reportHtml;
@QField()
private String reportJson;
@QField()
private Instant startTime;
@QField()
private Instant endTime;
@QField()
private Instant createDate;
/*******************************************************************************
** Default constructor
*******************************************************************************/
public QuickSearchValidationRun()
{
}
/*******************************************************************************
** Constructor from a QRecord
*******************************************************************************/
public QuickSearchValidationRun(QRecord record) throws QException
{
populateFromQRecord(record);
}
/*******************************************************************************
** Getter for id
*******************************************************************************/
public Integer getId()
{
return (this.id);
}
/*******************************************************************************
** Setter for id
*******************************************************************************/
public void setId(Integer id)
{
this.id = id;
}
/*******************************************************************************
** Fluent setter for id
*******************************************************************************/
public QuickSearchValidationRun withId(Integer id)
{
this.id = id;
return (this);
}
/*******************************************************************************
** Getter for status
*******************************************************************************/
public String getStatus()
{
return (this.status);
}
/*******************************************************************************
** Setter for status
*******************************************************************************/
public void setStatus(String status)
{
this.status = status;
}
/*******************************************************************************
** Fluent setter for status
*******************************************************************************/
public QuickSearchValidationRun withStatus(String status)
{
this.status = status;
return (this);
}
/*******************************************************************************
** Getter for triggerType
*******************************************************************************/
public String getTriggerType()
{
return (this.triggerType);
}
/*******************************************************************************
** Setter for triggerType
*******************************************************************************/
public void setTriggerType(String triggerType)
{
this.triggerType = triggerType;
}
/*******************************************************************************
** Fluent setter for triggerType
*******************************************************************************/
public QuickSearchValidationRun withTriggerType(String triggerType)
{
this.triggerType = triggerType;
return (this);
}
/*******************************************************************************
** Getter for userName
*******************************************************************************/
public String getUserName()
{
return (this.userName);
}
/*******************************************************************************
** Setter for userName
*******************************************************************************/
public void setUserName(String userName)
{
this.userName = userName;
}
/*******************************************************************************
** Fluent setter for userName
*******************************************************************************/
public QuickSearchValidationRun withUserName(String userName)
{
this.userName = userName;
return (this);
}
/*******************************************************************************
** Getter for tableNames
*******************************************************************************/
public String getTableNames()
{
return (this.tableNames);
}
/*******************************************************************************
** Setter for tableNames
*******************************************************************************/
public void setTableNames(String tableNames)
{
this.tableNames = tableNames;
}
/*******************************************************************************
** Fluent setter for tableNames
*******************************************************************************/
public QuickSearchValidationRun withTableNames(String tableNames)
{
this.tableNames = tableNames;
return (this);
}
/*******************************************************************************
** Getter for sampleSize
*******************************************************************************/
public Integer getSampleSize()
{
return (this.sampleSize);
}
/*******************************************************************************
** Setter for sampleSize
*******************************************************************************/
public void setSampleSize(Integer sampleSize)
{
this.sampleSize = sampleSize;
}
/*******************************************************************************
** Fluent setter for sampleSize
*******************************************************************************/
public QuickSearchValidationRun withSampleSize(Integer sampleSize)
{
this.sampleSize = sampleSize;
return (this);
}
/*******************************************************************************
** Getter for tablesChecked
*******************************************************************************/
public Integer getTablesChecked()
{
return (this.tablesChecked);
}
/*******************************************************************************
** Setter for tablesChecked
*******************************************************************************/
public void setTablesChecked(Integer tablesChecked)
{
this.tablesChecked = tablesChecked;
}
/*******************************************************************************
** Fluent setter for tablesChecked
*******************************************************************************/
public QuickSearchValidationRun withTablesChecked(Integer tablesChecked)
{
this.tablesChecked = tablesChecked;
return (this);
}
/*******************************************************************************
** Getter for failCount
*******************************************************************************/
public Integer getFailCount()
{
return (this.failCount);
}
/*******************************************************************************
** Setter for failCount
*******************************************************************************/
public void setFailCount(Integer failCount)
{
this.failCount = failCount;
}
/*******************************************************************************
** Fluent setter for failCount
*******************************************************************************/
public QuickSearchValidationRun withFailCount(Integer failCount)
{
this.failCount = failCount;
return (this);
}
/*******************************************************************************
** Getter for warnCount
*******************************************************************************/
public Integer getWarnCount()
{
return (this.warnCount);
}
/*******************************************************************************
** Setter for warnCount
*******************************************************************************/
public void setWarnCount(Integer warnCount)
{
this.warnCount = warnCount;
}
/*******************************************************************************
** Fluent setter for warnCount
*******************************************************************************/
public QuickSearchValidationRun withWarnCount(Integer warnCount)
{
this.warnCount = warnCount;
return (this);
}
/*******************************************************************************
** Getter for summary
*******************************************************************************/
public String getSummary()
{
return (this.summary);
}
/*******************************************************************************
** Setter for summary
*******************************************************************************/
public void setSummary(String summary)
{
this.summary = summary;
}
/*******************************************************************************
** Fluent setter for summary
*******************************************************************************/
public QuickSearchValidationRun withSummary(String summary)
{
this.summary = summary;
return (this);
}
/*******************************************************************************
** Getter for reportHtml
*******************************************************************************/
public String getReportHtml()
{
return (this.reportHtml);
}
/*******************************************************************************
** Setter for reportHtml
*******************************************************************************/
public void setReportHtml(String reportHtml)
{
this.reportHtml = reportHtml;
}
/*******************************************************************************
** Fluent setter for reportHtml
*******************************************************************************/
public QuickSearchValidationRun withReportHtml(String reportHtml)
{
this.reportHtml = reportHtml;
return (this);
}
/*******************************************************************************
** Getter for reportJson
*******************************************************************************/
public String getReportJson()
{
return (this.reportJson);
}
/*******************************************************************************
** Setter for reportJson
*******************************************************************************/
public void setReportJson(String reportJson)
{
this.reportJson = reportJson;
}
/*******************************************************************************
** Fluent setter for reportJson
*******************************************************************************/
public QuickSearchValidationRun withReportJson(String reportJson)
{
this.reportJson = reportJson;
return (this);
}
/*******************************************************************************
** Getter for startTime
*******************************************************************************/
public Instant getStartTime()
{
return (this.startTime);
}
/*******************************************************************************
** Setter for startTime
*******************************************************************************/
public void setStartTime(Instant startTime)
{
this.startTime = startTime;
}
/*******************************************************************************
** Fluent setter for startTime
*******************************************************************************/
public QuickSearchValidationRun withStartTime(Instant startTime)
{
this.startTime = startTime;
return (this);
}
/*******************************************************************************
** Getter for endTime
*******************************************************************************/
public Instant getEndTime()
{
return (this.endTime);
}
/*******************************************************************************
** Setter for endTime
*******************************************************************************/
public void setEndTime(Instant endTime)
{
this.endTime = endTime;
}
/*******************************************************************************
** Fluent setter for endTime
*******************************************************************************/
public QuickSearchValidationRun withEndTime(Instant endTime)
{
this.endTime = endTime;
return (this);
}
/*******************************************************************************
** Getter for createDate
*******************************************************************************/
public Instant getCreateDate()
{
return (this.createDate);
}
/*******************************************************************************
** Setter for createDate
*******************************************************************************/
public void setCreateDate(Instant createDate)
{
this.createDate = createDate;
}
/*******************************************************************************
** Fluent setter for createDate
*******************************************************************************/
public QuickSearchValidationRun withCreateDate(Instant createDate)
{
this.createDate = createDate;
return (this);
}
}
src/main/java/com/kingsrook/qbits/quicksearch/opensearch/QuickSearchDiagnosticsOperations.java
+566
View File
@@ -0,0 +1,566 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.opensearch;
import java.io.IOException;
import java.io.StringWriter;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Collection;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.JsonNodeFactory;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qbits.quicksearch.QuickSearchableTableConfig;
import jakarta.json.stream.JsonGenerator;
import org.opensearch.client.json.JsonpMapper;
import org.opensearch.client.json.JsonpSerializable;
import org.opensearch.client.opensearch.OpenSearchClient;
import org.opensearch.client.opensearch._types.OpenSearchException;
import org.opensearch.client.opensearch._types.query_dsl.Query;
import org.opensearch.client.opensearch.core.ExplainResponse;
import org.opensearch.client.opensearch.core.SearchRequest;
import org.opensearch.client.opensearch.core.SearchResponse;
import org.opensearch.client.opensearch.core.search.Hit;
import org.opensearch.client.opensearch.core.search.HighlightField;
import org.opensearch.client.opensearch.core.search.MatchedQueries;
import org.opensearch.client.opensearch.core.search.TotalHitsRelation;
import org.opensearch.client.opensearch.generic.Body;
import org.opensearch.client.opensearch.generic.Requests;
import org.opensearch.client.opensearch.generic.Response;
/*******************************************************************************
** Read-only OpenSearch operations behind the Quick Search admin diagnostics:
** a probe search that reports scores, highlights and matched clauses with
** its request and response JSON, explain for one document, document reads,
** _analyze, random document sampling, and raw cluster / index / mapping /
** settings reads. Nothing here writes to the cluster.
** The probe uses exactly the query production search builds (same clauses,
** operator, boosts and table filter); it only adds query names and
** highlighting on the field values, which change neither matching nor
** scoring.
*******************************************************************************/
public class QuickSearchDiagnosticsOperations
{
public static final int MAX_ANALYZE_TEXT_LENGTH = 10_000;
public static final int MAX_PROBE_SIZE = 100;
public static final int MAX_SAMPLE_SIZE = 1_000;
private static final ObjectMapper MAPPER = new ObjectMapper();
private final QuickSearchOpenSearchClient quickSearchClient;
private final OpenSearchClient client;
private final String indexName;
/*******************************************************************************
** One hit of a probe search.
*******************************************************************************/
public record ProbeHit(String recordId, String recordLabel, Double score, List<String> matchedClauses, Map<String, List<String>> highlights)
{
}
/*******************************************************************************
** A probe search of one table: request and response JSON, server and
** wall-clock time, total hits and the hits.
*******************************************************************************/
public record SearchProbe(String tableName, String requestJson, String responseJson, Long tookMillis, Long wallMillis, Long totalHits, Boolean totalIsLowerBound, List<ProbeHit> hits)
{
}
/*******************************************************************************
** The result of explain for one document and the search query.
*******************************************************************************/
public record ExplainResult(Boolean documentFound, Boolean matched, Double score, String explanationText, String json)
{
}
/*******************************************************************************
** One indexed document as stored: whether it exists, its version, the
** physical index holding it and its source.
*******************************************************************************/
public record DocumentView(Boolean found, Long version, String physicalIndex, JsonNode source)
{
}
/*******************************************************************************
** One token produced by _analyze.
*******************************************************************************/
public record AnalyzedToken(String token, Integer position, Integer startOffset, Integer endOffset, String type)
{
}
/*******************************************************************************
** A raw JSON response: HTTP status and parsed body (null when empty).
*******************************************************************************/
public record RawResponse(Integer status, JsonNode body)
{
/*******************************************************************************
** Whether the status is 2xx.
*******************************************************************************/
public boolean isOk()
{
return (status != null && status >= 200 && status < 300);
}
}
/*******************************************************************************
** Constructor
*******************************************************************************/
public QuickSearchDiagnosticsOperations(QuickSearchOpenSearchClient quickSearchClient)
{
this.quickSearchClient = quickSearchClient;
this.client = quickSearchClient.getOpenSearchClient();
this.indexName = quickSearchClient.getIndexName();
}
/*******************************************************************************
** Getter for the alias name the operations read.
*******************************************************************************/
public String getIndexName()
{
return (indexName);
}
/*******************************************************************************
** Run the production search query against one table with query names and
** field highlighting, returning up to size hits (capped at MAX_PROBE_SIZE).
*******************************************************************************/
public SearchProbe probeSearch(String term, String tableName, int size, List<QuickSearchableTableConfig> tableConfigs) throws QException
{
int boundedSize = Math.max(1, Math.min(size, MAX_PROBE_SIZE));
Query query = quickSearchClient.buildSearchQuery(term, List.of(tableName), tableConfigs, true);
SearchRequest request = SearchRequest.of(r -> r
.index(indexName)
.query(query)
.highlight(h -> h
.requireFieldMatch(true)
.fields("searchableText", HighlightField.of(hf -> hf))
.fields("fieldValues.*", HighlightField.of(hf -> hf)))
.trackTotalHits(t -> t.count(QuickSearchOpenSearchClient.MAX_RESULT_WINDOW))
.size(boundedSize));
long start = System.nanoTime();
try
{
SearchResponse<OpenSearchDocument> response = client.search(request, OpenSearchDocument.class);
long wall = (System.nanoTime() - start) / 1_000_000;
List<ProbeHit> hits = new ArrayList<>();
for(Hit<OpenSearchDocument> hit : response.hits().hits())
{
OpenSearchDocument source = hit.source();
hits.add(new ProbeHit(
source == null ? idFromDocumentId(hit.id()) : source.getRecordId(),
source == null ? null : source.getRecordLabel(),
hit.score(),
matchedClauses(hit.matchedQueries()),
hit.highlight() == null ? Map.of() : new LinkedHashMap<>(hit.highlight())));
}
Long total = response.hits().total() == null ? (long) hits.size() : response.hits().total().value();
Boolean lowerBound = response.hits().total() != null && response.hits().total().relation() == TotalHitsRelation.Gte;
return (new SearchProbe(tableName, toJson(request), toJson(response), response.took(), wall, total, lowerBound, hits));
}
catch(OpenSearchException | IOException e)
{
throw (wrap("Probe search failed for table [" + tableName + "]", e));
}
}
/*******************************************************************************
** Names of the clauses a hit matched (query names or, in newer servers,
** the keys of the named-query scores).
*******************************************************************************/
static List<String> matchedClauses(MatchedQueries matchedQueries)
{
if(matchedQueries == null)
{
return (List.of());
}
if(matchedQueries.isScores())
{
return (new ArrayList<>(matchedQueries.scores().keySet()));
}
return (new ArrayList<>(matchedQueries.names()));
}
/*******************************************************************************
** Explain how the production query scores one document of a table. A
** missing document gives documentFound false (not an error).
*******************************************************************************/
public ExplainResult explain(String term, String tableName, String recordId, List<QuickSearchableTableConfig> tableConfigs) throws QException
{
Query query = quickSearchClient.buildSearchQuery(term, List.of(tableName), tableConfigs, false);
String documentId = OpenSearchDocument.buildDocumentId(tableName, recordId);
try
{
ExplainResponse<OpenSearchDocument> response = client.explain(e -> e.index(indexName).id(documentId).query(query), OpenSearchDocument.class);
String json = toJson(response);
JsonNode tree = MAPPER.readTree(json);
JsonNode explanation = tree.path("explanation");
Double score = explanation.isMissingNode() ? null : explanation.path("value").asDouble();
return (new ExplainResult(true, response.matched(), score, formatExplanation(explanation), json));
}
catch(OpenSearchException e)
{
if(e.status() == 404)
{
return (new ExplainResult(false, false, null, null, null));
}
throw (wrap("Explain failed for document [" + documentId + "]", e));
}
catch(IOException e)
{
throw (wrap("Explain failed for document [" + documentId + "]", e));
}
}
/*******************************************************************************
** An explanation tree as indented text ("value description"), bounded to
** 400 lines.
*******************************************************************************/
public static String formatExplanation(JsonNode explanation)
{
if(explanation == null || explanation.isMissingNode() || explanation.isNull())
{
return ("");
}
List<String> lines = new ArrayList<>();
appendExplanation(explanation, 0, lines);
return (String.join("\n", lines));
}
/*******************************************************************************
*******************************************************************************/
private static void appendExplanation(JsonNode node, int depth, List<String> lines)
{
if(lines.size() >= 400)
{
return;
}
lines.add(" ".repeat(depth) + String.format("%.4f", node.path("value").asDouble()) + " " + node.path("description").asText(""));
for(JsonNode detail : node.path("details"))
{
appendExplanation(detail, depth + 1, lines);
}
}
/*******************************************************************************
** Read one document of a table by record id.
*******************************************************************************/
public DocumentView getDocument(String tableName, String recordId) throws QException
{
RawResponse response = raw("GET", "/" + encode(indexName) + "/_doc/" + encode(OpenSearchDocument.buildDocumentId(tableName, recordId)), null);
if(response.status() == 404)
{
return (new DocumentView(false, null, null, null));
}
requireOk(response, "Document read failed");
JsonNode body = response.body();
return (new DocumentView(body.path("found").asBoolean(false), body.has("_version") ? body.get("_version").asLong() : null,
body.path("_index").asText(null), body.get("_source")));
}
/*******************************************************************************
** Read many documents of a table by record id: record id to source, for
** the documents that exist.
*******************************************************************************/
public Map<String, JsonNode> getDocuments(String tableName, Collection<String> recordIds) throws QException
{
Map<String, JsonNode> sources = new LinkedHashMap<>();
if(recordIds == null || recordIds.isEmpty())
{
return (sources);
}
ObjectNode body = JsonNodeFactory.instance.objectNode();
ArrayNode ids = body.putArray("ids");
for(String recordId : recordIds)
{
ids.add(OpenSearchDocument.buildDocumentId(tableName, recordId));
}
RawResponse response = raw("POST", "/" + encode(indexName) + "/_mget", body.toString());
requireOk(response, "Document read failed");
for(JsonNode doc : response.body().path("docs"))
{
if(doc.path("found").asBoolean(false) && doc.has("_source"))
{
sources.put(idFromDocumentId(doc.path("_id").asText()), doc.get("_source"));
}
}
return (sources);
}
/*******************************************************************************
** Run _analyze on the index with a named analyzer (an index analyzer or a
** built-in one). Text is truncated to MAX_ANALYZE_TEXT_LENGTH.
*******************************************************************************/
public List<AnalyzedToken> analyze(String analyzer, String text) throws QException
{
String bounded = text == null ? "" : (text.length() > MAX_ANALYZE_TEXT_LENGTH ? text.substring(0, MAX_ANALYZE_TEXT_LENGTH) : text);
ObjectNode body = JsonNodeFactory.instance.objectNode().put("analyzer", analyzer).put("text", bounded);
RawResponse response = raw("POST", "/" + encode(indexName) + "/_analyze", body.toString());
requireOk(response, "Analyze failed for analyzer [" + analyzer + "]");
List<AnalyzedToken> tokens = new ArrayList<>();
for(JsonNode token : response.body().path("tokens"))
{
tokens.add(new AnalyzedToken(token.path("token").asText(), token.path("position").asInt(), token.path("start_offset").asInt(),
token.path("end_offset").asInt(), token.path("type").asText(null)));
}
return (tokens);
}
/*******************************************************************************
** Up to n record ids of a table's documents, chosen at random.
*******************************************************************************/
public List<String> sampleRecordIds(String tableName, int n) throws QException
{
int size = Math.max(1, Math.min(n, MAX_SAMPLE_SIZE));
ObjectNode body = JsonNodeFactory.instance.objectNode();
body.put("size", size);
body.putArray("_source").add("recordId");
ObjectNode functionScore = body.putObject("query").putObject("function_score");
functionScore.putObject("query").putObject("term").put("sourceTable", tableName);
functionScore.putObject("random_score");
RawResponse response = raw("POST", "/" + encode(indexName) + "/_search", body.toString());
requireOk(response, "Sampling documents failed for table [" + tableName + "]");
List<String> recordIds = new ArrayList<>();
for(JsonNode hit : response.body().path("hits").path("hits"))
{
String recordId = hit.path("_source").path("recordId").asText(null);
recordIds.add(recordId != null ? recordId : idFromDocumentId(hit.path("_id").asText()));
}
return (recordIds);
}
/*******************************************************************************
** Cluster health, with the alias's indexes (level=indices).
*******************************************************************************/
public RawResponse clusterHealth() throws QException
{
return (raw("GET", "/_cluster/health/" + encode(indexName) + "?level=indices", null));
}
/*******************************************************************************
** The live mapping of the alias's index(es).
*******************************************************************************/
public RawResponse mapping() throws QException
{
return (raw("GET", "/" + encode(indexName) + "/_mapping", null));
}
/*******************************************************************************
** The live settings of the alias's index(es).
*******************************************************************************/
public RawResponse settings() throws QException
{
return (raw("GET", "/" + encode(indexName) + "/_settings", null));
}
/*******************************************************************************
** The physical indexes named like this alias's ({alias}-v*), with health,
** status, document counts and size, from _cat/indices.
*******************************************************************************/
public RawResponse physicalIndexes() throws QException
{
return (raw("GET", "/_cat/indices/" + encode(indexName) + "-v*?format=json&h=index,health,status,docs.count,docs.deleted,store.size&expand_wildcards=all", null));
}
/*******************************************************************************
** The record id part of a document id ("table:id").
*******************************************************************************/
static String idFromDocumentId(String documentId)
{
if(documentId == null)
{
return (null);
}
int colon = documentId.indexOf(':');
return (colon < 0 ? documentId : documentId.substring(colon + 1));
}
/*******************************************************************************
** Send a raw request and parse the JSON body. HTTP errors are returned
** (status and body), not thrown; transport errors throw.
*******************************************************************************/
public RawResponse raw(String method, String endpoint, String jsonBody) throws QException
{
Requests.JsonBodyBuilder builder = Requests.builder().method(method).endpoint(endpoint);
if(jsonBody != null)
{
builder.json(jsonBody);
}
try(Response response = client.generic().execute(builder.build()))
{
JsonNode body = null;
if(response.getBody().isPresent())
{
try(Body responseBody = response.getBody().get())
{
String text = responseBody.bodyAsString();
body = text == null || text.isBlank() ? null : MAPPER.readTree(text);
}
}
return (new RawResponse(response.getStatus(), body));
}
catch(OpenSearchException | IOException e)
{
throw (wrap(method + " " + endpoint.replaceAll("\\?.*", "") + " failed", e));
}
}
/*******************************************************************************
** Throw a QException with OpenSearch's reason when a raw response is not
** 2xx.
*******************************************************************************/
public static void requireOk(RawResponse response, String message) throws QException
{
if(!response.isOk())
{
throw (new QException(message + ": OpenSearch returned status " + response.status() + ": " + errorReason(response.body())));
}
}
/*******************************************************************************
** OpenSearch's error reason from an error body, or a short form of it.
*******************************************************************************/
public static String errorReason(JsonNode body)
{
if(body == null)
{
return ("no response body");
}
JsonNode error = body.path("error");
if(error.isTextual())
{
return (error.asText());
}
String reason = error.path("reason").asText(null);
if(reason != null)
{
return (reason);
}
String text = body.toString();
return (text.length() > 300 ? text.substring(0, 300) + "..." : text);
}
/*******************************************************************************
** Serialize a request or response with the transport's mapper (which knows
** OpenSearchDocument; the default mapper of toJsonString does not).
*******************************************************************************/
private String toJson(JsonpSerializable value)
{
JsonpMapper mapper = client._transport().jsonpMapper();
StringWriter writer = new StringWriter();
try(JsonGenerator generator = mapper.jsonProvider().createGenerator(writer))
{
value.serialize(generator, mapper);
}
return (writer.toString());
}
/*******************************************************************************
** URL-encode one path segment.
*******************************************************************************/
static String encode(String segment)
{
return (URLEncoder.encode(segment, StandardCharsets.UTF_8).replace("+", "%20"));
}
/*******************************************************************************
*******************************************************************************/
private static QException wrap(String message, Exception e)
{
if(e instanceof OpenSearchException openSearchException)
{
String reason = openSearchException.error() == null ? openSearchException.getMessage() : openSearchException.error().reason();
return (new QException(message + ": OpenSearch returned status " + openSearchException.status() + ": " + reason, e));
}
return (new QException(message + ": " + e.getMessage(), e));
}
}
src/main/java/com/kingsrook/qbits/quicksearch/opensearch/QuickSearchOpenSearchClient.java
+42 -9
View File
@@ -102,6 +102,8 @@ public class QuickSearchOpenSearchClient implements Closeable
public static final String INDEX_ANALYZER = "quick_search_analyzer";
public static final String SEARCH_ANALYZER = "quick_search_search_analyzer";
public static final int MAX_RESULT_WINDOW = 10_000;
public static final String MATCH_CLAUSE_NAME = "searchableText";
public static final String FIELD_CLAUSE_PREFIX = "field:";
private final OpenSearchClient client;
private final OpenSearchAsyncClient asyncClient;
@@ -785,13 +787,30 @@ public class QuickSearchOpenSearchClient implements Closeable
** nothing), and per-field should clauses boost by configured weight.
*******************************************************************************/
private Query buildSearchQuery(String searchTerm, Collection<String> allowedTables, List<QuickSearchableTableConfig> tableConfigs)
{
return (buildSearchQuery(searchTerm, allowedTables, tableConfigs, false));
}
/*******************************************************************************
** The search query; with named true each clause carries a query name
** (MATCH_CLAUSE_NAME for the required searchableText match, the field name
** for each boost clause) so a hit reports which clauses matched. Names do
** not change matching or scoring.
*******************************************************************************/
Query buildSearchQuery(String searchTerm, Collection<String> allowedTables, List<QuickSearchableTableConfig> tableConfigs, boolean named)
{
List<FieldValue> allowed = allowedTables.stream().map(FieldValue::of).toList();
BoolQuery.Builder boolBuilder = new BoolQuery.Builder()
.must(Query.of(q -> q.multiMatch(MultiMatchQuery.of(mm -> mm.query(searchTerm).fields("searchableText").operator(Operator.And)))))
.must(Query.of(q -> q.multiMatch(MultiMatchQuery.of(mm ->
{
mm.query(searchTerm).fields("searchableText").operator(Operator.And);
return (named ? mm.queryName(MATCH_CLAUSE_NAME) : mm);
}))))
.filter(Query.of(q -> q.terms(t -> t.field("sourceTable").terms(tv -> tv.value(allowed)))))
.should(buildFieldBoostQueries(searchTerm, tableConfigs, allowedTables));
.should(buildFieldBoostQueries(searchTerm, tableConfigs, allowedTables, named));
return (Query.of(q -> q.bool(boolBuilder.build())));
}
@@ -801,7 +820,7 @@ public class QuickSearchOpenSearchClient implements Closeable
/*******************************************************************************
**
*******************************************************************************/
private List<Query> buildFieldBoostQueries(String searchTerm, List<QuickSearchableTableConfig> tableConfigs, Collection<String> allowedTables)
private List<Query> buildFieldBoostQueries(String searchTerm, List<QuickSearchableTableConfig> tableConfigs, Collection<String> allowedTables, boolean named)
{
List<Query> queries = new ArrayList<>();
if(tableConfigs == null)
@@ -821,12 +840,15 @@ public class QuickSearchOpenSearchClient implements Closeable
for(String field : fields)
{
float boost = (weights == null || weights.get(field) == null) ? 1f : weights.get(field).floatValue();
queries.add(Query.of(q -> q.multiMatch(MultiMatchQuery.of(mm -> mm
.query(searchTerm)
.fields("fieldValues." + field)
.operator(Operator.And)
.lenient(true)
.boost(boost)))));
queries.add(Query.of(q -> q.multiMatch(MultiMatchQuery.of(mm ->
{
mm.query(searchTerm)
.fields("fieldValues." + field)
.operator(Operator.And)
.lenient(true)
.boost(boost);
return (named ? mm.queryName(FIELD_CLAUSE_PREFIX + field) : mm);
}))));
}
}
@@ -869,6 +891,17 @@ public class QuickSearchOpenSearchClient implements Closeable
/*******************************************************************************
** The underlying OpenSearch client, for the read-only diagnostics
** (QuickSearchDiagnosticsOperations).
*******************************************************************************/
OpenSearchClient getOpenSearchClient()
{
return (client);
}
/*******************************************************************************
** Getter for the configured alias name.
*******************************************************************************/
src/main/java/com/kingsrook/qbits/quicksearch/processes/AbstractIndexingStep.java
+46 -8
View File
@@ -32,6 +32,7 @@ import com.kingsrook.qqq.backend.core.actions.tables.DeleteAction;
import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.logging.QLogger;
import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
@@ -48,7 +49,9 @@ import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitContext;
import com.kingsrook.qbits.quicksearch.QuickSearchableTableConfig;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
import com.kingsrook.qbits.quicksearch.model.QuickSearchIndexRun;
import com.kingsrook.qbits.quicksearch.model.QuickSearchValidationRun;
import com.kingsrook.qbits.quicksearch.opensearch.BulkIndexResult;
import com.kingsrook.qbits.quicksearch.opensearch.OpenSearchDocument;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchOpenSearchClient;
@@ -565,19 +568,37 @@ public abstract class AbstractIndexingStep implements BackendStep
** Delete run records older than runHistoryRetentionDays. Never throws.
*******************************************************************************/
protected void purgeOldRuns()
{
Integer retentionDays = getConfigOrNull() == null ? null : getConfigOrNull().getRunHistoryRetentionDays();
if(retentionDays == null || retentionDays <= 0)
{
return;
}
Instant cutoff = Instant.now().minus(retentionDays, ChronoUnit.DAYS);
purgeOlderThan(getConfigOrNull().getQuickSearchIndexRunTableName(), "startTime", cutoff, retentionDays);
purgeOlderThan(getConfigOrNull().applyPrefix(QuickSearchDiagnosticEvent.TABLE_NAME), "createDate", cutoff, retentionDays);
purgeOlderThan(getConfigOrNull().applyPrefix(QuickSearchValidationRun.TABLE_NAME), "createDate", cutoff, retentionDays);
}
/*******************************************************************************
** Delete up to 5000 rows of a history table older than the cutoff. A table
** not in the instance is skipped; failures are logged.
*******************************************************************************/
private void purgeOlderThan(String tableName, String dateField, Instant cutoff, Integer retentionDays)
{
try
{
Integer retentionDays = getConfig().getRunHistoryRetentionDays();
if(retentionDays == null || retentionDays <= 0)
if(QContext.getQInstance() == null || QContext.getQInstance().getTable(tableName) == null)
{
return;
}
Instant cutoff = Instant.now().minus(retentionDays, ChronoUnit.DAYS);
QueryInput queryInput = new QueryInput();
queryInput.setTableName(getConfig().getQuickSearchIndexRunTableName());
queryInput.setFilter(new QQueryFilter(new QFilterCriteria("startTime", QCriteriaOperator.LESS_THAN, cutoff)).withLimit(5000));
queryInput.setTableName(tableName);
queryInput.setFilter(new QQueryFilter(new QFilterCriteria(dateField, QCriteriaOperator.LESS_THAN, cutoff)).withLimit(5000));
List<QRecord> old = new QueryAction().execute(queryInput).getRecords();
if(CollectionUtils.nullSafeIsEmpty(old))
{
@@ -591,14 +612,31 @@ public abstract class AbstractIndexingStep implements BackendStep
}
DeleteInput deleteInput = new DeleteInput();
deleteInput.setTableName(getConfig().getQuickSearchIndexRunTableName());
deleteInput.setTableName(tableName);
deleteInput.setPrimaryKeys(ids);
new DeleteAction().execute(deleteInput);
LOG.info("Purged old Quick Search run records", logPair("count", ids.size()), logPair("olderThanDays", retentionDays));
LOG.info("Purged old Quick Search history records", logPair("tableName", tableName), logPair("count", ids.size()), logPair("olderThanDays", retentionDays));
}
catch(Exception e)
{
LOG.warn("Failed to purge old run records", e);
LOG.warn("Failed to purge old Quick Search history records", e, logPair("tableName", tableName));
}
}
/*******************************************************************************
** The config, or null when it cannot be resolved (purging is best effort).
*******************************************************************************/
private QuickSearchQBitConfig getConfigOrNull()
{
try
{
return (getConfig());
}
catch(Exception e)
{
return (null);
}
}
src/main/java/com/kingsrook/qbits/quicksearch/processes/diagnostics/AbstractDiagnosticToolStep.java
+162
View File
@@ -0,0 +1,162 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.processes.diagnostics;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
import com.kingsrook.qqq.backend.core.utils.StringUtils;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml;
import com.kingsrook.qbits.quicksearch.model.QuickSearchFailedEvent;
/*******************************************************************************
** Base of the diagnostic tool steps. Each tool's process has the steps
** PREPARE (backend), FORM or CONFIRM (frontend: fields and an HTML block),
** RUN (backend) and, for one-shot tools, RESULT (frontend: HTML). One step
** class serves a tool's backend steps, switching on the step name.
** Looping tools (playground, analyzer, inspect) end RUN by pointing the
** process back at PREPARE, so the next step is FORM again with the results
** below the fields: change the input, run again, without restarting.
** HTML goes in the process value "{step}.html", which the HTML component of
** that frontend step renders.
*******************************************************************************/
public abstract class AbstractDiagnosticToolStep implements BackendStep
{
public static final String STEP_PREPARE = "prepare";
public static final String STEP_FORM = "form";
public static final String STEP_CONFIRM = "confirm";
public static final String STEP_RUN = "run";
public static final String STEP_RESULT = "result";
/*******************************************************************************
** One record a tool works on.
*******************************************************************************/
public record Target(String tableName, String recordId)
{
/*******************************************************************************
** "table:recordId"
*******************************************************************************/
@Override
public String toString()
{
return (tableName + ":" + recordId);
}
/*******************************************************************************
** Parse "table:recordId" (null when malformed).
*******************************************************************************/
public static Target parse(String value)
{
int colon = value == null ? -1 : value.indexOf(':');
return (colon <= 0 || colon == value.length() - 1 ? null : new Target(value.substring(0, colon), value.substring(colon + 1)));
}
}
/*******************************************************************************
** Set the HTML shown by a frontend step.
*******************************************************************************/
protected static void setHtml(RunBackendStepOutput output, String frontendStepName, String html)
{
output.addValue(frontendStepName + ".html", html);
}
/*******************************************************************************
** After RUN, show FORM again (the step after PREPARE).
*******************************************************************************/
protected static void loopBackToForm(RunBackendStepOutput output)
{
output.setOverrideLastStepName(STEP_PREPARE);
}
/*******************************************************************************
** A failure shown in the step's HTML instead of ending the process, so the
** user can change the input and run again.
*******************************************************************************/
protected static String failureHtml(String what, Exception e)
{
return (new DiagnosticsHtml().open().status(DiagnosticsHtml.Level.FAIL, what + ": " + e.getMessage()).close().toString());
}
/*******************************************************************************
** The records the process was started on, as targets: for a source table,
** its primary keys; for the failed event table, each row's table and
** record id (only tables Quick Search indexes). Read from the records the
** backend loaded into the process state (never from client values), so
** every step works on exactly the records the user selected and may read.
** At most max; more is a user-facing error.
*******************************************************************************/
protected static List<Target> targetsFromInput(RunBackendStepInput input, QuickSearchRuntime runtime, int max) throws QException
{
QProcessMetaData process = QContext.getQInstance().getProcess(input.getProcessName());
String tableName = process == null ? null : process.getTableName();
QTableMetaData table = tableName == null ? null : QContext.getQInstance().getTable(tableName);
if(table == null)
{
throw (new QUserFacingException("This tool runs on records of a table."));
}
List<QRecord> records = CollectionUtils.nonNullList(input.getRecords());
if(records.isEmpty())
{
throw (new QUserFacingException("Select at least one record."));
}
if(records.size() > max)
{
throw (new QUserFacingException("Select at most " + max + " records (" + records.size() + "+ selected)."));
}
boolean failedEvents = tableName.equals(runtime.getConfig().applyPrefix(QuickSearchFailedEvent.TABLE_NAME));
Set<Target> targets = new LinkedHashSet<>();
for(QRecord record : records)
{
String targetTable = failedEvents ? record.getValueString("tableName") : tableName;
String recordId = failedEvents ? record.getValueString("recordId") : record.getValueString(table.getPrimaryKeyField());
if(StringUtils.hasContent(targetTable) && StringUtils.hasContent(recordId) && runtime.getTableConfig(targetTable) != null)
{
targets.add(new Target(targetTable, recordId));
}
}
return (new ArrayList<>(targets));
}
}
src/main/java/com/kingsrook/qbits/quicksearch/processes/diagnostics/AnalyzeTextStep.java
+83
View File
@@ -0,0 +1,83 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.processes.diagnostics;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.diagnostics.AnalyzerTester;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsSupport;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
/*******************************************************************************
** Steps of the Test Search Analyzer process (a table action on Quick Search
** Index): run the index's analyzers on text, and check a query against it.
** Loops back to the form.
*******************************************************************************/
public class AnalyzeTextStep extends AbstractDiagnosticToolStep
{
public static final String FIELD_TEXT = "analyzeText";
public static final String FIELD_QUERY = "analyzeQuery";
/*******************************************************************************
*******************************************************************************/
@Override
public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
{
QuickSearchRuntime runtime = DiagnosticsSupport.requireRuntime();
if(STEP_PREPARE.equals(input.getStepName()))
{
setHtml(output, STEP_FORM, new DiagnosticsHtml().open()
.paragraph("Enter text as it would be indexed (a field value) and, optionally, a search term. You get the tokens each of the index's analyzers produces "
+ "and, with a term, whether every term token is among the text's indexed tokens: that is how a document's searchable text matches. Nothing is changed.")
.close().toString());
return;
}
loopBackToForm(output);
long start = System.currentTimeMillis();
try
{
DiagnosticsSupport.checkRateLimit(runtime, DiagnosticsSupport.TOOL_ANALYZE_TEXT);
}
catch(QUserFacingException e)
{
setHtml(output, STEP_FORM, failureHtml("Not run", e));
return;
}
String query = input.getValueString(FIELD_QUERY);
try
{
setHtml(output, STEP_FORM, AnalyzerTester.render(new AnalyzerTester().analyze(runtime, input.getValueString(FIELD_TEXT), query)));
DiagnosticsSupport.recordToolRun(runtime, DiagnosticsSupport.TOOL_ANALYZE_TEXT, QuickSearchDiagnosticEvent.TYPE_TOOL_RUN, null, query, start, null, null);
}
catch(Exception e)
{
setHtml(output, STEP_FORM, failureHtml("Analyzing failed (is OpenSearch reachable and the index created?)", e));
DiagnosticsSupport.recordToolRun(runtime, DiagnosticsSupport.TOOL_ANALYZE_TEXT, QuickSearchDiagnosticEvent.TYPE_TOOL_RUN, null, query, start, e, null);
}
}
}
src/main/java/com/kingsrook/qbits/quicksearch/processes/diagnostics/InspectRecordStep.java
+92
View File
@@ -0,0 +1,92 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.processes.diagnostics;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsSupport;
import com.kingsrook.qbits.quicksearch.diagnostics.RecordInspector;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
/*******************************************************************************
** Steps of Inspect Search Document, a record action on every indexed table
** (and on Quick Search Failed Event, for the event's record). PREPARE shows
** each selected record's indexed document next to the database; RUN adds
** the match analysis for the entered term and loops back to the form.
** Read-only.
*******************************************************************************/
public class InspectRecordStep extends AbstractDiagnosticToolStep
{
public static final String FIELD_TERM = "searchTerm";
public static final int MAX_RECORDS = 10;
/*******************************************************************************
*******************************************************************************/
@Override
public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
{
QuickSearchRuntime runtime = DiagnosticsSupport.requireRuntime();
if(!STEP_PREPARE.equals(input.getStepName()))
{
loopBackToForm(output);
}
List<Target> targets = targetsFromInput(input, runtime, MAX_RECORDS);
long start = System.currentTimeMillis();
String term = STEP_PREPARE.equals(input.getStepName()) ? null : input.getValueString(FIELD_TERM);
try
{
DiagnosticsSupport.checkRateLimit(runtime, DiagnosticsSupport.TOOL_INSPECT_RECORD);
}
catch(QUserFacingException e)
{
setHtml(output, STEP_FORM, failureHtml("Not run", e));
return;
}
Set<String> tables = new LinkedHashSet<>();
try
{
List<RecordInspector.Inspection> inspections = new ArrayList<>();
for(Target target : targets)
{
tables.add(target.tableName());
inspections.add(new RecordInspector().inspect(runtime, target.tableName(), target.recordId(), term, input));
}
setHtml(output, STEP_FORM, RecordInspector.render(inspections, term));
DiagnosticsSupport.recordToolRun(runtime, DiagnosticsSupport.TOOL_INSPECT_RECORD, QuickSearchDiagnosticEvent.TYPE_TOOL_RUN, tables, term, start, null,
"records: " + String.join(", ", targets.stream().map(Target::toString).toList()));
}
catch(Exception e)
{
setHtml(output, STEP_FORM, failureHtml("Inspecting failed (is OpenSearch reachable?)", e));
DiagnosticsSupport.recordToolRun(runtime, DiagnosticsSupport.TOOL_INSPECT_RECORD, QuickSearchDiagnosticEvent.TYPE_TOOL_RUN, tables, term, start, e, null);
}
}
}
src/main/java/com/kingsrook/qbits/quicksearch/processes/diagnostics/ReindexRecordsStep.java
+109
View File
@@ -0,0 +1,109 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.processes.diagnostics;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsSupport;
import com.kingsrook.qbits.quicksearch.diagnostics.RecordReindexer;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
/*******************************************************************************
** Steps of Reindex in Search, a record action on every indexed table (and
** on Quick Search Failed Event, for the event's record): PREPARE asks to
** confirm, RUN rebuilds the selected records' documents (RecordReindexer)
** and shows the outcome. The only diagnostic action that writes to the
** index; it needs the Quick Search admin permission.
*******************************************************************************/
public class ReindexRecordsStep extends AbstractDiagnosticToolStep
{
public static final int MAX_RECORDS = 500;
/*******************************************************************************
*******************************************************************************/
@Override
public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
{
QuickSearchRuntime runtime = DiagnosticsSupport.requireRuntime();
if(STEP_PREPARE.equals(input.getStepName()))
{
List<Target> targets = targetsFromInput(input, runtime, MAX_RECORDS);
Map<String, List<String>> byTable = groupByTable(targets);
List<String> lines = new ArrayList<>();
byTable.forEach((table, ids) -> lines.add(ids.size() + " record(s) of " + table));
setHtml(output, STEP_CONFIRM, new DiagnosticsHtml().open()
.paragraph("Rebuild the search documents of " + String.join(", ", lines) + " from the database now? Records that no longer exist have their documents removed. "
+ "Records are not changed. The run is recorded in Quick Search Diagnostic Event.")
.close().toString());
return;
}
long start = System.currentTimeMillis();
DiagnosticsSupport.checkRateLimit(runtime, DiagnosticsSupport.TOOL_REINDEX_RECORDS);
StringBuilder html = new StringBuilder();
for(Map.Entry<String, List<String>> entry : groupByTable(targetsFromInput(input, runtime, MAX_RECORDS)).entrySet())
{
try
{
List<RecordReindexer.Outcome> outcomes = new RecordReindexer().reindex(runtime, entry.getKey(), entry.getValue());
html.append(RecordReindexer.render(entry.getKey(), outcomes));
DiagnosticsSupport.recordToolRun(runtime, DiagnosticsSupport.TOOL_REINDEX_RECORDS, QuickSearchDiagnosticEvent.TYPE_REINDEX, List.of(entry.getKey()), null, start, null,
"records: " + String.join(", ", entry.getValue()) + "; outcomes: " + String.join(", ", outcomes.stream().map(o -> o.recordId() + "=" + o.outcome()).toList()));
}
catch(Exception e)
{
html.append(failureHtml("Reindexing " + entry.getKey() + " failed", e));
DiagnosticsSupport.recordToolRun(runtime, DiagnosticsSupport.TOOL_REINDEX_RECORDS, QuickSearchDiagnosticEvent.TYPE_REINDEX, List.of(entry.getKey()), null, start, e,
"records: " + String.join(", ", entry.getValue()));
}
}
setHtml(output, STEP_RESULT, html.toString());
}
/*******************************************************************************
** Record ids grouped by table, in selection order.
*******************************************************************************/
static Map<String, List<String>> groupByTable(List<Target> targets) throws QUserFacingException
{
if(targets.isEmpty())
{
throw (new QUserFacingException("No records to reindex."));
}
Map<String, List<String>> byTable = new LinkedHashMap<>();
for(Target target : targets)
{
byTable.computeIfAbsent(target.tableName(), k -> new ArrayList<>()).add(target.recordId());
}
return (byTable);
}
}
src/main/java/com/kingsrook/qbits/quicksearch/processes/diagnostics/SearchPlaygroundStep.java
+169
View File
@@ -0,0 +1,169 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.processes.diagnostics;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
import com.kingsrook.qqq.backend.core.utils.StringUtils;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsSupport;
import com.kingsrook.qbits.quicksearch.diagnostics.SearchPathDiagnosis;
import com.kingsrook.qbits.quicksearch.diagnostics.SearchPlayground;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
/*******************************************************************************
** Steps of the Search Playground process (a table action on Quick Search
** Index). PREPARE shows which tables are indexed and the provider's state,
** and pre-fills the tables from the selected Quick Search Index rows; RUN
** runs SearchPlayground as the current user and loops back to the form.
*******************************************************************************/
public class SearchPlaygroundStep extends AbstractDiagnosticToolStep
{
public static final String FIELD_TERM = "searchTerm";
public static final String FIELD_TABLES = "tableNames";
public static final String FIELD_LIMIT_PER_TABLE = "limitPerTable";
public static final String FIELD_EXPLAIN_HIT = "explainHit";
/*******************************************************************************
*******************************************************************************/
@Override
public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
{
QuickSearchRuntime runtime = DiagnosticsSupport.requireRuntime();
if(STEP_PREPARE.equals(input.getStepName()))
{
prepare(input, output, runtime);
return;
}
loopBackToForm(output);
long start = System.currentTimeMillis();
try
{
DiagnosticsSupport.checkRateLimit(runtime, DiagnosticsSupport.TOOL_PLAYGROUND);
}
catch(QUserFacingException e)
{
setHtml(output, STEP_FORM, failureHtml("Not run", e));
return;
}
String term = input.getValueString(FIELD_TERM);
List<String> tables = parseTables(input.getValueString(FIELD_TABLES));
try
{
SearchPlayground.Report report = new SearchPlayground().run(runtime,
new SearchPlayground.Input(term, tables, input.getValueInteger(FIELD_LIMIT_PER_TABLE), input.getValueString(FIELD_EXPLAIN_HIT)), input);
setHtml(output, STEP_FORM, SearchPlayground.render(report));
DiagnosticsSupport.recordToolRun(runtime, DiagnosticsSupport.TOOL_PLAYGROUND, QuickSearchDiagnosticEvent.TYPE_TOOL_RUN, tables, term, start, null,
report.coreError() != null ? "global search failed: " + report.coreError() : (report.providerError() != null ? "provider failed: " + report.providerError() : null));
}
catch(Exception e)
{
setHtml(output, STEP_FORM, failureHtml("The playground failed", e));
DiagnosticsSupport.recordToolRun(runtime, DiagnosticsSupport.TOOL_PLAYGROUND, QuickSearchDiagnosticEvent.TYPE_TOOL_RUN, tables, term, start, e, null);
}
}
/*******************************************************************************
** Intro HTML and table pre-fill.
*******************************************************************************/
private void prepare(RunBackendStepInput input, RunBackendStepOutput output, QuickSearchRuntime runtime) throws QException
{
List<String> selected = selectedIndexTables(input, runtime);
if(!selected.isEmpty())
{
output.addValue(FIELD_TABLES, String.join(", ", selected));
}
List<String> indexed = new ArrayList<>();
runtime.getDiscoveredTables().forEach(t -> indexed.add(t.getTableName()));
SearchPathDiagnosis.ProviderState state = SearchPathDiagnosis.providerState(QContext.getQInstance(), runtime);
DiagnosticsHtml html = new DiagnosticsHtml().open()
.paragraph("Type a term and run it. The playground runs it the way the global search does, as you, and shows the path each table takes, what you would see, "
+ "and the OpenSearch query, scores, matched fields and raw response behind it. Leave the tables blank to search every searchable table. "
+ "To explain a hit, copy its document id (table:id) into Explain hit. Nothing is changed.")
.facts(List.of(
new String[] { "Indexed tables", indexed.isEmpty() ? null : String.join(", ", indexed) },
new String[] { "Provider", Boolean.TRUE.equals(state.quickSearchProvider()) ? "Quick Search serves the global search" : "Quick Search does not serve the global search" },
new String[] { "Backing off", state.backoffRemainingMillis() > 0 ? (state.backoffRemainingMillis() / 1000) + " s left after a failure" : "no" }))
.close();
setHtml(output, STEP_FORM, html.toString());
}
/*******************************************************************************
** Table names of the Quick Search Index rows the process was started on
** (the recordIds value), if any.
*******************************************************************************/
static List<String> selectedIndexTables(RunBackendStepInput input, QuickSearchRuntime runtime) throws QException
{
String recordIds = input.getValueString("recordIds");
String table = runtime.getConfig().getQuickSearchIndexTableName();
if(!StringUtils.hasContent(recordIds) || QContext.getQInstance().getTable(table) == null)
{
return (List.of());
}
QueryInput queryInput = new QueryInput();
queryInput.setTableName(table);
queryInput.setFilter(new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.IN, Arrays.stream(recordIds.split(",")).map(String::trim).filter(s -> !s.isEmpty()).toList())));
List<String> tables = new ArrayList<>();
for(QRecord row : CollectionUtils.nonNullList(new QueryAction().execute(queryInput).getRecords()))
{
tables.add(row.getValueString("tableName"));
}
return (tables);
}
/*******************************************************************************
** Table names from a comma- or space-separated list.
*******************************************************************************/
public static List<String> parseTables(String value)
{
if(!StringUtils.hasContent(value))
{
return (List.of());
}
return (Arrays.stream(value.split("[,\\s]+")).map(String::trim).filter(s -> !s.isEmpty()).distinct().toList());
}
}
src/main/java/com/kingsrook/qbits/quicksearch/processes/diagnostics/ValidateIndexStep.java
+124
View File
@@ -0,0 +1,124 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.processes.diagnostics;
import java.util.List;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
import com.kingsrook.qqq.backend.core.model.session.QSession;
import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsSupport;
import com.kingsrook.qbits.quicksearch.diagnostics.IndexValidator;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
import com.kingsrook.qbits.quicksearch.model.QuickSearchValidationRun;
/*******************************************************************************
** Steps of Validate Search Index (a table action on Quick Search Index, and
** schedulable with validationCronExpression). PREPARE picks the tables (the
** selected Quick Search Index rows, else all); RUN validates them
** (IndexValidator), saves the report as a Quick Search Validation Run row
** and shows it. One validation runs at a time per server. A scheduled run
** (frontend steps skipped) validates every table with the configured sample
** size and is not rate-limited.
*******************************************************************************/
public class ValidateIndexStep extends AbstractDiagnosticToolStep
{
public static final String FIELD_SAMPLE_SIZE = "sampleSize";
public static final String FIELD_TABLES = "validateTableNames";
public static final String FIELD_RUN_ID = "validationRunId";
/*******************************************************************************
*******************************************************************************/
@Override
public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
{
QuickSearchRuntime runtime = DiagnosticsSupport.requireRuntime();
QuickSearchQBitConfig config = runtime.getConfig();
if(STEP_PREPARE.equals(input.getStepName()))
{
List<String> tables = SearchPlaygroundStep.selectedIndexTables(input, runtime);
output.addValue(FIELD_TABLES, String.join(",", tables));
if(input.getValue(FIELD_SAMPLE_SIZE) == null)
{
output.addValue(FIELD_SAMPLE_SIZE, config.getValidationSampleSize());
}
setHtml(output, STEP_FORM, new DiagnosticsHtml().open()
.paragraph("Validate " + (tables.isEmpty() ? "every indexed table" : String.join(", ", tables)) + ": cluster and index health, the mapping and analyzers, "
+ "database rows vs indexed documents, and a sample of records and documents checked for missing, stale and orphaned documents. "
+ "Read-only; the report is saved as a Quick Search Validation Run.")
.close().toString());
return;
}
//////////////////////////////////////////////////////////////////////
// a scheduled run skips the frontend and has no user; an API caller //
// asking to skip the frontend is still a user, so still rate-limited //
//////////////////////////////////////////////////////////////////////
QSession session = QContext.getQSession();
boolean scheduled = input.getFrontendStepBehavior() == RunProcessInput.FrontendStepBehavior.SKIP
&& (session == null || session instanceof QSystemUserSession || session.getUser() == null);
long start = System.currentTimeMillis();
if(!scheduled)
{
DiagnosticsSupport.checkRateLimit(runtime, DiagnosticsSupport.TOOL_VALIDATE_INDEX);
}
if(!runtime.beginValidation())
{
throw (new QUserFacingException("A validation is already running on this server. Try again when it finishes."));
}
List<String> tables = SearchPlaygroundStep.parseTables(input.getValueString(FIELD_TABLES));
Integer sample = input.getValueInteger(FIELD_SAMPLE_SIZE);
try
{
IndexValidator validator = new IndexValidator();
IndexValidator.Report report = validator.validate(runtime, tables, sample == null ? config.getValidationSampleSize() : sample);
Integer runId = validator.persist(runtime, report, scheduled ? QuickSearchValidationRun.TRIGGER_SCHEDULED : QuickSearchValidationRun.TRIGGER_MANUAL,
DiagnosticsSupport.currentUserName());
String link = runId == null
? "<p><em>The report was not saved (the validation run table is not configured or the insert failed; see the log).</em></p>"
: "<p>Saved as <a href=\"/app/" + DiagnosticsHtml.escape(config.applyPrefix(QuickSearchValidationRun.TABLE_NAME)) + "/" + runId + "\">validation run #" + runId + "</a>.</p>";
setHtml(output, STEP_RESULT, IndexValidator.render(report) + link);
output.addValue(FIELD_RUN_ID, runId);
output.addValue("status", report.status());
DiagnosticsSupport.recordToolRun(runtime, DiagnosticsSupport.TOOL_VALIDATE_INDEX, QuickSearchDiagnosticEvent.TYPE_TOOL_RUN, report.tableNames(), null, start, null,
IndexValidator.summary(report) + (runId == null ? "" : " run #" + runId));
}
catch(QException e)
{
DiagnosticsSupport.recordToolRun(runtime, DiagnosticsSupport.TOOL_VALIDATE_INDEX, QuickSearchDiagnosticEvent.TYPE_TOOL_RUN, tables, null, start, e, null);
throw (e);
}
finally
{
runtime.endValidation();
}
}
}
src/test/java/com/kingsrook/qbits/quicksearch/DiagnosticsIntegrationTest.java
+431
View File
@@ -0,0 +1,431 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch;
import java.time.Instant;
import java.util.List;
import java.util.Map;
import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction;
import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessOutput;
import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType;
import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.core.model.session.QSession;
import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule;
import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryRecordStore;
import com.kingsrook.qbits.quicksearch.diagnostics.AnalyzerTester;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml.Check;
import com.kingsrook.qbits.quicksearch.diagnostics.DiagnosticsHtml.Level;
import com.kingsrook.qbits.quicksearch.diagnostics.IndexValidator;
import com.kingsrook.qbits.quicksearch.diagnostics.RecordInspector;
import com.kingsrook.qbits.quicksearch.diagnostics.RecordReindexer;
import com.kingsrook.qbits.quicksearch.diagnostics.SearchPathDiagnosis;
import com.kingsrook.qbits.quicksearch.diagnostics.SearchPlayground;
import com.kingsrook.qbits.quicksearch.metadata.QuickSearchDiagnosticsProcessMetaDataHelper;
import com.kingsrook.qbits.quicksearch.model.QuickSearchValidationRun;
import com.kingsrook.qbits.quicksearch.opensearch.OpenSearchDocument;
import com.kingsrook.qbits.quicksearch.opensearch.QuickSearchDiagnosticsOperations;
import com.kingsrook.qbits.quicksearch.processes.FullReindexStep;
import com.kingsrook.qbits.quicksearch.processes.diagnostics.AbstractDiagnosticToolStep;
import com.kingsrook.qbits.quicksearch.processes.diagnostics.InspectRecordStep;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.MethodOrderer;
import org.junit.jupiter.api.Order;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestMethodOrder;
import org.junit.jupiter.api.extension.ExtendWith;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import static org.assertj.core.api.Assertions.assertThat;
/*******************************************************************************
** The diagnostic tools against a real OpenSearch (Testcontainers): the
** playground (paths, provider ids, global search results, scores, matched
** clauses, highlights, query DSL, explain, term tokens), the analyzer
** tester, record inspection (current, stale, missing, and why a term does
** or does not match), index validation (counts, missing, stale and orphaned
** documents, mapping, analyzers, leftover physical index, the saved
** report), reindexing records, and the tool processes end to end.
** Real-time indexing is off so the tests can make the index drift.
*******************************************************************************/
@ExtendWith(RequiresDockerCondition.class)
@Testcontainers
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
class DiagnosticsIntegrationTest
{
private static final String BACKEND = "memory";
private static final String PRODUCT = "diagProduct";
private static final String INDEX = "quick_search_diagnostics_it";
@Container
static GenericContainer<?> opensearch = new GenericContainer<>(System.getProperty("opensearch.test.image", "opensearchproject/opensearch:2.19.6"))
.withExposedPorts(9200)
.withEnv("discovery.type", "single-node")
.withEnv("DISABLE_SECURITY_PLUGIN", "true")
.withEnv("DISABLE_INSTALL_DEMO_CONFIG", "true")
.waitingFor(Wait.forHttp("/_cluster/health").forStatusCode(200));
private static QuickSearchQBitConfig config;
private static QuickSearchRuntime runtime;
/*******************************************************************************
** Instance with one indexed product table; four products indexed.
*******************************************************************************/
@BeforeAll
static void setUpAll() throws Exception
{
MemoryRecordStore.getInstance().reset();
QInstance qInstance = new QInstance();
qInstance.addBackend(new QBackendMetaData().withName(BACKEND).withBackendType(MemoryBackendModule.class));
qInstance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("anonymous").withType(QAuthenticationType.FULLY_ANONYMOUS));
qInstance.addTable(new QTableMetaData()
.withName(PRODUCT)
.withLabel("Product")
.withBackendName(BACKEND)
.withPrimaryKeyField("id")
.withRecordLabelFormat("%s")
.withRecordLabelFields("name")
.withField(new QFieldMetaData("id", QFieldType.INTEGER).withIsEditable(false))
.withField(new QFieldMetaData("name", QFieldType.STRING))
.withField(new QFieldMetaData("description", QFieldType.STRING))
.withField(new QFieldMetaData("modifyDate", QFieldType.DATE_TIME)));
config = new QuickSearchQBitConfig()
.withBackendName(BACKEND)
.withOpensearchHost(opensearch.getHost())
.withOpensearchPort(opensearch.getMappedPort(9200))
.withOpensearchIndexName(INDEX)
.withEnableRealTimeIndexing(false)
.withDiagnosticRunsPerMinute(1000)
.withSearchableTable(new SearchableTableConfig(PRODUCT, List.of(
new SearchableFieldConfig("name").withWeight(3),
new SearchableFieldConfig("description"))));
new QuickSearchQBitProducer().withConfig(config).produce(qInstance);
QContext.init(qInstance, new QSession());
runtime = config.getRuntime();
new InsertAction().execute(new InsertInput(PRODUCT).withRecords(List.of(
product(1, "Blue Widget", "the original"),
product(2, "Widget", "comes in blue and green"),
product(3, "Red Widget", "not that colour"),
product(4, "Gadget", "no match here"))));
new FullReindexStep().run(new RunBackendStepInput(), new RunBackendStepOutput());
runtime.getClient().refreshIndex();
}
/*******************************************************************************
*******************************************************************************/
@AfterAll
static void tearDownAll()
{
if(runtime != null)
{
runtime.close();
}
QContext.clear();
QuickSearchQBitContext.clear();
MemoryRecordStore.getInstance().reset();
}
/*******************************************************************************
*******************************************************************************/
private static QRecord product(int id, String name, String description)
{
return (new QRecord().withValue("id", id).withValue("name", name).withValue("description", description).withValue("modifyDate", Instant.now()));
}
/*******************************************************************************
*******************************************************************************/
private static QuickSearchDiagnosticsOperations ops() throws Exception
{
return (new QuickSearchDiagnosticsOperations(runtime.getClient()));
}
/*******************************************************************************
*******************************************************************************/
private static Check check(List<Check> checks, String name)
{
return (checks.stream().filter(c -> c.name().equals(name)).findFirst().orElseThrow(() -> new AssertionError("no check " + name + " in " + checks)));
}
@Test
@Order(1)
void testPlayground_fullPicture() throws Exception
{
SearchPlayground.Report report = new SearchPlayground().run(runtime, new SearchPlayground.Input("blue widget", List.of(PRODUCT), 5, PRODUCT + ":1"), new QueryInput());
assertThat(report.paths()).singleElement().satisfies(p -> assertThat(p.path()).isEqualTo(SearchPathDiagnosis.PATH_OPENSEARCH));
assertThat(report.providerError()).isNull();
assertThat(report.providerIds().get(PRODUCT)).containsExactlyInAnyOrder("1", "2");
assertThat(report.coreError()).isNull();
assertThat(report.coreResults().get(PRODUCT)).extracting(r -> String.valueOf(r.getRecordId())).containsExactlyInAnyOrder("1", "2");
assertThat(report.termTokens()).extracting(QuickSearchDiagnosticsOperations.AnalyzedToken::token).containsExactly("blue", "widget");
SearchPlayground.TableProbe probe = report.probes().get(0);
assertThat(probe.error()).isNull();
assertThat(probe.hiddenCount()).isZero();
assertThat(report.providerHiddenCounts().get(PRODUCT)).isZero();
assertThat(probe.probe().hits()).hasSize(2);
QuickSearchDiagnosticsOperations.ProbeHit top = probe.probe().hits().get(0);
assertThat(top.recordId()).isEqualTo("1");
assertThat(top.matchedClauses()).contains("searchableText", "field:name");
assertThat(top.highlights().values().stream().flatMap(List::stream).toList()).anyMatch(f -> f.contains("<em>"));
assertThat(probe.readableIds()).contains("1", "2");
assertThat(probe.shownIds()).contains("1", "2");
assertThat(probe.probe().requestJson()).contains("\"_name\"").contains("searchableText");
assertThat(probe.probe().responseJson()).contains("\"hits\"");
assertThat(report.explain().documentFound()).isTrue();
assertThat(report.explain().matched()).isTrue();
assertThat(report.explain().score()).isPositive();
assertThat(report.explain().explanationText()).isNotBlank();
String html = SearchPlayground.render(report);
assertThat(html).contains("Query DSL").contains("Raw response").contains("shown in global search").contains("<mark>").contains("Matched: searchableText, name");
}
@Test
@Order(2)
void testAnalyzer_tokensAndQueryMatch() throws Exception
{
AnalyzerTester.Result result = new AnalyzerTester().analyze(runtime, "Blue Widgets", "wid x");
assertThat(result.indexTokens()).extracting(QuickSearchDiagnosticsOperations.AnalyzedToken::token).contains("bl", "blue", "wi", "wid", "widgets");
assertThat(result.textAsQueryTokens()).extracting(QuickSearchDiagnosticsOperations.AnalyzedToken::token).containsExactly("blue", "widgets");
assertThat(result.queryTokens()).extracting(QuickSearchDiagnosticsOperations.AnalyzedToken::token).containsExactly("wid", "x");
String html = AnalyzerTester.render(result);
assertThat(html).contains("never indexed (n-grams start at 2)").contains("At least one query token is missing");
assertThat(AnalyzerTester.render(new AnalyzerTester().analyze(runtime, "Blue Widgets", "wid blu"))).contains("Every query token is found");
}
@Test
@Order(3)
void testInspect_currentRecordAndMatchReasons() throws Exception
{
RecordInspector.Inspection current = new RecordInspector().inspect(runtime, PRODUCT, "1", null, new QueryInput());
assertThat(current.verdict()).isEqualTo(RecordInspector.VERDICT_CURRENT);
assertThat(current.diffs()).allMatch(RecordInspector.FieldDiff::isSame);
assertThat(current.indexed().version()).isNotNull();
RecordInspector.Inspection matched = new RecordInspector().inspect(runtime, PRODUCT, "1", "blue", new QueryInput());
assertThat(check(matched.matchChecks(), "Token \"blue\"").level()).isEqualTo(Level.OK);
assertThat(check(matched.matchChecks(), "OpenSearch explain").level()).isEqualTo(Level.OK);
assertThat(check(matched.matchChecks(), "Rank").level()).isEqualTo(Level.OK);
RecordInspector.Inspection oneChar = new RecordInspector().inspect(runtime, PRODUCT, "1", "blue x", new QueryInput());
assertThat(check(oneChar.matchChecks(), "Token \"x\"").message()).contains("One character");
assertThat(check(oneChar.matchChecks(), "OpenSearch explain").level()).isEqualTo(Level.FAIL);
RecordInspector.Inspection tooLong = new RecordInspector().inspect(runtime, PRODUCT, "1", "abcdefghijklmnopqrstuvwxy", new QueryInput());
assertThat(check(tooLong.matchChecks(), "Token \"abcdefghijklmnopqrstuvwxy\"").message()).contains("Longer than 20");
RecordInspector.Inspection absent = new RecordInspector().inspect(runtime, PRODUCT, "1", "gadget", new QueryInput());
assertThat(check(absent.matchChecks(), "Token \"gadget\"").message()).contains("Not in this record");
assertThat(RecordInspector.render(List.of(matched), "blue")).contains("Indexed and current").contains("Why does (or doesn&#39;t) this record match");
RecordInspector.Inspection none = new RecordInspector().inspect(runtime, PRODUCT, "999", null, new QueryInput());
assertThat(none.verdict()).isEqualTo(RecordInspector.VERDICT_NO_RECORD);
}
@Test
@Order(4)
void testInspect_staleAndMissing() throws Exception
{
new UpdateAction().execute(new UpdateInput(PRODUCT).withRecord(new QRecord().withValue("id", 3).withValue("name", "Crimson Widget").withValue("modifyDate", Instant.now())));
new InsertAction().execute(new InsertInput(PRODUCT).withRecord(product(5, "Purple Widget", "brand new")));
RecordInspector.Inspection stale = new RecordInspector().inspect(runtime, PRODUCT, "3", "crimson", new QueryInput());
assertThat(stale.verdict()).isEqualTo(RecordInspector.VERDICT_STALE);
assertThat(stale.diffs()).filteredOn(d -> !d.isSame()).extracting(RecordInspector.FieldDiff::name).contains("fieldValues.name", "searchableText", "recordLabel");
assertThat(check(stale.matchChecks(), "Token \"crimson\"").level()).isEqualTo(Level.WARN);
assertThat(check(stale.matchChecks(), "Indexed document").level()).isEqualTo(Level.WARN);
RecordInspector.Inspection missing = new RecordInspector().inspect(runtime, PRODUCT, "5", "purple", new QueryInput());
assertThat(missing.verdict()).isEqualTo(RecordInspector.VERDICT_MISSING);
assertThat(check(missing.matchChecks(), "Indexed document").level()).isEqualTo(Level.FAIL);
}
@Test
@Order(5)
void testValidate_findsDriftOrphansAndLeftovers() throws Exception
{
runtime.getClient().indexDocuments(List.of(new OpenSearchDocument().withSourceTable(PRODUCT).withRecordId("99").withSearchableText("orphan")
.withFieldValues(Map.of("name", "orphan")).withIndexedAt(Instant.now())), 10);
runtime.getClient().refreshIndex();
QuickSearchDiagnosticsOperations.RawResponse created = ops().raw("PUT", "/" + INDEX + "-v2-1", "{}");
assertThat(created.isOk()).isTrue();
try
{
IndexValidator validator = new IndexValidator();
IndexValidator.Report report = validator.validate(runtime, List.of(), 50);
assertThat(report.status()).isEqualTo(QuickSearchValidationRun.STATUS_FAIL);
IndexValidator.TableStats stats = report.tableStats().get(0);
assertThat(stats.databaseCount()).isEqualTo(5);
assertThat(stats.indexCount()).isEqualTo(5L);
assertThat(stats.missingIds()).containsExactly("5");
assertThat(stats.staleFields()).containsKey("3");
assertThat(stats.extraIds()).containsExactly("99");
assertThat(report.findings()).anyMatch(f -> f.check().equals("Mapping version") && f.level() == Level.OK);
assertThat(report.findings()).anyMatch(f -> f.check().equals("Field mappings") && f.level() == Level.OK);
assertThat(report.findings()).anyMatch(f -> f.check().equals("Analysis settings") && f.level() == Level.OK);
assertThat(report.findings()).anyMatch(f -> f.check().equals("Alias") && f.level() == Level.OK);
assertThat(report.findings()).anyMatch(f -> f.check().equals("Leftover index") && f.message().contains(INDEX + "-v2-1"));
assertThat(report.findings()).anyMatch(f -> f.check().equals("Sampled documents") && f.level() == Level.FAIL && f.message().contains("99"));
Integer runId = validator.persist(runtime, report, QuickSearchValidationRun.TRIGGER_MANUAL, "tester");
assertThat(runId).isNotNull();
QRecord row = new QueryAction().execute(new QueryInput(QuickSearchValidationRun.TABLE_NAME)).getRecords().get(0);
assertThat(row.getValueString("status")).isEqualTo(QuickSearchValidationRun.STATUS_FAIL);
assertThat(row.getValueString("reportHtml")).contains("Sampled records").contains("Stale fields in " + PRODUCT);
assertThat(row.getValueString("reportJson")).contains("\"missingIds\":[\"5\"]");
assertThat(row.getValueInteger("failCount")).isPositive();
}
finally
{
ops().raw("DELETE", "/" + INDEX + "-v2-1", null);
}
}
@Test
@Order(6)
void testReindex_fixesStaleMissingAndOrphan() throws Exception
{
List<RecordReindexer.Outcome> outcomes = new RecordReindexer().reindex(runtime, PRODUCT, List.of("3", "5", "99", "abc"));
assertThat(outcomes).extracting(RecordReindexer.Outcome::outcome)
.containsExactly(RecordReindexer.OUTCOME_INDEXED, RecordReindexer.OUTCOME_INDEXED, RecordReindexer.OUTCOME_DELETED, RecordReindexer.OUTCOME_SKIPPED);
assertThat(new RecordInspector().inspect(runtime, PRODUCT, "3", null, new QueryInput()).verdict()).isEqualTo(RecordInspector.VERDICT_CURRENT);
assertThat(new RecordInspector().inspect(runtime, PRODUCT, "5", null, new QueryInput()).verdict()).isEqualTo(RecordInspector.VERDICT_CURRENT);
assertThat(ops().getDocument(PRODUCT, "99").found()).isFalse();
IndexValidator.Report report = new IndexValidator().validate(runtime, List.of(PRODUCT), 50);
assertThat(report.findings()).noneMatch(f -> f.level() == Level.FAIL);
assertThat(report.status()).isIn(QuickSearchValidationRun.STATUS_PASS, QuickSearchValidationRun.STATUS_WARN);
}
/*******************************************************************************
** The record actions and the validation as processes, through
** RunProcessAction (what the UI calls).
*******************************************************************************/
@Test
@Order(7)
void testProcesses_endToEnd() throws Exception
{
///////////////////////////////////////////////////////////////////
// inspect: stops at the form with the document already compared //
///////////////////////////////////////////////////////////////////
RunProcessInput inspect = new RunProcessInput();
inspect.setProcessName(QuickSearchDiagnosticsProcessMetaDataHelper.inspectProcessName(config, PRODUCT));
inspect.setFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.BREAK);
inspect.addValue("recordIds", "1");
RunProcessOutput inspected = new RunProcessAction().execute(inspect);
assertThat(inspected.getProcessState().getNextStepName()).hasValue(AbstractDiagnosticToolStep.STEP_FORM);
assertThat(inspected.getValues().get("form.html").toString()).contains("Indexed and current");
RunProcessInput inspectTerm = new RunProcessInput();
inspectTerm.setProcessName(inspect.getProcessName());
inspectTerm.setProcessUUID(inspected.getProcessUUID());
inspectTerm.setStartAfterStep(AbstractDiagnosticToolStep.STEP_FORM);
inspectTerm.setFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.BREAK);
inspectTerm.addValue(InspectRecordStep.FIELD_TERM, "gadget");
RunProcessOutput withTerm = new RunProcessAction().execute(inspectTerm);
assertThat(withTerm.getProcessState().getNextStepName()).hasValue(AbstractDiagnosticToolStep.STEP_FORM);
assertThat(withTerm.getValues().get("form.html").toString()).contains("Not in this record");
////////////////////////////////////////
// reindex: confirm, then the outcome //
////////////////////////////////////////
RunProcessInput reindex = new RunProcessInput();
reindex.setProcessName(QuickSearchDiagnosticsProcessMetaDataHelper.reindexRecordsProcessName(config, PRODUCT));
reindex.setFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.BREAK);
reindex.addValue("recordIds", "2");
RunProcessOutput confirm = new RunProcessAction().execute(reindex);
assertThat(confirm.getProcessState().getNextStepName()).hasValue(AbstractDiagnosticToolStep.STEP_CONFIRM);
assertThat(confirm.getValues().get("confirm.html").toString()).contains("1 record(s) of " + PRODUCT);
RunProcessInput reindexRun = new RunProcessInput();
reindexRun.setProcessName(reindex.getProcessName());
reindexRun.setProcessUUID(confirm.getProcessUUID());
reindexRun.setStartAfterStep(AbstractDiagnosticToolStep.STEP_CONFIRM);
reindexRun.setFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.BREAK);
RunProcessOutput reindexed = new RunProcessAction().execute(reindexRun);
assertThat(reindexed.getValues().get("result.html").toString()).contains("1 reindexed");
/////////////////////////////////////////////////////////////
// validation as the scheduler runs it (frontend skipped) //
/////////////////////////////////////////////////////////////
RunProcessInput validate = new RunProcessInput();
validate.setProcessName(QuickSearchDiagnosticsProcessMetaDataHelper.VALIDATE_PROCESS_NAME);
validate.setFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP);
RunProcessOutput validated = new RunProcessAction().execute(validate);
assertThat(validated.getValues().get("validationRunId")).isNotNull();
List<QRecord> runs = new QueryAction().execute(new QueryInput(QuickSearchValidationRun.TABLE_NAME)).getRecords();
assertThat(runs).anyMatch(r -> QuickSearchValidationRun.TRIGGER_SCHEDULED.equals(r.getValueString("triggerType")));
}
}
src/test/java/com/kingsrook/qbits/quicksearch/DiagnosticsMetaDataTest.java
+303
View File
@@ -0,0 +1,303 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch;
import java.util.List;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.instances.QInstanceValidator;
import com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType;
import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.permissions.PermissionLevel;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.scheduleing.QSchedulerMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.scheduleing.quartz.QuartzSchedulerMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.scheduleing.simple.SimpleSchedulerMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.tables.Capability;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.core.model.session.QSession;
import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule;
import com.kingsrook.qbits.quicksearch.metadata.QuickSearchDiagnosticsProcessMetaDataHelper;
import com.kingsrook.qbits.quicksearch.metadata.QuickSearchDiagnosticsWidgetMetaDataProducer;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
import com.kingsrook.qbits.quicksearch.model.QuickSearchFailedEvent;
import com.kingsrook.qbits.quicksearch.model.QuickSearchIndex;
import com.kingsrook.qbits.quicksearch.model.QuickSearchValidationRun;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
/*******************************************************************************
** The metadata the diagnostic tools add: the two history tables, the fixed
** processes on Quick Search Index and Quick Search Failed Event, the
** per-table record actions, the widget on the admin app, their permission
** rules, scheduling, the opt-out flags, and that the produced instance
** passes QInstanceValidator.
*******************************************************************************/
class DiagnosticsMetaDataTest
{
private static final String BACKEND = "memory";
private static final String SOURCE = "product";
/*******************************************************************************
*******************************************************************************/
@AfterEach
void tearDown()
{
QContext.clear();
QuickSearchQBitContext.clear();
}
/*******************************************************************************
*******************************************************************************/
private static QInstance buildInstance()
{
QInstance qInstance = new QInstance();
qInstance.addBackend(new QBackendMetaData().withName(BACKEND).withBackendType(MemoryBackendModule.class));
qInstance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("anonymous").withType(QAuthenticationType.FULLY_ANONYMOUS));
qInstance.addTable(new QTableMetaData()
.withName(SOURCE)
.withBackendName(BACKEND)
.withPrimaryKeyField("id")
.withField(new QFieldMetaData("id", QFieldType.INTEGER))
.withField(new QFieldMetaData("name", QFieldType.STRING))
.withField(new QFieldMetaData("modifyDate", QFieldType.DATE_TIME)));
QContext.init(qInstance, new QSession());
return (qInstance);
}
/*******************************************************************************
*******************************************************************************/
private static QuickSearchQBitConfig config()
{
return (new QuickSearchQBitConfig()
.withStartupMode(QuickSearchStartupMode.DEGRADED)
.withBackendName(BACKEND)
.withOpensearchHost("localhost")
.withOpensearchPort(9200)
.withOpensearchIndexName("diag-meta")
.withSearchableTable(SOURCE, List.of(new SearchableFieldConfig("name"))));
}
@Test
void testProduce_addsTablesProcessesAndWidget() throws QException
{
QInstance qInstance = buildInstance();
new QuickSearchQBitProducer().withConfig(config()).produce(qInstance);
assertThat(qInstance.getTable(QuickSearchDiagnosticEvent.TABLE_NAME)).isNotNull();
assertThat(qInstance.getTable(QuickSearchValidationRun.TABLE_NAME)).isNotNull();
assertThat(qInstance.getTable(QuickSearchValidationRun.TABLE_NAME).getField("reportHtml").getType()).isEqualTo(QFieldType.HTML);
for(String history : List.of(QuickSearchDiagnosticEvent.TABLE_NAME, QuickSearchValidationRun.TABLE_NAME))
{
assertThat(qInstance.getTable(history).getDisabledCapabilities()).as(history)
.contains(Capability.TABLE_INSERT, Capability.TABLE_UPDATE, Capability.TABLE_DELETE);
}
for(String name : List.of(QuickSearchDiagnosticsProcessMetaDataHelper.PLAYGROUND_PROCESS_NAME, QuickSearchDiagnosticsProcessMetaDataHelper.VALIDATE_PROCESS_NAME,
QuickSearchDiagnosticsProcessMetaDataHelper.ANALYZE_PROCESS_NAME))
{
QProcessMetaData process = qInstance.getProcess(name);
assertThat(process).as(name).isNotNull();
assertThat(process.getTableName()).isEqualTo(QuickSearchIndex.TABLE_NAME);
assertThat(process.getPermissionRules().getLevel()).isEqualTo(PermissionLevel.HAS_ACCESS_PERMISSION);
assertThat(process.getPermissionRules().getPermissionBaseName()).isEqualTo(QuickSearchQBitConfig.DEFAULT_DEBUG_PERMISSION_BASE_NAME);
}
QProcessMetaData inspect = qInstance.getProcess(QuickSearchDiagnosticsProcessMetaDataHelper.inspectProcessName(config(), SOURCE));
QProcessMetaData reindex = qInstance.getProcess(QuickSearchDiagnosticsProcessMetaDataHelper.reindexRecordsProcessName(config(), SOURCE));
assertThat(inspect.getTableName()).isEqualTo(SOURCE);
assertThat(inspect.getPermissionRules().getPermissionBaseName()).isEqualTo(QuickSearchQBitConfig.DEFAULT_DEBUG_PERMISSION_BASE_NAME);
assertThat(inspect.getSourceQBitName()).isNotBlank();
assertThat(reindex.getTableName()).isEqualTo(SOURCE);
assertThat(reindex.getPermissionRules().getPermissionBaseName()).isEqualTo(QuickSearchQBitConfig.DEFAULT_ADMIN_PERMISSION_BASE_NAME);
assertThat(qInstance.getProcess(QuickSearchDiagnosticsProcessMetaDataHelper.inspectProcessName(config(), QuickSearchFailedEvent.TABLE_NAME)).getTableName())
.isEqualTo(QuickSearchFailedEvent.TABLE_NAME);
assertThat(qInstance.getProcess(QuickSearchDiagnosticsProcessMetaDataHelper.reindexRecordsProcessName(config(), QuickSearchFailedEvent.TABLE_NAME))).isNotNull();
assertThat(qInstance.getWidget(QuickSearchDiagnosticsWidgetMetaDataProducer.WIDGET_NAME)).isNotNull();
assertThat(qInstance.getWidget(QuickSearchDiagnosticsWidgetMetaDataProducer.WIDGET_NAME).getPermissionRules().getPermissionBaseName())
.isEqualTo(QuickSearchQBitConfig.DEFAULT_DEBUG_PERMISSION_BASE_NAME);
}
/*******************************************************************************
** The tools are actions, never nav entries: no diagnostic process is a
** child of the admin app; the history tables and the widget are.
*******************************************************************************/
@Test
void testProduce_toolsAreNotInTheAppNav() throws QException
{
QInstance qInstance = buildInstance();
new QuickSearchQBitProducer().withConfig(config()).produce(qInstance);
QAppMetaData app = qInstance.getApp(QuickSearchQBitProducer.APP_NAME);
List<String> children = app.getChildren().stream().map(c -> c.getName()).toList();
assertThat(children).contains(QuickSearchDiagnosticEvent.TABLE_NAME, QuickSearchValidationRun.TABLE_NAME);
assertThat(children).noneMatch(n -> n.startsWith("quickSearchPlayground") || n.startsWith("quickSearchInspect") || n.startsWith("quickSearchReindexRecords")
|| n.startsWith("quickSearchValidateIndex") || n.startsWith("quickSearchAnalyzeText"));
assertThat(app.getWidgets()).containsExactly(QuickSearchDiagnosticsWidgetMetaDataProducer.WIDGET_NAME);
}
@Test
void testProduce_instancePassesValidation() throws QException
{
QInstance qInstance = buildInstance();
new QuickSearchQBitProducer().withConfig(config()).produce(qInstance);
new QInstanceValidator().revalidate(qInstance);
}
@Test
void testProduce_diagnosticsOff_addsNothing() throws QException
{
QInstance qInstance = buildInstance();
new QuickSearchQBitProducer().withConfig(config().withEnableDiagnosticTools(false)).produce(qInstance);
assertThat(qInstance.getTable(QuickSearchDiagnosticEvent.TABLE_NAME)).isNull();
assertThat(qInstance.getTable(QuickSearchValidationRun.TABLE_NAME)).isNull();
assertThat(qInstance.getProcess(QuickSearchDiagnosticsProcessMetaDataHelper.PLAYGROUND_PROCESS_NAME)).isNull();
assertThat(qInstance.getProcess(QuickSearchDiagnosticsProcessMetaDataHelper.inspectProcessName(config(), SOURCE))).isNull();
assertThat(qInstance.getWidget(QuickSearchDiagnosticsWidgetMetaDataProducer.WIDGET_NAME)).isNull();
}
@Test
void testProduce_recordActionsOff_keepsFixedTools() throws QException
{
QInstance qInstance = buildInstance();
new QuickSearchQBitProducer().withConfig(config().withEnableRecordDiagnosticActions(false)).produce(qInstance);
assertThat(qInstance.getProcess(QuickSearchDiagnosticsProcessMetaDataHelper.PLAYGROUND_PROCESS_NAME)).isNotNull();
assertThat(qInstance.getProcess(QuickSearchDiagnosticsProcessMetaDataHelper.inspectProcessName(config(), SOURCE))).isNull();
assertThat(qInstance.getProcess(QuickSearchDiagnosticsProcessMetaDataHelper.reindexRecordsProcessName(config(), SOURCE))).isNull();
}
@Test
void testProduce_validationCron_schedulesTheValidation() throws QException
{
QInstance qInstance = buildInstance();
QSchedulerMetaData scheduler = new QuartzSchedulerMetaData().withName("simple");
qInstance.addScheduler(scheduler);
new QuickSearchQBitProducer().withConfig(config().withSchedulerName("simple").withValidationCronExpression("0 0 4 * * ?").withValidationCronTimeZoneId("UTC")).produce(qInstance);
QProcessMetaData validate = qInstance.getProcess(QuickSearchDiagnosticsProcessMetaDataHelper.VALIDATE_PROCESS_NAME);
assertThat(validate.getSchedule()).isNotNull();
assertThat(validate.getSchedule().getCronExpression()).isEqualTo("0 0 4 * * ?");
assertThat(validate.getSchedule().getCronTimeZoneId()).isEqualTo("UTC");
}
@Test
void testValidate_validationCronNeedsSchedulerAndTools()
{
QInstance qInstance = buildInstance();
assertThatThrownBy(() -> new QuickSearchQBitProducer().withConfig(config().withValidationCronExpression("0 0 4 * * ?")).produce(qInstance))
.hasMessageContaining("validationCronExpression requires schedulerName");
QInstance second = buildInstance();
second.addScheduler(new QuartzSchedulerMetaData().withName("simple"));
assertThatThrownBy(() -> new QuickSearchQBitProducer().withConfig(config().withSchedulerName("simple").withValidationCronExpression("0 0 4 * * ?").withValidationCronTimeZoneId("UTC")
.withEnableDiagnosticTools(false))
.produce(second))
.hasMessageContaining("validationCronExpression requires enableDiagnosticTools");
}
/*******************************************************************************
** The validation schedule follows the same rules as the reconcile one: a
** cron-capable scheduler, a valid Quartz expression and a time zone.
*******************************************************************************/
@Test
void testValidate_validationCronRules()
{
QInstance simple = buildInstance();
simple.addScheduler(new SimpleSchedulerMetaData().withName("simple"));
assertThatThrownBy(() -> new QuickSearchQBitProducer().withConfig(config().withSchedulerName("simple").withValidationCronExpression("0 0 4 * * ?").withValidationCronTimeZoneId("UTC"))
.produce(simple))
.hasMessageContaining("validationCronExpression requires a scheduler that supports cron schedules");
QInstance quartz = buildInstance();
quartz.addScheduler(new QuartzSchedulerMetaData().withName("quartz"));
assertThatThrownBy(() -> new QuickSearchQBitProducer().withConfig(config().withSchedulerName("quartz").withValidationCronExpression("0 0 4 * *")).produce(quartz))
.hasMessageContaining("validationCronExpression [0 0 4 * *] is not a valid Quartz cron expression")
.hasMessageContaining("validationCronExpression requires validationCronTimeZoneId");
QInstance zone = buildInstance();
zone.addScheduler(new QuartzSchedulerMetaData().withName("quartz"));
assertThatThrownBy(() -> new QuickSearchQBitProducer().withConfig(config().withSchedulerName("quartz").withValidationCronExpression("0 0 4 * * ?").withValidationCronTimeZoneId("Mars/Base"))
.produce(zone))
.hasMessageContaining("validationCronTimeZoneId [Mars/Base] is not a recognized time zone ID");
}
@Test
void testValidate_sampleSizeAndRateBounds()
{
assertThatThrownBy(() -> new QuickSearchQBitProducer().withConfig(config().withValidationSampleSize(0)).produce(buildInstance()))
.hasMessageContaining("validationSampleSize must be positive");
assertThatThrownBy(() -> new QuickSearchQBitProducer().withConfig(config().withValidationSampleSize(5000)).produce(buildInstance()))
.hasMessageContaining("validationSampleSize must be at most");
assertThatThrownBy(() -> new QuickSearchQBitProducer().withConfig(config().withDiagnosticRunsPerMinute(-1)).produce(buildInstance()))
.hasMessageContaining("diagnosticRunsPerMinute must be positive");
}
@Test
void testProduce_prefixAppliesToToolsAndTables() throws QException
{
QInstance qInstance = buildInstance();
QuickSearchQBitConfig config = config().withTableNamePrefix("myApp_");
new QuickSearchQBitProducer().withConfig(config).produce(qInstance);
assertThat(qInstance.getTable("myApp_" + QuickSearchDiagnosticEvent.TABLE_NAME)).isNotNull();
assertThat(qInstance.getTable("myApp_" + QuickSearchValidationRun.TABLE_NAME)).isNotNull();
QProcessMetaData playground = qInstance.getProcess("myApp_" + QuickSearchDiagnosticsProcessMetaDataHelper.PLAYGROUND_PROCESS_NAME);
assertThat(playground.getTableName()).isEqualTo("myApp_" + QuickSearchIndex.TABLE_NAME);
assertThat(qInstance.getProcess("myApp_quickSearchInspect_" + SOURCE)).isNotNull();
}
}
src/test/java/com/kingsrook/qbits/quicksearch/diagnostics/DiagnosticsOfflineTest.java
+490
View File
@@ -0,0 +1,490 @@
/*
* Copyright 2026 Kingsrook, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.quicksearch.diagnostics;
import java.time.Instant;
import java.util.List;
import java.util.Set;
import java.util.concurrent.atomic.AtomicLong;
import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction;
import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.actions.tables.RecordSearchAction;
import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessOutput;
import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.search.RecordSearchInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType;
import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.permissions.PermissionLevel;
import com.kingsrook.qqq.backend.core.model.metadata.permissions.QPermissionRules;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.core.model.session.QSession;
import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule;
import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryRecordStore;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitConfig;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitContext;
import com.kingsrook.qbits.quicksearch.QuickSearchQBitProducer;
import com.kingsrook.qbits.quicksearch.QuickSearchRuntime;
import com.kingsrook.qbits.quicksearch.QuickSearchStartupMode;
import com.kingsrook.qbits.quicksearch.SearchableFieldConfig;
import com.kingsrook.qbits.quicksearch.actions.QuickSearchRecordSearchProvider;
import com.kingsrook.qbits.quicksearch.metadata.QuickSearchDiagnosticsProcessMetaDataHelper;
import com.kingsrook.qbits.quicksearch.model.QuickSearchDiagnosticEvent;
import com.kingsrook.qbits.quicksearch.model.QuickSearchIndex;
import com.kingsrook.qbits.quicksearch.model.QuickSearchValidationRun;
import com.kingsrook.qbits.quicksearch.processes.diagnostics.AbstractDiagnosticToolStep;
import com.kingsrook.qbits.quicksearch.processes.diagnostics.SearchPlaygroundStep;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
/*******************************************************************************
** The diagnostic tools without a reachable OpenSearch (the client points at a
** closed port), plus their pure parts: rate limiting, HTML escaping, target
** parsing, redaction, the path diagnosis branches, event recording and its
** cap, provider failure events and counters, the widget, the playground's
** honest failure output and its form loop through RunProcessAction.
*******************************************************************************/
class DiagnosticsOfflineTest
{
private static final String BACKEND = "memory";
private static final String PRODUCT = "product";
private static final String NOTE = "note";
private static final String NO_SEARCH = "plain";
private static final String LOCKED = "secret";
private QuickSearchQBitConfig config;
private QuickSearchRuntime runtime;
/*******************************************************************************
** An instance with an indexed product table, an unindexed note table with
** core searchFields, a table without searchFields, and a permissioned
** table; Quick Search produced in DEGRADED mode against a closed port.
*******************************************************************************/
@BeforeEach
void setUp() throws QException
{
MemoryRecordStore.getInstance().reset();
QInstance qInstance = new QInstance();
qInstance.addBackend(new QBackendMetaData().withName(BACKEND).withBackendType(MemoryBackendModule.class));
qInstance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("anonymous").withType(QAuthenticationType.FULLY_ANONYMOUS));
qInstance.addTable(table(PRODUCT));
qInstance.addTable(table(NOTE).withSearchFields("name"));
qInstance.addTable(table(NO_SEARCH));
qInstance.addTable(table(LOCKED).withSearchFields("name").withPermissionRules(new QPermissionRules().withLevel(PermissionLevel.READ_WRITE_PERMISSIONS)));
QContext.init(qInstance, new QSession());
config = new QuickSearchQBitConfig()
.withStartupMode(QuickSearchStartupMode.DEGRADED)
.withBackendName(BACKEND)
.withOpensearchHost("127.0.0.1")
.withOpensearchPort(1)
.withConnectTimeoutMillis(500)
.withResponseTimeoutMillis(1000)
.withRecordSearchTimeoutMillis(1000)
.withOpensearchIndexName("diag-offline")
.withEnableRealTimeIndexing(false)
.withDiagnosticRunsPerMinute(1000)
.withSearchableTable(PRODUCT, List.of(new SearchableFieldConfig("name")));
new QuickSearchQBitProducer().withConfig(config).produce(qInstance);
runtime = config.getRuntime();
new InsertAction().execute(new InsertInput(PRODUCT).withRecords(List.of(
new QRecord().withValue("id", 1).withValue("name", "Blue Widget").withValue("modifyDate", Instant.now()),
new QRecord().withValue("id", 2).withValue("name", "Red Gadget").withValue("modifyDate", Instant.now()))));
}
/*******************************************************************************
*******************************************************************************/
@AfterEach
void tearDown()
{
if(runtime != null)
{
runtime.close();
}
QContext.clear();
QuickSearchQBitContext.clear();
MemoryRecordStore.getInstance().reset();
}
/*******************************************************************************
*******************************************************************************/
private static QTableMetaData table(String name)
{
return (new QTableMetaData()
.withName(name)
.withLabel(name)
.withBackendName(BACKEND)
.withPrimaryKeyField("id")
.withField(new QFieldMetaData("id", QFieldType.INTEGER))
.withField(new QFieldMetaData("name", QFieldType.STRING))
.withField(new QFieldMetaData("modifyDate", QFieldType.DATE_TIME)));
}
/*******************************************************************************
*******************************************************************************/
private static List<QRecord> events() throws QException
{
QueryInput queryInput = new QueryInput(QuickSearchDiagnosticEvent.TABLE_NAME);
return (new QueryAction().execute(queryInput).getRecords());
}
@Test
void testRateLimiter_slidingMinute()
{
AtomicLong now = new AtomicLong(1_000_000L);
DiagnosticsRateLimiter limiter = new DiagnosticsRateLimiter(now::get);
assertThat(limiter.tryAcquire("a", 2)).isTrue();
assertThat(limiter.tryAcquire("a", 2)).isTrue();
assertThat(limiter.tryAcquire("a", 2)).isFalse();
assertThat(limiter.tryAcquire("b", 2)).isTrue();
now.addAndGet(60_000L);
assertThat(limiter.tryAcquire("a", 2)).isTrue();
assertThat(limiter.tryAcquire("a", null)).isTrue();
assertThat(limiter.tryAcquire("a", 0)).isTrue();
}
@Test
void testHtml_escapesAndKeepsHighlights()
{
assertThat(DiagnosticsHtml.escape("<script>alert('x')</script> & \"q\"")).isEqualTo("&lt;script&gt;alert(&#39;x&#39;)&lt;/script&gt; &amp; &quot;q&quot;");
assertThat(DiagnosticsHtml.highlight("a <em>blue</em> <b>x</b>")).isEqualTo("a <mark>blue</mark> &lt;b&gt;x&lt;/b&gt;");
assertThat(DiagnosticsHtml.prettyJson("{\"a\":1}")).contains("\"a\" : 1");
assertThat(DiagnosticsHtml.prettyJson("not json")).isEqualTo("not json");
assertThat(DiagnosticsHtml.prettyJson("\"" + "x".repeat(DiagnosticsHtml.MAX_JSON_CHARS + 10) + "\"")).contains("truncated at");
String html = new DiagnosticsHtml().open().facts(java.util.Collections.singletonList(new String[] { "<k>", null })).pre("<v>").close().toString();
assertThat(html).contains("&lt;k&gt;").contains("<em>none</em>").contains("&lt;v&gt;").contains("overflow-wrap:anywhere").doesNotContain("<k>");
}
@Test
void testTargetParseAndTableLists()
{
assertThat(AbstractDiagnosticToolStep.Target.parse("blogPost:42")).isEqualTo(new AbstractDiagnosticToolStep.Target("blogPost", "42"));
assertThat(AbstractDiagnosticToolStep.Target.parse("t:a:b")).isEqualTo(new AbstractDiagnosticToolStep.Target("t", "a:b"));
assertThat(AbstractDiagnosticToolStep.Target.parse(":1")).isNull();
assertThat(AbstractDiagnosticToolStep.Target.parse("t:")).isNull();
assertThat(AbstractDiagnosticToolStep.Target.parse(null)).isNull();
assertThat(SearchPlaygroundStep.parseTables(" a, b c,a ")).containsExactly("a", "b", "c");
assertThat(SearchPlaygroundStep.parseTables(null)).isEmpty();
}
@Test
void testRedactResponse_hidesUnreadableHits()
{
String json = "{\"hits\":{\"hits\":[{\"_source\":{\"recordId\":\"1\",\"recordLabel\":\"ok\"},\"highlight\":{\"x\":[\"y\"]}},"
+ "{\"_source\":{\"recordId\":\"2\",\"recordLabel\":\"private\"},\"highlight\":{\"x\":[\"secret\"]}}]}}";
String redacted = SearchPlayground.redactResponse(json, Set.of("1"));
assertThat(redacted).contains("\"recordLabel\":\"ok\"").doesNotContain("private").doesNotContain("secret").doesNotContain("\"2\"").contains("redacted: 1 hit(s)");
assertThat(SearchPlayground.redactResponse("nope", Set.of())).contains("could not be parsed");
}
/*******************************************************************************
** Each branch of the path diagnosis.
*******************************************************************************/
@Test
void testPathDiagnosis_branches() throws QException
{
QInstance qInstance = QContext.getQInstance();
List<SearchPathDiagnosis.TablePath> paths = SearchPathDiagnosis.diagnose(qInstance, runtime, List.of(PRODUCT, NOTE, NO_SEARCH, LOCKED, "missing"), new QueryInput());
assertThat(paths.get(0).path()).isEqualTo(SearchPathDiagnosis.PATH_OPENSEARCH);
assertThat(paths.get(1).path()).isEqualTo(SearchPathDiagnosis.PATH_CORE);
assertThat(paths.get(1).reason()).contains("does not index");
assertThat(paths.get(2).path()).isEqualTo(SearchPathDiagnosis.PATH_NONE);
assertThat(paths.get(2).reason()).contains("no core searchFields");
assertThat(paths.get(3).path()).isEqualTo(SearchPathDiagnosis.PATH_NONE);
assertThat(paths.get(3).reason()).contains("read permission");
assertThat(paths.get(4).reason()).contains("no table");
runtime.markRecordSearchFailed("connection refused");
assertThat(SearchPathDiagnosis.diagnose(qInstance, runtime, List.of(PRODUCT), new QueryInput()).get(0).reason()).contains("backing off").contains("connection refused");
runtime.clearRecordSearchBackoff();
new InsertAction().execute(new InsertInput(QuickSearchIndex.TABLE_NAME).withRecord(new QRecord().withValue("tableName", PRODUCT).withValue("enabled", false)));
runtime.invalidateEnabledCache();
assertThat(SearchPathDiagnosis.diagnose(qInstance, runtime, List.of(PRODUCT), new QueryInput()).get(0).reason()).contains("disabled");
runtime.invalidateEnabledCache();
new UpdateAction().execute(new UpdateInput(QuickSearchIndex.TABLE_NAME).withRecord(new QRecord().withValue("id", 1).withValue("enabled", true)));
runtime.invalidateEnabledCache();
config.setServeCoreRecordSearch(false);
assertThat(SearchPathDiagnosis.diagnose(qInstance, runtime, List.of(PRODUCT), new QueryInput()).get(0).reason()).contains("serveCoreRecordSearch is off");
config.setServeCoreRecordSearch(true);
qInstance.withRecordSearchProvider(new QCodeReference(DiagnosticsOfflineTest.class));
assertThat(SearchPathDiagnosis.diagnose(qInstance, runtime, List.of(PRODUCT), new QueryInput()).get(0).reason()).contains("Another record search provider");
}
@Test
void testRecorder_writesEventsAsSystemAndCapsVolume() throws QException
{
DiagnosticEventRecorder recorder = runtime.getDiagnosticEventRecorder();
recorder.record(new QuickSearchDiagnosticEvent().withEventType(QuickSearchDiagnosticEvent.TYPE_TOOL_RUN).withSource("TEST").withSearchTerm("x".repeat(500)));
recorder.flush(5000);
List<QRecord> rows = events();
assertThat(rows).hasSize(1);
assertThat(rows.get(0).getValueString("hostName")).isNotBlank();
assertThat(rows.get(0).getValueString("searchTerm")).hasSize(100);
assertThat(rows.get(0).getValueInstant("createDate")).isNotNull();
for(int i = 0; i < DiagnosticEventRecorder.MAX_EVENTS_PER_MINUTE + 5; i++)
{
recorder.record(new QuickSearchDiagnosticEvent().withEventType(QuickSearchDiagnosticEvent.TYPE_TOOL_RUN).withSource("FLOOD"));
}
recorder.flush(5000);
assertThat(events()).hasSize(DiagnosticEventRecorder.MAX_EVENTS_PER_MINUTE);
assertThat(recorder.getDroppedCount()).isEqualTo(6);
}
@Test
void testRecorder_noTableIsANoOp()
{
QContext.getQInstance().getTables().remove(QuickSearchDiagnosticEvent.TABLE_NAME);
DiagnosticEventRecorder recorder = runtime.getDiagnosticEventRecorder();
recorder.record(new QuickSearchDiagnosticEvent().withEventType(QuickSearchDiagnosticEvent.TYPE_TOOL_RUN));
recorder.flush(5000);
assertThat(recorder.getFailedCount()).isZero();
}
@Test
void testRateLimit_refusesAndRecords() throws QException
{
config.setDiagnosticRunsPerMinute(1);
DiagnosticsSupport.checkRateLimit(runtime, DiagnosticsSupport.TOOL_PLAYGROUND);
assertThatThrownBy(() -> DiagnosticsSupport.checkRateLimit(runtime, DiagnosticsSupport.TOOL_PLAYGROUND))
.isInstanceOf(QUserFacingException.class).hasMessageContaining("Too many");
runtime.getDiagnosticEventRecorder().flush(5000);
assertThat(events()).anyMatch(r -> QuickSearchDiagnosticEvent.TYPE_RATE_LIMITED.equals(r.getValueString("eventType")));
}
/*******************************************************************************
** A global search with OpenSearch down: core falls back (results still
** come back), the provider counts and records the failure without the
** term, and claims during the backoff are counted.
*******************************************************************************/
@Test
void testProviderFailure_recordedAndCounted() throws QException
{
List<?> results = new RecordSearchAction().execute(new RecordSearchInput().withSearchTerm("widget").withTableNames(List.of(PRODUCT))).getResults();
assertThat(results).hasSize(1);
assertThat(runtime.getRecordSearchFailureCount()).isEqualTo(1);
assertThat(runtime.getLastRecordSearchFailureMessage()).isNotBlank();
assertThat(runtime.getRecordSearchBackoffRemainingMillis()).isPositive();
new RecordSearchAction().execute(new RecordSearchInput().withSearchTerm("widget").withTableNames(List.of(PRODUCT)));
assertThat(runtime.getBackoffDeclinedClaimCount()).isEqualTo(1);
runtime.getDiagnosticEventRecorder().flush(5000);
QRecord event = events().stream().filter(r -> QuickSearchDiagnosticEvent.TYPE_SEARCH_FAILED.equals(r.getValueString("eventType"))).findFirst().orElseThrow();
assertThat(event.getValueString("source")).isEqualTo(QuickSearchDiagnosticEvent.SOURCE_CORE_RECORD_SEARCH);
assertThat(event.getValueString("searchTerm")).isNull();
assertThat(event.getValueString("detail")).contains("term length 6");
assertThat(event.getValueString("tableNames")).isEqualTo(PRODUCT);
assertThat(event.getValueString("errorClass")).isNotBlank();
assertThat(event.getValueString("errorMessage")).doesNotContainIgnoringCase("widget");
}
/*******************************************************************************
** QuickSearchAction's failure message names the term; the event never
** keeps it.
*******************************************************************************/
@Test
void testQuickSearchActionFailure_termNeverStored() throws QException
{
assertThatThrownBy(() -> new com.kingsrook.qbits.quicksearch.actions.QuickSearchAction().execute(
new com.kingsrook.qbits.quicksearch.actions.QuickSearchInput().withSearchTerm("Jane Doe-Smith")))
.hasMessageContaining("Jane Doe-Smith");
runtime.getDiagnosticEventRecorder().flush(5000);
QRecord event = events().stream().filter(r -> QuickSearchDiagnosticEvent.SOURCE_QUICK_SEARCH_ACTION.equals(r.getValueString("source"))).findFirst().orElseThrow();
assertThat(event.getValueString("searchTerm")).isNull();
assertThat(event.getValueString("errorMessage")).contains("[search term]").doesNotContainIgnoringCase("jane").doesNotContainIgnoringCase("smith");
assertThat(event.getValueString("detail")).contains("term length 14");
}
@Test
void testRedactTerm()
{
assertThat(DiagnosticsSupport.redactTerm("Search failed for term [Blue Widget]: parse error near 'widget'", "blue widget"))
.isEqualTo("Search failed for term [[search term]]: parse error near '[search term]'");
assertThat(DiagnosticsSupport.redactTerm("no term here", "a b")).isEqualTo("no term here");
assertThat(DiagnosticsSupport.redactTerm(null, "x")).isNull();
assertThat(DiagnosticsSupport.redactTerm("x (y)", "(y)")).isEqualTo("x [search term]");
}
/*******************************************************************************
** The playground with OpenSearch down still reports honestly: the core
** fallback's results, the provider failure, and failed probes.
*******************************************************************************/
@Test
void testPlayground_openSearchDown_reportsFailureAndFallback()
{
SearchPlayground.Report report = new SearchPlayground().run(runtime, new SearchPlayground.Input("widget", List.of(PRODUCT, NOTE), null, "product:1"), new QueryInput());
assertThat(report.providerError()).isNotBlank();
assertThat(report.coreError()).isNull();
assertThat(report.coreResults().get(PRODUCT)).hasSize(1);
assertThat(report.probes()).singleElement().satisfies(p -> assertThat(p.error()).isNotBlank());
assertThat(report.termTokensError()).isNotBlank();
assertThat(report.explainError()).isNotBlank();
String html = SearchPlayground.render(report);
assertThat(html).contains("FAIL").contains("falls back").contains("(#1)");
}
/*******************************************************************************
** The playground process through RunProcessAction: it stops at the form
** with intro HTML, and after a run the next step is the form again (with
** results), so the user can search again.
*******************************************************************************/
@Test
void testPlaygroundProcess_loopsBackToTheForm() throws QException
{
String processName = QuickSearchDiagnosticsProcessMetaDataHelper.PLAYGROUND_PROCESS_NAME;
RunProcessInput first = new RunProcessInput();
first.setProcessName(processName);
first.setFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.BREAK);
RunProcessOutput firstOutput = new RunProcessAction().execute(first);
assertThat(firstOutput.getProcessState().getNextStepName()).hasValue(AbstractDiagnosticToolStep.STEP_FORM);
assertThat(firstOutput.getValues().get(AbstractDiagnosticToolStep.STEP_FORM + ".html").toString()).contains("Indexed tables").contains(PRODUCT);
for(int run = 0; run < 2; run++)
{
RunProcessInput again = new RunProcessInput();
again.setProcessName(processName);
again.setProcessUUID(firstOutput.getProcessUUID());
again.setStartAfterStep(AbstractDiagnosticToolStep.STEP_FORM);
again.setFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.BREAK);
again.addValue(SearchPlaygroundStep.FIELD_TERM, "widget");
again.addValue(SearchPlaygroundStep.FIELD_TABLES, PRODUCT);
RunProcessOutput output = new RunProcessAction().execute(again);
assertThat(output.getProcessState().getNextStepName()).hasValue(AbstractDiagnosticToolStep.STEP_FORM);
assertThat(output.getValues().get(AbstractDiagnosticToolStep.STEP_FORM + ".html").toString()).contains("Search playground").contains("widget");
}
runtime.getDiagnosticEventRecorder().flush(5000);
assertThat(events()).filteredOn(r -> DiagnosticsSupport.TOOL_PLAYGROUND.equals(r.getValueString("source"))).hasSize(2);
}
/*******************************************************************************
** Validation with OpenSearch down: a FAIL report that says why, saved as
** a validation run.
*******************************************************************************/
@Test
void testValidate_openSearchDown_savesFailReport() throws QException
{
IndexValidator validator = new IndexValidator();
IndexValidator.Report report = validator.validate(runtime, List.of(), 10);
assertThat(report.status()).isEqualTo(QuickSearchValidationRun.STATUS_FAIL);
assertThat(report.findings()).anyMatch(f -> f.check().equals("Reachable") && f.message().contains("did not answer"));
Integer runId = validator.persist(runtime, report, QuickSearchValidationRun.TRIGGER_MANUAL, "tester");
assertThat(runId).isNotNull();
QRecord row = new QueryAction().execute(new QueryInput(QuickSearchValidationRun.TABLE_NAME)).getRecords().get(0);
assertThat(row.getValueString("reportHtml")).contains("did not answer");
assertThat(row.getValueString("userName")).isEqualTo("tester");
assertThat(IndexValidator.toJson(report)).contains("\"status\":\"FAIL\"");
assertThat(row.getValueString("reportJson")).contains("\"status\":\"FAIL\"");
}
/*******************************************************************************
** The widget says plainly what it knows: the backoff, the recorded
** failure, and that no validation ran yet; then the latest validation.
*******************************************************************************/
@Test
void testWidget_honestStates() throws QException
{
String empty = QuickSearchDiagnosticsWidgetRenderer.renderHtml(runtime);
assertThat(empty).contains("Served by OpenSearch").contains("None recorded").contains("None yet");
new RecordSearchAction().execute(new RecordSearchInput().withSearchTerm("widget").withTableNames(List.of(PRODUCT)));
runtime.getDiagnosticEventRecorder().flush(5000);
new InsertAction().execute(new InsertInput(QuickSearchValidationRun.TABLE_NAME).withRecordEntity(new QuickSearchValidationRun()
.withStatus(QuickSearchValidationRun.STATUS_WARN).withTriggerType(QuickSearchValidationRun.TRIGGER_MANUAL).withSummary("WARN: 1 table(s)").withStartTime(Instant.now())));
String html = QuickSearchDiagnosticsWidgetRenderer.renderHtml(runtime);
assertThat(html).contains("Backing off").contains(QuickSearchDiagnosticEvent.SOURCE_CORE_RECORD_SEARCH).contains("WARN: 1 table(s)")
.contains("/app/" + QuickSearchValidationRun.TABLE_NAME + "/1");
assertThat(new QuickSearchRecordSearchProvider().claimsTable(QContext.getQInstance().getTable(PRODUCT))).isFalse();
}
}