Events

An event is a notification of a change. Together, events form a feed of activity recording what's happening across your stack.

Events power several features in Prefect Cloud, including flow run logs, audit logs, and automations.

Events can represent API calls, state transitions, or changes in your execution environment or infrastructure.

Events enable observability into your data stack via the event feed, and the configuration of Prefect's reactivity via automations.

Event specification

Events adhere to a structured specification.

Name	Type	Required?	Description
occurred	String	yes	When the event happened
event	String	yes	The name of the event that happened
resource	Object	yes	The primary Resource this event concerns
related	Array	no	A list of additional Resources involved in this event
payload	Object	no	An open-ended set of data describing what happened
id	String	yes	The client-provided identifier of this event
follows	String	no	The ID of an event that is known to have occurred prior to this one.

Event grammar

Generally, events have a consistent and informative grammar - an event describes a resource and an action that the resource 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

Events are automatically emitted by all Prefect objects, including flows, tasks, deployments, work queues, and logs. Prefect-emitted events will contain the prefect or prefect-cloud resource prefix. Events can also be sent to the Prefect events API via authenticated http request.

Emit custom events from Python code

The Prefect Python SDK provides an emit_event function that emits an Prefect event when called. The function can be called inside or outside of a task or flow. Running the following code will emit an event to Prefect Cloud, which will validate and ingest 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}"})

some_function()

Note that the emit_event arguments shown above are required: event represents the name of the event and resource={"prefect.resource.id": "my_string"} is the resource id. To get data into an event for use in an automation action, you can specify a dictionary of values for the payload parameter.

Emit events via 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.

Events emitted from any source will appear in the event feed, where you can visualize activity in context and configure automations to react to the presence or absence of it in the future.

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, such as:

"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, such as in the case that the primary resource acted on or with another 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 Cloud UI

Prefect Cloud 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.

You can view more information about an event by clicking into it, where you can view the full details of an event's resource, related resources, and its payload.

Reacting 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 will fire every time it sees an event with a matching resource identifier. Advanced configuration is possible via custom triggers.