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
110 lines (109 loc) • 5.18 kB
TypeScript
/**
* SDK compatibility layer — vendored utilities + resilient import resolution.
*
* Pure utility functions (jsonResult, readStringParam, readNumberParam) were
* removed from the root `openclaw/plugin-sdk` in OpenClaw 2026.3.16
* (commit f2bd76cd1a "finalize plugin sdk legacy boundary cleanup").
* These are vendored locally (ponyfill pattern) — zero SDK dependency.
*
* SDK hooks (onDiagnosticEvent, registerLogTransport) can't be vendored since
* they connect to openclaw's internal event bus. These are resolved via dynamic
* import fallback chains — tries new subpaths first, falls back to root.
*
* All SDK coupling lives in this one file. Future breakage = one-file fix.
*/
type StringParamOptions = {
required?: boolean;
trim?: boolean;
label?: string;
allowEmpty?: boolean;
};
export declare function readStringParam(params: Record<string, unknown>, key: string, options: StringParamOptions & {
required: true;
}): string;
export declare function readStringParam(params: Record<string, unknown>, key: string, options?: StringParamOptions): string | undefined;
export declare function readNumberParam(params: Record<string, unknown>, key: string, options?: {
required?: boolean;
label?: string;
integer?: boolean;
strict?: boolean;
}): number | undefined;
export declare function jsonResult(payload: unknown): {
content: Array<{
type: "text";
text: string;
}>;
details: unknown;
};
export declare function getErrorMessage(err: unknown): string;
/**
* Resolve or create a process-wide singleton keyed by a symbol on globalThis.
*
* Mirrors `resolveGlobalSingleton` from `openclaw/plugin-sdk/global-singleton`
* (the canonical SDK helper). We vendor it because openclaw 2026.4.25 declares
* the subpath in `package.json` exports but doesn't ship `dist/.../global-singleton.js`,
* so a direct import would crash at runtime. When upstream fixes the packaging,
* this helper can be swapped for `import { resolveGlobalSingleton } from "openclaw/plugin-sdk/global-singleton"`.
*/
export declare function resolveGlobalSingleton<T>(key: symbol, create: () => T): T;
/**
* Test-only: drop a singleton entry created by `resolveGlobalSingleton`.
* Production code must not call this — it bypasses the re-register protection
* the singleton exists to provide.
*/
export declare function clearGlobalSingletonForTests(key: symbol): void;
export type DiagnosticHooks = {
onDiagnosticEvent: ((listener: (evt: unknown) => void) => () => void) | null;
/**
* Unfiltered diagnostic-event subscription. The public `onDiagnosticEvent`
* filters events whose dispatch metadata is `trusted` (and `log.record`).
* Starting openclaw 2026.5.7 the `model.usage` event is emitted via
* `emitTrustedDiagnosticEvent` — so every metric grafana-lens derives from
* `model.usage` (tokens, context, cost, cache ratios, etc.) goes silent on
* 2026.5.7+ unless we subscribe via this unfiltered hook.
*
* Reached via the `openclaw/plugin-sdk/diagnostic-runtime` subpath. The
* naming `onInternal*` signals "internal-by-name but kept exported": same
* shape openclaw uses for its own privileged consumers. Treat as semver-
* minor-fragile — `contracts.test.ts` is the canary that fires the day it
* is renamed or removed.
*/
onInternalDiagnosticEvent: ((listener: (event: unknown, metadata: {
trusted?: boolean;
}) => void) => () => void) | null;
/**
* App-log forwarding hook. Permanently removed from openclaw's public SDK
* at v2026.5.5+ (openclaw's own logger-transport.test asserts it's undefined
* on every plugin-sdk export site). Will be `null` on 2026.5.5+; callers
* must degrade gracefully — that's the documented new normal, not a compat
* regression.
*/
registerLogTransport: ((transport: (logObj: unknown) => void) => () => void) | null;
};
/**
* Minimal logger shape (matches `OpenClawPluginServiceContext.logger` without
* requiring the SDK type import). Pass `ctx.logger` from a plugin service start.
*/
export type SdkResolverLogger = {
warn?: (msg: string) => void;
debug?: (msg: string) => void;
};
/**
* Resolve SDK diagnostic hooks from whichever subpath is available.
*
* Order matters:
* 1. `plugin-sdk/diagnostic-runtime` — canonical scoped subpath (openclaw >= 2026.5.0).
* Explicit migration target named in `plugin-sdk/compat`'s deprecation warning.
* Present in every 2026.5.x release.
* 2. `plugin-sdk` root — re-exports `onDiagnosticEvent` for older openclaw versions.
* May or may not work on 2026.5.5+ depending on dist bundling.
*
* Failures emit `logger.warn` with the import path + Node error code (e.g.
* `ERR_MODULE_NOT_FOUND`) so operators see the actionable reason in the
* gateway log, not a generic "not available" line.
*
* The `GRAFANA_LENS_DEBUG_SDK=1` env var continues to mirror failures to
* `console.warn` for environments where no logger is wired (tests, scripts).
*/
export declare function resolveDiagnosticHooks(logger?: SdkResolverLogger): Promise<DiagnosticHooks>;
export {};