Understanding Agent Logging
Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2
Agent logs record the actions performed on a message by specific anti-spam agents installed and configured on a computer running Microsoft Exchange Server 2010 that has the Edge Transport server role or the Hub Transport server role installed. Only the following agents can write information to the agent log:
Connection Filter agent
Content Filter agent
Edge Rules agent
Recipient Filter agent
Sender Filter agent
Sender ID agent
The information written to the agent log depends on the agent, the SMTP event, and the action performed on the message.
The only configurable option for agent logging is the AgentLogEnabled parameter in the EdgeTransport.exe.config application configuration file. By default, agent logging is enabled on Hub Transport servers or Edge Transport servers. The other agent log values that aren't configurable are described in the following list:
Path where the agent logs are stored is C:\Program Files\Microsoft\Exchange Server\V14\TransportRoles\Logs\AgentLog.
Maximum size for the individual agent log files is 10 megabytes (MB).
Maximum size for the directory that contains the agent log files is 250 MB.
Maximum age for the agent log files is 30 days.
The Exchange 2010 server uses circular logging to limit the agent logs based on file size and file age to help control the hard disk space used by the log files.
Note
If you want to keep the agent log files longer than allowed by file age or directory size values that you can't configure, you can create a scheduled task that periodically moves the unused agent log files to a different location.
Note
By default, the transport logging process has a logging level value of 0 (Lowest). If you want Exchange to write an event log entry when circular logging removes a log file, you must change the logging level value of the transport logging process to 5 (Maximum) or 7 (Expert).
Contents
Overview of Transport Agents
Structure of the Agent Log Files
Information Written to the Agent Log
Searching the Agent Logs
Enable or Disable Agent Logging
Looking for management tasks related to agent logging? See Managing Transport Servers.
Overview of Transport Agents
Agents can only act upon messages at specific points in the SMTP command sequence used to transport the messages through a Hub Transport server or Edge Transport server. These access points in the SMTP command sequence are called SMTP events. Each agent has a priority value that can be assigned. However, the SMTP events must always occur in a specific order. Therefore, the agent priority depends on the SMTP event. If two agents can act on a message during the same SMTP event, the agent that has the highest priority will act on the message first.
The following table lists the SMTP events in order of occurrence and the agents that write information to the agent log in order of priority from highest to lowest for each SMTP event.
SMTP events in order of occurrence and the agents that write information to the agent log in order of priority for each SMTP event
| SMTP event | Agent |
|---|---|
OnConnect |
Connection Filter agent |
OnMailCommand |
Connection Filter agent Sender Filter agent |
OnRcptCommand |
Connection Filter agent Recipient Filter agent |
OnEndOfHeaders |
Connection Filter agent Sender ID agent Sender Filter agent |
OnEndOfData |
Edge Rules agent Content Filter agent |
For more information about agents, SMTP events, and agent priority, see Understanding Transport Agents.
Return to top
Structure of the Agent Log Files
The agent logs exist in C:\Program Files\Microsoft\Exchange Server\V14\TransportRoles\Logs\AgentLog.
The naming convention for the agent log files is AGENTLOGyyyymmdd-nnnn.log. The placeholders represent the following information:
The placeholder yyyymmdd is the Coordinated Universal Time (UTC) date that the log file was created. The placeholder yyyy = year, mm = month, and dd = day.
The placeholder nnnn is an instance number that starts at the value of 1 for each day.
Information is written to the log file until the file size reaches 10 MB. Then, a new log file that has an incremented instance number is opened. This process is repeated throughout the day. Circular logging deletes the oldest log files when the agent log directory reaches 250 MB, or when a log file is 30 days old.
The agent log files are text files that contain data in the comma-separated value file (CSV) format. Each agent log file has a header that contains the following information:
#Software Name of the software that created the agent log file. Typically, the value is Microsoft Exchange Server.
#Version Version number of the software that created the agent log file. Currently, the value is 8.0.0.0.
#Log-Type Log type value, which is Agent Log.
#Date UTC date-time when the log file was created. The UTC date-time is represented in the ISO 8601 date-time format: yyyy-mm-ddThh:mm:ss.fffZ, where yyyy = year, mm = month, dd = day, hh = hour, mm = minute, ss = second, fff = fractions of a second, and Z signifies Zulu, which is another way to denote UTC.
#Fields Comma delimited field names used in the agent log files.
Return to top
Information Written to the Agent Log
The agent log stores each agent transaction on a single line in the log. The information stored on each line is organized by fields. These fields are separated by commas. The field name is generally descriptive enough to determine the type of information it contains. However, some of the fields may be blank. Or the type of information stored in the field may change based on the agent or the action performed on the message by the agent. The following table describes the fields used to classify each agent transaction.
Fields used to classify each agent transaction
| Field name | Description |
|---|---|
Timestamp |
UTC date-time of the agent event. This is represented in the ISO 8601 format. The value is formatted as yyyy-mm-ddThh:mm:ss.fffZ, where yyyy = year, mm = month, dd = day, hh = hour, mm = minute, ss = second, fff = fractions of a second, and Z signifies Zulu, which is another way to denote UTC. |
SessionId |
Unique SMTP session identifier. This identifier is represented as a 16-digit hexadecimal number. |
LocalEndpoint |
Local IP address and port number that accepted the message. SMTP sessions typically use port 25. |
RemoteEndpoint |
IP address and port number of the previous SMTP server that connected to this server to deliver the message. In an Edge Transport server and Hub Transport server topology, the value of RemoteEndpoint in the agent log on the Hub Transport server will be the IP address of the Edge Transport server. Even though the message is transmitted by SMTP, the port number used by the sending server will be a random number larger than 1,024. |
EnteredOrgFromIP |
IP address of the remote SMTP server that first connected to the Exchange organization to deliver the message. On an Edge Transport server, the value of RemoteEndpoint and EnteredOrgFromIP are the same. Anti-spam agents use the IP address in EnteredOrgFromIP to examine a message. |
MessageId |
Value of the |
P1FromAddress |
Sender e-mail address specified in |
P2FromAddresses |
Sender e-mail address specified in the |
Recipient |
E-mail address of the recipients. Although the original message may contain multiple recipients, only one recipient is displayed per line in the agent log. |
NumRecipients |
Total number of recipients in the original message. |
Agent |
Name of the agent that took the action. The possible values are as follows:
|
Event |
SMTP event where the action was taken by the agent. The value of Event depends on the agent. The SMTP events available to each agent are described in the first table earlier in this topic. The possible values for Event are as follows:
|
Action |
Action performed on the message by the agent. The possible values for Action are as follows:
|
SmtpResponse |
Enhanced SMTP response as defined in RFC 2034. |
Reason |
Reason for the action supplied by the agent. |
ReasonData |
Descriptive details for the action supplied by the agent. |
Return to top
Searching the Agent Logs
You can use the Get-AgentLog cmdlet in the Exchange Management Shell and the Get-AntiSpamFilteringReport script to search the agent logs. For more information, see Get-AgentLog.
Return to top
Enable or Disable Agent Logging
By default, agent logging is enabled on a Hub Transport server or an Edge Transport server. Agent logging is enabled or disabled by modifying the EdgeTransport.exe.config file located in C:\Program Files\Microsoft\Exchange Server\V14\Bin. For more information, see Understanding the EdgeTransport.exe.Config File. EdgeTransport.exe and MSExchangeTransport.exe are the executable files used by the Microsoft Exchange Transport service.
Many available configuration options are unrelated to agent logging. Any configuration options that don't involve agent logging are outside the scope of this topic.
Open the following file by using Notepad: C:\Program Files\Microsoft\Exchange Server\V14\Bin\EdgeTransport.exe.config
Modify the following line in the
<appSettings>section.<add key="AgentLogEnabled" value="<TRUE | FALSE>" />This example disables agent logging by modifying the AgentLogEnabled parameter.
<add key="AgentLogEnabled" value="FALSE" />Save and close the EdgeTransport.exe.config file.
Restart the Microsoft Exchange Transport service.
Return to top
© 2010 Microsoft Corporation. All rights reserved.