Producing Diagnostic Log Files

Producing an ArcaOS install log zip file

When an install or update terminates it can stop for one of three reasons described below. The way the installer stops determines how the zip file is created and what it is named. Note that an install log zip file is not the same as a TestLog log file and contains different information. If you need to produce a TestLog Log file, see the Producing a TestLog log file section. To find the install log zip file appropriate for your situation, one of the following three options will match the outcome of your install.

1. The installer completes successfully without any apparent errors. In this case the install or update runs to completion, all the reboots happen as expected, and the end result is a booted running system. This is the most common outcome of an install or update. In this case, the installer creates an install log zip file identified by the current date.
   Go to \sys\install on your boot disk and look for a file named install_*.zip where ‘*’ is a numeric date string (like ‘20190815’). For example

   install_20190815.zip

   There may be multiple files like this. Attach the zip file with the most recent date string to your ticket.

2. The installer produces an error and stops. In this case the installer maintains control of the system and is able to create the install log zip file. This is the least likely and least common outcome.
   Go to \sys\install on your boot disk and look for a file named install_abend.zip and attach that zip file to your ticket. If this file does not exist, then the install or update did not fail in this way. See outcome 3.
3. Something happens and the system hangs or crashes and the installer loses control of the system. This is the most common way an install or update can fail and usually indicates some kind of hardware problem or system setup problem. In this case install_abend.zip is not automatically created and you need to create the install log zip file using the following procedure.
   1. Reboot your system back into the installer using your install media.
   2. Click on System Management.
   3. If you had to do a hard reset, or power off to regain control of your system, you might need to run chkdsk on the target volume. If so, do that now.
   4. Click on Command Prompts and open a Command Line (CMD)
   5. Type

      MkSupZip

   6. Answer any questions the script asks.
   7. The script will zip up all the required files and announce the file name that was created. Attach the created zip file to your ticket.

Producing a TestLog log file

A TestLog log file is not the same as an install log zip file and contains different information. If you need an install log zip file, see the previous sections.

Warning: The TestLog program captures real time state from your system as well as captured driver state. Always run the TestLog program when the problem you are reporting exists on your system, and as close to when the problem happened, so it can try to capture data about the problem. Also, do not run the TestLog program more than once per boot. Each time you run the TestLog program it clears the debug buffers so a second run will not collect the needed data.

Always make sure you have the latest TestLog program. Get the latest version here. This is a self-executing WarpIn package. Simply execute it to install. Then open an OS/2 command window and type the requested testlog command. If no specific testlog command was specified use one that is appropriate for your problem. Some common commands are shown below:

For network problems use:

testlog network

For printer problems use:

testlog printer

Otherwise, if unsure use:

testlog generic

The TestLog program will prompt for a description of the problem. Type your ticket number and a brief comment describing your particular problem and press enter. This comment is included inside the log to help the developer match the log file to your ticket. A log file will be generated and the name of the log file will be displayed. Attach that log file to your ticket. Do not edit, rename, or zip the log file. A testlog log file name looks like this:

SYSTEMNAME-DATE-TYPE[-TestID].log

where

SYSTEMNAME is the name of your system as specified by the HOST environment variable. The developer will use this name to refer to your system. The developer also uses this name to sort and organize log files. It is strongly recommended that you name your system a reasonable, identifiable name when installing ArcaOS. Do not change this part of the file name from what is generated by the testlog program.

DATE is the date the log file was created. The developer uses this to sort and organize log files. Do not change this part of the file name from what is generated by the testlog program.

TYPE is the type of log file that was generated. The developer uses this to quickly identify what data are in the log file, especially when several different types of log files were generated for the same issue on the same system. Do not change this part of the file name.

TestID is an optional addition to the file name that can be added on the testlog command line, or you can add this after the file is created. This is the only part of the testlog file name that you may change. Never add characters to the beginning of the file name.

You are free to examine the contents of the TestLog log file, however beware that it is intended for the developers only. The log file contains raw data and things that might look like problems, including the words “error” and “failure” when these things may be normal and correct operation. Only the developer knows how to interpret the log file. You may not use anything in a log file as the basis for opening a ticket.

Producing a TestLog log file when booted from the ArcaOS installation media

Warning: Do not run the TestLog program more than once per boot. Each time you run the TestLog program it clears the debug buffers so a second run will not log needed data.

1. Boot your ArcaOS installation media (Either DVD or USB stick) using the specific options specified by the developer. If nothing was specified use all the defaults. Wait until the installer GUI is displayed.
2. Click “System Management”
3. Click “Command Prompts->Command Line (CMD)”.
4. Type this command:

   testlog generic

5. The TestLog program will prompt for a description of the problem. Type your ticket number and a brief comment describing your particular problem and press enter. This comment is included inside the log file to help the developer match the log file to your ticket.
6. A log file will be generated and the name of the log file will be displayed. Attach that log file to your ticket. Do not zip the log file.

There are several options for getting this log file attached to your ticket. Methods 1 or 2 are preferred. Use option 3 only as a last resort. If you do end up needing to use option 3, you must also post a message in the ticket saying that you have used the automatic upload feature. The automatic upload feature does not attach the log to your ticket. Instead a developer must take time to go searching for your log file in FTP archives.

1. Copy the log file to a USB stick and use a different system to attach it to your ticket.
2. Use the web browser on the DVD to attach the log file to your ticket. Simply click “Tools->Web Browser” and go to mantis.arcanoae.com, log in and access your ticket. This will only work if the system is working well enough that the network is working.
3. Use the automatic upload feature of the TestLog program.

Using the Automatic Upload Feature of the TestLog Program

TestLog v3.15 or later is required to use this feature. ArcaOS 5.0.3 and later versions contain a version of TestLog with this feature.

Warning: The TestLog program captures real time state from your system as well as captured driver state. Always run the TestLog program when the the problem you are reporting exists on your system so it can try to capture data about the problem. Also, do not run the TestLog program more than once per boot. Each time you run the TestLog program it clears the debug buffers so a second run will not collect the needed data.

1. Boot your ArcaOS install media (Either DVD or USB stick) using the specific options specified by the developer. If nothing was specified use all the defaults. Wait until the installer GUI is displayed.
2. Click “System Management”
3. Click “Command Prompts->Command Line (CMD)”.
4. Type this command:

   testlog -u generic

5. The TestLog program will prompt for a description of the problem. Type your ticket number and a brief comment describing your particular problem and press enter. This comment is included inside the log file to help the developer match the log file to your ticket.
6. The TestLog program will attempt to upload the log file to the Arca Noae FTP server in a private location. If the upload is successful, post a note in your ticket and the developer will find the log file and attach it to your ticket. If the upload is successful it will finish very quickly. If there is a problem with the upload there could be a very long timeout period before the program continues.
7. If the upload is not successful because of a data transfer error, the TestLog program will retry after a delay. You will have the option of cancelling the retry during this delay period. If the second upload attempt is not successful, the TestLog program will automatically try to find a writable disk and it will copy the log file there. There will be a delay before the copy takes place and you will have the option to cancel the copy during the delay period. If you are booted from an USB stick, the TestLog program will copy the log file to that USB stick. If you are booted from the DVD, The TestLog program will find the first disk that supports long file names and the log file will be copied to that disk. Then you can reboot to a working system and attach the log file to your ticket. Do not zip the log file.

Note that the TestLog program always tries to generate a unique file name that corresponds to your system. Make a note of the file name so you can find it when you go to upload it.

Providing pre-boot diagnostics from a UEFI system

This section applies to UEFI BIOS systems when not using a CSM. This will not work on Traditional systems, or UEFI BIOS systems when using a CSM.

1. Boot the install medium
2. When the first menu appears, press Alt-F1
3. Select “Diagnostics…” and press enter.
4. Select “Write info dump file” and press enter
5. Choose a volume on which to write the dump file. This should be a volume that you can access later. You may write the dump file to any FAT or FAT32 formatted volume in the system, including the AOSBOOT USB stick, or another FAT or FAT32 formatted USB stick.
6. Note the name of the dump file and attach that dump file to your ticket.

Providing a Trap Screen Image

If you get a trap, or an IPE (Internal Processing Error) that results in a trap screen, often the developer will want to see the trap screen. If you provide a trap screen, also always provide a matching testlog log file. A matching log file is one that matches exactly the system configuration when the trap occurred. The best time to capture a testlog log file for submitting with a trap screen is immediately after rebooting after the trap occurred.

You can use any digital camera device, such as a cell phone to take a picture of the screen. However, be careful of the following things:

• Do not use a flash. Turn the flash setting off.
• The screen contents must be readable by the developer. Try to take the picture straight on, so the image is not skewed, and not too far away. Look at the picture after you take it and make sure the contents of the screen are clearly readable with no shadows, reflections, etc. Make sure you take a picture of just the screen and not a lot of background and walls behind the screen. Crop the picture with a picture editing tool such as PMView if necessary so only the screen contents are in the image.
• Make sure the image is JPG or PNG format.
• Make sure the file size is reasonable (less than about 1MB). You will not be allowed to upload excessively large files.
• Do not zip the trap screen image.

Capturing DFSDISK data

This requires having the DFSee software.

• Change to the DFSee bin directory.
• Execute the DFSDISK command. The DFSDISK command will create a collection of files usually named DFSDISKo.*
• Zip those files it creates and attach the zip file to your ticket.

Capturing a Serial Debug Log

In order to do this, you need

• A machine that reproduces the problem and has a supported serial port.
• A second machine with a serial port that reads the log. The serial port of this machine can be an add-in card or even use a USB to serial adapter if supported by the OS
• A terminal program such as ZOC, or PMDF running on the second machine
• A null modem cable to connect the two machines

Perform the following steps:

• Setup the driver under test to output debug data to the serial port. The developer will tell you how to do this.
• Launch the terminal program on the 2nd machine and enable the log-to-file feature
• Reboot the 1st machine
• Reproduce the problem
• Include the log file generated on the 2nd machine in the bug report

Terminal Program on Second Machine

Launch the terminal program and configure it to use the correct port and serial parameters; these are:

• speed 115200
• 8 bits
• Parity: None
• X-on: On

This is often abbreviated as 115200 8N1.

Under ArcaOS, eCS, or OS/2, you can use ZOC or the PM Dump Facility (pmdf.exe) as a terminal program, or on a Linux machine you can use minicom and set up the terminal to use a large scroll back buffer (10000 lines or so).

Reboot the 1st machine and watch the terminal window on the 2nd. You should see a detailed log of all it does.

Reproduce the problem and include the log from the 2nd machine in your bug report.

If you see nothing on the second machine:

• Do both machines use the correct ports? If any of them has more than one serial port, try them all in all possible combinations.
• Is the cable really a null modem cable?
• Check the command line of the driver under test. Did you correctly specify the serial port debug arguments?
• Check that the correct baud rate is specified and that it matches the baud rate on the second machine.

If the text is garbled on second machine, make sure serial parameters such as baud rate are correct.

Producing a test case

If you have been asked for a test case, that means your problem cannot be diagnosed remotely and the developer must be able to reproduce the problem himself in order to debug the problem. A test case is the specifications for a system and/or configuration that has only the required components and operations necessary to produce the problem, and the method necessary to produce the problem. At a minimum, the test case must

• run on a minimal clean system running released GA software and drivers in a standard as-installed configuration that isolates the issue without a lot of extraneous distractions.
• have only the minimum amount of hardware necessary to reproduce the problem.
• be narrowed down to the minimum number of commands or operations necessary to reproduce the problem. For developers reporting problems with core ArcaOS functions, you must provide a testcase program that contains and calls the minimum number of functions necessary to produce the issue. See the Providing a testcase program section below.
• provide all files and programs used to reproduce the problem if they are not already included in ArcaOS and if they are necessary. For example, if only “an arbitrary file of size nnn” is required, then that file does not need to be provided.
• provide an exact list of steps necessary for someone else to reproduce the problem on another system.
• provide the expected and actual results from running the test case.

Remember that a test case is not about how you produce the problem, it is to provide the simplest configuration, data, method, and steps so that someone else can reproduce the problem on a different system.

Some guidelines for specific types of problems

• For disk issues, the minimum number of disks and the minimum number of partitions in the system necessary to reproduce the problem. There should be no foreign (non-ArcaOS) operating systems or foreign file systems on the disk(s). No foreign (non-ArcaOS) or third party software, including DFSee, should have ever modified partitions or file systems on the disk(s). All partitioning must be done with MiniLVM, and formatted with ArcaOS supplied file system drivers.
• For USB issues, the minimum number of USB devices attached necessary to reproduce the problem.

Below are some examples of what a test case should look like. These are fictitious scenarios but should help give you an idea of the kind of things that should be in your test case.

Example of a test case for a USB problem

Minimum hardware requirements
* A generic single or multi-CPU system running ArcaOS 5.0.5
* One XHCI controller with switchable ports
* One companion EHCI controller
* One USB3 hub
* One USB mouse

Method
1. Plug the USB mouse into the USB3 hub
2. Plug the USB3 hub into a blue USB3 connector
3. Power on the computer and boot ArcaOS
4. Observe that the USB mouse is not detected.
5. Warm boot the computer
6. Observe that the USB mouse is detected.

Example of a test case for a disk problem

Minimum hardware requirements
* A generic single or multi-CPU system running ArcaOS 5.0.8
* One AHCI controller
* Two 100 GB disks or larger attached to the AHCI controller

Software requirements
* Disk one has one 2 GB ArcaOS bootable partition as C:
* DIsk one has one 10 GB JFS data partition as D: with at least 4 GB of data in at least 750 files.
* Disk two has one 10 GB JFS data partition as E:, empty.
* The XCOPY command

Method
1. Power on the computer and boot ArcaOS
2. Open a command window and type “xcopy /s d:\ e:\”
3. The system will hang after copying 3.6 GB of data.

Providing a testcase program

For some problems you may need to provide a program that produces the problem you are reporting. This is especially true if your problem occurs running a complex application. It is your responsibility to narrow down the problem and produce a small testcase program that only includes the one or two functions or operations needed to produce the problem. The developer can use this small testcase program to see and diagnose the problem. The testcase program must be a completely self-contained single file C program buildable with official current OpenWatcom tools by using a single wcl or wmake command. You may also provide a built binary. However, the developer will likely build his own version using the source file you provide. Do not expect the developer to use or debug your whole application.

This entry last updated: October 13th, 2024 by David A