Skip to content

Configure Message Trace inputs for the Splunk Add-on for Microsoft Office 365

Description: Message Trace provides detailed insights into email message flow within a system, tracking message delivery, status, and potential issues.

Prerequisites:

Before you enable inputs, complete the previous steps in the configuration process:

Supported environments

Microsoft Graph Message Trace (/admin/exchange/tracing/messageTraces) is available only in Global service and is not available in US Government L4, US Government L5 (DOD), or China operated by 21Vianet. In this add-on, Message Trace runs only for tenants configured with endpoint Worldwide.

Provisioning behavior

During the first Message Trace run, the add-on attempts to provision the required Microsoft service principal (8bd644d1-64a1-4d4b-ae52-2e0cbf64e373) automatically when Application.ReadWrite.All is granted. If you do not want to grant this extra permission, pre-provision the service principal manually using the Microsoft prerequisites documentation. Provisioning changes on the Microsoft side can take up to a few hours before Message Trace data becomes available.

Message Trace sourcetype

Message Trace events collected through Microsoft Graph use sourcetype o365:graph:messagetrace. The legacy sourcetype o365:reporting:messagetrace is retained for historical events that were ingested using the retired Reporting Web Service API.

Configure inputs using Splunk Web

Configure your inputs using Splunk Web on the Splunk platform instance that you have designated as your configuration server, and is responsible for collecting data for this add-on. The best practice for this is usually a heavy forwarder.

  1. Launch the Splunk add-on for Microsoft Office 365.
  2. Click on the Inputs tab.
  3. Click Create New Input.
  4. Select “Message Trace”.
  5. Enter the Input Name, Tenant Name, Start Date Time, Input Mode, and Index using information in the input parameter table below.
  6. Click Add.
  7. Enter the details of the given fields in the input page using the information in the input parameter table below.
  8. Verify that data is successfully arriving by running the following search on your search head:

Splunk Search

sourcetype=o365:graph:messagetrace

If you do not see any events, check the Troubleshooting tab on your data collection node to verify that your accounts, forwarders, and inputs are all configured successfully.

Configure inputs in the configuration files

Configure your inputs using the configuration files on the Splunk platform instance responsible for collecting data for this add-on, usually a heavy forwarder.

  1. Navigate to $SPLUNK_HOME/etc/apps/Splunk_ta_o365/local/, and create an inputs.conf
  2. Open the inputs.conf file with a text editor.
  3. Add the following stanza.
[splunk_ta_o365_message_trace://<messagetrace_input_name>]
delay_throttle = <value>
input_mode = <value>
interval = <value>
tenant_name = <value>
query_window_size = <value>
start_date_time = <value>
end_date_time = <value>
index = <value>
  1. (Optional) Configure a custom index.
  2. Restart your Splunk platform instance.
  3. Verify that data is successfully being ingested by running the following search on your search head:

Splunk Search

sourcetype=o365:graph:messagetrace

If you do not see any events, check the Troubleshooting tab on your data collection node to verify that your accounts, forwarders, and inputs are all configured successfully.

Input parameters

Each attribute in the following table corresponds to a field in Splunk Web.

Input Name Corresponding field in Splunk Web Description
messagetrace_input_name Name A unique name for your input.
tenant_name Tenant Name Select the configured tenant from where you want to gather data.
input_mode Input Mode Input Mode Types:
Continuously Monitor:- Continuously ingesting data into the Splunk platform based on the Query Window Size.
Index Once:- Ingest data only once and ignore “Query window size” and “Delay throttle”. Additionally, “Start date/time” and “End date/time” are required.
start_date_time Start Date/Time Select a Start date/time to specify how far back to go when initially collecting data. This parameter is optional when Continuously Monitor is selected, but the parameter is required when Index Once is selected.
If no date/time is given, the input will start 5 days in the past.
Format: YYYY-MM-DDTHH:MM:SS, interpreted as UTC. The Microsoft Graph Message Trace API is queried using UTC timestamps. The start date/time cannot be more than 90 days in the past.
end_date_time End Date/Time End date/time for data collection. Required when Index Once is selected.
Format: YYYY-MM-DDTHH:MM:SS, interpreted as UTC. Use the same UTC format as start_date_time.
index Index The index in which the Message Trace data should be stored. The default is main.
interval Interval (seconds) Rerun the input after the defined value, in seconds.

Note: If the Input mode is Index Once then the interval must be -1
query_window_size Query Window Size (minutes) When Continuously Monitor is selected, each time this input runs a start date is calculated for the Graph Message Trace API query. The end date for the query is the calculated start date plus this value. Allowed range is 1 to 14400 minutes (maximum 10 days per query window).
delay_throttle Delay Throttle (minutes) This parameter specifies how close to “now” the end date for a query may be (where “now” is the time that the input runs). The value must be 0 or greater.