Add a tutorial showing how to set up an email alert in Prefect Cloud (#…

…16345)
PrefectHQ · Dec 18, 2024 · 6343036 · 6343036
1 parent 1cd3d60
commit 6343036
Show file tree

Hide file tree

Showing 4 changed files with 101 additions and 8 deletions.
diff --git a/docs/mint.json b/docs/mint.json
@@ -74,7 +74,8 @@
           "group": "For platform engineers",
           "pages": [
             "v3/tutorials/platform",
-            "v3/tutorials/debug"
+            "v3/tutorials/debug",
+            "v3/tutorials/alerts"
           ]
         }
       ],

diff --git a/docs/v3/tutorials/alerts.mdx b/docs/v3/tutorials/alerts.mdx
@@ -0,0 +1,92 @@
+---
+title: Send alerts on failure
+description: Learn how to use automations to notify your team when a flow fails.
+---
+
+In the [Debug a data pipeline](/v3/tutorials/debug) tutorial, you learned how to troubleshoot failed flow runs.
+In this tutorial, you'll learn how to set up an email alert that proactively notifies your team about failures.
+Alerts let team members engage with the troubleshooting process, even if they don't typically log into Prefect Cloud.
+
+<Info>
+This tutorial starts where the [Set up a platform for data pipelines](/v3/tutorials/platform) tutorial leaves off, so complete that one first.
+You will need a paid Prefect Cloud account.
+</Info>
+
+## Set up an automation
+
+Automations are used to set up alerts in Prefect.
+First, you need to create a new automation.
+
+1. Sign in to Prefect Cloud, and use the workspace switcher to open the `staging` workspace.
+1. Go to **Automations** and then click **Add Automation**.
+
+### Specify the trigger
+
+An automation triggers whenever a specified condition is met.
+
+1. Select the **Flow run state** trigger type.
+1. Trigger whenever the `data-pipeline` flow has flow runs that enter the **Failed** or **Crashed** states.
+1. Click **Next** to go to the next step.
+
+### Specify the action
+
+Once an automation triggers, it can perform one or more actions.
+
+1. Choose the **Send a notification** action type
+1. In order to send an email notification, you need to create a block.
+Blocks store configuration and provide an interface for external systems.
+    1. Under **Block**, click **Add**.
+    1. Find the **Email** block, and then click **Create**.
+    1. Specify `email-alerts` as the block name, and provide a JSON list of email addresses to send notifications to (e.g. `["[email protected]"]`).
+    1. Click **Create** to save the block.
+1. Click **Next** to go to the next step.
+
+### Save the automation
+
+Give the automation a name and description so that you can identify its purpose later.
+
+1. Name: `email-alert`
+2. Description: `Send an email when the 'data-pipeline' flow fails`
+3. Click **Save**.
+
+You've now created an automation that sends an email whenever the `data-pipeline` flow in the `staging` workspace has a failed run.
+
+## Test the alert
+
+To test the alert, you need to trigger a flow run failure in the `staging` workspace.
+
+```bash
+# Switch to the staging workspace (if not already in it)
+prefect cloud workspace set --workspace "<account handle>/staging"
+
+# Run the script to simulate a failed flow run
+python simulate_failures.py --fail-at-run 1 --runs 1
+```
+
+After the script finishes, you should receive an email with details about the failed flow run.
+The email should look similar to the following:
+
+```
+Subject: Prefect flow run notification
+
+Flow run data-pipeline/courageous-buffalo observed in state Failed at 2024-12-11 18:59:17.212585+00:00.
+Flow ID: 89053371-0d7e-4ef6-9a5f-63ea69689f66
+Flow run ID: 33c2dac9-7d2a-48dd-a8cf-3894c6cd6063
+Flow run URL: https://app.prefect.cloud/account/9b649228-0419-40e1-9e0d-44954b5c0ab6/workspace/a2127afa-ad10-4862-bdb0-5d065df64c8a/flow-runs/flow-run/33c2dac9-7d2a-48dd-a8cf-3894c6cd6063
+State message: Flow run encountered an exception: Exception: Run failed
+```
+
+You can open the URL to view the flow run in Prefect Cloud.
+
+## Next steps
+
+In this tutorial, you used Prefect Cloud automations to set up an email alert.
+
+To learn more about automations:
+
+* Read [Trigger actions on events](/v3/automate/events/automations-triggers) to become an automations expert.
+* See [Python](https://github.com/PrefectHQ/examples/blob/main/scripts/create-automation.py) and [Terraform](https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/automation) examples for creating an automation programmatically.
+
+<Tip>
+Need help? [Book a meeting](https://calendly.com/prefect-experts/prefect-product-advocates?utm_campaign=prefect_docs_cloud&utm_content=prefect_docs&utm_medium=docs&utm_source=docs) with a Prefect Product Advocate to get your questions answered.
+</Tip>
diff --git a/docs/v3/tutorials/debug.mdx b/docs/v3/tutorials/debug.mdx
@@ -95,7 +95,7 @@ Now, all flow runs succeed in spite of the `--fail-at-run` flag.
 Deploy the fix to the staging workspace to confirm this new behavior.
 
 ```bash
-prefect cloud workspace set --workspace "<account>/staging"
+prefect cloud workspace set --workspace "<account handle>/staging"
 python simulate_failures.py --fail-at-run 3
 ```
 
@@ -104,7 +104,7 @@ After the script finishes, open the **Home** page in Prefect Cloud to verify tha
 You can now switch workspaces to update the code used in the production workspace as well.
 
 ```bash
-prefect cloud workspace set --workspace "<account>/production"
+prefect cloud workspace set --workspace "<account handle>/production"
 python simulate_failures.py
 ```
 
@@ -113,7 +113,7 @@ python simulate_failures.py
 
 In this tutorial, you successfully used Prefect Cloud to fix a failing data pipeline.
 
-To take this to the next level, learn how to [set up an alert](/v3/automate/events/automations-triggers) so that you get notified about failures automatically.
+Next, learn how to [alert your team](/v3/tutorials/alerts) when failures occur.
 
 <Tip>
 Need help? [Book a meeting](https://calendly.com/prefect-experts/prefect-product-advocates?utm_campaign=prefect_docs_cloud&utm_content=prefect_docs&utm_medium=docs&utm_source=docs) with a Prefect Product Advocate to get your questions answered.

diff --git a/docs/v3/tutorials/platform.mdx b/docs/v3/tutorials/platform.mdx
@@ -77,15 +77,15 @@ Once you've authenticated to Prefect Cloud, open two terminal windows and run tw
 
 ```bash Terminal 1
 # Switch to the production workspace
-prefect cloud workspace set --workspace "<account>/production"
+prefect cloud workspace set --workspace "<account handle>/production"
 
 # Start a worker for the production work pool
 prefect worker start --pool default-work-pool
 ```
 
 ```bash Terminal 2
 # Switch to the staging workspace
-prefect cloud workspace set --workspace "<account>/staging"
+prefect cloud workspace set --workspace "<account handle>/staging"
 
 # Start a worker for the staging work pool
 prefect worker start --pool default-work-pool
@@ -101,13 +101,13 @@ Run the following script from the demo repository to create flow runs in each wo
 
 ```bash
 # Run flows in the production workspace
-prefect cloud workspace set --workspace "<account>/production"
+prefect cloud workspace set --workspace "<account handle>/production"
 python simulate_failures.py
 ```
 
 ```bash
 # Run flows in the staging workspace 
-prefect cloud workspace set --workspace "<account>/staging"
+prefect cloud workspace set --workspace "<account handle>/staging"
 python simulate_failures.py --fail-at-run 3
 ```