Pipeline tracing in Exchange 2013
Applies to: Exchange Server 2013
Pipeline tracing captures copies of email messages from a specific sender as they move through the Transport service on Mailbox servers, the Mailbox Transport Delivery service on Mailbox servers, and through Edge Transport servers.. Pipeline tracing captures verbose information about the changes that each transport agent applies to messages in the transport pipeline in message snapshot files. By examining the contents of the message snapshot files, you can determine whether the transport agents have applied the changes to the messages in the transport pipeline that you expected. If you are troubleshooting a problem, you should determine which transport agent is at fault. Then you can focus your troubleshooting efforts on that agent to resolve the problem. You can then view the message snapshot files again to verify that your solution is successful.
Warning
- Pipeline tracing copies the complete contents of email messages that are sent from the sender's email address. To avoid unwanted exposure of confidential information, you need to set appropriate security permissions on the pipeline tracing folder.
- Don't enable pipeline tracing for long periods of time. Pipeline tracing creates files that can accumulate quickly. Always monitor available disk space when pipeline tracing is enabled.
Configure pipeline tracing
Before you enable pipeline tracing, you need to specify the sender's email address you want to monitor. Pipeline tracing is designed to log messages sent from a specific email address. The sender's email address can be internal or external to your Exchange organization. Alternatively, you can enable pipeline tracing for system messages generated by the transport service on the specified Mailbox or Edge Transport server, such as automatic replies, delivery status notification (DSN) messages, journal reports, and other system-generated messages You can also modify the location of the pipeline tracing folder.
The parameters that you use to configure pipeline tracing are summarized in the following table:
| Cmdlet | Parameter | Default value | Description |
|---|---|---|---|
| Set-TransportService Set-MailboxTransportService |
PipelineTracingSenderAddress | Blank ($null) |
Specify the email address of the sender you want to monitor. Specify the value " |
| Set-TransportService Set-MailboxTransportService |
PipelineTracingPath | Transport service: %ExchangeInstallPath%TransportRoles\Logs\Hub\PipelineTracing Mailbox Transport service: |
The path must be on the local server. UNC paths aren't supported. The specified path contains the |
| Set-TransportService Set-MailboxTransportService |
PipelineTracingEnabled | $false |
You can only enable pipeline tracing for the specified transport service on the server after you configure the sender address you want to monitor. |
For more information about how to enable pipeline tracing and configure the sender address for pipeline tracing, see Configure pipeline tracing.
Message snapshot files
Message snapshots are files that capture any changes made to a message by transport agents in the Transport service or the Mailbox Transport Delivery service. These files are stored in the MessageSnapshots folder in the corresponding pipeline tracing path for the transport service.
In the MessageSnapshots folder, Exchange creates one folder for each message sent by the monitored sender that flows through the specified transport service. Each folder is named after a GUID that's assigned to the message. If you enable pipeline tracing for the Transport service and the Mailbox Transport service on the same Mailbox server, a different GUID is assigned to the same message by each transport service, so the folder name for a message in the MessageSnapshots folder for the Transport service is different than the folder name for the same message in the MessageSnapshots folder for the Mailbox Transport service. If you enable pipeline tracing on more than one Exchange server, a different GUID is assigned to the same message as it travels through the specified transport service on each Exchange server.
In each message folder, Exchange creates several message snapshot files that have .eml file extensions. These message snapshot files contain the contents of the message as it encounters each SMTP event and transport agent.
If a transport agent is registered on an SMTP event, Exchange creates a message snapshot of the message before the message encounters any transport agents. This gives you a copy of the message before the message encounters transport agents that are registered on that event. Then, a new message snapshot is created for each transport agent that the message encounters, regardless of whether a transport agent modifies the contents of the message. However, if no agents are registered on an event, Exchange doesn't create any messages snapshots for that event.
For example, if three agents are registered on the OnEndofData event but only two of the transport agents modify a message, four message snapshots are created. The first message snapshot captures the message as it encounters the OnEndofData event before any modifications that are made by the transport agents that registered on that event. Then, one message snapshot is created for each transport agent regardless of whether a transport agent modifies the message.
The message snapshot files that are created are described in the following list:
Original.eml: This file contains the original unmodified contents of the email message before it encounters any SMTP events or transport agents.
Routingnnnn.eml: These files contain the contents of the email message as it encounters transport the SMTP events and transport agents registered on those events in the categorization part of the Transport service. The placeholder nnnn represents an integer value that starts with
0001. The value is incremented for every SMTP event and transport agent registered on those events in the order in which the events and agents act on the message. The Mailbox Transport Delivery service doesn't generate these Routing snapshot files.SmtpReceivennnn.eml: These files contain the contents of the email message as it encounters the OnEndofData and OnEndOfHeaders SMTP events and transport agents registered on those events during the SMTP receive part of the Transport service or the Mailbox Transport Delivery service. The placeholder nnnn represents an integer value that starts with
0001. The value is incremented for every SMTP event and transport agent registered on those events in the order in which the events and agents act on the message.
You can open the message snapshot files by using Notepad or any text editor.
Each message snapshot file starts with headers that are added to the message contents and list the SMTP event and transport agent that the message snapshot file relates to. These headers start with X-CreatedBy: MessageSnapshot-Begin injected headers and end with X-EndOfInjectedXHeaders: MessageSnapshot-End injected headers. These headers are replaced in each message snapshot file by each subsequent transport agent and SMTP event. The following is an example of the headers that are added to an email message file:
X-CreatedBy: MessageSnapshot-Begin injected headers
X-MessageSnapshot-UTC-Time: 2013-01-23T23:20:18.138Z
X-MessageSnapshot-Record-Id: 21474836486
X-MessageSnapshot-Source: OnSubmittedMessageX-Sender: michelle@nwtraders.com
X-Receiver: chris@contoso.com
X-EndOfInjectedXHeaders: MessageSnapshot-End injected headers
After the message snapshot headers, the file contains the contents of the message including all the original message headers. If a transport agent modifies the contents of the message, the changes appear integrated with the message. As the message is processed by each transport agent, the changes that are made by each agent are applied to the message contents. If a transport agent makes no changes to the message contents, the message snapshot that is created by that agent will be identical to the message snapshot created by the previous transport agent.