Track activity through events
An event is a notification of a change, creating a history of activity in your stack.
Events can represent API calls, state transitions, or changes in your execution environment or infrastructure.
Events power several features, including flow run logs and automations. In Prefect Cloud, events power audit logs.
Events enable observability into your data stack through the event feed in the UI and the configuration of Prefect’s reactivity through automations.
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 have 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 by Prefect objects take the form of:
prefect.block.write-method.called
prefect-cloud.automation.action.executed
prefect-cloud.user.logged-in
Event sources
Prefect objects automatically emit events, including flows, tasks, deployments, work queues, and logs.
Prefect-emitted events contain the prefect
or prefect-cloud
resource prefix.
You can also send events to the Prefect
events API through an authenticated HTTP request.
Emit custom events from Python code
The Prefect Python SDK provides an emit_event
function that emits a Prefect event when called. You can call
emit_event
inside or outside of a task or flow. For example, running this code emits an event to the Prefect API, which validates and ingests the event data:
from prefect.events import emit_event
def some_function(name: str="kiki") -> None:
print(f"hi {name}!")
emit_event(event=f"{name}.sent.event!", resource={"prefect.resource.id": f"coder.{name}"})
if __name__ == "__main__":
some_function()
emit_event
requires two arguments: event
, the name of the event, and resource={"prefect.resource.id": "my_string"}
, the resource ID.
To get data into an event for use in an automation action, specify a dictionary of values for the payload
parameter.
Emit events through webhooks
Prefect Cloud offers programmable webhooks to receive HTTP requests from other systems and translate them into events within your workspace. Webhooks can emit pre-defined static events, dynamic events that use portions of the incoming HTTP request, or events derived from CloudEvents.
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 constructed as dot-delimited strings. For example:
prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3.action.0
acme.user.kiki.elt_script_1
prefect.flow-run.e3755d32-cec5-42ca-9bcd-af236e308ba6
Resources can optionally have additional arbitrary labels which can be used in event aggregation queries. For example:
"resource": {
"prefect.resource.id": "prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3",
"prefect-cloud.action.type": "call-webhook"
}
Events can optionally 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:
"resource": {
"prefect.resource.id": "prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3.action.0",
"prefect-cloud.action.type": "call-webhook"
},
"related": [
{
"prefect.resource.id": "prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3",
"prefect.resource.role": "automation",
"prefect-cloud.name": "webhook_body_demo",
"prefect-cloud.posture": "Reactive"
}
]
Events in the UI
The Prefect UI provides an interactive dashboard to analyze and take action on events that occurred in your workspace on the event feed page.
The event feed is the primary place to view, search, and filter events to understand activity across your stack. Each entry displays data on the resource, related resource, and event that took place.
View more information about an event by clicking into it. You will see full details of an event’s resource, related resources, and its payload.
Respond to events
From an event 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 triggers.
Was this page helpful?