openclaw-grafana-lens
Version:
OpenClaw plugin that gives AI agents full Grafana access — 18 composable tools for PromQL/LogQL/TraceQL queries, dashboard creation, alerting, SRE investigation, security monitoring, data collection pipeline management via Grafana Alloy (29 recipes), and
78 lines (77 loc) • 2.82 kB
TypeScript
/**
* grafana_explain_metric tool
*
* Gathers structured data about a metric — current value, trend over a period,
* min/max/avg statistics, and metadata (type/help/unit). The agent uses this
* enriched context to explain what a metric means and why it changed.
*
* Counter-aware: auto-detects counter metrics (via metadata or _total suffix)
* and wraps the trend query in rate() so the agent sees actual rate of change
* instead of raw monotonically-increasing cumulative values.
*/
import type { GrafanaClientRegistry } from "../grafana-client-registry.js";
/**
* Resolve meaningful label names for breaking down a metric.
* Uses static knowledge for well-known metrics (works even with no data);
* falls back to dynamically-discovered labels from query results.
*
* Suffix-tolerant: tries the exact name first, then strips Prometheus
* suffixes (_total, _bucket, _count, _sum) to match the base definition.
* This handles the OTel→Prometheus naming gap — agents may pass either form.
*/
export declare function resolveBreakdowns(metricName: string, dynamicLabels: string[]): string[];
/**
* Extract unique semantic label names from instant query results.
* Excludes infrastructure labels (__name__, job, instance, etc.)
* that don't provide useful drill-down dimensions.
*/
export declare function extractLabelNames(results: Array<{
metric: Record<string, string>;
}>): string[];
type SuggestedQuery = {
query: string;
description: string;
};
/**
* Generate suggested drill-down queries based on discovered labels and metric type.
* Counter metrics get rate() wrapping; gauges/unknown use raw expressions.
* Returns empty array when no labels are available.
*/
export declare function buildSuggestedQueries(expr: string, labels: string[], metricType: string | undefined): SuggestedQuery[];
export declare function createExplainMetricToolFactory(registry: GrafanaClientRegistry): (_ctx: unknown) => {
name: string;
label: string;
description: string;
parameters: {
type: "object";
properties: {
datasourceUid: {
type: string;
description: string;
};
expr: {
type: string;
description: string;
};
period: {
type: string;
enum: string[];
description: string;
};
compareWith: {
type: string;
enum: string[];
description: string;
};
};
required: string[];
};
execute(_toolCallId: string, params: Record<string, unknown>): Promise<{
content: Array<{
type: "text";
text: string;
}>;
details: unknown;
}>;
};
export {};