Overview
How to gather event trace information for diagnosis purposes.
Event trace logs (ETLs) can be recorded for the M-Files Client and M-Files Server processes. They contain all the M-Files methods that have been executed as well as information on how long they have run. You can see methods and SQL queries which has been run during the operation and execution times. Sometimes both client and server-side ETL logs are needed from the same time/use case.
Please note that server-side ETL logs can take quite much disk space if the logs are taken from a long time. Size can be configured.
ETL logs are many times needed when investigating M-Files performance problems.
When sending the ETLs to M-Files, inform exact M-Files versions and UTC timestamp
- It is very important that you inform via the support case:
- The exact (M-Files Server, M-Files Client) versions with which the ETL logs are taken with Investigating ETLs require the exact version information. The Exact version numbers have 4 parts (E.g., M-Files Server 22.10.11903.5, M-Files Client 22.9.11816.9). Where to find the version numbers? See: M-Files User Guide
- It is also important that you inform the time point in UTC time when the issue reproduces/happens on the logs.
- Put the gathered ETL logs into a ZIP or 7-ZIP package and send it to M-Files.
Upload the ZIPs via secure CryptShare to M-Files: /article/Event-Trace-Logging-instructions-for-Customers
Gathering Events
Query parameters
If you are collecting logs from the M-Files server, set the below registry keys before setting up logging.
Registry Key: HKEY_LOCAL_MACHINE\Software\Motive\M-Files\<version>\Server\MFServer\EventTracing
Value name: SQLQueryTraceThresholdInMilliseconds
Value type: REG_DWORD (DWORD 32-bit Value)
Value data: 0
Registry Key: HKEY_LOCAL_MACHINE\Software\Motive\M-Files\<version>\Server\MFServer\EventTracing
Value name: TraceQueryParameters
Value type: REG_DWORD (DWORD 32-bit Value)
Value data: 1
If you are adding the above registry keys, you will have to delete any existing data collector set and create a new one for them to take effect.
If you set these keys before creating the data collector sets, the M-Files Server takes them into account. Otherwise, you need to restart the M-Files Server service, which is a service break.
NOTE: The logs can contain sensitive data when those keys are in place. Make sure to always send it securely to M-Files as explained above.
If you do not set them, the logs contain less data which may not be sufficient for the investigation, so we recommend setting them when possible.
Configuring the event gathering
Configure the Performance Monitor as shown in the screenshots. Performance Monitor can be started through Control Panel -> Administrative Tools.
Create a new Data Collector Set:
Figure 1 - Creating a new data collector set
Figure 2 - Selecting data collector creation method
Figure 3 - Include event trace data
Select event trace provider. If you wish desktop-side ETL logs, you can select:
- MFiles-Client-MFClient <version>
Figure 4a - Select event trace provider (MFiles-Client)
If Server side ETL logs:
- MFiles-Server-MFServer-<version>
Figure 4b - Select event trace provider (MFiles-Server)
If you are collecting logs from both Server and Client on the same machines, select both providers.
Figure 5 - Define the path for the event trace log and finish the creation
Setting event trace buffers
To properly capture all events from M-Files Server the size and number of trace buffers must be adjusted from the defaults. Otherwise, some events will be lost.
Start by selecting the data collector Trace that you previously created. Open the properties of that collector.
Figure 6 - Opening the properties of the trace
Go to the Trace Buffers tab
Figure 7 - Trace properties
Set the buffer size to 32 KB and the minimum number of buffers to 1024. Then press OK to save the changes.
Figure 8 - Trace buffers
Open properties of Data Collector set:
Figure 9 - Opening properties of the data collector set
Go to the Stop Condition tab. Enable the "Restart the data collector set and limits" and "Maximum Size" checkboxes.
Set the Maximum Size value to 2000 MB. Press OK to save changes.
Figure 10 - Defining the stop condition rule
Launching the Event Gathering
To launch the event gathering, select the data collector set and press Start as shown in Figure 11 - Start Event Collection.
Figure 11 - Start Event Collection
Stopping the Event Gathering
To stop the event trace gathering, select the data collector set and press Stop as shown in Figure 12.
Figure 12 - Stop event trace gathering
Reconfiguring the ETL logging if the M-Files version is upgraded
If you have configured the ETL logging and upgraded the M-Files version, the current ETL configuration will become outdated and needs to be updated.
Open the Performance Monitor (Performance Monitor can be started through Control Panel -> Administrative Tools)
Find the ETL configuration that you or someone else has made and change the Trace Provider to the same version that is the M-Files installation currently (See the below figures). Remove the outdated one and add the correct provider with the correct version number.
Figure 13 - Remove the old version provider
After removing the old provider, click "Add.." to add a provider with the correct version number.
