Skip to content

Commit afef8ae

Browse files
waleedlatif1claude
waleedlatif1
and
claude
committed
docs(grafana): expose alert-rule output fields in generated docs
Move ALERT_RULE_OUTPUT_FIELDS from utils.ts to types.ts and rename to SCREAMING_SNAKE_CASE so scripts/generate-docs.ts (which only resolves const references from types.ts matching [A-Z][A-Z_0-9]+) can inline the per-field rows into the generated alert-rule output tables. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent e997595 commit afef8ae

7 files changed

Lines changed: 131 additions & 134 deletions

File tree

‎apps/docs/content/docs/en/tools/grafana.mdx‎

Lines changed: 69 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,26 @@ List all alert rules in the Grafana instance
190190
| Parameter | Type | Description |
191191
| --------- | ---- | ----------- |
192192
| `rules` | array | List of alert rules |
193+
| ↳ `id` | number | Alert rule numeric ID |
194+
| ↳ `uid` | string | Alert rule UID |
195+
| ↳ `title` | string | Alert rule title |
196+
| ↳ `condition` | string | RefId of the query used as the alert condition |
197+
| ↳ `data` | json | Alert rule query/expression data array |
198+
| ↳ `updated` | string | Last update timestamp |
199+
| ↳ `noDataState` | string | State when no data is returned |
200+
| ↳ `execErrState` | string | State on execution error |
201+
| ↳ `for` | string | Duration the condition must hold before firing |
202+
| ↳ `keepFiringFor` | string | Duration to keep firing after condition stops |
203+
| ↳ `missingSeriesEvalsToResolve` | number | Number of missing series evaluations before resolving |
204+
| ↳ `annotations` | json | Alert annotations |
205+
| ↳ `labels` | json | Alert labels |
206+
| ↳ `isPaused` | boolean | Whether the rule is paused |
207+
| ↳ `folderUID` | string | Parent folder UID |
208+
| ↳ `ruleGroup` | string | Rule group name |
209+
| ↳ `orgID` | number | Organization ID |
210+
| ↳ `provenance` | string | Provisioning source \(empty if API-managed\) |
211+
| ↳ `notification_settings` | json | Per-rule notification settings \(overrides\) |
212+
| ↳ `record` | json | Recording rule configuration \(recording rules only\) |
193213

194214
### `grafana_get_alert_rule`
195215

@@ -208,35 +228,26 @@ Get a specific alert rule by its UID
208228

209229
| Parameter | Type | Description |
210230
| --------- | ---- | ----------- |
211-
| `version` | string | Grafana version |
212-
| `database` | string | Database health status |
213-
| `status` | string | Health status |
214-
| `dashboard` | json | Dashboard JSON |
215-
| `meta` | json | Dashboard metadata |
216-
| `dashboards` | json | List of dashboards |
217-
| `uid` | string | Created/updated UID |
218-
| `url` | string | Dashboard URL |
219-
| `rules` | json | Alert rules list |
220-
| `contactPoints` | json | Contact points list |
221-
| `condition` | string | Alert condition refId |
231+
| `id` | number | Alert rule numeric ID |
232+
| `uid` | string | Alert rule UID |
233+
| `title` | string | Alert rule title |
234+
| `condition` | string | RefId of the query used as the alert condition |
235+
| `data` | json | Alert rule query/expression data array |
236+
| `updated` | string | Last update timestamp |
237+
| `noDataState` | string | State when no data is returned |
238+
| `execErrState` | string | State on execution error |
222239
| `for` | string | Duration the condition must hold before firing |
223-
| `keepFiringFor` | string | Duration to keep firing after the condition stops |
224-
| `missingSeriesEvalsToResolve` | number | Missing series evaluations before resolving |
225-
| `isPaused` | boolean | Whether the alert rule is paused |
240+
| `keepFiringFor` | string | Duration to keep firing after condition stops |
241+
| `missingSeriesEvalsToResolve` | number | Number of missing series evaluations before resolving |
242+
| `annotations` | json | Alert annotations |
243+
| `labels` | json | Alert labels |
244+
| `isPaused` | boolean | Whether the rule is paused |
226245
| `folderUID` | string | Parent folder UID |
227246
| `ruleGroup` | string | Rule group name |
228247
| `orgID` | number | Organization ID |
229-
| `provenance` | string | Provisioning source |
230-
| `noDataState` | string | State on no data |
231-
| `execErrState` | string | State on execution error |
232-
| `notification_settings` | json | Per-rule notification settings |
233-
| `record` | json | Recording rule configuration |
234-
| `updated` | string | Last update timestamp |
235-
| `annotations` | json | Annotations list |
236-
| `id` | number | Annotation ID |
237-
| `dataSources` | json | Data sources list |
238-
| `folders` | json | Folders list |
239-
| `message` | string | Status message |
248+
| `provenance` | string | Provisioning source \(empty if API-managed\) |
249+
| `notification_settings` | json | Per-rule notification settings \(overrides\) |
250+
| `record` | json | Recording rule configuration \(recording rules only\) |
240251

241252
### `grafana_create_alert_rule`
242253

@@ -271,35 +282,26 @@ Create a new alert rule
271282

272283
| Parameter | Type | Description |
273284
| --------- | ---- | ----------- |
274-
| `version` | string | Grafana version |
275-
| `database` | string | Database health status |
276-
| `status` | string | Health status |
277-
| `dashboard` | json | Dashboard JSON |
278-
| `meta` | json | Dashboard metadata |
279-
| `dashboards` | json | List of dashboards |
280-
| `uid` | string | Created/updated UID |
281-
| `url` | string | Dashboard URL |
282-
| `rules` | json | Alert rules list |
283-
| `contactPoints` | json | Contact points list |
284-
| `condition` | string | Alert condition refId |
285+
| `id` | number | Alert rule numeric ID |
286+
| `uid` | string | Alert rule UID |
287+
| `title` | string | Alert rule title |
288+
| `condition` | string | RefId of the query used as the alert condition |
289+
| `data` | json | Alert rule query/expression data array |
290+
| `updated` | string | Last update timestamp |
291+
| `noDataState` | string | State when no data is returned |
292+
| `execErrState` | string | State on execution error |
285293
| `for` | string | Duration the condition must hold before firing |
286-
| `keepFiringFor` | string | Duration to keep firing after the condition stops |
287-
| `missingSeriesEvalsToResolve` | number | Missing series evaluations before resolving |
288-
| `isPaused` | boolean | Whether the alert rule is paused |
294+
| `keepFiringFor` | string | Duration to keep firing after condition stops |
295+
| `missingSeriesEvalsToResolve` | number | Number of missing series evaluations before resolving |
296+
| `annotations` | json | Alert annotations |
297+
| `labels` | json | Alert labels |
298+
| `isPaused` | boolean | Whether the rule is paused |
289299
| `folderUID` | string | Parent folder UID |
290300
| `ruleGroup` | string | Rule group name |
291301
| `orgID` | number | Organization ID |
292-
| `provenance` | string | Provisioning source |
293-
| `noDataState` | string | State on no data |
294-
| `execErrState` | string | State on execution error |
295-
| `notification_settings` | json | Per-rule notification settings |
296-
| `record` | json | Recording rule configuration |
297-
| `updated` | string | Last update timestamp |
298-
| `annotations` | json | Annotations list |
299-
| `id` | number | Annotation ID |
300-
| `dataSources` | json | Data sources list |
301-
| `folders` | json | Folders list |
302-
| `message` | string | Status message |
302+
| `provenance` | string | Provisioning source \(empty if API-managed\) |
303+
| `notification_settings` | json | Per-rule notification settings \(overrides\) |
304+
| `record` | json | Recording rule configuration \(recording rules only\) |
303305

304306
### `grafana_update_alert_rule`
305307

@@ -320,7 +322,7 @@ Update an existing alert rule. Fetches the current rule and merges your changes.
320322
| `data` | string | No | New JSON array of query/expression data objects |
321323
| `forDuration` | string | No | Duration to wait before firing \(e.g., 5m, 1h\) |
322324
| `noDataState` | string | No | State when no data is returned \(NoData, Alerting, OK\) |
323-
| `execErrState` | string | No | State on execution error \(Alerting, OK\) |
325+
| `execErrState` | string | No | State on execution error \(Error, Alerting, OK\) |
324326
| `annotations` | string | No | JSON object of annotations |
325327
| `labels` | string | No | JSON object of labels |
326328
| `isPaused` | boolean | No | Whether the rule is paused |
@@ -334,35 +336,26 @@ Update an existing alert rule. Fetches the current rule and merges your changes.
334336

335337
| Parameter | Type | Description |
336338
| --------- | ---- | ----------- |
337-
| `version` | string | Grafana version |
338-
| `database` | string | Database health status |
339-
| `status` | string | Health status |
340-
| `dashboard` | json | Dashboard JSON |
341-
| `meta` | json | Dashboard metadata |
342-
| `dashboards` | json | List of dashboards |
343-
| `uid` | string | Created/updated UID |
344-
| `url` | string | Dashboard URL |
345-
| `rules` | json | Alert rules list |
346-
| `contactPoints` | json | Contact points list |
347-
| `condition` | string | Alert condition refId |
339+
| `id` | number | Alert rule numeric ID |
340+
| `uid` | string | Alert rule UID |
341+
| `title` | string | Alert rule title |
342+
| `condition` | string | RefId of the query used as the alert condition |
343+
| `data` | json | Alert rule query/expression data array |
344+
| `updated` | string | Last update timestamp |
345+
| `noDataState` | string | State when no data is returned |
346+
| `execErrState` | string | State on execution error |
348347
| `for` | string | Duration the condition must hold before firing |
349-
| `keepFiringFor` | string | Duration to keep firing after the condition stops |
350-
| `missingSeriesEvalsToResolve` | number | Missing series evaluations before resolving |
351-
| `isPaused` | boolean | Whether the alert rule is paused |
348+
| `keepFiringFor` | string | Duration to keep firing after condition stops |
349+
| `missingSeriesEvalsToResolve` | number | Number of missing series evaluations before resolving |
350+
| `annotations` | json | Alert annotations |
351+
| `labels` | json | Alert labels |
352+
| `isPaused` | boolean | Whether the rule is paused |
352353
| `folderUID` | string | Parent folder UID |
353354
| `ruleGroup` | string | Rule group name |
354355
| `orgID` | number | Organization ID |
355-
| `provenance` | string | Provisioning source |
356-
| `noDataState` | string | State on no data |
357-
| `execErrState` | string | State on execution error |
358-
| `notification_settings` | json | Per-rule notification settings |
359-
| `record` | json | Recording rule configuration |
360-
| `updated` | string | Last update timestamp |
361-
| `annotations` | json | Annotations list |
362-
| `id` | number | Annotation ID |
363-
| `dataSources` | json | Data sources list |
364-
| `folders` | json | Folders list |
365-
| `message` | string | Status message |
356+
| `provenance` | string | Provisioning source \(empty if API-managed\) |
357+
| `notification_settings` | json | Per-rule notification settings \(overrides\) |
358+
| `record` | json | Recording rule configuration \(recording rules only\) |
366359

367360
### `grafana_delete_alert_rule`
368361

‎apps/sim/tools/grafana/create_alert_rule.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@ import type {
22
GrafanaCreateAlertRuleParams,
33
GrafanaCreateAlertRuleResponse,
44
} from '@/tools/grafana/types'
5-
import { alertRuleOutputFields, mapAlertRule } from '@/tools/grafana/utils'
5+
import { ALERT_RULE_OUTPUT_FIELDS } from '@/tools/grafana/types'
6+
import { mapAlertRule } from '@/tools/grafana/utils'
67
import type { ToolConfig } from '@/tools/types'
78

89
export const createAlertRuleTool: ToolConfig<
@@ -222,5 +223,5 @@ export const createAlertRuleTool: ToolConfig<
222223
return { success: true, output: mapAlertRule(data) }
223224
},
224225

225-
outputs: alertRuleOutputFields,
226+
outputs: ALERT_RULE_OUTPUT_FIELDS,
226227
}

‎apps/sim/tools/grafana/get_alert_rule.ts‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
1-
import type { GrafanaGetAlertRuleParams, GrafanaGetAlertRuleResponse } from '@/tools/grafana/types'
2-
import { alertRuleOutputFields, mapAlertRule } from '@/tools/grafana/utils'
1+
import {
2+
ALERT_RULE_OUTPUT_FIELDS,
3+
type GrafanaGetAlertRuleParams,
4+
type GrafanaGetAlertRuleResponse,
5+
} from '@/tools/grafana/types'
6+
import { mapAlertRule } from '@/tools/grafana/utils'
37
import type { ToolConfig } from '@/tools/types'
48

59
export const getAlertRuleTool: ToolConfig<GrafanaGetAlertRuleParams, GrafanaGetAlertRuleResponse> =
@@ -57,5 +61,5 @@ export const getAlertRuleTool: ToolConfig<GrafanaGetAlertRuleParams, GrafanaGetA
5761
return { success: true, output: mapAlertRule(data) }
5862
},
5963

60-
outputs: alertRuleOutputFields,
64+
outputs: ALERT_RULE_OUTPUT_FIELDS,
6165
}

‎apps/sim/tools/grafana/list_alert_rules.ts‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
import type {
2-
GrafanaListAlertRulesParams,
3-
GrafanaListAlertRulesResponse,
1+
import {
2+
ALERT_RULE_OUTPUT_FIELDS,
3+
type GrafanaListAlertRulesParams,
4+
type GrafanaListAlertRulesResponse,
45
} from '@/tools/grafana/types'
5-
import { alertRuleOutputFields, mapAlertRule } from '@/tools/grafana/utils'
6+
import { mapAlertRule } from '@/tools/grafana/utils'
67
import type { ToolConfig } from '@/tools/types'
78

89
export const listAlertRulesTool: ToolConfig<
@@ -69,7 +70,7 @@ export const listAlertRulesTool: ToolConfig<
6970
description: 'List of alert rules',
7071
items: {
7172
type: 'object',
72-
properties: alertRuleOutputFields,
73+
properties: ALERT_RULE_OUTPUT_FIELDS,
7374
},
7475
},
7576
},

‎apps/sim/tools/grafana/types.ts‎

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,47 @@
11
// Common types for Grafana API tools
2-
import type { ToolResponse } from '@/tools/types'
2+
import type { OutputProperty, ToolResponse } from '@/tools/types'
3+
4+
/**
5+
* Canonical output schema fields shared across alert rule tools.
6+
*/
7+
export const ALERT_RULE_OUTPUT_FIELDS: Record<string, OutputProperty> = {
8+
id: { type: 'number', description: 'Alert rule numeric ID', optional: true },
9+
uid: { type: 'string', description: 'Alert rule UID' },
10+
title: { type: 'string', description: 'Alert rule title' },
11+
condition: { type: 'string', description: 'RefId of the query used as the alert condition' },
12+
data: { type: 'json', description: 'Alert rule query/expression data array' },
13+
updated: { type: 'string', description: 'Last update timestamp', optional: true },
14+
noDataState: { type: 'string', description: 'State when no data is returned' },
15+
execErrState: { type: 'string', description: 'State on execution error' },
16+
for: { type: 'string', description: 'Duration the condition must hold before firing' },
17+
keepFiringFor: {
18+
type: 'string',
19+
description: 'Duration to keep firing after condition stops',
20+
optional: true,
21+
},
22+
missingSeriesEvalsToResolve: {
23+
type: 'number',
24+
description: 'Number of missing series evaluations before resolving',
25+
optional: true,
26+
},
27+
annotations: { type: 'json', description: 'Alert annotations' },
28+
labels: { type: 'json', description: 'Alert labels' },
29+
isPaused: { type: 'boolean', description: 'Whether the rule is paused' },
30+
folderUID: { type: 'string', description: 'Parent folder UID' },
31+
ruleGroup: { type: 'string', description: 'Rule group name' },
32+
orgID: { type: 'number', description: 'Organization ID' },
33+
provenance: { type: 'string', description: 'Provisioning source (empty if API-managed)' },
34+
notification_settings: {
35+
type: 'json',
36+
description: 'Per-rule notification settings (overrides)',
37+
optional: true,
38+
},
39+
record: {
40+
type: 'json',
41+
description: 'Recording rule configuration (recording rules only)',
42+
optional: true,
43+
},
44+
}
345

446
// Common parameters for all Grafana tools
547
interface GrafanaBaseParams {

‎apps/sim/tools/grafana/update_alert_rule.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import type { GrafanaUpdateAlertRuleParams } from '@/tools/grafana/types'
2-
import { alertRuleOutputFields, mapAlertRule } from '@/tools/grafana/utils'
1+
import { ALERT_RULE_OUTPUT_FIELDS, type GrafanaUpdateAlertRuleParams } from '@/tools/grafana/types'
2+
import { mapAlertRule } from '@/tools/grafana/utils'
33
import type { ToolConfig, ToolResponse } from '@/tools/types'
44

55
// Using ToolResponse for intermediate state since this tool fetches existing data first
@@ -291,5 +291,5 @@ export const updateAlertRuleTool: ToolConfig<GrafanaUpdateAlertRuleParams, ToolR
291291
return { success: true, output: mapAlertRule(data) }
292292
},
293293

294-
outputs: alertRuleOutputFields,
294+
outputs: ALERT_RULE_OUTPUT_FIELDS,
295295
}

‎apps/sim/tools/grafana/utils.ts‎

Lines changed: 0 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
import type { OutputProperty } from '@/tools/types'
2-
31
/**
42
* Map a raw Grafana ProvisionedAlertRule JSON object to the canonical output shape
53
* shared across list/get/create/update alert rule tools.
@@ -31,45 +29,3 @@ export function mapAlertRule(rule: Record<string, unknown>) {
3129
record: (rule.record as Record<string, unknown>) ?? null,
3230
}
3331
}
34-
35-
/**
36-
* Canonical output schema fields shared across alert rule tools.
37-
*/
38-
export const alertRuleOutputFields: Record<string, OutputProperty> = {
39-
id: { type: 'number', description: 'Alert rule numeric ID', optional: true },
40-
uid: { type: 'string', description: 'Alert rule UID' },
41-
title: { type: 'string', description: 'Alert rule title' },
42-
condition: { type: 'string', description: 'RefId of the query used as the alert condition' },
43-
data: { type: 'json', description: 'Alert rule query/expression data array' },
44-
updated: { type: 'string', description: 'Last update timestamp', optional: true },
45-
noDataState: { type: 'string', description: 'State when no data is returned' },
46-
execErrState: { type: 'string', description: 'State on execution error' },
47-
for: { type: 'string', description: 'Duration the condition must hold before firing' },
48-
keepFiringFor: {
49-
type: 'string',
50-
description: 'Duration to keep firing after condition stops',
51-
optional: true,
52-
},
53-
missingSeriesEvalsToResolve: {
54-
type: 'number',
55-
description: 'Number of missing series evaluations before resolving',
56-
optional: true,
57-
},
58-
annotations: { type: 'json', description: 'Alert annotations' },
59-
labels: { type: 'json', description: 'Alert labels' },
60-
isPaused: { type: 'boolean', description: 'Whether the rule is paused' },
61-
folderUID: { type: 'string', description: 'Parent folder UID' },
62-
ruleGroup: { type: 'string', description: 'Rule group name' },
63-
orgID: { type: 'number', description: 'Organization ID' },
64-
provenance: { type: 'string', description: 'Provisioning source (empty if API-managed)' },
65-
notification_settings: {
66-
type: 'json',
67-
description: 'Per-rule notification settings (overrides)',
68-
optional: true,
69-
},
70-
record: {
71-
type: 'json',
72-
description: 'Recording rule configuration (recording rules only)',
73-
optional: true,
74-
},
75-
}

0 commit comments

Comments
 (0)