Alert Annotations

Every Kloudfuse alert rule carries a set of annotations: free-form key-value pairs attached to the rule. Kloudfuse uses some of these annotations to record how the alert was built, so that it can rebuild the query builder, draw the right visualization, and render the alert detail page correctly. You can add your own annotations alongside them to carry context such as an owning team, a ticket reference, or an escalation note.

This page lists the annotation names that Kloudfuse reserves, explains what each one carries, and describes how to add your own annotations safely.

Annotations Compared to Labels

Alert rules carry two separate key-value collections. They are not interchangeable.

Annotations

Descriptive metadata about the alert. Annotations do not affect routing or grouping. Kloudfuse stores its own rendering metadata here, and your custom annotations appear in the Annotations section of the alert detail page.

Labels

Identifying metadata that participates in routing, grouping, and silencing. Kloudfuse stores custom labels here, and also records the contact points selected for the alert as labels.

Contact points and custom labels are stored as labels, not as annotations. Do not attempt to change an alert’s notification target by editing its annotations.

Adding Custom Annotations

Add your own annotations while creating or editing any alert.

  1. Open the alert for creation or editing, and scroll to the alert details section.

  2. In the Custom annotations field, enter an annotation name and its value.

  3. Add as many key-value pairs as you need.

  4. Save the alert.

Custom annotations appear in the Annotations section of the alert detail page. Kloudfuse renders any value that contains a URL as a clickable link, which makes annotations a convenient place to store links to runbooks, dashboards, or tickets.

For a runbook link, prefer the dedicated Runbook URL field in the alert details form over a custom annotation. Kloudfuse stores it as runbook_url and surfaces it consistently across the alert views.

Reserved Annotation Names

Kloudfuse reserves the annotation names listed in this section. When you enter one of them in the Custom annotations field, Kloudfuse rejects the entry with the message Annotation key <name> is reserved. Please use a different key.

Do not reuse a reserved annotation name for your own metadata, and do not edit the value of a reserved annotation directly in Grafana. Kloudfuse parses these values when it renders an alert. A reserved annotation that holds an unexpected value can cause the alert detail page to fail to load, or cause the query builder to open with the wrong query when you edit the alert.

If you need to attach your own metadata, choose a name that does not appear in the tables on this page. Prefixing your annotation names, for example team_owner rather than summary, avoids collisions with names Kloudfuse may reserve in future releases.

Descriptive Annotations

These annotations hold text you supply when you create the alert. They are the annotations most likely to appear in a notification template.

Name Description Example

summary

Short title of the alert. This is distinct from the rule name and the rule ID.

Checkout latency above SLO

description

Longer description of what the alert detects and why it matters.

p99 latency for the checkout service exceeded 2s

runbook_url

Link to the runbook for responders. Kloudfuse renders it as a clickable link.

https://runbooks.example.com/checkout

Classification Annotations

Kloudfuse reads these two annotations to decide which detail view, parameter panel, and chart to render for an alert. They are set automatically from the alert type you choose in the UI.

Name Description Values

ruleType

Signal the alert is built on.

apm, logs, metrics, slo, rum, traces, events

alertType

Detection method the alert uses.

threshold, change, outliers, forecast, anomaly, slo

Internal State Annotations

Kloudfuse writes these annotations to preserve state that the underlying Grafana alert rule model cannot hold. Treat their values as opaque.

Name Description

extraData

JSON blob holding the complete query builder state for the alert, including queries, formulas, and filters. Kloudfuse replays this blob to reopen the query builder when you edit the alert. Without it, an alert can only be edited as a raw query.

forWindow

Pending period configured for the alert, preserved so that the UI can restore it. This matters in particular when the underlying Grafana for duration is 0.

kfuseAlertVersion

Version of the Kloudfuse alert schema that created or last saved the rule. Kloudfuse uses it to apply the correct backward-compatibility handling, such as query unescaping for older log alerts.

Kloudfuse Source

Records the part of the product that created the alert, for example an alert created from an APM view.

created

ISO-8601 timestamp recorded when the rule was created.

defaultZero

Set to true when the alert condition treats missing data as zero.

__dashboardUid__

UID of the dashboard the alert was created from, when the alert originated from a dashboard panel.

__panelId__

ID of the dashboard panel the alert was created from.
Grafana hides annotation names that begin with a double underscore. Kloudfuse follows the same convention for the dashboard link annotations, and displays only __value__ and __value_string__ from Grafana’s own internal set.

Warning Threshold Annotations

An alert configured with both a critical and a warning threshold is stored as two rules: the main rule, and a companion warning rule whose name ends with [Warning]. These annotations tie the pair together, and Kloudfuse merges them back into a single alert in the UI.

Name Description

warningValue

Threshold value for the warning condition.

warningRecoveryValue

Recovery threshold value for the warning condition.

warningContacts

JSON array of the contact points notified for the warning condition.

parentRuleUid

On the companion warning rule, the UID of the main rule it belongs to.
Deleting or renaming the companion warning rule outside the Kloudfuse UI orphans it. The UI then shows it as a separate alert rather than as the warning threshold of its parent.

Reserved Legacy Annotations

These names are still reserved, so that alerts created by older releases continue to render, but current releases no longer write them. Do not use them for your own metadata.

Name Description

componentName

Deprecated. Formerly recorded the component an alert applied to.

logQL

Deprecated. Stored the LogQL query for log alerts created when LogQL could be entered directly in the UI. The UI retains it for backward compatibility only; entering LogQL directly is no longer supported.

rrcfInnerExpression

Stored the inner PromQL expression of an RRCF alert, so that the expression could be restored for editing.

kfuseTags

Set on preinstalled alerts only, with a value such as logs or outliers. The catalog service reads it to decide whether a given preinstalled alert should be installed.

kfuseASMFilter

Reserved for internal use.

KfSource

Superseded by Kloudfuse Source. Kloudfuse removes this annotation when it saves an alert.

kfuse_policy_group_id

Recorded the notification policy group an alert belonged to. Notification policy grouping has been retired, and Kloudfuse strips this annotation on save, so that restoring an older version of a rule cannot re-enroll it.

Reserved Label Names

Kloudfuse also reserves two label names, which are excluded from the Custom labels field and stripped when an alert is saved:

  • kfuse_policy

  • kfuse_policy_group

Both belong to the retired notification policy subtree. They are recognized only so that alerts created by older releases can be cleaned up.

Editing Alerts Outside Kloudfuse

Kloudfuse alerts are backed by Grafana alert rules, so it is technically possible to edit a rule’s annotations through Grafana directly. Avoid it.

  • Adding an annotation whose name collides with a reserved name can break the Kloudfuse alert detail page for that alert.

  • Changing the value of ruleType, alertType, or extraData causes Kloudfuse to render the wrong view for the alert, or to fail to open the query builder when you edit it.

  • Removing parentRuleUid from a warning rule detaches it from its parent alert.

Make all annotation changes through the Kloudfuse alert creation and editing screens, which validate reserved names before saving.

Best Practices

  • Use summary and description for text that responders read first, and reserve custom annotations for structured metadata such as an owning team or a ticket ID.

  • Use the Runbook URL field for the runbook rather than inventing your own link annotation.

  • Keep annotation values short. Long values are stored on every alert instance and are carried into every notification.

  • Put anything that must affect routing, grouping, or silencing into labels, not annotations.

  • Choose distinctive custom annotation names to reduce the chance of colliding with a name that a future Kloudfuse release reserves.