How to enable debug logging for Trellix Agent to troubleshoot Windows
Technical Articles ID:
KB82170
Last Modified: 2023-03-28 09:15:41 Etc/GMT
Summary
Technical Support might request debug-level log files when troubleshooting an issue. Also, Technical Support might request either of the following:
- McTray debug logging for issues related to the Trellix Tray Icon
- An event trace log (ETL) for an issue with upgrading or uninstalling TA
The registry setting on Windows clients controls the TA log levels. Debug logging produces more log entries if there's an error. Debug logging allows for more granularity when diagnosing an issue. Because debug logging generates so many more entries, you must increase the size of the logs to capture the additional information. Use the advice in this article to define a suitable log size. The log size makes sure that the logs are written to drives with sufficient space. A larger log file size is better than a smaller one to make sure that the relevant data is captured. If the log is too small, you might not capture the relevant data.
TA 5.x differs from previous versions in the following ways:
- Specific logs that are in use
- Location of the logs
- Logging configuration
Log descriptions
TA uses the following logs:
- macmnsvc_<hostname>.log
The macmnsvc.exe process hosts services including peer-to-peer, relay, SuperAgent, agent wake-up, and SuperAgent wake-up. The macmnsvc_<hostname>.log captures logging related to these functions. In addition, it also captures the following:
- Logging related to the message bus broker
- Operations performed by message bus architecture-based Enterprise-managed products. For example, Threat Intelligence Exchange and Data Exchange Layer
- macompatsvc_<hostname>.log
The macompatsvc.exe service is a compatibility service for masvc. This service is responsible for the compatibility of TA with plug-in and Local Procedure Call (LPC)-based managed products. The macompatsvc_<hostname>.log captures the operations performed on plug-in and LPC-based managed products.
- masvc_<hostname>.log
The masvc.exe service is responsible for property collection, policy enforcement, task scheduling, agent-server communication, and trigger update sessions. The masvc_<hostname>.log captures logging related to these operations.
- McScript.log and McScript_Deploy.log
When masvc.exe triggers an update, McScript.exe and McScript_InUse.exe are invoked and responsible for the install/uninstall or update session. The McScript.log captures details related to the update session, for example, the repository from which the file is downloaded, file download status, install and uninstall script execution, and update session status details. McScript_Deploy.log records the same details for install/uninstall operations.
- marepomirror_<hostname>.log
The marepomirror.exe process is responsible for repository mirroring. When the mirror task is invoked, marepomirror_<hostname>.log captures all operations related to mirroring.
Log locations
The logs are stored in the following locations:
- Windows - C:\ProgramData\McAfee\Common Framework\logs
- Non-Windows - /var/McAfee/agent/logs
Guidance for enabling debug logging
You must enable the appropriate debug logging before you reproduce an issue. If you enable debug logging for an issue that can't be reproduced, it doesn't provide adequate information for troubleshooting. If you're investigating client and server issues, you must enable debug logging on both the client and server before you reproduce the problem. Both are needed to successfully capture the additional information needed to help investigate the issue.
Solution
1
To set the TA log level
There are four possible log levels:
- Disabled - Designates that logging is disabled
- Info - Designates informational messages that highlight the progress of the application at a coarse-grained level
- Debug - Designates fine-grained informational events that are most useful to debug an application
- Trace - Designates finer-grained informational events than Debug. This log level isn't applicable to McScript.log because it doesn't have trace logs
There are two ways to set the log level:
- Option 1: Set the log level (Debug or Info) in the TA policy using the ePolicy Orchestrator (ePO) console
If Enable detail logging is set, the log level is set to Debug for all agent logs. If Enable detail logging isn't set, the log level is set to Info for all agent logs. You can control the log size and rotation only through the TA policy. They can't be changed on the local system.
- Log on to the ePO console.
- Click Menu, Policy, Policy Catalog.
- Select McAfee Agent from the Product drop-down list.
- Select General from the Category drop-down list.
- Click the policy that you want to change.
- Click the Logging tab.
- Select the option Enable detail logging.
- If needed, change the Log file size limit (MB) and Roll over count options.
- Click Save.
- To receive the policy change, send an agent wake-up call to the client.
- Option 2: Set the log level (Disabled, Info, Debug, or Trace) using the maconfig tool from the command line
The maconfig settings override the settings in the TA policy and are applicable until you restart the TA service. After you restart the TA service, the agent honors the log level set in the TA policy.
NOTE: By default, the location of maconfig.exe for TA 5.x is C:\Program Files\McAfee\Agent\
Open an administrative command prompt on the local system and use maconfig.exe to enable debug logging:
maconfig.exe -enforce -loglevel n
Example:
maconfig -enforce -loglevel 3
Here, n equals one of the following:
0 - Logging is disabled
1 - Log level is set to Info
2 - Log level is set to Debug
3 - Log level is set to Trace
NOTE: When collecting Minimum Escalation Requirements (MER) information, perform the following:
- It's best to enable trace level logging using maconfig –enforce –loglevel 3
- Enforce the policy using the command cmdagent –e
Solution
2
To enable McTray debug logging, create debug logs for McTray.exe when troubleshooting issues related to the Trellix Tray Icon.
NOTE: You must temporarily disable self-protection to make the following changes. You can control self-protection only through the TA policy. It can't be changed on the local system. Re-enable self-protection after you finish troubleshooting.
- Log on to the ePO console.
- Click Menu, Policy, Policy Catalog.
- Select McAfee Agent from the Product drop-down list.
- Select General from the Category drop-down list.
- Click the policy that you want to change.
- Click the General tab.
- Deselect the option Enable self-protection (Windows only).
- Click Save.
- To receive the policy change, send an agent wake-up call to the client.
- Reboot the client system.
To enable debug logging, follow these steps:
CAUTION: This article contains information about opening or modifying the registry.
- The following information is intended for System Administrators. Registry modifications are irreversible and could cause system failure if done incorrectly.
- Before proceeding, Technical Support strongly recommends that you back up your registry and understand the restore process. For more information, see the Microsoft Windows registry information for advanced users article.
- Do not run a REG file that is not confirmed to be a genuine registry import file.
- Press Windows+R, type regedit, and click OK.
- Navigate to the following key:
64-bit: [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\McAfee\Win32_GUI_Support_DLL]
32-bit: [HKEY_LOCAL_MACHINE\SOFTWARE\McAfee\Win32_GUI_Support_DLL]
- Double-click the debug_tracing string value and set Value data to 1.
- Close the registry editor.
- Restart the McTray.exe process.
NOTES:
- Debug logging continues until you change the value back to 0. Technical Support recommends that you change the value back after you've collected sufficient logs.
- Because McTray.exe runs under the logged-on user's profile, it also stores the debug logs under the logged-on user's profile. The MER tool doesn't collect these logs; you must obtain them manually.
McTray log is located in the following:
- Agent 5.5.1 or later:
C:\Users\<username>\AppData\Local\Temp\McAfeeLogs
- Agent 5.0.x:
C:\Users\<username>\AppData\Roaming\McAfee\Common Framework\DB\Support DLL\DebugTraceFile
NOTE: A separate log file is created for each new instance of McTray, with up to 20 historical files, plus one file for the currently active log. Each log file is dynamically pruned at runtime to 2 MB in length, until debug logging is turned off.
Solution
3
To collect an ETL
For an issue with upgrading or uninstalling TA, collect an ETL by following the steps below:
- Download and extract the file ETLTrace*.zip from the "Attachment" section of this article.
- Press Windows+R, type cmd, and click OK.
- Navigate to the directory to which you extracted ETLTrace*.zip.
- Run the following command:
EtlTrace.exe -Start
- Reproduce the issue.
- Return to the command prompt and run the following command: EtlTrace.exe -Stop
- If you need to collect binary file versions, run the following command: EtlTrace.exe -GetVer
- Gather the following files:
|