---
title: "Custom amend alert mapping | Grafana Cloud documentation"
description: "Track configuration and version changes using amend alerts in the knowledge graph."
---

# Custom amend alert mapping

Amend alerts record when configuration, version, or metadata changes occur in your environment. These alerts don’t represent failures; instead, they provide context for understanding how systems evolve.

## When to create an amend alert

Use an amend alert for:

- Application version changes
- Deployment scaling events
- Node replacement or lifecycle transitions
- Feature flag toggles
- Configuration drift that is not yet a failure
- Rolling upgrades or rollbacks

Amend alerts help correlate what changed with what broke.

## Required labels

Expand table

| Label                          | Purpose                                              |
|--------------------------------|------------------------------------------------------|
| `asserts_alert_category=amend` | Marks the event as a configuration change            |
| `asserts_entity_type`          | Identifies the changed entity                        |
| `asserts_severity`             | Indicates the impact level. Typically `info`.        |
| `asserts_source`               | Identifies the subsystem where the change originated |
| `asserts_version_type`         | Describes the type of configuration change           |

Recommended:

Expand table

| Label          | Purpose                                                |
|----------------|--------------------------------------------------------|
| `asserts_env`  | Enables accurate entity resolution across environments |
| `asserts_site` | Identifies region or cluster alignment                 |

## Best practices to write failure alerts

Use the following best practices to help you write amend failure alerts.

### Detect label/value transitions using `changes()`

promql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```promql
changes(label_replace(myapp_build_info, "version", "$1", "app_version", "(.+)")[10m]) > 0
```

### Use normalized recording rules for version tracking

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
record: asserts:version:info
expr: |
  group by (job, service, asserts_env, asserts_site, asserts_source, version) (
    label_replace(build_info, "version", "$1", "app_version", "(.+)")
  )
labels:
  asserts_source: myapp
  asserts_version_type: service
```

### Avoid using `for:`

Change events represent discrete transitions, so a waiting period isn’t needed.

### Example: Version change

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
alert: MyAppVersionChanged
expr: |
  changes(label_replace(myapp_build_info, "version", "$1", "version_label", "(.+)")[10m]) > 0
labels:
  asserts_alert_category: amend
  asserts_entity_type: Service
  asserts_severity: info
  asserts_source: myapp
  asserts_version_type: service
annotations:
  summary: 'MyApp version changed'
  description: 'Detected a version update or rollback.'
```

### Example: Scaling event

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
alert: DeploymentReplicaCountChanged
expr: |
  kube_deployment_spec_replicas{deployment="checkout"} 
    != kube_deployment_status_replicas{deployment="checkout"}
labels:
  asserts_alert_category: amend
  asserts_entity_type: Deployment
  asserts_severity: info
  asserts_source: kubernetes
  asserts_version_type: deployment_scale
annotations:
  summary: 'Replica count changed'
  description: 'Replica count for the checkout deployment was updated.'
```

### How amend alerts appear in the knowledge graph

Amends:

- Display as blue bars along an entity’s RCA workbench timeline
- Provide critical context when analyzing failures or performance regressions
- Don’t impact entity health scoring
- Are recorded as a historical timeline of configuration evolution

Amends and failures are often reviewed together. Amends explain what changed; failures explain what went wrong.

## Next steps

- To learn how to create alerts, refer to [Configure alert rules](/docs/grafana/latest/alerting/alerting-rules/)
- To learn how to import a YAML file for alert creation, refer to [Import to Grafana-managed rules](/docs/grafana/latest/alerting/alerting-rules/alerting-migration/)