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

Description: Message Trace rovides 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:

• Configure an integration application in Microsoft Entra ID (Azure AD) for the Splunk Add-on for Microsoft Office 365
• Configure a Tenant in the Splunk Add-on for Microsoft Office 365
• Configure application to have one of the following IAM roles.
  • Exchange Administrator
  • Global Administrator
  • Global Reader role
• Configure application to have the ReportingWebService.Read.All permission. To add the permission, follow the following steps:
  • Navigate to Application permissions in the API Permissions > Add a permission
  • Select APIs my organisation uses
  • Select Office 365 exchange online by searching in the search box
  • Select Application Permission, and search for ReportingWebService
  • Add the ReportingWebService.Read.All permission

Note

The Message Trace API for the Splunk Add-on for Microsoft Office 365 does not support data collection for USGovGCC and USGovGCCHigh endpoints.

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:reporting: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>

4. (Optional) Configure a custom index.
5. Restart your Splunk platform instance.
6. Verify that data is successfully being ingested by running the following search on your search head:

Splunk Search

sourcetype=o365:reporting: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 7 days in the past.
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 Office 365 API query. The end date for the Office 365 API query will be the calculated start date plus the number of minutes specified by this parameter. For example, if the calculated start date is 2022-01-01T00:00:00 (midnight on January 1, 2022), the end date for the query will be 2022-01-01T00:01:00 (one hour after midnight) if the query window size is 60 minutes.
delay_throttle	Delay Throttle (minutes)	Microsoft may delay trace events for up to 24 hours, and events are not guaranteed to be sequential during this delay. For more information, see the Data granularity, persistence, and availability section of the Message Trace report topic in the Microsoft documentation. This parameter specifies how close to “now” the end date for a query may be (where “now” is the time that the input runs). Continuing from the example above, if “now” is 2022-01-01T00:02:00 (two minutes after midnight) and the delay throttle is 60 minutes, the input will exit because the end date for the query is only 1 minute away from “now”. Each time the input runs, the input will exit and do nothing until the end date is at least 60 minutes away from “now”.