Troubleshooting Tips
This page contains information that can help track down errors and performance problems in a running Carmenta Engine application. It also contains detailed instructions on how to create crash dumps and other information that the Carmenta Support Team might need to be able to track down an error.
Contents
Creating a px-file from a View in a running application
Sometimes it is hard to understand exactly what triggers unwanted behavior in a View. This can be especially tricky if an application adds elements to the configuration at runtime, or even builds it entirely in code.
To help you analyze and understand how the View has been configured an application can be modified to serialize a View to a px-file which can then be opened and examined in Carmenta Studio or tested without the application logic in Carmenta Explorer. This is done using the Configuration class. The following example code shows you how to save a View to a px-file:
void SaveViewAsPxFile(string filename, View view, bool includeFeatures)
{
if (includeFeatures)
{
// Include all points, lines and polygons that have been inserted
// into MemoryDataSets by the application.
Configuration.Save(filename, view, SaveMode.IncludeFeatures);
}
else
{
Configuration.Save(filename, view);
}
}
Profile map updates in a running application
Carmenta Explorer has a built-in profiler that you can use to find performance bottlenecks in a px-file but you can also use the profiler programmatically to examine the performance of map updates in a running application.
To profile a View in a running application you use the Profiler class. The following examples shows you how to profile a single update.
// Profile a single update. You can of course keep the Profiler instance alive
// in a variable, profile a longer sequence of updates and/or map interactions
// and only save the PerformanceReport when you are done.
void ProfileUpdate(View view, string filename)
{
Profiler profiler = new Profiler(view);
profiler.Start();
view.Update(true); // Force an immediate update
PerformanceReport report = profiler.Stop();
report.Save(filename);
}
After you have saved the performance report to disk you can open it in Carmenta Explorer which will display the same user interface as if the profiling session had been done by Carmenta Explorer.
Please see the Profiler section in the Carmenta Explorer User's Guide for information on how to interpret the result.
Activating the Carmenta Engine log
Carmenta Engine has a built-in log that is disabled by default because it can affect the performance, especially with the log level set to Debug which might generate output of interest to the Carmenta Support Team.
The log can be enabled programmatically by an application, see the documentation for the Log class for more details.
The Log can be enabled before Runtime.Initialize is called.
Generating a crash dump
If your application crashes and you suspect the error lies within Carmenta Engine and not in the application code then, unless you can create a small application that reproduces the crash, the Carmenta Support Team will often need a crash dump.
Generating a crash dump on Windows using Visual Studio
If you have Visual Studio installed on the machine where an application is crashing you can create a crash dump following these steps:
Start the application that crashes.
Start Visual Studio
Inside Visual Studio select "Debug" - "Attach to Process..."
Make sure the "Attach to:" field says "Native code". If not press "Select..." which opens the "Select Code Type" dialog and make sure "Native" is selected and then press OK.
Select the process you want to generate a crash dump for in the "Available Processes" list and the press the "Attach" button.
Run your application and try to crash it.
Visual Studio will display an error dialog when the application crashes. Press the "Break" button.
Select "Debug" - "Save Dump As..." from Visual Studio's menu.
Make sure that the "Save as type:" field shows "Minidump with Heap (.dmp)" and save the dump file.
Generating a crash dump on Windows using Procdump
If you do not have Visual Studio installed on the machine where the application crashes then you can use Microsoft's Procdump command line utility.
Download Procdump from Windows Sysinternals.
Extract everything in the downloaded zip-archive.
Open a "Command Prompt" window with Administrator privileges.
Create a directory for the crash dump files, for example: C:\dumps.
CD to the directory where procdump.exe is located.
Run the command: procdump.exe -ma -i c:\dumps
If this is the first time you run procdump.exe you will also have to press OK to accept a EULA. Procdump is now registered as the Just-in-Time debugger on the machine and will generate a crash dump for any application that crashes.Run your application and try to crash it.
When a crash occurs the "Command Prompt" window where procdump.exe is running will generate some output which will include the location and name of the crash dump file.
Procdump will remain as the Just-in-Time debugger unless it is removed or replaced. If you have Visual Studio installed on the machine you can restore it as the system's Just-in-Time debugger:
Start Visual Studio with Administrator privileges.
Open the "Tools" - "Options" dialog.
Select "Debugging" - "Just-in-Time".
Check all check boxes (Managed, Native and Script).
Press OK.
Quit Visual Studio.
If you do not have Visual Studio on the machine you can remove the registry entry that specifies the Just-in-Time debugger:
Open a "Command Prompt" window with Administrator privileges.
Run regedit.exe
Delete the value from Debugger under:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebugClose the "Registry Editor".
Close the command prompt.
Generating a crash dump on Linux
On Linux you can create a crash dump following these steps on the machine where an application is crashing:
Open a terminal
Run ulimit -c unlimited
Run your application and try to crash it.
When a crash occurs a core file will be generated in the current directory.
To save some space the core file can be compressed with xz core to create a core.xz file.