Event Annotations

Event annotations add structured key-value metadata to AME events. They are useful when an event needs extra operational context that should stay with the event, but does not fit into a fixed AME field such as status, assignee, tags, priority, or notable fields.

info

A valid support subscription is required to create, edit, append, or display event annotations.

What Annotations Are For

Use annotations for compact event context that should be easy to show, filter, automate on, or synchronize with another system.

Examples:

• owner = platform-team to show the responsible team when the AME assignee is still an individual user.
• environment = production to separate production and non-production events without creating many tags.
• source_ticket = INC0012345 to preserve an external reference.
• affected_services = ["auth", "payments"] to keep a small list of affected services.
• runbook = linux-disk-pressure to make automation and notifications refer to the right procedure.
• snow_assignment_group = Network Security to map event context into a ServiceNow field.

Annotations work best for stable, searchable metadata. Use comments for investigation notes, tags for broad classification, and notable fields for alert-result data.

Limits

Annotations have these limits:

Limit	Value
Maximum annotations per event	16
Annotation key length	32 characters
Annotation key characters	lowercase letters, numbers, underscores, and dashes
String value length	1024 characters
List value item count	32 items
Combined list value length	1024 characters
Value types	string or list of strings

Annotation keys are normalized by trimming whitespace and converting to lowercase. For example, Owner becomes owner. If two keys normalize to the same name, the annotation set is invalid.

note

Annotations are not a replacement for large alert payloads. Keep them small and predictable, especially when they are shown in tables or synchronized to a ticketing system.

Where Annotations Can Be Set

Annotations can be set when an event is created and when an existing event is updated.

Templates

Templates can define default annotations for events created from that template. This is useful for metadata that belongs to a use case, team, integration, or alert family.

Alert Result Fields

Search results can set annotations with ame.annotations or _ame.annotations. The value must be a JSON object.

Use _ame.annotations when you want to hide the field from the visible alert result.

Example:

<base search>
| eval _ame.annotations=json_object(
    "owner", "platform-team",
    "environment", "production"
    )

Saved Search Parameters

Saved searches can set annotations with the alert action parameter:

action.create_alert.param.annotations = {"owner":"soc","runbook":"malware-triage"}

Event Summary

Existing events can be updated from the Event Summary with the Edit Annotations action. The modal replaces the event's annotation set with the submitted values and can include a comment.

The action must be enabled in the tenant's Event Action configuration. It is disabled for users without the required role or without a valid support subscription.

API and Bulk Updates

Annotation updates use the event update attribute annotations. Supported change types are:

Change Type	Behavior
update	Merge the submitted annotations into the event. Existing keys are overwritten when the submitted key already exists.
replace	Replace the full annotation set. Keys not included in the submitted set are removed.
remove	Remove the submitted annotation keys from the event. Values in the submitted object are ignored for removal.

Creation and Append Lifecycle

When AME creates an event, annotations can come from three sources:

1. Alert result fields: ame.annotations or _ame.annotations
2. Saved search alert action parameter: action.create_alert.param.annotations
3. Template annotations

The sources are merged in that order of priority. If the same key exists in more than one source, the higher-priority source keeps its value.

When an alert appends to an existing event, AME tries to extend the event annotations with annotations from the appended alert. Existing annotation values are preserved on key conflicts. If the merge would exceed the per-event limit, the append still happens, but the new annotations are skipped and AME writes a warning message.

If no valid support subscription is installed, AME removes annotations from newly created events and skips annotation updates on existing events.

Where Annotations Can Be Used

Annotations are exposed as ame.annotations.<key> in event-facing contexts.

Examples:

Use	Example
Event Summary column	ame.annotations.owner
Event Summary filter	field owner, value platform-team in annotation filters
Notification data condition	ame.annotations.environment = production
Notification update trigger condition	changed contains ame.annotations.owner
Rule or readable event metadata	ame.annotations.runbook
SPL command filter	annotation_fields on ameevents or ameenrich
Ticketing integration	Map annotation keys to Jira or ServiceNow fields

Filtering in SPL

The ameevents and ameenrich commands accept annotation_fields as a JSON stringified list of string field filters.

Example:

| ameevents tenants="default" annotation_fields="[{\"field\":\"owner\",\"values\":[\"platform-team\"],\"comparator\":\"eq\"}]"

Only string comparators are supported for annotation filters.

How Annotations Are Shown

Annotations are shown only when configured for the tenant or selected as event table columns.

Event Table

Add an annotation column with the field name:

ame.annotations.<key>

Example:

ame.annotations.owner

Annotation columns use the annotation icon in the table header and support the same column filtering controls as other displayed event fields.

Expanded Event Title

Tenant configuration controls which annotations are shown in the expanded event title. Add annotation keys to the Shown Annotations list and choose whether annotations are displayed as:

• value-only chips, where the key is available as the tooltip
• key-value chips, such as owner: platform-team

Only configured annotation keys are shown. A wildcard entry such as * is not expanded for annotations.

Expanded Event

When an event is expanded, annotations are shown within the tags and impact/urgency section as chips. The annotation key is shown on hover as a tooltip. If the annotation value is a list, the chip shows the items comma-separated. Long annotations might be truncated but can be copied in full.

Notification and History Lifecycle

Annotation changes participate in the normal event update lifecycle.

For single-event updates, AME compares the previous and final annotation sets and emits field-level changes:

ame.annotations.owner: soc -> platform-team

Removed annotation keys are shown with the new value:

(removed)

For bulk updates, AME cannot show one previous value for every selected event, so update contexts use:

(various)

Notification schemes can use these flattened fields in update trigger conditions. For example, a notification can trigger when changed contains ame.annotations.environment, or when the changed value for ame.annotations.owner matches a specific team.