Today we will focus our energy on the tracing and logging options available to us from within the many applications we use in day-to-day activities.
We will discuss the tracing and logging options for various components used with X3 and what type of information they would typically provide.
Not only is this information valuable to help identify various problems, but these records will also be requested by the support team from time to time to help elaborate on error messages, troubleshoot poor performance and to determine potential source code issues.
Having the ability to gather, read and understand these traces and logs can save valuable time.
Let begin this trip from within X3 with an overview of the very robust Engine trace.
ENGINE TRACE
What is an Engine trace and what can we learn from it?
Engine traces provide a way to illustrate the inner workings of X3 from both the application and System levels. Depending on the modes used, the results can be used in conjunction with source code to identify areas of concern and potential root causes to the issues you are looking to troubleshoot.
What Modes can I use?
From the image below you will see the various modes available to use and what they are designed to illustrate.
From the returned trace file, you can identify the values for each mode specified as noted by the “Channel” values.
Great, now how do I run the Engine trace?
*Note: Activating a trace can effect performance and generate large trace files, so be ready to trace the action before starting the trace. Basically, be one click away from recreating the issue before stating the trace.
Typically, from within most functions you will see the “Diagnosis” menu on the right under the “actions” menu, from here choose “Calculator”.
This will display the following screen where you will now populate the formula of the trace you are looking to execute. In other words, you will now tell X3 what modes to trace.
In the Calculation field you will be prompted to type in text and should type in OpenLog()
Use the format = OpenLog(<volume-name>,<flag-value>).
For example, OpenLog(“TRA”,2)
The “Volume-Name” will indicate where the log is stored.
The “Flag-Value” will indicate what mode the trace will run in.
To start the Trace, populate the field with your formula and hit enter.
You should see the “Result” field return ‘0’ indicating it’s successfully started.
Go ahead now and replicate the issue you are tracing.
When done and ready to stop the trace, return to the calculator and type: Closelog()
The Trace-file will be created in the <folder>\<volume-name> directory –for example, D:\sage\X3\LIVE\TRA\.
You can expect to see a file named X3diary_admin_####.tra with results similar to this:
The Engine trace capabilities are vast and therefor its recommended to discuss with your business partner the modes that would be best be suited to trace the issues you are experiencing.
As mentioned, this is an overview, you can gather additional detailed Engine trace information from the following Knowledgebase article:
Timing Trace
Timing traces are used to visually illustrate the time it takes to call and execute certain tasks.
This is a good tool to use when looking to identify which calls are taking the longest to perform, typically when investigating performance issues.
How do I run a Timing Trace.
The timing trace is accessed via the actions menu on the right side of most functions.
To start this trace, select “Log activation” under Diagnosis.
In the following screen,
- Select the activation flag.
- Note the log file location.
- Click OK.
This activates the timing trace, once active go ahead and work through the steps you are tracing.
Once complete, go back to the right actions panel and click “Log deactivation”.
This ends the log and pops up the results on screen.
I recommend using the results shown on screen as they are formatted and will display in order based on calls with the longest duration.
This file can be found in D:\Sage\LIVE\folders\Prod\TRA\F###.tra
Session logs
Session logs have been re-vamped since V12P27, the new updated logging is now called X3 session logs, it still has the same information available but is easier to track and compare to previous traces.
Let check it out..
From Administration, Usage, Logs, select X3 Session logs;
After adding a new session log, with name and description, there are a few items here we will touch on that add value to using session logging.
- Max Log Time (min) – Time in minutes the log will run if it’s not ended before the indicated time.
- Type – Indicate the type of logging you are setting up.
3. Levels – Select the level of logging you need to achieve using the various provided levels.
The following are available to choose:
After Saving the new log, click the “Enable” button to start the logging.
This will start logging until you choose to “Disable log” or until the max time value is reached.
You can find the logs in the Main runtime folder in the log directory.
Host trace
The Host trace has the ability to be setup to trace certain events with elevated logging details. You can see all available options from Administrator, Settings, Global settings under the “Logs” tab.
You will see the code and descriptions to help identify the area to log, you can also increase logging levels.
Available levels include Error, Warning, Info, Debug and Silly. Silly logging being the most verbose.
**Note: Using elevated logging can and will negatively impact performance so it’s recommended to be sure to disable the logging when finished.
Additional details on all options available in Global settings can be found in the Online Help : https://online-help.sageerpx3.com/erp/12/staticpost/global-settings/
Stay tuned next month for more information on Logs and traces.