elastic / elastic/docs-content

[Alerting V2] Rule artifacts (runbooks and dashboards) now use structured per-type fields, with better handling of deleted dashboards

Open
#8,065 1 comment 0 reactions 1 assignee Claimed by @nastasha-solomon View on GitHub
alerting-v2 Team:SKI
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 12h
Merged PRs (30d)
116

Description

## Summary

Rule artifacts (runbooks and linked dashboards) now use structured, per-type fields instead of a single string value:

| Before | After |
|---|---|
| `artifacts[].value: string` | `artifacts[].data: object` |

**Validation is now per artifact type:** a runbook needs non-blank `content` (up to 50,000 characters); a dashboard needs a `dashboardId`; any other field defaults to a 1,024-character cap.

**Also new:** a rule whose linked dashboard was deleted now shows a "Dashboard deleted" indicator and survives saving, instead of being silently dropped.

This is a breaking change to the YAML `artifacts[].value` field specifically — existing saved rules are migrated automatically on read, but any docs or examples using `value` are now wrong.

**Why this needs docs:** The YAML schema reference documents the exact field this PR removed, and neither existing rule-authoring page mentions dashboards as an artifact type at all.

## Resources

- PR [#281751](https://github.com/elastic/kibana/pull/281751) — [Alerting V2] Change artifacts schema
- Product issue: https://github.com/elastic/rna-program/issues/764
- Related: [#284481](https://github.com/elastic/kibana/pull/284481) — companion PR adding the inline "Attach related dashboards" UI (tracked separately)

## Availability

| Channel | Details |
|---------|---------|
| **Stack** | v9.6.0 |
| **Serverless** | Aug 12–Aug 19 |
| **Feature status** | Technical preview |
| **Feature flag** | Requires the Alerting v2 preview to be enabled |

---
*Created with [Docs Quest Scanner](https://github.com/florent-leborgne/docs-quest-scanner) by @nastasha-solomon*

## Suggested edits

### 1. [YAML rule schema reference](https://www.elastic.co/docs/explore-analyze/alerting/experimental-alerting-system/rules/yaml-rule-schema-reference) > Artifact fields — breaking change
- **What's wrong:** Documents `artifacts[].value` (string, markdown content) as the field for artifact content. That field no longer exists.
- **What to add:** Replace `artifacts[].value` with `artifacts[].data` (object), and document the per-type shape:
- `runbook`: `{ content: string }` — required, non-blank, max 50,000 characters
- `dashboard`: `{ dashboardId: string }` — required
- any other/unregistered type: unvalidated `data`, other fields default to a 1,024-character cap
Update the `type` field's example to list both `runbook` and `dashboard`. Applies from 9.6.0 (technical preview) and in serverless.

### 2. [Tags and runbooks in the experimental alerting system](https://www.elastic.co/docs/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-tags)
- **What's wrong:** This is the dedicated page for rule artifacts, but it only covers tags and runbooks — dashboards aren't mentioned as an artifact type anywhere, despite having their own UI on the rule details page.
- **What to add:** Add a "Dashboards" subsection alongside Tags and Runbooks (or retitle the page, at the writer's discretion) covering: how to link a dashboard for investigation context, and that a rule whose linked dashboard was deleted shows a "Dashboard deleted" indicator rather than losing the link silently. Applies from 9.6.0 (technical preview) and in serverless.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.