Learn how to write events() queries.

You use events() queries to customize how events display in charts. An events() query cannot be the only query on the chart. At least one ts() query must also be enabled on the chart.

Event Query Syntax

The events() query syntax includes several parameters that you can combine:

<events_function>(<eventSet>)

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

Parameters

ParameterDescription
event_function One of the supported events functions. Events functions let you fine tune your events() query.
eventSet Set of events returned by a call to events().
filterName An event filter. You can optionally specify multiple event filters separated by the boolean operators (and, or, not).

You can combine the syntax elements, that is, you can use both an event function and a filter in a query.

Examples

The following examples use only filters, see Advanced events() Queries for examples for using events functions.

To display user events or events based on any alerts that start with Request and are either severity severe or warn, run one of the following queries:

  • events(name="Request\*" and (severity="severe" or severity="warn")
  • events(name="Request\*", severity="warn" or severity="severe")

To display events that either have severity warn or that are generated by the source app-1, run the following query:

  • events(severity="warn" or source="app-1")

Event Filters

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

FilterDescriptionExample
alertId The ID of the alert that created the event. events(alertId=1411189741192)
alertTag A tag associated with the alert that generated the event. events(alertTag="ops")
eventTag A tag associated with the event. events(eventTag="codepushes")
name The name of the event. Manually created events have a unique name, while events generated by an alert have the same name as the associated alert. The name filter requires quotes if spaces exist in the name. events(name="Request Latency too high")
severity The classification of the user event or the severity of alert that generated the event. User event classification levels are severe, warn, info, and unclassified. Although an event can be left as unclassified, the severity filter does not accept the string “unclassified” as a valid value. events(severity="info")
source or tag The source or source tag associated with the alert that generated the event. The source filter allows you to display events generated by an alert based on a single source or set of sources. The tag filter works the same way, but allows you to specify a source tag instead of a source name. events(source="app-*" or tag="dc2")
subtype The subtype of event of type alert-detail: failing, recovered. events(subtype="failing")
target The target of the alert that generated the event. The list of targets associated with an alert are considered a single string. If you want to identify a single target within that string, then you must use wildcards. For example, if the notification field contains: john.doe@example.com, jane.doe@example.com, pd:fbw21c9ee0219473w2179r4t23f8c34, to use jane.doe@example.com as the target filter, specify the email as \*jane.doe@example.com\*. events(target="*jane.doe@example.com*")
type The type of an event. The sytem-generated event types are:
  • alert
  • maintenanceWindow
  • alert-detail
  • credentials-error
  • alert-created
  • alert-updated
  • alert-deleted
  • alert-undeleted
  • alert-snoozed
  • alert-unsnoozed
  • dashboard-deleted
  • maintenancewindow-created
  • maintenancewindow-updated
  • maintenancewindow-deleted
You can optionally assign a type to a user event. The value requires quotes if it contains spaces or starts with a wildcard.
events(type="Code push")
events(type="*-created")

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 illustration illustrates the behavior:

when events return

Here are the details:

Event Number Event start Event end Returned?
Event 1 Before query start time time Before query start time No
Event 2 After query start time Before query end time Yes
Event 3 Before query start time After query start time Yes
Event 4 Before query start time After query end time No
Event 5 Before query start time N.A. (ongoing event) No
Event 6 After query start time After query end time Yes
Event 7 After query end time N.A. (ongoing event) No
Event 8 After query start time N.A. (ongoing event) Yes
Event 9 After query end time After query end time No

More Info

You can use events() functions to fine-tune your events query.