Skip to content

Commit b37c97a

Browse files
marciocloudflaremarciocloudflare
authored
[MT/MWAN] Magic tunnel health alerts API examples (#16775)
* moved how-to to pages * moved info to rec slo partial * added rec slo partial to pages * added api commands * added api * refined text and added components * refined text
1 parent e39bc0f commit b37c97a

File tree

4 files changed

+253
-75
lines changed

4 files changed

+253
-75
lines changed

‎src/content/docs/magic-transit/how-to/configure-magic-tunnel-alerts.mdx‎

Lines changed: 112 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,118 @@ pcx_content_type: how-to
33
title: Configure Magic Tunnel health alerts
44
head: []
55
description: Use the API to set up and configure Magic Tunnel health alerts
6-
76
---
87

9-
import { Render } from "~/components"
8+
import { Render, Tabs, TabItem } from "~/components";
9+
10+
<Render
11+
file="magic-tunnel-health-alerts/magic-tunnel-health-alerts"
12+
product="magic-wan"
13+
params={{
14+
one: "Magic Transit",
15+
two: "/magic-transit/reference/magic-tunnels/",
16+
three: "/magic-transit/analytics/network-analytics/",
17+
four: "/magic-transit/reference/tunnel-health-checks/",
18+
}}
19+
/>
20+
21+
## Set up Magic Tunnel health alerts
22+
23+
<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
24+
25+
1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account.
26+
2. Select **Notifications** > **Add**.
27+
3. Select **{props.one}** > **Magic Tunnel Health Check Alert** > **Select** to add a notification.
28+
4. Enter a name and description for the notification.
29+
5. Add webhooks or an email address for the person who should receive the notification, and select **Next**.
30+
6. Choose the tunnels you want to receive alerts for.
31+
7. Select the **Alert Sensitivity Level** threshold. It is predefined for _Medium_, but you can choose between _High_, _Medium_, and _Low_. If you need more than three sensitivity levels, use the API.
32+
8. Select **Create** when you are done.
33+
34+
</TabItem> <TabItem label="API">
35+
36+
:::note
37+
Refer to the [documentation for Notifications](/notifications/get-started/) to learn about specific permissions you need to access the service via the API.
38+
:::
39+
40+
Send a [`POST` request](/api/operations/notification-policies-create-a-notification-policy) to create a Magic Transit tunnel health alert. You can set tunnel health alerts with any SLO value between `0` and `99.99`.
41+
42+
```bash
43+
curl https://api.cloudflare.com/client/v4/accounts/account_id/alerting/v3/policies \
44+
--header 'Authorization: Bearer <YOUR_TOKEN>' \
45+
--header 'Content-Type: application/json' \
46+
--data '{
47+
"alert_type": "magic_tunnel_health_check_event",
48+
"description": "<DESCRIBE_POLICY>",
49+
"enabled": true,
50+
"filters": {
51+
"slo": [
52+
"99.9"
53+
]
54+
},
55+
"mechanisms": {
56+
"email": [
57+
{
58+
"id": "EMAIL_ADDRESS"
59+
}
60+
],
61+
"name": "<DESCRIBE_ALERT>"
62+
}'
63+
```
64+
65+
```json output
66+
{
67+
"result": [
68+
{
69+
"id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
70+
"name": "<POLICY_NAME>",
71+
"description": "<POLICY_DESCRIPTION>",
72+
"enabled": true,
73+
"alert_type": "magic_tunnel_health_check_event",
74+
"mechanisms": {
75+
"email": [
76+
{
77+
"id": "<YOUR_EMAIL>"
78+
}
79+
]
80+
},
81+
"created": "2024-09-11T14:13:29.585658Z",
82+
"modified": "2024-09-11T14:13:29.585658Z",
83+
"conditions": {
84+
"and": [
85+
{
86+
"or": [
87+
{
88+
"<=": [
89+
{
90+
"var": "slo"
91+
},
92+
"99.9"
93+
]
94+
}
95+
]
96+
}
97+
]
98+
},
99+
"filters": {
100+
"slo": ["99.9"]
101+
}
102+
}
103+
],
104+
"success": true,
105+
"errors": [],
106+
"messages": []
107+
}
108+
```
109+
110+
</TabItem> </Tabs>
10111

11-
<Render file="magic-tunnel-health-alerts/magic-tunnel-health-alerts" product="magic-wan" params={{ one: "Magic Transit", two: "/magic-transit/reference/magic-tunnels/", three: "/magic-transit/analytics/network-analytics/", four: "/magic-transit/reference/tunnel-health-checks/" }} />
112+
<Render
113+
file="magic-tunnel-health-alerts/recommended-slo"
114+
product="magic-wan"
115+
params={{
116+
one: "/magic-transit/reference/magic-tunnels/",
117+
two: "/magic-transit/analytics/network-analytics/",
118+
three: "/magic-transit/reference/tunnel-health-checks/",
119+
}}
120+
/>

‎src/content/docs/magic-wan/configuration/common-settings/configure-magic-tunnel-alerts.mdx‎

Lines changed: 111 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,117 @@ pcx_content_type: how-to
33
title: Configure Magic Tunnel health alerts
44
head: []
55
description: Use the API to set up and configure Magic Tunnel health alerts
6-
76
---
87

9-
import { Render } from "~/components"
8+
import { Render, Tabs, TabItem } from "~/components";
9+
10+
<Render
11+
file="magic-tunnel-health-alerts/magic-tunnel-health-alerts"
12+
params={{
13+
one: "Magic WAN",
14+
two: "/magic-wan/reference/magic-tunnels/",
15+
three: "/magic-wan/analytics/network-analytics/",
16+
four: "/magic-wan/reference/tunnel-health-checks/",
17+
}}
18+
/>
19+
20+
## Set up Magic Tunnel health alerts
21+
22+
<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
23+
24+
1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account.
25+
2. Select **Notifications** > **Add**.
26+
3. Select **{props.one}** > **Magic Tunnel Health Check Alert** > **Select** to add a notification.
27+
4. Enter a name and description for the notification.
28+
5. Add webhooks or an email address for the person who should receive the notification, and select **Next**.
29+
6. Choose the tunnels you want to receive alerts for.
30+
7. Select the **Alert Sensitivity Level** threshold. It is predefined for _Medium_, but you can choose between _High_, _Medium_, and _Low_. If you need more than three sensitivity levels, use the API.
31+
8. Select **Create** when you are done.
32+
33+
</TabItem> <TabItem label="API">
34+
35+
:::note
36+
Refer to the [documentation for Notifications](/notifications/get-started/) to learn about specific permissions you need to access the service via the API.
37+
:::
38+
39+
Send a [`POST` request](/api/operations/notification-policies-create-a-notification-policy) to create a Magic WAN tunnel health alert. You can set tunnel health alerts with any SLO value between `0` and `99.99`.
40+
41+
```bash
42+
curl https://api.cloudflare.com/client/v4/accounts/account_id/alerting/v3/policies \
43+
--header 'Authorization: Bearer <YOUR_TOKEN>' \
44+
--header 'Content-Type: application/json' \
45+
--data '{
46+
"alert_type": "magic_wan_tunnel_health",
47+
"description": "<DESCRIBE_POLICY>",
48+
"enabled": true,
49+
"filters": {
50+
"slo": [
51+
"99.9"
52+
]
53+
},
54+
"mechanisms": {
55+
"email": [
56+
{
57+
"id": "EMAIL_ADDRESS"
58+
}
59+
],
60+
"name": "<DESCRIBE_ALERT>"
61+
}'
62+
```
63+
64+
```json output
65+
{
66+
"result": [
67+
{
68+
"id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
69+
"name": "<POLICY_NAME>",
70+
"description": "<POLICY_DESCRIPTION>",
71+
"enabled": true,
72+
"alert_type": "magic_wan_tunnel_health",
73+
"mechanisms": {
74+
"email": [
75+
{
76+
"id": "<YOUR_EMAIL>"
77+
}
78+
]
79+
},
80+
"created": "2024-09-11T14:13:29.585658Z",
81+
"modified": "2024-09-11T14:13:29.585658Z",
82+
"conditions": {
83+
"and": [
84+
{
85+
"or": [
86+
{
87+
"<=": [
88+
{
89+
"var": "slo"
90+
},
91+
"99.9"
92+
]
93+
}
94+
]
95+
}
96+
]
97+
},
98+
"filters": {
99+
"slo": ["99.9"]
100+
}
101+
}
102+
],
103+
"success": true,
104+
"errors": [],
105+
"messages": []
106+
}
107+
```
108+
109+
</TabItem> </Tabs>
10110

11-
<Render file="magic-tunnel-health-alerts/magic-tunnel-health-alerts" params={{ one: "Magic WAN", two: "/magic-wan/reference/magic-tunnels/", three: "/magic-wan/analytics/network-analytics/", four: "/magic-wan/reference/tunnel-health-checks/" }} />
111+
<Render
112+
file="magic-tunnel-health-alerts/recommended-slo"
113+
product="magic-wan"
114+
params={{
115+
one: "/magic-transit/reference/magic-tunnels/",
116+
two: "/magic-transit/analytics/network-analytics/",
117+
three: "/magic-transit/reference/tunnel-health-checks/",
118+
}}
119+
/>

‎src/content/partials/magic-wan/magic-tunnel-health-alerts/magic-tunnel-health-alerts.mdx‎

Lines changed: 1 addition & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
inputParameters: productName;;backgroundInfoPath;;networkAnalyticsPath;;healthChecks
2+
inputParameters: productName;;backgroundInfoPath
33
---
44

55
import { GlossaryTooltip, Markdown, TabItem, Tabs } from "~/components";
@@ -20,71 +20,3 @@ If a Magic Tunnel health alert is fired, customers can expect the following data
2020
- Tunnel status
2121
- Alert SLO
2222
- Timestamp
23-
24-
## Set up Magic Tunnel health alerts
25-
26-
<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
27-
28-
1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account.
29-
2. Select **Notifications** > **Add**.
30-
3. Select **{props.one}** > **Magic Tunnel Health Check Alert** > **Select** to add a notification.
31-
4. Enter a name and description for the notification.
32-
5. Add webhooks or an email address for the person who should receive the notification, and select **Next**.
33-
6. Choose the tunnels you want to receive alerts for.
34-
7. Select the **Alert Sensitivity Level** threshold. It is predefined for _Medium_, but you can choose between _High_, _Medium_, and _Low_.
35-
8. Select **Create** when you are done.
36-
37-
</TabItem> <TabItem label="API">
38-
39-
An example of the API configuration for Magic Tunnel health alerts is provided below:
40-
41-
```bash
42-
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/alerting/v3/policies \
43-
--header "Authorization: Bearer <API_TOKEN>" \
44-
--header "Content-Type: application/json" \
45-
--data '{
46-
"name": "<NAME_OF_MAGIC_TUNNEL_HEALTH_ALERT>",
47-
"alert_type": "magic_tunnel_health_check_event",
48-
"description": "<DESCRIPTION_OF_MAGIC_TUNNEL_HEALTH_ALERT>",
49-
"enabled": true,
50-
"filters": {
51-
"slo": [ "99.0" ],
52-
"tunnel_name": [ "Name(s) of the tunnels monitored in the alert" ]
53-
},
54-
"mechanisms": {
55-
"email": [ { "id": "[email protected]" } ],
56-
"pagerduty": [ { "id": "<PAGERDUTY_ID>" } ],
57-
"webhooks": [ { "id": "<WEBHOOKS_ID>" } ]
58-
}
59-
}'
60-
```
61-
62-
Refer to the [API documentation](/api/operations/notification-policies-list-notification-policies) for more details.
63-
64-
</TabItem> </Tabs>
65-
66-
## Recommended SLO thresholds
67-
68-
Currently, there are three SLO threshold values that are supported by the API. The SLO threshold for Magic Tunnel health alerts can be defined as the percentage of health checks that must be successful for each of the Magic Tunnel(s) included in the alert:
69-
70-
| Alert Sensitivity Level | Recommended SLO threshold |
71-
| ----------------------- | ------------------------- |
72-
| High | 99.0 |
73-
| Medium | 98.0 |
74-
| Low | 97.0 |
75-
76-
With these settings, at 100% failure Cloudflare will send alerts at the following time frames, after a problem is detected:
77-
78-
- **High sensitivity**: First alert within 10 minutes.
79-
- **Medium sensitivity**: First alert within 20 minutes.
80-
- **Low sensitivity**: First alert within 30 minutes.
81-
82-
Refer to the <a href={props.two}>Magic tunnels background information page</a> for more information on this topic.
83-
84-
## Test SLOs
85-
86-
To test whether a specific alert sensitivity level works for your use case:
87-
88-
1. [Create an alert](#set-up-magic-tunnel-health-alerts) with a specific sensitivity level for a tunnel with active traffic within the past six hours. If you are not sure of what tunnels to choose, refer to <a href={props.three}>Network Analytics</a> to learn how you can view real-time and historical data about your network.
89-
2. Disable the tunnel you are testing, so there is 100% <a href={props.four}>health check failure</a>.
90-
3. The time it takes for Cloudflare to send you an alert will depend on the sensitivity you chose for your alerts (High, Medium or Low).

‎src/content/partials/magic-wan/magic-tunnel-health-alerts/recommended-slo.mdx‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
inputParameters: backgroundInfoPath;;networkAnalyticsPath;;healthChecks
3+
---
4+
5+
## Recommended SLO thresholds
6+
7+
Currently, there are three SLO threshold values that are supported by the API. The SLO threshold for Magic Tunnel health alerts can be defined as the percentage of health checks that must be successful for each of the Magic Tunnel(s) included in the alert:
8+
9+
| Alert Sensitivity Level | Recommended SLO threshold |
10+
| ----------------------- | ------------------------- |
11+
| High | 99.0 |
12+
| Medium | 98.0 |
13+
| Low | 97.0 |
14+
15+
With these settings, at 100% failure Cloudflare will send alerts at the following time frames, after a problem is detected:
16+
17+
- **High sensitivity**: First alert within 10 minutes.
18+
- **Medium sensitivity**: First alert within 20 minutes.
19+
- **Low sensitivity**: First alert within 30 minutes.
20+
21+
Refer to the <a href={props.one}>Magic tunnels background information page</a> for more information on this topic.
22+
23+
## Test SLOs
24+
25+
To test whether a specific alert sensitivity level works for your use case:
26+
27+
1. [Create an alert](#set-up-magic-tunnel-health-alerts) with a specific sensitivity level for a tunnel with active traffic within the past six hours. If you are not sure of what tunnels to choose, refer to <a href={props.two}>Network Analytics</a> to learn how you can view real-time and historical data about your network.
28+
2. Disable the tunnel you are testing, so there is 100% <a href={props.three}>health check failure</a>.
29+
3. The time it takes for Cloudflare to send you an alert will depend on the sensitivity you chose for your alerts (High, Medium or Low).

0 commit comments

Comments
 (0)