Define a custom trigger to react to many kinds of events and metrics.
{"type": "event"}
.
Name | Type | Supports trailing wildcards | Description |
---|---|---|---|
match | object | ✅ | Labels for resources which this Automation will match. |
match_related | object OR array of object | ✅ | Labels for related resources which this Automation will match. |
posture | string enum | N/A | The posture of this Automation, either Reactive or Proactive. Reactive automations respond to the presence of the expected events, while Proactive automations respond to the absence of those expected events. |
after | array of strings | ✅ | Event(s), one of which must have first been seen to start this automation. |
expect | array of strings | ✅ | The event(s) this automation expects to see. If empty, this automation will evaluate any matched event. |
for_each | array of strings | ❌ | Evaluate the Automation separately for each distinct value of these labels on the resource. By default, labels refer to the primary resource of the triggering event. You may also refer to labels from related resources by specifying related:<role>:<label> . This will use the value of that label for the first related resource in that role. |
threshold | integer | N/A | The number of events required for this Automation to trigger (for Reactive automations), or the number of events expected (for Proactive automations) |
within | number | N/A | The time period over which the events must occur. For Reactive triggers, this may be as low as 0 seconds, but must be at least 10 seconds for Proactive triggers. |
event
and metric
triggers support matching events for specific resources in your workspace, including most
Prefect objects (like flows, deployment, blocks, work pools, tags) as well as resources you have defined in any
events you emit yourself.
The match
and match_related
fields control which events a trigger considers for evaluation
by filtering on the contents of their resource
and related
fields, respectively. Each label added to a match
filter
is AND
ed with the other labels, and can accept a single value or a list of multiple values that are OR
ed together.
resource
and related
fields on the following prefect.flow-run.Completed
event, truncated for this example.
Its primary resource is a flow run, and since that flow run was started by a deployment, it is related to both its flow and its deployment:
cute-
or radical-
.
prefect.flow-run.Completed
event, but will permit additional,
possibly undesired events through the filter as well. You can combine match
and match_related
for more restrictive
filtering:
cute-
or radical-
.
match_related
also supports an array of objects, each of which can contain multiple labels.
This allows for more complex matching on related resources, such as filtering for events that are related to a specific work pool or tag.
To match flow runs on a work pool with specific tags, you can use the following configuration:
match
filters, you must decide if this event counts toward the
trigger’s threshold
. That is determined by the event names present in expect
.
This configuration informs the trigger to evaluate only prefect.flow-run.Completed
events that have passed the
match
filters.
threshold
decides the quantity of expect
ed events needed to satisfy the trigger. Increasing the threshold
above 1 requires use of within
to define a range of time when multiple events are seen. The following
configuration expects two occurrences of prefect.flow-run.Completed
within 60 seconds:
after
to handle scenarios that require more complex event reactivity.
For example, this flow emits an event indicating the table it operates on is missing or empty:
after
to prevent this automation from firing unless either a table-missing
or a
table-empty
event has occurred before a flow run of this deployment completes.
match
and match_related
ensure the trigger only evaluates events that are relevant to its
purpose.posture
; that is, count up events toward the
threshold
until it is met, then execute actions. To respond to the absence of events, use a proactive posture
.
A proactive trigger fires when its threshold
has not been met by the end of the window of time defined by within
.
Proactive triggers must have a within
value of at least 10 seconds.
The following trigger fires if a prefect.flow-run.Completed
event is not seen within 60 seconds after a
prefect.flow-run.Running
event is seen:
for_each
, a prefect.flow-run.Completed
event from a different flow run than the one that
started this trigger with its prefect.flow-run.Running
event could satisfy the condition. Adding a for_each
of
prefect.resource.id
causes this trigger to be evaluated separately for each flow run id associated with these events.
{"type": "metric"}
) fire when the value of a metric in your workspace crosses a threshold you defined.
For example, you can trigger an automation when the success rate of flows in your workspace drops below 95% over the course
of an hour.
Prefect’s metrics are all derived by examining your workspace’s events, and if applicable, use the occurred
times of
those events as the basis for their calculations.
Prefect defines three metrics:
{"name": "successes"}
), defined as the number of flow runs that went Pending
and then the latest
state we saw was not a failure (Failed
or Crashed
). This metric accounts for retries if the ultimate state was
successful.{"name": "duration"}
), defined as the length of time that a flow remains in a Running
state before
transitioning to a terminal state such as Completed
, Failed
, or Crashed
. Because this time is derived in terms of
flow run state change events, it may be greater than the runtime of your function.{"name": "lateness"}
), defined as the length of time that a Scheduled
flow remains in a Late
state before transitioning to a Running
and/or Crashed
state. Only flow runs that the system marks Late
are included.Name | Type | Supports trailing wildcards | Description |
---|---|---|---|
match | object | ✅ | Labels for resources which this Automation will match. |
match_related | object OR array of object | ✅ | Labels for related resources which this Automation will match. |
metric | MetricTriggerQuery | N/A | The definition of the metric query to run. |
MetricTriggerQuery
query is defined as:
Name | Type | Description |
---|---|---|
name | string | The name of the Prefect metric to evaluate (see above). |
threshold | number | The threshold the current metric value is compared to. |
operator | string ("<" , "<=" , ">" , ">=" ) | The comparison operator to use to decide if the threshold value is met. |
range | duration in seconds | How far back to evaluate the metric. |
firing_for | duration in seconds | How long the value must exceed the threshold before this trigger fires. |
production
in your workspace are failing at a rate of 10% or worse for the last hour (in other words, your success rate is below 90%), create this trigger:
kubernetes
) in the
last day exceeds five minutes late—and that number hasn’t gotten better for the last 10 minutes—use a trigger like this:
compound
or sequence
trigger.
These higher-order triggers are composed from a set of underlying event
and metric
triggers.
For example, if you want to run a deployment only after three different flows in your workspace have written their
results to a remote filesystem, combine them with a ‘compound’ trigger:
daily-export-initiator
flow complete, and then the three
files written by the other flows.
The within
parameter for compound and sequence triggers restricts how close in time (in seconds) the child triggers
must fire to satisfy the composite trigger. For example, if the daily-export-initiator
flow runs, but the other three
flows don’t write their result files until three hours later, this trigger won’t fire. Placing these time constraints
on the triggers can prevent a misfire if you know that the events will generally happen within a specific timeframe—
and you don’t want a stray older event included in the evaluation of the trigger.
If this isn’t a concern for you, you may omit the within
period, in which case there is no limit to how far apart in time the child triggers occur.
You can compose any type of trigger into higher-order composite triggers, including proactive event triggers and metric
triggers. In the following example, the compound trigger fires if any of the following events occur: a flow run
stuck in Pending
, a work pool becoming unready, or the average amount of Late
work in your workspace going over
10 minutes:
require
parameter may be "any"
, "all"
, or a number between 1 and the number of child
triggers. In the example above, if you feel that you are receiving too many spurious notifications for issues that
resolve on their own, you can specify {"require": 2}
to express that any two of the triggers must fire in order
for the compound trigger to fire. Sequence triggers, on the other hand, always require all of their child triggers to
fire before they fire.
Compound triggers are defined as:
Name | Type | Description |
---|---|---|
require | number, "any" , or "all" | The number of child triggers that must fire for this trigger to fire |
within | time, in seconds | How close in time the child triggers must fire for this trigger to fire |
triggers | array of other triggers |
Name | Type | Description |
---|---|---|
within | time, in seconds | How close in time the child triggers must fire for this trigger to fire |
triggers | array of other triggers |
Feature | Prefect Open Source | Prefect Cloud |
---|---|---|
Event Triggers | ✅ | ✅ |
Composite Triggers (Compound & Sequence) | ✅ | ✅ |
Metric Triggers | ❌ | ✅ |