Producing Diagnostic Log Files

Wikis > Producing Diagnostic Log Files

Producing an ArcaOS install zip

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 zip is not the same as a TestLog log file. If you need to produce a TestLog Log file, see the Producing a TestLog log file section.

  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 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 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 item 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 you need to create the install 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 zip. If you need an install zip, 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 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 from 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 rename or zip the log file.

While you are free to examine the contents of the TestLog log file, 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 AOSBOOT 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 AOSBOOT 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 AOSBOOT 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 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.

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.

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 the developer can see and use to diagnose the problem. The testcase program must be a single file C program buildable with OpenWatcom tools. You may also provide a built binary. However, the developer will likely build his own version using the source file you provide.

 

This entry last updated: by David Azarewicz