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:

Tenant endpoint API used Sourcetype
Worldwide Microsoft Graph Message Trace API o365:graph:messagetrace
USGovGCC Exchange Online Reporting Web Service o365:reporting:messagetrace
USGovGCCHigh Exchange Online Reporting Web Service o365:reporting:messagetrace

For Worldwide tenants, configure application permissions in Microsoft Graph:

  • ExchangeMessageTrace.Read.All (required)
  • Application.ReadWrite.All (optional, only for automatic provisioning by the input)

In Microsoft Entra ID, go to API Permissions > Add a permission > Microsoft Graph > Application permissions, add the permissions you want to use, and grant admin consent.

Complete the Microsoft Graph Message Trace prerequisites in Microsoft documentation: exchangeMessageTrace prerequisites. You can complete prerequisites either automatically (by granting Application.ReadWrite.All) or manually (without granting it to the add-on app).

For USGovGCC and USGovGCCHigh tenants, configure the ReportingWebService.Read.All application permission in Exchange Online. The Microsoft Graph permissions mentioned on this page are not required.

Provisioning behavior (Worldwide only)

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. This automatic provisioning step does not apply to USGovGCC or USGovGCCHigh tenants.

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 OR 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>
  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 OR 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 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 for Worldwide tenants. For USGovGCC and USGovGCCHigh tenants (RWS API), the maximum lookback is 10 days.
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.