events() Queries

Summary

events(<filterName>="<filterValue>” [,|and|or [not] <filter2Name>="<filter2Value>"] ...)

Controls how events display in a chart. Can be combined with event set operators and event functions that let you fine tune your events() query.

Parameters

Description

The events() function returns the set of stored events that match one or more event filters. You can use events() to display events in time-series charts, for example, to inform other users about reasons for a change in a time series. The result set of an events() query depends on the timing of the query.

You can describe the set of events to be returned using event filters:

• Match events in general by filtering on name, source, type, severity, and event tags.
• Match events that are associated with alerts by filtering on alert tags, targets, and alert ID.

You can combine multiple event filters with Boolean operators. For example:

• Return events of any type that start with Request and have severity that is either severe or warn:
  • events(name="Request*" and (severity="severe" or severity="warn"))
  • events(name="Request*", severity="warn" or severity="severe")
• Return events of any type that either have severity warn or are generated by the source app-1:
  • events(severity="warn" or source="app-1")

You can use events() as an eventsExpression that you specify to another event function or to an event set operator. For example:

• Filter a set of events and return only the events that have ended: closed(events(name="Request*"))
• Examine a set of events and return the single event with the earliest start time: first(events(name="Request*"))
• Use a set of events as the basis for creating synthetic ongoing events: since(events(name="Request*"))
• Count the number of events at each point in time and return a time series: count(events(name="Request*"))
• Return all ongoing events: events(name="Request*") - closed(events(name="Request*"))

Event Filters

Event filters allow you to limit which events are returned from events() queries.

Event Set Operators

An event set operator combines or compares two sets of events, and returns a set of events as the result.

Event Set Combination Operators

events(type="maintenanceWindow") union events(name="test")

events(type="maintenanceWindow" or name="test")   // Equivalent alternative 

events(type="maintenanceWindow") intersect events(name="test")

events(type="maintenanceWindow" and name="test")  // Equivalent alternative 

events() - closed(events()) 

Event Set Comparison Operators

You can use Allen’s interval algebra operators to compare two event sets, based on the time intervals (start time and end time) of the events in each set.

Examples:

• events(severity="severe") d since(1d) returns all events with severity severe that occurred in the last day.
• events(severity="severe") - (events(severity="severe") d since(1d)) returns all events with severity severe that are older than one day.

When Does an Event Query Return Events?

Where an event happens in relation to the query start time and query end time determines whether a query returns an event or not. Returning an event means showing the event in the UI, or, if you use the API, returning the event itself. The following diagram illustrates the behavior:

Here are the details: