Using Pipeline Tracing to Diagnose Transport Agent Problems
Applies to: Exchange Server 2007 SP1, Exchange Server 2007
Topic Last Modified: 2007-02-12
Pipeline tracing is a diagnostic feature in Microsoft Exchange Server 2007 that enables you to capture diagnostic information about e-mail messages as they encounter transport agents registered on Simple Mail Transfer Protocol (SMTP) events in the transport pipeline. Exchange captures verbose information about the changes that each transport agent applies to messages in the transport pipeline in message snapshot files. If transport rules are configured, Exchange Server also records any actions that each transport rule takes on these messages.
Pipeline tracing is configured per server in your organization and can be enabled on computers that have the Hub Transport server role and the Edge Transport server role installed.
When you enable pipeline tracing and use the default location of the pipeline tracing log file, the C:\Program Files\Microsoft\Exchange Server\TransportRoles\Logs\PipelineTracing is created. This directory contains the MessageSnapshots directory and the RulesTracking directory.
Pipeline tracing is designed to log messages that are sent only from a specific sender's SMTP e-mail address. The sender's SMTP address can be a mailbox that is inside or outside your Exchange organization. Before you enable pipeline tracing, you must specify a sender SMTP address for pipeline tracing. You can configure the sender SMTP address for pipeline tracing by using the PipelineTracingSenderAddress parameter on the Set-TransportServer cmdlet.
After you configure the sender SMTP address for pipeline tracing, you can modify the location of the pipeline tracing log files if you want. You must put the pipeline tracing log files on the local computer. You can't use Universal Naming Convention (UNC) file paths or mapped drives.
|Pipeline tracing copies the complete contents of e-mail messages that are sent from the sender's e-mail address. To avoid unwanted exposure of confidential information, you must set appropriate security permissions on the location of the pipeline tracing log file.|
|Do not enable pipeline tracing for long periods of time. Pipeline tracing creates verbose log files that can accumulate quickly. Always monitor available disk space when pipeline tracing is enabled.|
You can configure the location of the pipeline tracing log files by using the PipelineTracingPath parameter on the Set-TransportServer cmdlet. For more information, see Set-TransportServer.
For more information about how to enable pipeline tracing and configure the sender address for pipeline tracing, see How to Enable Pipeline Tracing.
Message snapshots are files that capture the exact changes, if any, transport agents make to a message. 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.
In the MessageSnapshots directory, Exchange creates one directory for each message that flows through the transport pipeline when pipeline tracing is enabled. Each directory is created by using the GUID that is assigned to the message as the directory name by the computer that is running Microsoft Exchange. If pipeline tracing is enabled on more than one Exchange server, a different GUID is assigned to the message on each Exchange server.
In each message directory, Exchange creates several message snapshot files that have .eml extensions. These message snapshot files contain the contents of the message as it encounters each event and transport agent.
Exchange creates message snapshots for agents that are registered on the four following events:
If a transport agent is registered to an 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 following list is an example of the files that can be created in a default installation of an Edge Transport server role:
- Original.eml This file contains the original unmodified contents of the e-mail message before it encounters any events or transport agents. If no transport agents are configured on any events, only this file is created.
- SmtpReceive0001.eml to SmtpReceive0009.eml These files contain the contents of the e-mail message as it encounters the OnEndofData and OnEndOfHeaders events and transport agents that are registered on those events in the SMTP receive part of the transport pipeline.
- Routing0001.eml and Routing0002.eml These files contain the contents of the e-mail message as it encounters transport the OnSubmittedMessage and OnRoutedMessage events and transport agents that are registered on those events in the categorization part of the transport pipeline.
You can open the message snapshot files by using a text editor, such as Notepad.
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. The following is an example of the headers that are added to an e-mail message that is processed by the Connection Filter agent on the OnEndOfHeaders event:
X-CreatedBy: MessageSnapshot-Begin injected headers X-MessageSnapshot-UTC-Time: 2006-07-31T23:18:55.972Z X-MessageSnapshot-Protocol-Id: 08C87FF14CCC969C;2006-07-31T23:18:53.408Z;1 X-MessageSnapshot-Source: OnEndOfHeaders,Connection Filtering Agent X-Sender: firstname.lastname@example.org X-Receiver: email@example.com X-EndOfInjectedXHeaders: MessageSnapshot-End injected headers
Underneath the message snapshot headers are 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.
The rules tracking file captures the result of each transport rule as it is applied to a message that encounters the Transport Rules agent on a Hub Transport server or Edge Rules agent on an Edge Transport server. The results that are captured by the rules tracking file indicate whether a transport rule took an action against a message. If the transport rule took an action, the rules tracking file indicates what action was taken. The rules tracking file contains the following fields in the comma-separated value (.csv) format:
- Date-Time This field indicates the date and time that the transport rule was run in coordinated Universal Time (UTC), or Zulu time.
- Message-Id This field indicates the value of the
MessageID:field that is located in the message header. This value is constant for the lifetime of the message and can be used with message tracking logs to track a message's path through an Exchange organization.
- Rule-Name This field indicates the name of the transport rule run against the message.
- Details This field indicates the values of the transport rule action applied to a message. If multiple values are set on a single transport rule action, the values are separated by semi-colons (;). If the transport rule isn't applied to a message, the string Conditions evaluated to false. Rule skipped. is inserted.
- Action This field indicates the transport rule action that is applied to a message. If the transport rule isn't applied to a message, the string NoAction is inserted.
- From-Address This field indicates the SMTP address of the sender of the message.
- Recipient-Address This field indicates the SMTP address of the recipient or recipients of the message. If the transport rule action is applied to a message sent to multiple recipients that match the transport rule conditions, the recipients are separated by semi-colons (;).
Each transport rule action that is applied to a message is written to a separate line in the rules tracking file. For example, if a transport rule has three actions, the result of each transport rule action is written to a separate line in the rules tracking file.
If more than one recipient is included on an e-mail message, but not all recipients meet all the transport rule conditions, the recipients that don't meet the transport rule conditions are separated out and written to a separate line.