@oneuptime/common 11.3.25 → 11.3.28

package/Server/Utils/AI/Toolbox/ToolTypes.ts

@@ -0,0 +1,249 @@
+import DatabaseCommonInteractionProps from "../../../../Types/BaseDatabase/DatabaseCommonInteractionProps";
+import BadDataException from "../../../../Types/Exception/BadDataException";
+import { JSONObject } from "../../../../Types/JSON";
+import ObjectID from "../../../../Types/ObjectID";
+import OneUptimeDate from "../../../../Types/Date";
+import Permission from "../../../../Types/Permission";
+import {
+  AIChatCitationTarget,
+  AIChatWidget,
+} from "../../../../Types/AI/AIChatTypes";
+
+/*
+ * The execution context for a tool call. projectId is ALWAYS the tenant from
+ * the authenticated request props — it is never a tool argument, so the model
+ * cannot point a tool at another project.
+ */
+export interface ToolContext {
+  projectId: ObjectID;
+  props: DatabaseCommonInteractionProps;
+}
+
+export interface ToolExecutionResult {
+  // Serialized, truncated and redacted data that goes into the LLM prompt.
+  dataForLlm: string;
+  rowCount: number;
+  citationLabel: string;
+  citationTarget?: AIChatCitationTarget | undefined;
+  redactionCount: number;
+  isTruncated: boolean;
+  /*
+   * Optional structured widget (chart, table, trace waterfall, resource card)
+   * rendered inline in the chat. Built from the RAW rows the tool fetched — not
+   * the redacted LLM payload — because it is rendered back to the same user who
+   * already has RBAC access to this data.
+   */
+  widget?: AIChatWidget | undefined;
+}
+
+export interface ObservabilityTool {
+  name: string;
+  description: string;
+  // JSON Schema for the tool arguments, handed to the LLM.
+  inputSchema: JSONObject;
+  /*
+   * The user must hold at least one of these permissions for the tool to
+   * execute. For tools that call permission-checked services this is
+   * defense-in-depth; for tools that call raw-SQL aggregation services it is
+   * the authorization.
+   */
+  requiredPermissions: Array<Permission>;
+  /*
+   * True for tools that MUTATE project data (create/acknowledge/resolve, etc).
+   * These are gated by the conversation's permission mode: paused for approval
+   * in AskForApproval mode, run immediately in AutoRun, and not offered to the
+   * model at all in ReadOnly. Undefined/false = a read-only tool that always
+   * runs.
+   */
+  isMutation?: boolean | undefined;
+  /*
+   * Optional human-readable label for the approval card, derived from the
+   * (already validated) tool arguments — e.g. "Create incident: Checkout down".
+   * Falls back to the tool name when omitted.
+   */
+  buildActionTitle?: ((args: JSONObject) => string) | undefined;
+  execute(args: JSONObject, ctx: ToolContext): Promise<ToolExecutionResult>;
+}
+
+/*
+ * Defensive argument readers. Tool arguments come from the LLM and are
+ * untrusted: everything is type-checked, defaulted and clamped.
+ */
+export class ToolArgs {
+  public static getString(args: JSONObject, key: string): string | undefined {
+    const value: unknown = args[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+    return undefined;
+  }
+
+  public static getStringArray(
+    args: JSONObject,
+    key: string,
+  ): Array<string> | undefined {
+    const value: unknown = args[key];
+    if (Array.isArray(value)) {
+      const strings: Array<string> = value.filter((item: unknown) => {
+        return typeof item === "string" && item.trim().length > 0;
+      }) as Array<string>;
+      if (strings.length > 0) {
+        return strings;
+      }
+    }
+    return undefined;
+  }
+
+  public static getNumber(
+    args: JSONObject,
+    key: string,
+    options: { defaultValue: number; min: number; max: number },
+  ): number {
+    const value: unknown = args[key];
+    let parsed: number = options.defaultValue;
+
+    if (typeof value === "number" && Number.isFinite(value)) {
+      parsed = value;
+    } else if (typeof value === "string" && value.trim().length > 0) {
+      const fromString: number = Number(value);
+      if (Number.isFinite(fromString)) {
+        parsed = fromString;
+      }
+    }
+
+    return Math.min(options.max, Math.max(options.min, Math.floor(parsed)));
+  }
+
+  public static getBoolean(args: JSONObject, key: string): boolean | undefined {
+    const value: unknown = args[key];
+    if (typeof value === "boolean") {
+      return value;
+    }
+    if (value === "true") {
+      return true;
+    }
+    if (value === "false") {
+      return false;
+    }
+    return undefined;
+  }
+
+  public static getObjectID(
+    args: JSONObject,
+    key: string,
+  ): ObjectID | undefined {
+    const value: string | undefined = this.getString(args, key);
+    if (!value) {
+      return undefined;
+    }
+    return new ObjectID(value);
+  }
+
+  /*
+   * Combines the caller's optional serviceId filter with the user's owned-scope
+   * access (from ModelPermission.getAccessibleServiceIdsForAnalyticsModel) into
+   * the `serviceIds` filter to hand an aggregation service.
+   *
+   * `allowed === null` means the user has project-wide access: pass only the
+   * caller's own filter (or undefined for no filter). Otherwise the user is
+   * label/owned-restricted: intersect with any requested service and NEVER
+   * return undefined or an empty array — an empty result is forced to a
+   * no-match sentinel, because the aggregation services treat a missing/empty
+   * serviceIds as "no filter" (which would leak the whole project).
+   */
+  public static scopeServiceIds(
+    allowed: Array<ObjectID> | null,
+    requested: ObjectID | undefined,
+  ): Array<ObjectID> | undefined {
+    if (allowed === null) {
+      return requested ? [requested] : undefined;
+    }
+
+    let effective: Array<ObjectID> = allowed;
+    if (requested) {
+      effective = allowed.filter((id: ObjectID) => {
+        return id.toString() === requested.toString();
+      });
+    }
+
+    if (effective.length === 0) {
+      return [ObjectID.getZeroObjectID()];
+    }
+
+    return effective;
+  }
+
+  /*
+   * Time range for a tool call: explicit ISO startTime/endTime arguments,
+   * clamped to a maximum window, defaulting to the last hour.
+   */
+  public static getTimeRange(
+    args: JSONObject,
+    options?: { defaultHours?: number; maxDays?: number },
+  ): { startTime: Date; endTime: Date } {
+    const defaultHours: number = options?.defaultHours ?? 1;
+    const maxDays: number = options?.maxDays ?? 30;
+
+    const endTimeString: string | undefined = this.getString(args, "endTime");
+    const startTimeString: string | undefined = this.getString(
+      args,
+      "startTime",
+    );
+
+    /*
+     * Reject unparseable timestamps instead of silently falling back to the
+     * default window — a silent fallback answers a different question than the
+     * one asked. Throwing lets the model see the error and retry with a valid
+     * ISO 8601 value.
+     */
+    let endTime: Date = OneUptimeDate.getCurrentDate();
+    if (endTimeString) {
+      const parsed: Date = new Date(endTimeString);
+      if (isNaN(parsed.getTime())) {
+        throw new BadDataException(
+          `endTime "${endTimeString}" is not a valid ISO 8601 timestamp (e.g. 2024-01-31T14:00:00Z).`,
+        );
+      }
+      endTime = parsed;
+    }
+
+    let startTime: Date = OneUptimeDate.addRemoveHours(
+      endTime,
+      -1 * defaultHours,
+    );
+    if (startTimeString) {
+      const parsed: Date = new Date(startTimeString);
+      if (isNaN(parsed.getTime())) {
+        throw new BadDataException(
+          `startTime "${startTimeString}" is not a valid ISO 8601 timestamp (e.g. 2024-01-31T13:00:00Z).`,
+        );
+      }
+      startTime = parsed;
+    }
+
+    if (startTime.getTime() >= endTime.getTime()) {
+      throw new BadDataException("startTime must be before endTime.");
+    }
+
+    const maxWindowMs: number = maxDays * 24 * 60 * 60 * 1000;
+    if (endTime.getTime() - startTime.getTime() > maxWindowMs) {
+      startTime = new Date(endTime.getTime() - maxWindowMs);
+    }
+
+    return { startTime, endTime };
+  }
+}
+
+// Shared JSON-Schema fragments for tool input schemas.
+export const TimeRangeSchemaProperties: JSONObject = {
+  startTime: {
+    type: "string",
+    description:
+      "Start of the time range as an ISO 8601 timestamp. Defaults to one hour before endTime.",
+  },
+  endTime: {
+    type: "string",
+    description:
+      "End of the time range as an ISO 8601 timestamp. Defaults to now.",
+  },
+};

package/Server/Utils/AI/Toolbox/TraceTools.ts

@@ -0,0 +1,402 @@
+import Span from "../../../../Models/AnalyticsModels/Span";
+import DatabaseRequestType from "../../../Types/BaseDatabase/DatabaseRequestType";
+import ModelPermission from "../../../Types/AnalyticsDatabase/ModelPermission";
+import SortOrder from "../../../../Types/BaseDatabase/SortOrder";
+import BadDataException from "../../../../Types/Exception/BadDataException";
+import { JSONObject } from "../../../../Types/JSON";
+import ObjectID from "../../../../Types/ObjectID";
+import Permission from "../../../../Types/Permission";
+import {
+  AIChatCitationTargetType,
+  AIChatWidgetSpan,
+} from "../../../../Types/AI/AIChatTypes";
+import SpanService from "../../../Services/SpanService";
+import TraceAggregationService, {
+  TraceAnalyticsTableRow,
+} from "../../../Services/TraceAggregationService";
+import ToolResultSerializer, { SerializedResult } from "./Serializer";
+import WidgetBuilder from "./WidgetBuilder";
+import {
+  ObservabilityTool,
+  TimeRangeSchemaProperties,
+  ToolArgs,
+  ToolContext,
+  ToolExecutionResult,
+} from "./ToolTypes";
+
+const TRACE_READ_PERMISSIONS: Array<Permission> = [
+  Permission.ProjectOwner,
+  Permission.ProjectAdmin,
+  Permission.ProjectMember,
+  Permission.Viewer,
+  Permission.TelemetryAdmin,
+  Permission.TelemetryMember,
+  Permission.TelemetryViewer,
+  Permission.ReadTelemetryServiceTraces,
+];
+
+const VALID_METRICS: Array<string> = [
+  "count",
+  "errorCount",
+  "avgDuration",
+  "minDuration",
+  "maxDuration",
+  "p50Duration",
+  "p90Duration",
+  "p95Duration",
+  "p99Duration",
+];
+
+const VALID_GROUP_BY: Array<string> = [
+  "name",
+  "primaryEntityId",
+  "kind",
+  "statusCode",
+  "isRootSpan",
+];
+
+/*
+ * Upper bound on spans fetched for a single trace waterfall. High enough for
+ * almost every real trace; when a trace exceeds it we say so explicitly rather
+ * than silently dropping spans (which also orphans their children into fake
+ * roots).
+ */
+const MAX_TRACE_SPANS: number = 500;
+
+export const QueryTracesTool: ObservabilityTool = {
+  name: "query_traces",
+  description:
+    "Analyze spans/traces: latency profile (count, errorCount, avg and p50/p90/p95/p99 durations in ms) grouped by one dimension such as span name or service. Use this to answer 'why is X slow', 'error rate by operation' or 'slowest endpoints'. Then drill into a single trace with get_trace.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ...TimeRangeSchemaProperties,
+      groupBy: {
+        type: "string",
+        enum: ["name", "primaryEntityId", "kind", "statusCode", "isRootSpan"],
+        description:
+          "Dimension to group by (default name = span/operation name; primaryEntityId = service).",
+      },
+      metric: {
+        type: "string",
+        enum: [
+          "count",
+          "errorCount",
+          "avgDuration",
+          "minDuration",
+          "maxDuration",
+          "p50Duration",
+          "p90Duration",
+          "p95Duration",
+          "p99Duration",
+        ],
+        description:
+          "Metric used to rank the groups (default p95Duration). The full latency profile is always returned per group.",
+      },
+      nameSearchText: {
+        type: "string",
+        description: "Only spans whose name contains this text.",
+      },
+      serviceId: {
+        type: "string",
+        description: "Only spans from this telemetry service.",
+      },
+      hasException: {
+        type: "boolean",
+        description: "Only spans that recorded an exception.",
+      },
+      rootOnly: {
+        type: "boolean",
+        description: "Only root spans (whole-request latency).",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum groups to return (default 10, max 25).",
+      },
+    },
+  },
+  requiredPermissions: TRACE_READ_PERMISSIONS,
+  execute: async (
+    args: JSONObject,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    const { startTime, endTime } = ToolArgs.getTimeRange(args, {
+      defaultHours: 24,
+      maxDays: 30,
+    });
+
+    const metric: string = ToolArgs.getString(args, "metric") || "p95Duration";
+    if (!VALID_METRICS.includes(metric)) {
+      throw new BadDataException(`Invalid metric: ${metric}`);
+    }
+
+    const groupBy: string = ToolArgs.getString(args, "groupBy") || "name";
+    if (!VALID_GROUP_BY.includes(groupBy)) {
+      throw new BadDataException(`Invalid groupBy: ${groupBy}`);
+    }
+
+    const limit: number = ToolArgs.getNumber(args, "limit", {
+      defaultValue: 10,
+      min: 1,
+      max: 25,
+    });
+
+    const serviceId: ObjectID | undefined = ToolArgs.getObjectID(
+      args,
+      "serviceId",
+    );
+
+    const windowMinutes: number =
+      (endTime.getTime() - startTime.getTime()) / (60 * 1000);
+
+    /*
+     * getAnalyticsTable builds raw aggregation SQL and skips the model layer's
+     * owned-scope filter, so a label-restricted user would otherwise see
+     * project-wide trace analytics. Constrain to the services this user may
+     * read (spans are owned through Service, same as logs).
+     */
+    const accessibleServiceIds: Array<ObjectID> | null =
+      await ModelPermission.getAccessibleServiceIdsForAnalyticsModel(
+        Span,
+        ctx.props,
+        DatabaseRequestType.Read,
+      );
+
+    const tableRows: Array<TraceAnalyticsTableRow> =
+      await TraceAggregationService.getAnalyticsTable({
+        projectId: ctx.projectId,
+        startTime: startTime,
+        endTime: endTime,
+        bucketSizeInMinutes: Math.max(1, Math.round(windowMinutes / 60)),
+        chartType: "table",
+        metric: metric as never,
+        groupBy: [groupBy],
+        limit: limit,
+        nameSearchText: ToolArgs.getString(args, "nameSearchText"),
+        serviceIds: ToolArgs.scopeServiceIds(accessibleServiceIds, serviceId),
+        hasException: ToolArgs.getBoolean(args, "hasException"),
+        rootOnly: ToolArgs.getBoolean(args, "rootOnly"),
+      });
+
+    const rows: Array<JSONObject> = tableRows.map(
+      (row: TraceAnalyticsTableRow) => {
+        return {
+          [groupBy]: Object.values(row.groupValues).join(" / "),
+          count: row.count,
+          errorCount: row.errorCount,
+          avgMs: Math.round(row.avgDurationMs * 100) / 100,
+          p50Ms: Math.round(row.p50DurationMs * 100) / 100,
+          p90Ms: Math.round(row.p90DurationMs * 100) / 100,
+          p95Ms: Math.round(row.p95DurationMs * 100) / 100,
+          p99Ms: Math.round(row.p99DurationMs * 100) / 100,
+        };
+      },
+    );
+
+    const serialized: SerializedResult =
+      ToolResultSerializer.serializeRows(rows);
+
+    return {
+      dataForLlm: serialized.text,
+      rowCount: serialized.rowCount,
+      citationLabel: `Trace analytics by ${groupBy} (${metric}), ${startTime.toISOString()} – ${endTime.toISOString()}`,
+      citationTarget: {
+        type: AIChatCitationTargetType.Traces,
+      },
+      redactionCount: serialized.redactionCount,
+      isTruncated: serialized.isTruncated,
+      widget:
+        rows.length > 0
+          ? WidgetBuilder.table({
+              title: `Trace analytics by ${groupBy}`,
+              description: `Ranked by ${metric} · ${startTime.toISOString()} – ${endTime.toISOString()}`,
+              columns: [
+                { key: groupBy, title: groupBy, type: "text" },
+                { key: "count", title: "Count", type: "number" },
+                { key: "errorCount", title: "Errors", type: "number" },
+                { key: "avgMs", title: "Avg (ms)", type: "number" },
+                { key: "p90Ms", title: "p90 (ms)", type: "number" },
+                { key: "p95Ms", title: "p95 (ms)", type: "number" },
+                { key: "p99Ms", title: "p99 (ms)", type: "number" },
+              ],
+              rows: rows,
+              link: { type: AIChatCitationTargetType.Traces },
+            })
+          : undefined,
+    };
+  },
+};
+
+interface SpanTreeNode {
+  span: Span;
+  children: Array<SpanTreeNode>;
+}
+
+export const GetTraceTool: ObservabilityTool = {
+  name: "get_trace",
+  description:
+    "Get the span tree (waterfall) of one trace by traceId: every span with its duration, status and whether it recorded an exception. Use after query_traces or search_logs surfaces an interesting traceId.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      traceId: {
+        type: "string",
+        description: "The trace ID (required).",
+      },
+    },
+    required: ["traceId"],
+  },
+  requiredPermissions: TRACE_READ_PERMISSIONS,
+  execute: async (
+    args: JSONObject,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    const traceId: string | undefined = ToolArgs.getString(args, "traceId");
+
+    if (!traceId) {
+      throw new BadDataException("traceId is required.");
+    }
+
+    const spans: Array<Span> = await SpanService.findBy({
+      query: {
+        traceId: traceId,
+      } as never,
+      select: {
+        spanId: true,
+        parentSpanId: true,
+        name: true,
+        startTimeUnixNano: true,
+        durationUnixNano: true,
+        statusCode: true,
+        kind: true,
+      } as never,
+      sort: {
+        startTimeUnixNano: SortOrder.Ascending,
+      } as never,
+      limit: MAX_TRACE_SPANS,
+      skip: 0,
+      props: ctx.props,
+    });
+
+    const isSpanLimitHit: boolean = spans.length >= MAX_TRACE_SPANS;
+
+    // Build the tree.
+    const nodesBySpanId: Map<string, SpanTreeNode> = new Map();
+    const roots: Array<SpanTreeNode> = [];
+
+    for (const span of spans) {
+      nodesBySpanId.set(span.spanId?.toString() || "", {
+        span,
+        children: [],
+      });
+    }
+
+    for (const node of nodesBySpanId.values()) {
+      const parentId: string = node.span.parentSpanId?.toString() || "";
+      const parent: SpanTreeNode | undefined = nodesBySpanId.get(parentId);
+      if (parent && parent !== node) {
+        parent.children.push(node);
+      } else {
+        roots.push(node);
+      }
+    }
+
+    const lines: Array<string> = [];
+
+    const renderNode: (node: SpanTreeNode, depth: number) => void = (
+      node: SpanTreeNode,
+      depth: number,
+    ): void => {
+      const durationMs: number =
+        Math.round((Number(node.span.durationUnixNano) / 1_000_000) * 100) /
+        100;
+      const status: string =
+        Number(node.span.statusCode) === 2 ? " [ERROR]" : "";
+      lines.push(
+        `${"  ".repeat(depth)}- ${node.span.name} (${durationMs}ms)${status}`,
+      );
+      for (const child of node.children) {
+        renderNode(child, depth + 1);
+      }
+    };
+
+    for (const root of roots) {
+      renderNode(root, 0);
+    }
+
+    if (isSpanLimitHit) {
+      lines.push(
+        `… trace truncated at ${MAX_TRACE_SPANS} spans; deeper spans are omitted and some shown here may appear as roots because their parent was cut off.`,
+      );
+    }
+
+    const serialized: SerializedResult = ToolResultSerializer.serializeText(
+      lines.join("\n"),
+      spans.length,
+    );
+
+    /*
+     * Build the waterfall widget: each span's start is expressed as an offset in
+     * ms from the earliest span start (the trace start), so the renderer can lay
+     * out proportional bars without any wall-clock math.
+     */
+    let traceStartNano: number | undefined = undefined;
+    let traceEndNano: number = 0;
+    for (const span of spans) {
+      const start: number = Number(span.startTimeUnixNano);
+      const end: number = start + Number(span.durationUnixNano);
+      if (traceStartNano === undefined || start < traceStartNano) {
+        traceStartNano = start;
+      }
+      if (end > traceEndNano) {
+        traceEndNano = end;
+      }
+    }
+
+    const nanoToMs: (nano: number) => number = (nano: number): number => {
+      return Math.round((nano / 1_000_000) * 100) / 100;
+    };
+
+    const widgetSpans: Array<AIChatWidgetSpan> = spans.map((span: Span) => {
+      const start: number = Number(span.startTimeUnixNano);
+      return {
+        spanId: span.spanId?.toString() || "",
+        parentSpanId: span.parentSpanId?.toString() || undefined,
+        name: span.name || "(unnamed span)",
+        startOffsetMs: nanoToMs(start - (traceStartNano ?? start)),
+        durationMs: nanoToMs(Number(span.durationUnixNano)),
+        isError: Number(span.statusCode) === 2,
+      };
+    });
+
+    const totalDurationMs: number =
+      traceStartNano !== undefined
+        ? nanoToMs(traceEndNano - traceStartNano)
+        : 0;
+
+    return {
+      dataForLlm: serialized.text,
+      rowCount: serialized.rowCount,
+      citationLabel: `Trace ${traceId} (${spans.length}${isSpanLimitHit ? "+" : ""} spans)`,
+      citationTarget: {
+        type: AIChatCitationTargetType.TraceView,
+        params: { traceId: traceId },
+      },
+      redactionCount: serialized.redactionCount,
+      isTruncated: serialized.isTruncated || isSpanLimitHit,
+      widget:
+        widgetSpans.length > 0
+          ? WidgetBuilder.traceWaterfall({
+              title: `Trace waterfall (${spans.length}${isSpanLimitHit ? "+" : ""} spans)`,
+              description: `${totalDurationMs} ms total`,
+              spans: widgetSpans,
+              totalDurationMs: totalDurationMs,
+              link: {
+                type: AIChatCitationTargetType.TraceView,
+                params: { traceId: traceId },
+              },
+            })
+          : undefined,
+    };
+  },
+};