feat(elasticsearch): add visual search profiler

This commit is contained in:
Abeautifulsnow authored and GitHub committed 2026-09-04 20:38:26 +08:00
1 parent 5d1061d490
commit 3ee0640fc2
22 files changed
+1093 -11

No files matched your search

@@ -0,0 +1,268 @@
import { isLosslessJsonNumber, parseJsonPreservingLargeNumbers } from "@/lib/common/safeJsonFormat";
import { heatLevel as planHeatLevel } from "@/lib/diagram/planCanvas";
import { isElasticsearchCompatibleDatabaseType, type DatabaseType, type QueryResult } from "@/types/database";
/**
* Visual Search Profiler for Elasticsearch `_search?profile=true` responses.
*
* Parses the `profile.shards[].searches[].query[]` timing tree so the frontend
* can render it as a collapsible tree with cost-share progress bars. The
* response body is preserved end-to-end by the REST-DSL query path
* (`QueryResult.elasticsearch_raw_body` or the two-column status/response
* result), so this is a pure-frontend feature — no Rust changes.
*
* `time_in_nanos` is cumulative over a node's subtree; `breakdown` is the
* node's own per-phase time. `selfTimeInNanos = timeInNanos − Σ children`,
* matching the self-cost accounting used by the SQL explain `planCanvas`.
*/
export type ElasticsearchProfileHeatLevel = "none" | "cool" | "warm" | "hot";
export interface ElasticsearchProfileNode {
/** Lucene query type, e.g. "BooleanQuery" / "TermQuery". */
type: string;
/** Human-readable query description when Elasticsearch provides one. */
description?: string;
/** Cumulative time including children, in nanoseconds. */
timeInNanos: number;
/** The node's own per-phase timings (next_doc / build_scorer / score / …). */
breakdown?: Record<string, number>;
children: ElasticsearchProfileNode[];
/** timeInNanos minus the children's cumulative time, clamped to ≥ 0. */
selfTimeInNanos: number;
/** selfTime / total self time of the shard's tree (planCanvas semantics). */
costShare: number;
heatLevel: ElasticsearchProfileHeatLevel;
/** Marked along the single highest-cost child chain down to a leaf. */
isCriticalPath: boolean;
}
export interface ElasticsearchProfileShard {
id: string;
tree: ElasticsearchProfileNode;
totalTimeInNanos: number;
/** Number of _search requests profiled on this shard (>1 when merged under a wrapper node). */
searchCount?: number;
}
export interface ElasticsearchProfileData {
/** Shards sorted by total time, highest first. */
shards: ElasticsearchProfileShard[];
/** The parsed `profile` section, kept for a potential raw view. */
raw: unknown;
}
interface RawQueryNode {
type?: unknown;
description?: unknown;
time_in_nanos?: unknown;
breakdown?: unknown;
children?: unknown;
}
function readRecord(value: unknown): Record<string, unknown> | null {
return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
}
/** Reads a numeric literal, including large numbers preserved by safeJsonFormat. */
function readProfileNumber(value: unknown): number {
if (isLosslessJsonNumber(value)) {
const parsed = Number(value.raw);
return Number.isFinite(parsed) ? parsed : 0;
}
if (typeof value === "number" && Number.isFinite(value)) return value;
return 0;
}
function mapQueryNode(raw: RawQueryNode): ElasticsearchProfileNode {
const childrenRaw = Array.isArray(raw.children) ? raw.children : [];
const children: ElasticsearchProfileNode[] = [];
for (const child of childrenRaw) {
const record = readRecord(child);
if (record) children.push(mapQueryNode(record as RawQueryNode));
}
const timeInNanos = Math.max(0, readProfileNumber(raw.time_in_nanos));
const childrenTotal = children.reduce((sum, child) => sum + child.timeInNanos, 0);
const selfTimeInNanos = Math.max(0, timeInNanos - childrenTotal);
let breakdown: Record<string, number> | undefined;
const breakdownRaw = readRecord(raw.breakdown);
if (breakdownRaw) {
const entries = Object.entries(breakdownRaw)
.map(([name, value]) => [name, readProfileNumber(value)] as const)
.filter(([, value]) => value > 0);
if (entries.length > 0) breakdown = Object.fromEntries(entries);
}
return {
type: typeof raw.type === "string" && raw.type ? raw.type : "Query",
description: typeof raw.description === "string" && raw.description ? raw.description : undefined,
timeInNanos,
breakdown,
children,
selfTimeInNanos,
costShare: 0,
heatLevel: "none",
isCriticalPath: false,
};
}
function applyCostShares(node: ElasticsearchProfileNode, denominator: number): void {
node.costShare = node.selfTimeInNanos / denominator;
// Zero-cost nodes render a plain label, not a green "cool" bar.
node.heatLevel = node.selfTimeInNanos > 0 ? planHeatLevel(node.costShare) : "none";
for (const child of node.children) applyCostShares(child, denominator);
}
function markCriticalPath(node: ElasticsearchProfileNode): void {
node.isCriticalPath = true;
if (node.children.length === 0) return;
let best = node.children[0];
for (const child of node.children) {
// Select by cumulative time_in_nanos (inclusive of descendants), not self
// time: a long branch whose cost is mostly in descendants must win over a
// child with more local work but a shorter subtree. Ties keep the first
// child (stable, deterministic).
if (child.timeInNanos > best.timeInNanos) best = child;
}
markCriticalPath(best);
}
/**
* Populates costShare/heatLevel/isCriticalPath for the tree. The total self
* time telescopes to the tree root's cumulative time, so `root.timeInNanos`
* is the same denominator planCanvas uses for SQL explain nodes.
*/
function finalizeTree(node: ElasticsearchProfileNode): void {
if (node.timeInNanos > 0) applyCostShares(node, node.timeInNanos);
markCriticalPath(node);
}
interface BuiltShard {
tree: ElasticsearchProfileNode;
total: number;
searchCount: number;
}
/** Builds a single query tree for one shard from its `searches[]` array. */
function buildShard(searches: unknown): BuiltShard | null {
const searchList = Array.isArray(searches) ? searches : [];
const queryRoots: ElasticsearchProfileNode[] = [];
for (const search of searchList) {
const record = readRecord(search);
if (!record) continue;
const queryArray = Array.isArray(record.query) ? record.query : [];
for (const query of queryArray) {
const queryRecord = readRecord(query);
if (queryRecord) queryRoots.push(mapQueryNode(queryRecord as RawQueryNode));
}
}
if (queryRoots.length === 0) return null;
const total = queryRoots.reduce((sum, root) => sum + root.timeInNanos, 0);
// A single search keeps its real query root as the tree; multiple searches
// are merged under a synthetic "search" container so cost shares stay on one
// comparable scale.
let tree: ElasticsearchProfileNode;
if (queryRoots.length === 1) {
tree = queryRoots[0];
} else {
tree = {
type: "search",
timeInNanos: total,
children: queryRoots,
selfTimeInNanos: 0,
costShare: 0,
heatLevel: "none",
isCriticalPath: false,
};
}
finalizeTree(tree);
return { tree, total, searchCount: queryRoots.length };
}
/**
* Parses an Elasticsearch `_search` response body into the profiler tree.
* Returns `null` for malformed JSON, a missing/invalid `profile` section,
* absent/empty `shards`, or searches with no query nodes — never throws.
*/
export function parseElasticsearchProfile(body: string): ElasticsearchProfileData | null {
let parsed: unknown;
try {
parsed = parseJsonPreservingLargeNumbers(body);
} catch {
return null;
}
const root = readRecord(parsed);
if (!root) return null;
const profile = readRecord(root.profile);
if (!profile) return null;
const shardsRaw = profile.shards;
if (!Array.isArray(shardsRaw) || shardsRaw.length === 0) return null;
const shards: ElasticsearchProfileShard[] = [];
for (const shardRaw of shardsRaw) {
const record = readRecord(shardRaw);
if (!record) continue;
const id = typeof record.id === "string" && record.id ? record.id : String(shards.length + 1);
const built = buildShard(record.searches);
if (!built) continue;
shards.push({ id, tree: built.tree, totalTimeInNanos: built.total, searchCount: built.searchCount });
}
if (shards.length === 0) return null;
shards.sort((a, b) => b.totalTimeInNanos - a.totalTimeInNanos);
return { shards, raw: profile };
}
/**
* Extracts the ES response body from a query result, either the preserved raw
* REST body (`elasticsearch_raw_body`) or the two-column status/response
* single-row shape used for large/error responses. Non-ES databases return null.
*/
export function elasticsearchProfileBodyForResult(databaseType: DatabaseType | undefined, result: QueryResult | undefined): string | null {
if (!isElasticsearchCompatibleDatabaseType(databaseType) || !result) return null;
if (typeof result.elasticsearch_raw_body === "string" && result.elasticsearch_raw_body.length > 0) return result.elasticsearch_raw_body;
if (result.columns.length === 2 && result.columns[0] === "status" && result.columns[1] === "response" && result.rows.length === 1) {
const body = result.rows[0]?.[1];
if (typeof body === "string" && body.length > 0) return body;
}
return null;
}
/** Counts every node in the tree, including the root. */
export function countProfileNodes(node: ElasticsearchProfileNode): number {
let count = 1;
for (const child of node.children) count += countProfileNodes(child);
return count;
}
/** Maximum depth below the given node (leaf = 0). */
export function maxProfileDepth(node: ElasticsearchProfileNode): number {
if (node.children.length === 0) return 0;
let max = 0;
for (const child of node.children) max = Math.max(max, maxProfileDepth(child));
return 1 + max;
}
function trimZero(value: string): string {
return value.replace(/(\.\d*?[1-9])0+$/, "$1").replace(/\.0+$/, "");
}
/** Formats nanoseconds as ns / µs / ms / s with sensible rounding. */
export function formatProfileNanos(nanos: number): string {
const value = Math.max(0, nanos);
if (value >= 1e9) return `${trimZero((value / 1e9).toFixed(2))}s`;
if (value >= 1e6) {
const ms = value / 1e6;
return `${trimZero(ms.toFixed(ms >= 100 ? 0 : 1))}ms`;
}
if (value >= 1e3) {
const us = value / 1e3;
return `${trimZero(us.toFixed(us >= 100 ? 0 : 1))}µs`;
}
return `${value}ns`;
}