From 3b2a48a681fcfa65f9069890d8574089085cab86 Mon Sep 17 00:00:00 2001 From: Kelly Date: Tue, 11 Aug 2020 17:40:14 -0700 Subject: [PATCH] add AWS SES and Mailjet as examples --- content/v2.0/monitor-alert/send-email.md | 170 ++++++++++++++++------- 1 file changed, 122 insertions(+), 48 deletions(-) diff --git a/content/v2.0/monitor-alert/send-email.md b/content/v2.0/monitor-alert/send-email.md index 6d7eaf35e..108c4ac12 100644 --- a/content/v2.0/monitor-alert/send-email.md +++ b/content/v2.0/monitor-alert/send-email.md @@ -11,19 +11,19 @@ related: - /v2.0/monitor-alert/checks/ --- -Send an alert email using a third party service, such as SendGrid, AWS SES, or Mailjet. - -To send an alert email, do the following: +Send an alert email using a third party service, such as SendGrid, AWS Simple Email Service (SES), Mailjet, or Mailgun. To send an alert email, complete the following steps: 1. [Create a check](/v2.0/monitor-alert/checks/create/#create-a-check-in-the-influxdb-ui) to identify the data to monitor and the status to alert on. -2. Set up your preferred email service: - - **SendGrid**: See [Getting Started With the SendGrid API](https://sendgrid.com/docs/API_Reference/api_getting_started.html) and complete the prerequisites. - - **AWS Simple Email Service (SES)**: See [Using the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email.html). {{% note %}} Your AWS SES request, including the url (endpoint), authentication, and the structure of the request may vary. For more information, see [Amazon SES API requests](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-requests.html) and [Authenticating requests to the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-authentication.html). - - **Mailjet**: See [Getting Started](https://dev.mailjet.com/email/guides/getting-started/). +2. Set up your preferred email service (sign up, retrieve API key, and send test email): + - **SendGrid**: See [Getting Started With the SendGrid API](https://sendgrid.com/docs/API_Reference/api_getting_started.html) + - **AWS Simple Email Service (SES)**: See [Using the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email.html). Your AWS SES request, including the url (endpoint), authentication, and the structure of the request may vary. For more information, see [Amazon SES API requests](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-requests.html) and [Authenticating requests to the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-authentication.html). + - **Mailjet**: See [Getting Started](https://dev.mailjet.com/email/guides/getting-started/) + - **Mailgun**: See [Mailgun Signup](https://signup.mailgun.com/new/signup) 3. [Create an alert email task](#create-an-alert-email-task) to call your email service and send an alert email. - {{% note %}} In the procedure below, we use the **Task UI** to create a task. Explore other ways to [create a task](/v2.0/process-data/manage-tasks/create-task/). - {{% /note %}} + {{% note %}} + In the procedure below, we use the **Task UI** to create a task. Explore other ways to [create a task](/v2.0/process-data/manage-tasks/create-task/). + {{% /note %}} ### Create an alert email task @@ -34,45 +34,57 @@ To send an alert email, do the following: 2. Click **{{< icon "plus" >}} Create Task**, and then select **New Task**. 3. In the **Name** field, enter a descriptive name, for example, **Send alert email**, and then schedule how often to run the task, for example, every `10m`. For more detail, such as using cron syntax or including an offset, see [Task configuration options](/v2.0/process-data/task-options/). -4. In the right panel, enter your **task script** with the **following detail**: +4. In the right panel, enter the following detail in your **task script** (see [examples below](#examples)): - Import the [Flux HTTP package](/v2.0/reference/flux/stdlib/http/). + - (Optional) Store your API key as a secret for reuse. First, import the [Flux InfluxDB Secrets package](/v2.0/reference/flux/stdlib/secrets/), and then [add your API key as a secret](/v2.0/security/secrets/manage-secrets/add/). - Specify the `_monitoring` bucket and `statuses` measurement. InfluxDB stores all [check](/v2.0/reference/glossary/#check) output data in this bucket and measurement. - - Specify the time range to monitor; use the same interval that the task is scheduled to run. - - Specify the `TARGET` as `EMAIL`. - - Specify the `_field` as `_message`. + - Set the time range to monitor; use the same interval that the task is scheduled to run. - Set the `_level` to alert on, for example, `crit`, `warn`, `info`, or `ok`. + - Use the `map()` function to evaluate the criteria to send an alert using `http.post()`. + - Specify your email service `url` (endpoint), include applicable request `headers`, and verify your request `data` format follows the format specified for your email service. -5. Use the `map()` function to specify the criteria to send an alert using `http.post()`. +#### Examples -#### Examples - alert email task script +{{< tabs-wrapper >}} +{{% tabs %}} +[SendGrid](#) +[AWS SES](#) +[Mailjet](#) +{{% /tabs %}} -##### SendGrid + +{{% tab-content %}} The example below uses the SendGrid API to send an alert email when more than 3 critical statuses occur within 10 minutes. -``` +```js import "http" +// Import the Secrets package if you store your API key as a secret. +// For detail on how to do this, see Step 4 above. +import "influxdata/influxdb/secrets" + +// Retrieve the secret if applicable. Otherwise, skip this line +// and add the API key as the Bearer token in the Authorization header. +SENDGRID_APIKEY = secrets.get(key: "SENDGRID_APIKEY") + numberOfCrits = from(bucket: "_monitoring") |> range(start: -10m) |> filter(fn: (r) => (r["_measurement"] == "statuses")) - |> filter(fn: (r) => (r["TARGET"] == "EMAIL")) - |> filter(fn: (r) => (r["_field"] == "_message")) |> filter(fn: (r) => (r["_level"] == "crit")) |> count() numberOfCrits |> map(fn: (r) => - (if r._value > 3 then {r with _value: http.post(url: "https://api.sendgrid.com/v3/mail/send", headers: {"Content-Type": "application/json", "Authorization": "Bearer "}, data: bytes(v: "{ - \"personalizations\": [{ - \"to\": [{ - \"email\": \”jane.doe@example.com\" - }], - \"subject\": \”InfluxData critical alert\" + (if r._value > 3 then {r with _value: http.post(url: "https://api.sendgrid.com/v3/mail/send", + headers: {"Content-Type": "application/json", "Authorization": "Bearer ${SENDGRID_APIKEY}", + data: bytes(v: "{ + \"personalizations\": [{ + \"to\": [{ + \"email\": \”jane.doe@example.com\"}], + \"subject\": \”InfluxData critical alert\" }], - \"from\": { - \"email\": \"john.doe@example.com\" - }, + \"from\": {\"email\": \"john.doe@example.com\"}, \"content\": [{ \"type\": \"text/plain\", \"value\": \”Example alert text\" @@ -80,36 +92,43 @@ numberOfCrits }\""))} else {r with _value: 0})) ``` -##### AWS Simple Email Service (SES) +{{% /tab-content %}} + + +{{% tab-content %}} The example below uses the AWS SES API v2 to send an alert email when more than 3 critical statuses occur within 10 minutes. {{% note %}} Your AWS SES request, including the url (endpoint), authentication, and the structure of the request may vary. For more information, see [Amazon SES API requests](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-requests.html) and [Authenticating requests to the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-authentication.html). We recommend signing your AWS API requests using the [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html). {{% /note %}} -``` +```js import "http" +// Import the Secrets package if you store your API key as a secret. +// For detail on how to do this, see Step 4 above. +import "influxdata/influxdb/secrets" + +// Retrieve the secret if applicable. Otherwise, skip this line +// and add the API key as the Bearer token in the Authorization header. +SENDGRID_APIKEY = secrets.get(key: "SENDGRID_APIKEY") + numberOfCrits = from(bucket: "_monitoring") |> range(start: -10m) |> filter(fn: (r) => (r["_measurement"] == "statuses")) - |> filter(fn: (r) => (r["TARGET"] == "EMAIL")) - |> filter(fn: (r) => (r["_field"] == "_message")) |> filter(fn: (r) => (r["_level"] == "crit")) |> count() numberOfCrits |> map(fn: (r) => - (if r._value > 3 then {r with _value: http.post(url: "https://email.your-aws-region.amazonaws.com/sendemail/v2/email/outbound-emails", headers: {"Content-Type": "application/json", "Authorization": "AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE,SignedHeaders=Date;x-amz-date,Signature=9d63c3b5b7623d1fa3dc7fd1547313b9546c6d0fbbb6773a420613b7EXAMPLE"}, data: bytes(v: "{ - \"personalizations\": [{ - \"to\": [{ - \"email\": \”jane.doe@example.com\" - }], - \"subject\": \”InfluxData critical alert\" + (if r._value > 3 then {r with _value: http.post(url: "https://email.your-aws-region.amazonaws.com/sendemail/v2/email/outbound-emails", headers: {"Content-Type": "application/json", "Authorization": "AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE,SignedHeaders=Datex-amz-date,Signature=9d63c3b5b7623d1fa3dc7fd1547313b9546c6d0fbbb6773a420613b7EXAMPLE"}, + data: bytes(v: "{ + \"personalizations\": [{ + \"to\": [{ + \"email\": \”jane.doe@example.com\"}], + \"subject\": \”InfluxData critical alert\" }], - \"from\": { - \"email\": \"john.doe@example.com\" - }, + \"from\": {\"email\": \"john.doe@example.com\"}, \"content\": [{ \"type\": \"text/plain\", \"value\": \”Example alert text\" @@ -117,33 +136,88 @@ numberOfCrits }\""))} else {r with _value: 0})) ``` -##### Mailjet +{{% /tab-content %}} -The example below uses the Mailjet Send API to send an alert email when more than 1 critical statuses occurs within 10 minutes. + +{{% tab-content %}} + +The example below uses the Mailjet Send API to send an alert email when more than 3 critical statuses occur within 10 minutes. {{% note %}} To view your Mailjet API credentials, sign in to Mailjet and open the [API Key Management page](https://app.mailjet.com/account/api_keys). {{% /note %}} -```sh +```js import "http" +// Import the Secrets package if you store your API key as a secret. +// For detail on how to do this, see Step 4 above. +import "influxdata/influxdb/secrets" + +// Retrieve the secret if applicable. Otherwise, skip this line +// and add the API key as the Bearer token in the Authorization header. +SENDGRID_APIKEY = secrets.get(key: "SENDGRID_APIKEY") + numberOfCrits = from(bucket: "_monitoring") |> range(start: -10m) |> filter(fn: (r) => (r["_measurement"] == "statuses")) - |> filter(fn: (r) => (r["TARGET"] == "EMAIL")) - |> filter(fn: (r) => (r["_field"] == "_message")) |> filter(fn: (r) => (r["_level"] == "crit")) |> count() numberOfCrits |> map(fn: (r) => - (if r._value > 1 then {r with _value: http.post(url: "https://api.mailjet.com/v3.1/send", headers: {"Content-type": "application/json", Authorization: "Basic : 3 then {r with _value: http.post(url: "https://api.mailjet.com/v3.1/send", headers: {"Content-type": "application/json", Authorization: "Basic :Hello, welcome to Mailjet!
}]}' + \"HTMLPart\": `"

Hello, to review critical alerts, review your Critical Alert Dashboard

}]}' }\""))} else {r with _value: 0})) ``` + +{{% /tab-content %}} + +{{< /tabs-wrapper >}} + +--- + + + + +