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
114 lines (113 loc) • 4.82 kB
TypeScript
/**
* Pipeline Recipe Types
*
* A recipe is a parameterized pipeline template that the agent matches
* to user intent. Each recipe knows how to:
* 1. Validate its required parameters
* 2. Generate a complete, self-contained .alloy config
* 3. Provide sample queries for the data it produces
* 4. Map to an appropriate Grafana dashboard template
*
* The recipe system is the abstraction layer between the LLM (which
* understands "monitor my Postgres") and Alloy (which needs specific
* component configuration). The agent never needs to know 188+ Alloy
* component types — it matches intent to ~18 recipe names.
*/
import type { ExportTargets } from "../types.js";
export type ParamType = "string" | "number" | "boolean" | "string[]" | "object";
export type ParamDef = {
/** Parameter name (e.g., "url", "connectionString"). */
name: string;
/** Parameter type. */
type: ParamType;
/** Human-readable description for the agent + user. */
description: string;
/** Default value — if present, parameter is optional. */
default?: unknown;
/** Whether this param contains a secret (password, token, connection string). */
sensitive?: boolean;
/** Example value for the agent to show the user. */
example?: string;
};
/**
* Parameters after validation — required params guaranteed present,
* optional params filled with defaults.
*/
export type ResolvedParams = Record<string, unknown>;
/**
* Enriched result from resolveParams() — includes the resolved params
* plus any warnings about unknown/mismatched parameter names.
* Warnings are advisory (params still resolve correctly) and flow
* through tool responses so the agent can relay them.
*/
export type ResolveResult = {
params: ResolvedParams;
warnings: string[];
};
/**
* Describes an environment variable the user must set for this pipeline.
* Generated when a recipe has sensitive parameters.
*/
export type CredentialRef = {
/** Env var name (e.g., "ALLOY_POSTGRES_ANALYTICS_DB_DSN"). */
envVar: string;
/** Description of what this credential is for. */
description: string;
/** Example value. */
example?: string;
};
export interface PipelineRecipe {
/** Recipe identifier (e.g., "scrape-endpoint", "postgres-exporter"). */
name: string;
/** Category for filtering. */
category: "metrics" | "logs" | "traces" | "infrastructure" | "profiling";
/** Signal type this pipeline produces. */
signal: "metrics" | "logs" | "traces" | "profiles";
/** One-line summary for the agent to match user intent. */
summary: string;
/** Required parameters — must be provided by the user. */
requiredParams: ParamDef[];
/** Optional parameters — have defaults, can be overridden. */
optionalParams: ParamDef[];
/** Parameter names that contain secrets (routed to sys.env()). */
credentialParams: string[];
/**
* Generate a complete .alloy config from resolved parameters.
* The config must be self-contained — no cross-file references.
*/
generateConfig(pipelineId: string, params: ResolvedParams, targets: ExportTargets, pipelineName: string): string;
/**
* Generate sample queries for the data this pipeline produces.
* Keys are descriptive names, values are PromQL/LogQL/TraceQL.
*/
sampleQueries(params: ResolvedParams, jobName: string): Record<string, string>;
/**
* Return Alloy component IDs that will be created by this pipeline.
* Used for health checking after deployment.
*/
componentIds(pipelineId: string): string[];
/** Suggested grafana_create_dashboard template, or null. */
dashboardTemplate: string | null;
/**
* Return ports this pipeline will bind to (for conflict detection).
* Only implement on recipes that create listener components
* (OTLP receivers, push APIs, syslog listeners, etc.).
* Returns empty array by default — override in listener recipes.
*/
boundPorts?(params: ResolvedParams): number[];
}
/**
* Validate and resolve recipe parameters.
* Returns resolved params with defaults applied and warnings about
* unrecognized parameter names. Throws on missing required params.
*/
export declare function resolveParams(recipe: PipelineRecipe, rawParams: Record<string, unknown> | undefined): ResolveResult;
/**
* Generate env var name for a credential parameter.
* Convention: ALLOY_{RECIPE_TYPE}_{PIPELINE_NAME}_{PARAM}
*/
export declare function credentialEnvVar(recipeName: string, pipelineName: string, paramName: string): string;
/**
* Generate credential references for a recipe's sensitive parameters.
*/
export declare function generateCredentialRefs(recipe: PipelineRecipe, pipelineName: string, params: ResolvedParams): CredentialRef[];