Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ const READ_ONLY_TOOLS = new Set([
"observability_metric_names",
"observability_query",
"observability_range_query",
"observability_metric_last_seen",
"observability_log_labels",
"observability_logs",
"pdf",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { registerLokiTools } from "./loki.ts";
import { registerGrafanaTools } from "./grafana.ts";
import { metricHistoryTool } from "./metric-history.ts";

type PrometheusVectorSample = {
metric: Record<string, string>;
Expand Down Expand Up @@ -80,6 +81,23 @@ function parsePromValue(value: string) {
return Number.isFinite(parsed) ? parsed : value;
}

function unixTimeIso(value: unknown) {
if (typeof value !== "number" || !Number.isFinite(value)) return null;
const date = new Date(value * 1000);
return Number.isFinite(date.getTime()) ? date.toISOString() : null;
}

function timestampValues(rawParams: Record<string, unknown>) {
if (rawParams.valueFormat === undefined) return false;
if (rawParams.valueFormat !== "unix_seconds") throw new Error("valueFormat must be unix_seconds when query values represent timestamps");
return true;
}

function compactSample(timestamp: number, rawValue: string, valuesAreTimestamps: boolean) {
const value = parsePromValue(rawValue);
return { timestamp, value, ...(valuesAreTimestamps ? { valueIso: unixTimeIso(value) } : {}) };
}

async function prometheusFetch(baseUrl: string, path: string, params?: Record<string, string | number>) {
const url = new URL(`${baseUrl}${path}`);
for (const [key, value] of Object.entries(params || {})) {
Expand All @@ -99,7 +117,7 @@ async function prometheusFetch(baseUrl: string, path: string, params?: Record<st
return payload;
}

function compactResult(payload: PrometheusResponse, maxSeries: number, maxPoints: number) {
function compactResult(payload: PrometheusResponse, maxSeries: number, maxPoints: number, valuesAreTimestamps = false) {
const result = payload.data?.result || [];
return {
resultType: payload.data?.resultType,
Expand All @@ -108,36 +126,42 @@ function compactResult(payload: PrometheusResponse, maxSeries: number, maxPoints
if (series.value) {
return {
metric: series.metric,
value: {
timestamp: series.value[0],
value: parsePromValue(series.value[1]),
},
value: compactSample(series.value[0], series.value[1], valuesAreTimestamps),
};
}
const values = series.values || [];
const stride = Math.max(1, Math.ceil(values.length / maxPoints));
// Keep both edges: stride sampling can omit the last observed point,
// making a data gap appear to begin earlier than the backend evidence.
const selected = values.length <= maxPoints ? values : maxPoints === 1
? [values[0]]
: Array.from({ length: maxPoints }, (_value, index) =>
values[Math.floor(index * (values.length - 1) / (maxPoints - 1))]);
return {
metric: series.metric,
pointCount: values.length,
values: values
.filter((_value, index) => index % stride === 0)
.slice(0, maxPoints)
.map(([timestamp, value]) => ({ timestamp, value: parsePromValue(value) })),
returnedPointCount: selected.length,
downsampled: selected.length < values.length,
firstReturnedTimestamp: values[0]?.[0] ?? null,
lastReturnedTimestamp: values.at(-1)?.[0] ?? null,
firstReturnedTimestampIso: unixTimeIso(values[0]?.[0]),
lastReturnedTimestampIso: unixTimeIso(values.at(-1)?.[0]),
values: selected.map(([timestamp, value]) => compactSample(timestamp, value, valuesAreTimestamps)),
};
}),
truncated: result.length > maxSeries,
};
}

async function query(baseUrl: string, promql: string, time?: string, maxSeries = 50) {
async function query(baseUrl: string, promql: string, time?: string, maxSeries = 50, valuesAreTimestamps = false) {
const payload = await prometheusFetch(baseUrl, "/api/v1/query", {
query: promql,
...(time ? { time } : {}),
});
return compactResult(payload, maxSeries, 1);
return compactResult(payload, maxSeries, 1, valuesAreTimestamps);
}

async function queryRange(baseUrl: string, promql: string, rawParams: Record<string, unknown>) {
const valuesAreTimestamps = timestampValues(rawParams);
const rangeMinutes = boundedNumber(rawParams.rangeMinutes, 60, 1, 10080);
const stepSeconds = boundedNumber(rawParams.stepSeconds, 60, 5, 3600);
const maxSeries = Math.trunc(boundedNumber(rawParams.maxSeries, 20, 1, 200));
Expand All @@ -155,12 +179,23 @@ async function queryRange(baseUrl: string, promql: string, rawParams: Record<str
end,
step: stepSeconds,
});
const hasSamples = (payload.data?.result || []).some(series => series.value || series.values?.length);
return {
query: promql,
start,
end,
startIso: unixTimeIso(start),
endIso: unixTimeIso(end),
stepSeconds,
...compactResult(payload, maxSeries, maxPoints),
...compactResult(payload, maxSeries, maxPoints, valuesAreTimestamps),
historyEvidence: {
status: hasSamples ? "samples_returned" : "no_samples_in_window",
incidentOnsetDetermined: false,
timestampMeaning: "query_evaluation_time",
guidance: hasSamples
? "Query boundaries are not incident onset times. To date a gap, find the last present and first missing observations for the same source, then refine that interval. Evaluation timestamps may differ from source sample timestamps; query timestamp(metric) with valueFormat: unix_seconds to obtain source sample times as valueIso. Use returned ISO times rather than mentally converting Unix timestamps. Downsampling can hide intermediate gaps."
: "No samples in this query window does not establish when data stopped. For a missing metric, call observability_metric_last_seen with the same metric and exact source labels to search earlier raw samples. If unavailable, search earlier windows for that source. If history or investigation limits prevent this, report the onset as unknown and state the checked window, not an incident start time.",
},
};
}

Expand All @@ -180,6 +215,7 @@ export default definePluginEntry({
registerLokiTools(api.pluginConfig, registerTool);
const baseUrl = resolveBaseUrl(api.pluginConfig);
if (!baseUrl) return;
registerTool(metricHistoryTool(baseUrl));

registerTool({
name: "observability_metric_names",
Expand Down Expand Up @@ -222,6 +258,7 @@ export default definePluginEntry({
properties: {
query: { type: "string", description: "PromQL or MetricsQL instant query supported by the configured backend." },
time: { type: "string", description: "Optional RFC3339 or Unix timestamp." },
valueFormat: { type: "string", enum: ["unix_seconds"], description: "Only for query values that represent Unix timestamps, e.g. timestamp(metric): add valueIso without changing the numeric value. Omit for ordinary metrics, durations, and counts." },
maxSeries: { type: "number", description: "Maximum returned series." },
},
},
Expand All @@ -233,6 +270,7 @@ export default definePluginEntry({
promql,
stringParam(rawParams.time),
Math.trunc(boundedNumber(rawParams.maxSeries, 50, 1, 500)),
timestampValues(rawParams),
);
return jsonToolResult({ source: baseUrl, query: promql, ...result });
},
Expand All @@ -241,17 +279,18 @@ export default definePluginEntry({
registerTool({
name: "observability_range_query",
label: "Metrics Range Query",
description: "Run a historical PromQL or MetricsQL range query.",
description: "Run a historical PromQL or MetricsQL range query. Query-window boundaries are not incident onset times; trace missing data backward to a last-present/first-missing interval.",
parameters: {
type: "object",
additionalProperties: false,
required: ["query"],
properties: {
query: { type: "string", description: "PromQL or MetricsQL range query supported by the configured backend." },
rangeMinutes: { type: "number", description: "Lookback window in minutes. Default 60." },
rangeMinutes: { type: "number", description: "Lookback window in minutes. Default 60; clamped to 1–10080 (7 days). Use explicit start/end for older windows." },
stepSeconds: { type: "number", description: "Prometheus step in seconds. Default 60." },
start: { type: "string", description: "Optional explicit start time." },
end: { type: "string", description: "Optional explicit end time." },
valueFormat: { type: "string", enum: ["unix_seconds"], description: "Only for query values that represent Unix timestamps, e.g. timestamp(metric): add valueIso without changing the numeric value. Omit for ordinary metrics, durations, and counts." },
maxSeries: { type: "number", description: "Maximum returned series." },
maxPoints: { type: "number", description: "Maximum returned points per series after downsampling." },
},
Expand Down
Loading
Loading