Events
An event is a notification of a change - a record of activity in your stack.
Events can represent API calls, state transitions, or changes in your execution environment or infrastructure.
Events power several Prefect features, including flow run logs and automations. In Prefect Cloud, events power audit logs.
You can manage events with the Prefect CLI, Terraform provider, or Prefect API.
Event specification
Events adhere to a structured specification.
| Name | Type | Required? | Description |
|---|---|---|---|
| occurred | String | yes | When the event happened |
| event | String | yes | Name of the event that happened |
| resource | Object | yes | Primary resource this event concerns |
| related | Array | no | List of additional Resources involved in this event |
| payload | Object | no | Open-ended set of data describing what happened |
| id | String | yes | Client-provided identifier of this event |
| follows | String | no | ID of an event that is known to have occurred prior to this one |
Event grammar
Events can be named arbitrarily, but are recommended to follow a consistent and informative grammar. An event describes a resource and an action it took— or that was taken—on that resource.
For example, events emitted automatically by Prefect objects take the following form:
See how to emit and use custom events to trigger automations.
Resources
Every event has a primary resource, which describes the object that emitted an event. Resources are used as quasi-stable identifiers for sources of events, and are represented as dot-delimited strings.
For example:
Resources can have additional arbitrary labels which can be used in event aggregation queries. For example:
Events may contain related resources, used to associate the event with other resources. For example, a primary resource can act on or with another resource. Here is an example of a related resource:
Respond to events
From any event detail page, you can configure an automation to trigger on the observation of matching events—or a lack of matching events—by clicking the automate button in the overflow menu:
The default trigger configuration fires every time it sees an event with a matching resource identifier. Advanced configuration is possible through custom event triggers.