The Agent writes messages to log files that are stored locally on the endpoint. For troubleshooting the following features are available:
The log level for specific endpoint can be modified from the Standard compact log file to a more comprehensive log level known as Trace.
In addition, all those collected log files (from both Standard and Trace level) can be pulled from the endpoint in order to make them available for downloading from the console (useful for sharing them with Proofpoint Support during troubleshooting).
Log Level Settings
The following are the 2 log levels that can be set:
-
Default: The recommended log level that is set by default for all endpoints and that captures standard log messages written by the Agent during operation.
-
Trace: The more comprehensive log level that captures much more information than the default log level, and is usually helpful for Agent troubleshooting.
Trace log level can be turned on for a selected endpoint from the Log Level area.
Generally, trace files are much larger than the standard log files. The trace files are stored on the endpoint’s local disk space. To make sure that agents do not run with the log level set to trace continuously, you are prompted to define the duration for this level (1 hour, 1 day, 3 days, 1 week). When the time defined is reached, the trace level is restored to the default level, and the trace is turned off.
You can set trace level by zone. Working with zones allows you to troubleshoot certain activities to zone in on the issues you want You can select all zones or specify the zone you want (Supported log zones are File Operation, Web Browsing, Web Upload. This includes Web Upload to USB, Web Upload to Sync Folder, Copy, Move, Rename and Delete.)
Enabling the Trace Level by Zone
To turn on the Trace Level, click Edit in the Log Level area. From the Log Level dropdown, select Trace for the zone you want, and then select the Duration you want.
By default the trace is not turned on and Log Level is set to Default (Recommended).
If you change the log level for a zone, you must reset any other previously set log levels.
Log Retrieval
You must contact Proofpoint Support for access to this feature.
This feature is behind a feature toggle and is intended for Proofpoint Support to request/enable the feature as/if required. In addition, if there are older agents, especially like 2.4.0438, special consideration is required.
Log Retrieval lets you schedule log file collection from specific endpoints.
When scheduled, log files are collected by the Agent and stored in a compressed (.zip) file that is sent to Proofpoint AWS S3 storage. The log files can then be downloaded locally and are available to share with Proofpoint Support.
The Agent will attempt to collect all the logs that are stored on the endpoint (both Standard and Trace level logs).
The Agent can collect up to 3 .zip files, each file size is not larger than 100MB (compressed).
When the collection is scheduled, an end time is automatically set for 7 days later. The Agent continues collecting for up to 7 days from the day the collection is scheduled. At 7 days, the collection is stopped whether or not it has expired.
The Agent collects all active files from newest to oldest. The Agent collects the files in the following order and format:
-
Agent logs:
ag-<session ID>-YYYY-MM-DD.log -
Agent Service logs:
sc-YYYY-MM-DD>log -
FAM logs (service):
famsc-YYYY-MM-DD.log -
FAM logs (agent):
famag-YYYY-MM-DD.log -
Content Detection logs:
contentdetectionsc-YYYY-MM-DD.log -
Agent Utility logs:
ut-YYYY-MM-DD.log
Log Retrieval Status
The status of the log retrieval can be one of the following:
-
Disabled: Log retrieval was previously completed and log retrieval is currently disabled. The status remains Disabled until another log retrieval is scheduled. This is the default status.
-
Expired: Log retrieval operation has ended.
-
Scheduled: Log retrieval operation is scheduled Agent will start collecting data at the next heartbeat signal. It will take approximately 10 minutes from the time the retrieval is scheduled until the retrieval actually starts.
-
In Progress: Log retrieval has begun and is in progress.
-
Completed: Log retrieval was completed. The scheduled End time has not been reached yet. When the scheduled end time has passed, the status automatically changes to Disabled.
-
Error: An error occurred during the log retrieval. You can click on the Error status for further information.
-
Log Retrieval Errors:
-
Failed to upload logs to storage. HttpCode = {response code}. Content = {response content}
-
Failed to collect logs
-
Failed to collect logs due to io error
-
Failed to collect logs due to permissions error
-
Failed to collect logs due to disk space error
-
-
Requesting Log Retrieval
Log retrieval is not supported for the Updater.
To request log retrieval, click Request Retrieval in the Log Retrieval area. From the Log Retrieval area, make sure Agent is selected.
You can request log retrieval only when the log retrieval status is Disabled, Error or Completed.
In the Log Retrieval panel, select when to start the retrieval. You can start immediately or set a date.
Currently, by default, Component Trace log type is included.
(A higher granularity will be offered in the future.)
Start indicates the time the scheduling will start.
The retrieval End time is automatically set for 7 days from the time the retrieval is initially scheduled. (The Agent may complete collecting all the logs before the end of the 7 days.)
Canceling Log Retrieval
You can cancel log retrieval when the Log Retrieval status is Scheduled, In Progress.
To cancel log retrieval, from the Logs tab in the Log Retrieval area, click Cancel Retrieval.
Downloading Retrieved Log Files
The logs that have been retrieved are displayed in the Logs Retrieved area. You can choose to download all the logs or select the specific logs you want to download. The log files can then be used for troubleshooting and you can optionally choose to share them with Proofpoint Support.
Reviewing and Filtering Log Files
Log files are displayed by selecting Show all x logs in the Log Retrieved area. You can filter to see specific logs by date. The Filter by retrieval date is based on the date retrieved in UTC time.
Deleting Retrieved Log Files
You can choose to delete logs. To delete logs, in the Log Retrieved area, select Show all x logs. When the list displays, select the logs you want, and click Delete Selected.
You will be promoted to confirm the deletion. Once logs are deleted, they cannot be retrieved again.
Important Note: Timing of Log Level Changes and Log Retrieval
When modifying the log level to Trace and immediately scheduling a log retrieval, the following behavior occurs:
-
The agent processes these commands during its next heartbeat (approximately 10 minutes, but this varies based on the agent's last heartbeat).
-
Both commands (log level update and retrieval) are executed in the same heartbeat, meaning:
-
Logs are collected before the log level change fully takes effect.
-
This results in the retrieved logs containing pre-Trace level information, not the detailed logs expected from the Trace setting.
-
Example from Agent Utility (ut-*) Logs
The following example illustrate this behavior during a simultaneous log level change and immediate retrieval request:
2024-12-04 10:57:51.6765 | INFO | 8 | | ***** Executing it-utility
log -l trace -s remote -z webUpload trace webBrowsing trace
dynamicPolicy trace fileOperation trace clipboardText error -i
703f****************************88c9 ***** |
Smt5G7rlerm7inuwUrNj.b7HUsmrl2m7EjSuGYvk5.rp6rlQXjGas |
2024-12-04 10:57:52.8708 | INFO | 8 | | ***** Executing it-utility
dump -d log -t C:\Program Files\IT Client Utility\Client
Utility\logUploadTemp -i 703f****************************88c9 -n
ed7bcaf1-0d80-4309-9d9c-3d583bac33c6-2-agent-trace.zip -m -l 98 -f 3
-a 1 ***** | Smt5G7rlerm7inuwUrNj.b7HUsmrl2m7EjSuGYvk5.rp6rlQXjGas |Key Insight:
In the example above, the logs were retrieved before the Trace log level could generate verbose output. For accurate and complete Trace logs:
-
Allow one full heartbeat cycle after updating the log level before scheduling log retrieval.
Related Topics: