Splunk® Enterprise

Alerting Manual

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Email notification action

You can configure an alert to send an email notification to specified recipients when the alert triggers. You can send the email notification as a multipart MIME message that includes both HTML and text parts. You can also send the notification as plain text.

You configure the email notification action for an alert when you save the alert from the Search page. You can also configure email notification from the Alerts Page and directly from a search command.

Email notification contexts

There are several contexts from which you can send email notifications. The email options available differ, depending on the context.

  • Alert actions
    Send email notifications as an alert action from a search. Specify the notification from the Search Page, a listing in the Alerts Page, or directly from the search command.
  • Scheduled report
    Configure email notifications for a scheduled report either from a listing in the Reports Page or from a report.
  • Scheduled PDF delivery of dashboards
    Configure PDF delivery either from a listing in the Dashboards Page or from a dashboard.

This topic covers alert actions from a search job. See Schedule reports and Generate Dashboard PDFs for information on the other contexts for email notification.

Configure email notification for alerts

You can configure email notifications when you save a search as an alert. You can also configure email notifications for when editing an alert's actions. The procedure is the same in both cases.

After running a search, save the search as an alert and configure email notification settings.

  1. Run the search.
  2. Select Save As > Alert.
  3. Provide a Title and other information about the alert.
  4. From the Add Actions menu, select Send email.

    AlertEmailNotification.png

  5. Specify the following:

    • To, CC, and BCC email recipients.
      Specify a comma-separated list of email recipients.
    • Priority
      Enforcement of priority depends on your email client.
    • Subject
    • Message
    • Include
      You can include the following items:

      Information about the search
        Link to the alert
        Search string
        Trigger condition
        Trigger time

      Information about search results
        Link to results
        Inline listing of results, as a table, raw events, or CSV file
        Results as a PDF attachment
        Results as a CSV attachment
    • Type
      Select HTML & Plain Text (multi-MIME message) or Plain Text
  6. Specify other alert actions.
    See set up alert actions for more information.
  7. Click Save.

Send email notification from a search command

You can send email notifications directly from the sendemail search command. For example:

index=main | head 5 | sendemail to=example@splunk.com server=mail.example.com subject="Here is an email notification" message="This is an example message" sendresults=true inline=true format=raw sendpdf=true

See the sendemail command listing in the Search Reference for details.

Send email to different recipients based on search results

This search example works with a token in the To email notification field to handle different notifications based on the result count. If there are more than 3500 results, a notification goes to recipient1. If there are fewer than 500 results, the notification goes to recipient2. If neither condition applies, then no notification is sent.

Here is the search.

"error" | stats count | eval recipient=case(count > 3500, "recipient1@domain.com", count >= 500, "recipient2@domain.com", 1==1, null()) | where isnotnull(recipient)

When the search is saved as an alert, configure the Send email alert action with the following token in the To recipient field.

$result.recipient$

Use tokens in email notifications

A token is a type of variable that represents data generated by a search job. Splunk Enterprise provides tokens that you can use to include information generated by a search in the fields of an email:

  • To
  • Cc
  • Bcc
  • Subject
  • Message
  • Footer

Access the value of a token with the following syntax:

$<token-name>$

For example, place the following token in the subject field of an email notification to reference the search ID of a search job.

Search results from $job.sid$

Tokens available for email notifications

This section lists common tokens you can use in email notifications. There are four categories of tokens that access data generated from a search. The context for using the tokens differ.

Category Description Context
Search metadata Information about the search. Alert actions from search
Scheduled reports
Scheduled PDF delivery of dashboards
Search results Access results of a search Alert actions from search
Scheduled reports
Job information Data specific to a search job Alert actions from search
Scheduled reports
Server information Information about the Splunk Enterprise server Alert actions from search
Scheduled reports
Scheduled PDF delivery of dashboards

In addition to the common tokens listed in this topic, the savedsearches.conf and alert_action.conf configuration files list attributes whose values are available from tokens. To access these attribute values, place the attribute between the '$' token delimiters. For example, to access the subject of an email notification, reference the following attribute listed in savedsearches.conf:

$action.email.subject$

Tokens that access search metadata

Common tokens that access information about a search. These tokens are available from the following contexts:

  • Alert actions
  • Scheduled reports
  • Scheduled PDF delivery of dashboards

Here are some of the common tokens available.

Token Description
$action.email.hostname$ Hostname of the email server.
$action.email.priority$ Priority of the search.
$app$ Name of the app containing the search.
$cron_schedule$ Cron schedule for the app.
$description$ Description of the search.
$name$ Name of the search.
$next_scheduled_time$ The next time the search runs.
$owner$ Owner of the search.
$results_link$ (Alert actions and scheduled reports only) Link to the search results.
$search$ The actual search.
$trigger_date$ (Alert actions only) The date that triggers the alert.
$trigger_time$ (Alert actions only) The scheduled time the alert runs.
$type$ Indicates if the search is from an alert, report, view, or the search command.
$alert.severity$ Severity level of the alert.
$alert.expires$ Time the alert expires.

Tokens available from results

From results, you use the result.<fieldname> token to access the first value of a specified field in search results. This token is available from the following contexts:

  • Alert actions
  • Scheduled reports
Token Description
$result.fieldname$ Returns the first value for the specified field name from the first result in the search. The field name must be present in the search.

Tokens that access job information

Common tokens that access data specific to a search job, such as the search ID or messages generated by the search job. These tokens are available from the following contexts:

  • Alert actions
  • Scheduled reports
Token Description
$job.earliestTime$ Initial time a search job starts.
$job.eventSearch$ Subset of the search that contains the part of the search before any transforming commands.
$job.latestTime$ Latest time recorded for the search job.
$job.messages$ List of error and debug messages generated by the search job.
$job.resultCount$ Number of results returned by the search job.
$job.runDuration$ Time, in seconds, that the search took to complete.
$job.sid$ Search ID.
$job.label$ Name given to the search job.

Tokens available from server

Common tokens that provide details available from your Splunk Enterprise server. They are available in the following contexts:

  • Alert actions
  • Scheduled reports
  • Scheduled PDF delivery of dashboards
Token Description
$server.build$ Build number of the Splunk Enterprise instance.
$server.serverName$ Server name hosting the Splunk Enterprise instance.
$server.version$ Version number of the Splunk Enterprise instance.

Deprecated email notification tokens

The following tokens from prior releases of Splunk Enterprise are deprecated.

Token Description
$results.count$ (Deprecated) Use $job.resultCount$.
$results.url$ (Deprecated) Use $results_link$.
$results.file$ (Deprecated) No equivalent available.
$search_id$ (Deprecated) Use $job.id$.

Configure email notification settings

Before you send an email notification for an alert, configure email notification settings.

Prerequisites

Here are the steps for configuring email notification settings in Splunk Web.

  1. Navigate to Settings > Server settings > Email settings.
  2. Select Mail Server Settings. Enter the following details.
    • Mail host. The default is localhost.
    • Email security.
    • (Optional) Username.
    • (Optional) Password.
  3. Specify Email Format. Specify the following details.
    • Link hostname. The host name of the server used for creating URLs for outgoing results.
    • Send emails as. Enter an email address or a string specifying the sender.
    • Email footer. Footer text for each email. You can use tokens in the email footer.
  4. Specify the following PDF Report Settings.
    • Report Paper Size.
    • Report Paper Orientation.
  5. Click Save.

To learn about configuring email alert notifications using a configuration file, see alert_actions.conf.

User role configuration to schedule PDF delivery of dashboards

For a user to schedule PDF delivery of dashboards, the user role must contain the following capabilities:

  • schedule_search
  • admin_all_objects
    This capability is required only if the mail host requires log-in credentials.

See About defining roles with capabilities.

PREVIOUS
Set up alert actions
  NEXT
Use a webhook alert action

This documentation applies to the following versions of Splunk® Enterprise: 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.3.14


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters