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
173 lines (172 loc) • 6.06 kB
TypeScript
/**
* Shared loki.process stage builder for all log recipes.
* Stage order: json → regex → timestamp → labels → structured_metadata → static_labels → tenant → match → output.
*/
/**
* A match route for conditional processing by label selector.
* Logs matching `selector` pass through the nested stages; others pass through unchanged.
*/
export type MatchRoute = {
/** LogQL selector, e.g., '{hostname=~"prod.*"}' or '{level="error"}'. */
selector: string;
/** Optional pipeline name for Alloy debugging UI. */
pipelineName?: string;
/** Static tenant value — sets X-Scope-OrgID for multi-tenant Loki. */
tenantValue?: string;
/** Dynamic tenant — reads tenant ID from an extracted field. */
tenantSource?: string;
};
/**
* Declarative log processing parameters.
* All fields are optional — return null when none are set.
*/
export type LogProcessingParams = {
/**
* stage.json — Extract fields from JSON log lines.
* Keys are output field names, values are JSON paths.
* Empty string "" extracts the top-level key matching the name.
* Example: { "timestamp": "", "level": "", "request_id": "context.rid" }
*/
jsonExpressions?: Record<string, string>;
/**
* stage.regex — Extract fields via regex with named capture groups.
* Example: "^(?P<timestamp>\\S+) (?P<level>\\w+) (?P<message>.*)$"
*/
regexExpression?: string;
/**
* stage.timestamp — Parse timestamps from an extracted field.
* source: field name containing the timestamp.
* format: "RFC3339", "RFC3339Nano", "Unix", "UnixMs", or Go time layout.
*/
timestampSource?: string;
timestampFormat?: string;
/**
* stage.labels — Promote extracted fields to Loki index labels.
* Keys are label names, values are source fields (empty string = same name).
* Use sparingly — high-cardinality labels hurt Loki performance.
*/
labelFields?: Record<string, string>;
/**
* stage.structured_metadata — Store high-cardinality fields as metadata.
* Queryable via `| field="value"` but not indexed as labels.
* Preferred over labels for request IDs, user IDs, trace IDs, etc.
*/
structuredMetadata?: Record<string, string>;
/**
* stage.static_labels — Add fixed labels to all log entries.
* Example: { "environment": "production", "service_name": "my-app" }
*/
staticLabels?: Record<string, string>;
/**
* stage.tenant — Set Loki tenant ID (X-Scope-OrgID header).
* Use `tenantValue` for a static tenant, `tenantSource` for dynamic (from extracted field).
* Only one of `tenantValue` or `tenantSource` should be set at top level.
*/
tenantValue?: string;
tenantSource?: string;
/**
* stage.match — Conditional processing branches by label selector.
* Each route applies nested stages only to logs matching its selector.
* Commonly used with stage.tenant inside for multi-tenant routing.
*
* Example: Route logs to different Loki tenants by environment label:
* ```
* matchRoutes: [
* { selector: '{env="prod"}', tenantValue: "prod-tenant" },
* { selector: '{env="staging"}', tenantValue: "staging-tenant" }
* ]
* ```
*/
matchRoutes?: MatchRoute[];
/**
* stage.output — Replace log line with an extracted field's value.
* Useful when the original line is raw JSON but you want a human-readable message.
*/
outputSource?: string;
};
export type ProcessBlockResult = {
/** The complete loki.process block as Alloy config string. */
block: string;
/** Component ID for health checking: "loki.process.lens_{id}_process" */
componentId: string;
/** Receiver reference for source forward_to: "loki.process.lens_{id}_process.receiver" */
receiverRef: string;
};
/**
* Build a loki.process config block from declarative parameters.
* Returns null if no processing params are set (backwards compatible).
*
* @param forwardTo — The Alloy receiver to forward processed logs to,
* e.g., "loki.write.lens_abc_write.receiver"
*/
export declare function buildProcessBlock(pipelineId: string, params: LogProcessingParams, forwardTo: string): ProcessBlockResult | null;
/**
* Check if any processing params are set.
* Useful for recipes that need to conditionally add processing params to optionalParams.
*/
export declare function hasProcessingParams(params: Record<string, unknown>): boolean;
/**
* Extract LogProcessingParams from a raw params object.
* Picks only the processing-related fields.
*/
export declare function extractProcessingParams(params: Record<string, unknown>): LogProcessingParams;
/**
* Common optional param definitions for log processing.
* Import and spread into any log recipe's optionalParams array.
*/
export declare const PROCESSING_OPTIONAL_PARAMS: ({
name: "jsonExpressions";
type: "object";
description: string;
default?: undefined;
} | {
name: "regexExpression";
type: "string";
description: string;
default?: undefined;
} | {
name: "timestampSource";
type: "string";
description: string;
default?: undefined;
} | {
name: "timestampFormat";
type: "string";
description: string;
default: string;
} | {
name: "labelFields";
type: "object";
description: string;
default?: undefined;
} | {
name: "structuredMetadata";
type: "object";
description: string;
default?: undefined;
} | {
name: "staticLabels";
type: "object";
description: string;
default?: undefined;
} | {
name: "tenantValue";
type: "string";
description: string;
default?: undefined;
} | {
name: "tenantSource";
type: "string";
description: string;
default?: undefined;
} | {
name: "matchRoutes";
type: "object";
description: string;
default?: undefined;
} | {
name: "outputSource";
type: "string";
description: string;
default?: undefined;
})[];