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.