@oneuptime/common 12.0.15 → 12.0.16

package/Server/Utils/Telemetry/LlmCostBudgetEvaluator.ts

@@ -0,0 +1,379 @@
+import LlmCostBudget from "../../../Models/DatabaseModels/LlmCostBudget";
+import MetricType from "../../../Models/DatabaseModels/MetricType";
+import Span from "../../../Models/AnalyticsModels/Span";
+import { MetricPointType } from "../../../Models/AnalyticsModels/Metric";
+import AggregatedModel from "../../../Types/BaseDatabase/AggregatedModel";
+import AggregatedResult from "../../../Types/BaseDatabase/AggregatedResult";
+import AggregationInterval from "../../../Types/BaseDatabase/AggregationInterval";
+import AggregationType from "../../../Types/BaseDatabase/AggregationType";
+import InBetween from "../../../Types/BaseDatabase/InBetween";
+import Query from "../../../Types/BaseDatabase/Query";
+import LIMIT_MAX, { LIMIT_PER_PROJECT } from "../../../Types/Database/LimitMax";
+import OneUptimeDate from "../../../Types/Date";
+import { JSONObject } from "../../../Types/JSON";
+import ObjectID from "../../../Types/ObjectID";
+import ServiceType from "../../../Types/Telemetry/ServiceType";
+import AggregateBy from "../../Types/AnalyticsDatabase/AggregateBy";
+import LlmCostBudgetService from "../../Services/LlmCostBudgetService";
+import MetricService from "../../Services/MetricService";
+import SpanService from "../../Services/SpanService";
+import logger, { LogAttributes } from "../Logger";
+import CaptureSpan from "../Telemetry/CaptureSpan";
+import TelemetryUtil from "./Telemetry";
+
+/*
+ * Evaluates LLM cost budgets against the day's LLM span spend.
+ *
+ * The worker job (App/FeatureSet/Workers/Jobs/Llm/EvaluateLlmCostBudgets.ts)
+ * calls evaluateAllBudgets() on a 15-minute tick. For each enabled budget it
+ * sums the UTC day's llmCost from ClickHouse (scoped by the budget's optional
+ * service / provider / model filters), stamps the spend back onto the budget
+ * row for the dashboard, and publishes two gauge metrics:
+ *
+ *   oneuptime.llm.budget.spend.usd      — the day's spend so far, in USD
+ *   oneuptime.llm.budget.percent.used   — spend as a percent of the budget
+ *
+ * Budgets do NOT alert directly. Alerting is a Metrics monitor on these
+ * series — filter by the oneuptime.llm.budget.id attribute (stable across
+ * renames; the name attribute is for charts and changes when the budget is
+ * renamed) — which brings thresholds, formulas, anomaly baselines, incidents
+ * and on-call routing without a parallel alerting pipeline here.
+ *
+ * The series gets ONE point per budget per 15-minute sweep. A monitor on it
+ * must use a rolling window of at least 15 minutes (30 recommended): the
+ * 1-minute default would see an empty series between sweeps and flap.
+ */
+
+export const LLM_BUDGET_SPEND_METRIC_NAME: string =
+  "oneuptime.llm.budget.spend.usd";
+export const LLM_BUDGET_PERCENT_METRIC_NAME: string =
+  "oneuptime.llm.budget.percent.used";
+
+// Attribute keys carried by both budget metrics, for monitor/chart filtering.
+export const LLM_BUDGET_ID_ATTRIBUTE: string = "oneuptime.llm.budget.id";
+export const LLM_BUDGET_NAME_ATTRIBUTE: string = "oneuptime.llm.budget.name";
+export const LLM_BUDGET_PROVIDER_ATTRIBUTE: string =
+  "oneuptime.llm.budget.provider";
+export const LLM_BUDGET_MODEL_ATTRIBUTE: string = "oneuptime.llm.budget.model";
+export const LLM_BUDGET_SERVICE_ID_ATTRIBUTE: string =
+  "oneuptime.llm.budget.service.id";
+
+/*
+ * Matches the derived-metric retention the trace/metric recording rules use.
+ * The series exists for monitors and short-range charts; long-range spend
+ * history belongs to the spans themselves.
+ */
+const BUDGET_METRIC_RETENTION_IN_DAYS: number = 15;
+
+export default class LlmCostBudgetEvaluator {
+  /**
+   * Percent of the daily budget consumed. 0 when the budget is missing or
+   * invalid — never NaN/Infinity, since these values feed monitors.
+   */
+  public static computePercentUsed(data: {
+    spendInUSD: number;
+    dailyBudgetInUSD: number;
+  }): number {
+    if (
+      !isFinite(data.dailyBudgetInUSD) ||
+      data.dailyBudgetInUSD <= 0 ||
+      !isFinite(data.spendInUSD) ||
+      data.spendInUSD < 0
+    ) {
+      return 0;
+    }
+
+    const percent: number = (data.spendInUSD / data.dailyBudgetInUSD) * 100;
+
+    // Trim float noise; hundredth-of-a-percent resolution is plenty.
+    return Math.round(percent * 100) / 100;
+  }
+
+  /**
+   * Start of the UTC day `now` falls in. UTC-explicit (not process-zone) so
+   * the budget day is the same day everywhere OneUptime runs.
+   */
+  public static getUtcDayStart(now: Date): Date {
+    return new Date(
+      Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()),
+    );
+  }
+
+  /**
+   * Build the ClickHouse span filter for a budget: the UTC day so far,
+   * LLM spans only, narrowed by the budget's optional service / provider /
+   * model scoping.
+   */
+  public static buildSpanQuery(data: {
+    budget: LlmCostBudget;
+    dayStart: Date;
+    now: Date;
+  }): Query<Span> {
+    const query: Query<Span> = {
+      projectId: data.budget.projectId!,
+      isLlmSpan: true,
+      /*
+       * Bound rows to the window — aggregateBy's startTimestamp/endTimestamp
+       * only pick the bucket grid, they do not filter rows.
+       */
+      startTime: new InBetween(data.dayStart, data.now),
+    } as Query<Span>;
+
+    if (data.budget.serviceId) {
+      (query as Record<string, unknown>)["primaryEntityId"] =
+        data.budget.serviceId;
+    }
+
+    if (data.budget.llmSystem) {
+      (query as Record<string, unknown>)["llmSystem"] = data.budget.llmSystem;
+    }
+
+    if (data.budget.llmModel) {
+      (query as Record<string, unknown>)["llmRequestModel"] =
+        data.budget.llmModel;
+    }
+
+    return query;
+  }
+
+  /**
+   * Build the two metric rows one evaluation publishes for one budget.
+   * Pure — mirrors the derived-metric row shape the trace recording rules
+   * write — so the series shape is unit-testable.
+   */
+  public static buildBudgetMetricRows(data: {
+    budget: LlmCostBudget;
+    spendInUSD: number;
+    percentUsed: number;
+    now: Date;
+  }): Array<JSONObject> {
+    const attributes: Record<string, string> = {
+      [LLM_BUDGET_ID_ATTRIBUTE]: data.budget.id?.toString() || "",
+      [LLM_BUDGET_NAME_ATTRIBUTE]: data.budget.name || "",
+    };
+
+    if (data.budget.serviceId) {
+      attributes[LLM_BUDGET_SERVICE_ID_ATTRIBUTE] =
+        data.budget.serviceId.toString();
+    }
+
+    if (data.budget.llmSystem) {
+      attributes[LLM_BUDGET_PROVIDER_ATTRIBUTE] = data.budget.llmSystem;
+    }
+
+    if (data.budget.llmModel) {
+      attributes[LLM_BUDGET_MODEL_ATTRIBUTE] = data.budget.llmModel;
+    }
+
+    const retentionDate: Date = OneUptimeDate.addRemoveDays(
+      data.now,
+      BUDGET_METRIC_RETENTION_IN_DAYS,
+    );
+
+    const buildRow: (name: string, value: number) => JSONObject = (
+      name: string,
+      value: number,
+    ): JSONObject => {
+      return {
+        _id: ObjectID.generateTimeOrdered().toString(),
+        projectId: data.budget.projectId!.toString(),
+        createdAt: OneUptimeDate.toClickhouseDateTime(data.now),
+        time: OneUptimeDate.toClickhouseDateTime(data.now),
+        timeUnixNano: (data.now.getTime() * 1_000_000).toString(),
+        primaryEntityType: ServiceType.OpenTelemetry,
+        name: name,
+        metricPointType: MetricPointType.Gauge,
+        value: value,
+        attributes: attributes,
+        attributeKeys: Object.keys(attributes).sort(),
+        retentionDate: OneUptimeDate.toClickhouseDateTime(retentionDate),
+      };
+    };
+
+    return [
+      buildRow(LLM_BUDGET_SPEND_METRIC_NAME, data.spendInUSD),
+      buildRow(LLM_BUDGET_PERCENT_METRIC_NAME, data.percentUsed),
+    ];
+  }
+
+  /**
+   * Evaluate every enabled budget. One bad budget never aborts the sweep.
+   */
+  @CaptureSpan()
+  public static async evaluateAllBudgets(): Promise<void> {
+    const budgets: Array<LlmCostBudget> = await LlmCostBudgetService.findBy({
+      query: {
+        isEnabled: true,
+      },
+      select: {
+        _id: true,
+        projectId: true,
+        name: true,
+        dailyBudgetInUSD: true,
+        serviceId: true,
+        llmSystem: true,
+        llmModel: true,
+      },
+      limit: LIMIT_MAX,
+      skip: 0,
+      props: {
+        isRoot: true,
+      },
+    });
+
+    if (budgets.length === 0) {
+      return;
+    }
+
+    logger.debug(
+      `Llm:EvaluateLlmCostBudgets: evaluating ${budgets.length} enabled budget(s)`,
+    );
+
+    const now: Date = new Date();
+
+    for (const budget of budgets) {
+      try {
+        await this.evaluateBudget({ budget, now });
+      } catch (err) {
+        logger.error(
+          `LLM cost budget ${budget.id?.toString()} for project ${budget.projectId?.toString() ?? "?"} failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+          { projectId: budget.projectId?.toString() } as LogAttributes,
+        );
+      }
+    }
+  }
+
+  /**
+   * Evaluate one budget: sum the day's spend, stamp it on the row, and
+   * publish the spend / percent-used metric points.
+   */
+  @CaptureSpan()
+  public static async evaluateBudget(data: {
+    budget: LlmCostBudget;
+    now: Date;
+  }): Promise<void> {
+    const budget: LlmCostBudget = data.budget;
+
+    if (!budget.id || !budget.projectId || !budget.dailyBudgetInUSD) {
+      return;
+    }
+
+    const dayStart: Date = this.getUtcDayStart(data.now);
+
+    const spendInUSD: number = await this.getSpendInUSD({
+      budget: budget,
+      dayStart: dayStart,
+      now: data.now,
+    });
+
+    const percentUsed: number = this.computePercentUsed({
+      spendInUSD: spendInUSD,
+      dailyBudgetInUSD: budget.dailyBudgetInUSD,
+    });
+
+    // Stamp the spend for the dashboard's Budgets tab.
+    await LlmCostBudgetService.updateOneById({
+      id: budget.id,
+      data: {
+        currentDaySpendInUSD: spendInUSD,
+        spendLastEvaluatedAt: data.now,
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    await this.writeBudgetMetrics({
+      budget: budget,
+      spendInUSD: spendInUSD,
+      percentUsed: percentUsed,
+      now: data.now,
+    });
+  }
+
+  /**
+   * Sum the day's llmCost for the budget's scope from ClickHouse.
+   */
+  @CaptureSpan()
+  private static async getSpendInUSD(data: {
+    budget: LlmCostBudget;
+    dayStart: Date;
+    now: Date;
+  }): Promise<number> {
+    const aggregateBy: AggregateBy<Span> = {
+      query: this.buildSpanQuery(data),
+      aggregationType: AggregationType.Sum,
+      aggregateColumnName: "llmCost",
+      aggregationTimestampColumnName: "startTime",
+      startTimestamp: data.dayStart,
+      endTimestamp: data.now,
+      // One total over the whole window — no time bucketing.
+      aggregationInterval: AggregationInterval.Total,
+      /*
+       * The sum feeds monitors: fail loud on a query timeout — the default
+       * 'break' overflow mode returns silently-partial sums, which would
+       * understate spend and suppress a real budget breach downstream.
+       */
+      timeoutOverflowMode: "throw",
+      limit: LIMIT_PER_PROJECT,
+      skip: 0,
+      props: {
+        isRoot: true,
+      },
+    };
+
+    const result: AggregatedResult = await SpanService.aggregateBy(aggregateBy);
+
+    return (result.data || []).reduce(
+      (acc: number, row: AggregatedModel): number => {
+        return acc + Number(row.value || 0);
+      },
+      0,
+    );
+  }
+
+  /**
+   * Publish the budget's spend and percent-used gauge points, and register
+   * the metric names so they appear in the dashboard's metric picker and the
+   * Metrics-monitor builder.
+   */
+  @CaptureSpan()
+  private static async writeBudgetMetrics(data: {
+    budget: LlmCostBudget;
+    spendInUSD: number;
+    percentUsed: number;
+    now: Date;
+  }): Promise<void> {
+    const rows: Array<JSONObject> = this.buildBudgetMetricRows(data);
+
+    await MetricService.insertJsonRows(rows);
+
+    const spendType: MetricType = new MetricType();
+    spendType.name = LLM_BUDGET_SPEND_METRIC_NAME;
+    spendType.description =
+      "LLM spend accrued so far in the current UTC day for an LLM cost budget, in USD. One point per budget every 15 minutes; filter by the oneuptime.llm.budget.id attribute.";
+    spendType.unit = "USD";
+
+    const percentType: MetricType = new MetricType();
+    percentType.name = LLM_BUDGET_PERCENT_METRIC_NAME;
+    percentType.description =
+      "LLM spend as a percent of an LLM cost budget's daily limit. One point per budget every 15 minutes — alert with a Metrics monitor (e.g. value >= 80) using a rolling window of 30 minutes, filtered by oneuptime.llm.budget.id.";
+    percentType.unit = "%";
+
+    /*
+     * Registration is what makes the names show up in the metric picker —
+     * fire-and-forget, a registration failure must not fail the sweep.
+     */
+    TelemetryUtil.indexMetricNameServiceNameMap({
+      metricNameServiceNameMap: {
+        [LLM_BUDGET_SPEND_METRIC_NAME]: spendType,
+        [LLM_BUDGET_PERCENT_METRIC_NAME]: percentType,
+      },
+      projectId: data.budget.projectId!,
+    }).catch((err: Error) => {
+      logger.error(err);
+    });
+  }
+}

package/Server/Utils/Telemetry/LlmSpan.ts

@@ -1,7 +1,12 @@
 import Dictionary from "../../../Types/Dictionary";
+import {
+  LlmCostCatalogUtil,
+  LlmModelPrice,
+} from "../../../Types/Telemetry/LlmCostCatalog";
 import {
   LlmAgentNameAttributeKeys,
   LlmAttributeNamespacePrefixes,
+  LlmConversationIdAttributeKeys,
   LlmCostAttributeKeys,
   LlmInputTokenAttributeKeys,
   LlmOperationAttributeKeys,
@@ -44,11 +49,18 @@ export interface LlmSpanFields {
   llmInputTokens: number;
   llmOutputTokens: number;
   llmTotalTokens: number;
-  // Cost in USD. Only populated when the SDK reports it (no built-in pricing).
+  /*
+   * Cost in USD. The SDK-reported cost (gen_ai.usage.cost) when present;
+   * otherwise an estimate computed from token counts against the project's
+   * custom price overrides and the built-in list-price catalog
+   * (Common/Types/Telemetry/LlmCostCatalog.ts). 0 when none is available.
+   */
   llmCost: number;
   // Agent / tool names for agent-framework spans.
   llmAgentName: string;
   llmToolName: string;
+  // Conversation / session id grouping calls of one interaction (gen_ai.conversation.id).
+  llmConversationId: string;
 }
 
 type SpanAttributes = Dictionary<AttributeType | Array<AttributeType>>;
@@ -70,14 +82,22 @@ export default class LlmSpanUtil {
       llmCost: 0,
       llmAgentName: "",
       llmToolName: "",
+      llmConversationId: "",
     };
   }
 
   /**
    * Extract first-class LLM fields from a flattened span attribute dictionary.
    * Pure + side-effect free so it can be unit tested in isolation.
+   *
+   * `projectPriceOverrides` are the project's custom model prices (loaded by
+   * the ingest pipeline); they take part in the cost fallback below with
+   * longest-prefix-wins semantics against the built-in catalog.
    */
-  public static extract(attributes: SpanAttributes): LlmSpanFields {
+  public static extract(
+    attributes: SpanAttributes,
+    projectPriceOverrides?: Array<LlmModelPrice>,
+  ): LlmSpanFields {
     const fields: LlmSpanFields = this.empty();
 
     if (!attributes || typeof attributes !== "object") {
@@ -134,7 +154,17 @@ export default class LlmSpanUtil {
       fields.llmTotalTokens = fields.llmInputTokens + fields.llmOutputTokens;
     }
 
-    fields.llmCost = this.getNumber(attributes, LlmCostAttributeKeys);
+    /*
+     * Cost must distinguish "reported as 0" from "not reported at all": a
+     * gateway fronting a free local model (or a fully-cached call) reports an
+     * explicit cost of 0, and that 0 must win over any catalog estimate.
+     */
+    const reportedCost: number | null = this.getNumberOrNull(
+      attributes,
+      LlmCostAttributeKeys,
+    );
+
+    fields.llmCost = reportedCost ?? 0;
 
     fields.llmAgentName = this.getString(attributes, LlmAgentNameAttributeKeys);
 
@@ -142,6 +172,43 @@ export default class LlmSpanUtil {
 
     fields.isLlmSpan = this.detectIsLlmSpan(keys, fields);
 
+    /*
+     * Conversation id is gated on isLlmSpan because one of its candidate keys
+     * ("session.id") is the generic OTel key RUM browser spans carry — those
+     * already denormalize it into the sessionId column, and stamping it here
+     * too would duplicate it (and its bloom-filter index) across the
+     * highest-volume span class for no reader.
+     */
+    if (fields.isLlmSpan) {
+      fields.llmConversationId = this.getString(
+        attributes,
+        LlmConversationIdAttributeKeys,
+      );
+    }
+
+    /*
+     * Cost fallback: the SDK-reported cost always wins — including an
+     * explicit 0 — but most instrumentations only report token counts. Price
+     * those against the project's custom price overrides and the built-in
+     * list-price catalog (longest prefix wins across both, project entries
+     * beat built-ins on ties) so spend shows up in dashboards and cost
+     * budgets without per-SDK pricing math. The response model is priced in
+     * preference to the request model — it names what the provider actually
+     * served (e.g. an alias like "gpt-4o" resolved to a dated snapshot).
+     */
+    if (fields.isLlmSpan && reportedCost === null) {
+      const computedCost: number | null = LlmCostCatalogUtil.computeCostInUSD({
+        model: fields.llmResponseModel || fields.llmRequestModel,
+        inputTokens: fields.llmInputTokens,
+        outputTokens: fields.llmOutputTokens,
+        projectPriceOverrides: projectPriceOverrides,
+      });
+
+      if (computedCost !== null) {
+        fields.llmCost = computedCost;
+      }
+    }
+
     return fields;
   }
 
@@ -199,6 +266,18 @@ export default class LlmSpanUtil {
     attributes: SpanAttributes,
     candidateKeys: Array<string>,
   ): number {
+    return this.getNumberOrNull(attributes, candidateKeys) ?? 0;
+  }
+
+  /**
+   * Like getNumber but null when no candidate key carries a parseable number
+   * — callers that must distinguish "reported as 0" from "absent" (cost) use
+   * this directly.
+   */
+  private static getNumberOrNull(
+    attributes: SpanAttributes,
+    candidateKeys: Array<string>,
+  ): number | null {
     for (const key of candidateKeys) {
       const value: AttributeType | Array<AttributeType> | undefined =
         attributes[key];
@@ -220,6 +299,6 @@ export default class LlmSpanUtil {
       }
     }
 
-    return 0;
+    return null;
   }
 }

package/Server/Utils/Telemetry/LogErrorPatternSql.ts

@@ -0,0 +1,136 @@
+import TableColumnType from "../../../Types/AnalyticsDatabase/TableColumnType";
+import { SQL, Statement } from "../AnalyticsDatabase/Statement";
+import {
+  LOG_ERROR_PATTERN_MAX_LENGTH,
+  LOG_ERROR_PATTERN_RULES,
+  LogErrorPatternRule,
+} from "../../../Utils/Telemetry/LogErrorPattern";
+
+/*
+ * Compiles the shared error-pattern rules (Common/Utils/Telemetry/
+ * LogErrorPattern) into the ClickHouse expression that does the grouping.
+ *
+ * The grouping has to happen in the database. Normalizing client-side would
+ * mean shipping a page of raw bodies to the browser and counting those,
+ * which answers "what are the top errors in the 5000 rows I happened to
+ * fetch" — a different, and much less useful, question than "what are the
+ * top errors in this window".
+ *
+ * Shape of the emitted expression, for rules r0..rN in order:
+ *
+ *   trimBoth(substringUTF8(trimBoth(
+ *     replaceRegexpAll(...replaceRegexpAll(ifNull(body,''), p0, x0)..., pN, xN)
+ *   ), 1, 300))
+ *
+ * The innermost call is the FIRST rule, matching the sequential application
+ * order `normalizeLogBodyToErrorPattern` uses, and the trim/truncate/trim
+ * tail mirrors its `.trim()` -> `.slice()` -> `.trim()`. The shape is pinned
+ * by Common/Tests/Server/Utils/Telemetry/LogErrorPatternSql.test.ts.
+ *
+ * Truncation uses substringUTF8, NOT substring. ClickHouse's `substring`
+ * counts BYTES, so a 300-byte cut through a Japanese message or an emoji
+ * lands mid-sequence and the group key ends in a broken UTF-8 fragment. The
+ * UTF8 variant counts characters, which is also what the JavaScript
+ * normalizer's `.slice()` approximates. The two are not bit-identical for
+ * astral-plane characters (JS slices UTF-16 code units, so an emoji costs it
+ * two) — that only shifts where a very long pattern is cut, never what it
+ * groups, and is deliberately not claimed as exact parity.
+ *
+ * Patterns and replacements ride as bound query parameters rather than
+ * being interpolated. ClickHouse substitutes parameters into the AST as
+ * constant literals during parsing, so `replaceRegexpAll` still sees the
+ * constant regexp argument it requires (the same shape the Sigma compiler
+ * already relies on for `match(expr, {p:String})`), and no rule text ever
+ * reaches the SQL text itself.
+ */
+
+/**
+ * The column expression the pattern is computed from.
+ *
+ * `body` is Nullable(String) on the Log table, and `replaceRegexpAll(NULL,
+ * ...)` is NULL — which would collapse every body-less row into one NULL
+ * group. Coalescing first turns those into the empty pattern, which the
+ * callers exclude with a `!= ''` predicate.
+ */
+export const LOG_ERROR_PATTERN_SOURCE_EXPRESSION: string = "ifNull(body, '')";
+
+/**
+ * Build the pattern expression over `sourceExpression`.
+ *
+ * `sourceExpression` is appended to the statement as trusted SQL — it must
+ * be a literal owned by this codebase (in practice always
+ * LOG_ERROR_PATTERN_SOURCE_EXPRESSION), never anything derived from a
+ * request.
+ */
+export function buildLogErrorPatternExpression(
+  sourceExpression: string = LOG_ERROR_PATTERN_SOURCE_EXPRESSION,
+): Statement {
+  const statement: Statement = new Statement();
+
+  statement.append("trimBoth(substringUTF8(trimBoth(");
+
+  // One open paren per rule; the arguments below close them inside-out.
+  statement.append("replaceRegexpAll(".repeat(LOG_ERROR_PATTERN_RULES.length));
+
+  statement.append(sourceExpression);
+
+  /*
+   * Ascending order: rule 0's arguments close the innermost call, so it is
+   * applied first — exactly as the JavaScript normalizer iterates.
+   */
+  for (const rule of LOG_ERROR_PATTERN_RULES) {
+    statement.append(
+      SQL`, ${{
+        type: TableColumnType.Text,
+        value: rule.pattern,
+      }}, ${{
+        type: TableColumnType.Text,
+        value: rule.replacement,
+      }})`,
+    );
+  }
+
+  statement.append(
+    SQL`), 1, ${{
+      type: TableColumnType.Number,
+      value: LOG_ERROR_PATTERN_MAX_LENGTH,
+    }}))`,
+  );
+
+  return statement;
+}
+
+/**
+ * How many bound parameters `buildLogErrorPatternExpression` contributes.
+ * Exported so callers reasoning about parameter budgets (and the tests that
+ * pin statement shapes) do not have to count rules by hand.
+ */
+export function getLogErrorPatternParameterCount(): number {
+  return LOG_ERROR_PATTERN_RULES.length * 2 + 1;
+}
+
+/**
+ * Guard for a caller-supplied pattern value (the detail endpoints echo one
+ * back to scope their queries), bounding the parameter without changing
+ * which rows it matches.
+ *
+ * Counted in CODE POINTS, because that is what the expression above cuts
+ * by. Measuring in JavaScript's UTF-16 code units instead would mangle a
+ * legitimate key: a 300-code-point pattern containing one emoji has
+ * `.length === 301`, so the clamp would fire on a value the database
+ * considers exactly at the limit and slice it — leaving a lone surrogate at
+ * the tail when the emoji sits there. The bind would then match zero rows
+ * and, since nothing throws, every drill-down panel would come back
+ * cheerfully empty for a Top Errors row showing a real count.
+ */
+export function clampLogErrorPattern(pattern: string): string {
+  const codePoints: Array<string> = Array.from(pattern);
+
+  if (codePoints.length <= LOG_ERROR_PATTERN_MAX_LENGTH) {
+    return pattern;
+  }
+
+  return codePoints.slice(0, LOG_ERROR_PATTERN_MAX_LENGTH).join("");
+}
+
+export type { LogErrorPatternRule };