Bug Reporting Best Practices

• If reporting an issue with hardware, or general failure issues, Include a System Profiler report
• If reporting a crashing bug, a Crash Log is required
• If reporting a kernel panic, a Panic Log is required
• If reporting a hang, freeze, or performance issues, a sample and/or Shark profile is required
• If reporting an error dialog message or UI bug, provide screen shots

1. Select "Save" from the File menu
2. Keep the format as 'System Profile'
3. Click the "Save" button
4. Append the file to your bug report

/usr/sbin/system_profiler -detailLevel full -xml >mymachine.spx

Thiis command will create a full System Profiler report, named "mymachine.spx", which will open in System Profiler on another machine.

NOTE: A full System Profiler report provides vital information from the user's hardware configuration (drive, audio, Bluetooth, graphics, and external hardware information), to networking configurations (including wireless, firewall, location networking, internal modem and volume information), to software configurations (including installed applications, extensions and fonts, frameworks, preferences, and access, console, error, install, mail, Software Update, and system log files).

3.2 : Crashing Issues:
If a crash has occurred, a crash log is essential. To locate the crash log in Tiger (10.4) or later, check the following location:

~/Library/Logs/CrashReporter
/Library/Logs/CrashReporter

If you are not able to locate any crash report information in either of these locations, check the /var/log/system.log for any relevant error messages from "crashreporter" or "crashdump."

iPhone crash logs can be obtained by following the instructions below.

NOTE: Only include one crash log per bug. If you're able to reproduce the crash the exact same way each time and the crashing thread looks identical in every instance, only one crash log is required. This allows us to efficiently distribute the necessary information to Apple Engineering. In instances where the crash doesn't look identical, file separate reports with one crash log submitted per bug.

***See TN2123 for information on the anatomy of a crash log.

3.3 : Kernel Panic:
If a kernel panic has occurred, a panic log is required. Backtraces are saved to nvram, then copied to the panic.log file on restart. This file can be located in /Library/Logs.

***See TN2063 for information on the anatomy of a panic log.

3.4 : Hanging/Performance Issues:
If you are experiencing a "hang" (includes freeze, spinning wheel, slowness), a sample of the application while it is in the hung state is required. A sample can be obtained by any of the below options:

• Using Terminal:

  run 'sample (Application Name) 15'
  
  *The output can be attached directly to your bug report via the 'My Originated Problems' section in the Bug Reporter.

  Note: The application name must be typed exactly as the application is named; this command line is case-sensitive. After the sampling has been completed, Terminal will supply the file path to the location to which the sample analysis was written.

• Using Activity Monitor:
  - Launch Activity Monitor (/Applications/Utilities/)
  - While the application is hung, click on the application to highlight it
  - Select View -> Sample Process
  - Click Save

  Note: more information about using "Sample" may be found on its man page, which can be retrieved by entering "man sample" in the Terminal window.

• How to SSH into a machine (from another machine on the same network):
  Providing the machine is not hung to the point that you cannot SSH into it, you can do the following from Terminal:
  1. ssh (IP address) -l (login account)
  2. top
  3. Identify the process taking a lot of CPU
  4. sample (process ID) 5
  5. cp /tmp/* ~/Desktop/
  6. Restart the machine and log in as the user you SSH'd into

  Note: Use monospaced font for Terminal commands.

• Shark:
  You must have Shark installed to provide a Shark profile.

  Steps on how to obtain a Shark sample can be found here.

NOTE: If you have an older application called "Sampler" on your system, do not use this. A Shark profile provides more useful information.

3.1 : Screen shots:
Provide a screen shot when it will help clarify the bug report. In addition to providing screen shots for error or dialog messages, please type the text of the error/dialog message you are seeing in the description of the bug report (so that the message contents are searchable. If there are steps involved, a sequence of screen shots, or even a movie is always appreciated (but be sure to write down the steps associated with each screen shot).

It is useful to provide a screen shot when:

• Seeing a dialog
• Experiencing rendering or redraw issues
• You are trying to describe an icon or other aspect of the screen and you're not sure what it is called

Back to Top

Be sure to include current contact information. This will ensure that we're able to correspond with you as we investigate your issue. This information can be updated by logging into the ADC Member Site and choosing the "Update Profile" page, or by logging into the My Info page.

Back to Top


5. Apple Product-specific Additional Information Requirements

For bug reports filed against any of the following Apple products, product-specific information is required in addition to any generic information as stipulated above.

• Xcode
• Java
• Safari
• Mail
• iChat
• Audio
• USB/FireWire
• AirPort
• iPhone/iPod touch
• iPod
• iDVD

• Mac OS X build number and version:
  Both can be obtained by clicking the 'Apple' logo in the menu bar, and then clicking 'About This Mac'.

• Xcode IDE build:
  The Xcode build can be obtained by selecting Xcode -> About Xcode.

• gcc and gdb builds: These builds can be obtained by entering the following commands in Terminal:
  
  gcc -v
  gdb -v
  
  The output for each will contain some of the following information:
  
  gcc:
  [stability-drive:~] name% gcc -v
  Using built-in specs.
  Target: i686-apple-darwin8
  Configured with: /private/var/tmp/gcc/gcc-5367.obj --target=i686-apple-darwin8
  Thread model: posix
  gcc version 4.0.1 (Apple Computer, Inc. build 5367)
  
  gdb:
  GNU gdb 6.3.50-20050815 (Apple version gdb-563) (Wed Jul 19 05:17:43 GMT 2006)
  
  
• Sample project/test case that reproduces the behavior. Do not include confidential information.

• Build log

• Temporary files located in [~]/Library/Caches/Xcode Build Directory

• Crash log and sample code for any crashing or hanging issues

  Logs can be found at:
  
  ~/Library/Logs/CrashReporter/Xcode.crash.log
  
  Note: Use of -save-temps leaves a preprocessed source file on the disk with the following file naming convention:
  
  .i for C language sourcefile.c
  .ii for C++ language sourcefile.cc
  .mi for Objective-C language sourcefile.m
  .mii for Objective-C++ language sourcefile.mm

Back to Top

• Java build information:
  Put the Java build number at the beginning of your title as such:

  1.5.0_06-112: Title Here

  • The java build can be obtained by entering the following command in Terminal:

    java -version
    
    The output will look like this:

    java version "1.5.0_06" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-112) Java HotSpot(TM) Client VM (build 1.5.0_06-64, mixed mode, sharing)
    

• Test case with clear and concise steps to reproduce that will enable us to reproduce this in-house.

• Crash logs required from both of the following locations:
  

  [~]/Library/Logs/Java/JavaNativeCrash.crash.log
  [~]/Library/Logs/CrashReporter/JavaCrash.log

• Hanging issues require that two samples be taken while Java is in a hung state. This includes:
  
  
  • Java Stack Trace :
    You will need to obtain the process number using "top" from the Terminal or /Applications/Utilities/Activity Monitor.app

    In Terminal, type "kill -QUIT pid" where pid is the process number obtained above. The dump will appear wherever the Java application is set to send its output (either into the Console log, or within the Terminal window if you chose to start the sample from the command line).
    

  • Native Stack Trace:
    - In Terminal, type "gdb attach pid". You will receive a gdb prompt that states "(gdb)".
    - In gdb, type "t a a bt". The results will appear in the Terminal/gdb window.

Back to Top

• URL-related issues:
  If you are experiencing URL-related issues, provide clear details on how the URL is not working, and screen shots which portray the issue. Additionally, be sure to include the URL.

• JavaScript issues:
  If you are experiencing a JavaScript-related issue, provide the actual JavaScript (or a test case).

Back to Top

• Mail Composition issues:
  For composition-related issues in Mail, try reproducing in TextEdit and Blot. Blot can be found in /Developer/Examples/WebKit/Blot/. If you are experiencing an issue that only occurs when replying to messages, reply to a message in Mail, do a Select All, copy, and paste it into Blot before proceeding. For reply bugs, it's often necessary to provide the message itself. To do that, select the message in the message list, select File -> Save As, Raw Message Source, and provide the raw source with the bug report.

  NOTE: Raw Message Source is always necessary for display bugs as well.

• Test Account:
  If you're able to provide a test account for reproducible issues, provide that. Being able to log into an account and test the issue is the best way to identify the problem at hand and reach a resolution.

• Connection Logs:
  Provide the smallest connection log as possible that captures the issue.
  Note: Connection logs may contain a lot of spurious information that doesn't pertain to the issue at hand.

  Scenario Example
  Mail deletes a message when you try to move it from one mailbox to another on the same IMAP server.

  1. First you want to check Mail to ensure that there's nothing pending
  2. Select the source mailbox,
  3. Quit Mail
  4. Run the below command line:

     /Applications/Mail.app/Contents/MacOS/Mail -LogSocketErrors YES -LogActivityOnHost your.mail.server -LogActivityOnPort 143 &> ~/Desktop/ConnectionLog.txt

  Additionally, if you are on Leopard (10.5) or later, you can run this logging instead:
  /Applications/Mail.app/Contents/MacOS/Mail -LogActivitiyOnHost your.mail.server -LogMaximumBytes 200 -LogIMAPErrors YES &>˜/Desktop/ConnectionLog.txt . (This will cut out a lot of unnecessary personal information that would otherwise be logged.)
  
  NOTE: **You will need to populate your IMAP server's actual hostname and port number where applicable.**

  Also note that "&>" assumes the default shell in Mac OS, bash. And, csh/tsch users will have to say ">&"instead. LogSocketErrors will launch Mail. When Mail is launched, open the Activity panel (Window -> Activity), and once it has died down, drag your message into your mailbox. When the activity is done, quit Mail. That will give you the shortest connection log possible with just the right information required.

• Mail Plug-ins or system third-party applications enhancers installed:

  If you have any system third-party applications enhancers installed, always remove them and retest the issue you are experiencing before reporting the issue to Apple. Mail plug-ins go in one of the [~]Library/Mail/Bundles/ folders, and third-party applications enhancers can be anywhere (one that is known is iAlert which injects itself into Mail without installing a plug-in).

  ***NOTE: These plug-ins and third-party applications enhancers are not currently supported by Mail.***

• If your computer setup is slightly non-standard, indicate that in the bug report. (For example, if you're using a network or portable home directory, have FileVault on, or if you've run out of disk space.)

Back to Top

• iChat version being used

• For issues with other IM clients:
  Provide the version of the client, and version of the OS and include any logging of over-the-wire activity if appropriate: (Example: If a bug where the text display malformed on the receiving end or vice versa, a tcpflow dump [or Windows equivalent] is useful in determining if the data is  being sent correctly. Additionally, Be sure to provide regression information, (i.e., did this always occur with the client or did it start happening after an iChat upgrade/OS upgrade, etc...?))

• Provide details on how you are connected to the Internet. (e.g., Comcast DSL, AirPort hooked into an office LAN, etc....) Be sure to include the brand and model of the router you have for AV-related issues.

• For issues regarding failed video conference attempts, provide the connection log(s) by doing the following:
  1. Quit iChat
  2. Launch terminal
  3. Type in the following command in terminal:
     /Applications/iChat.app/Contents/MacOS/iChat -errorLogLevel 7
  4. Attempt a video/audio chat with the other user
  5. Gather the terminal output from the failed attempt from both users, and provide us with both files.

• In 10.4.8 and later, the connection log can be copied directly from the iChat dialog.
• Additionally, some basic trouble-shooting of ports can help. Make sure you have UDP ports 16384 - 16403 open both ways for UDP traffic. Port 5060 needs to be open for communication in establishing a video/audio chat. Port 3456 is another communication port that we need open.

• Additionally, please take a look at /Applications/Utilities/Console for iChat- or iChatAgent-related error/warning messages and provide us with any details.

• For API issues (AppleScript and our IM Framework), a small sample application or snippet of sample code that demonstrates the problem is required.

Back to Top


Audio
When submitting a bug report against audio, be sure to provide the following additional information:

• Reproducible sample case or project
• Hardware drivers (if applicable)
• Audio/speaker settings located in the Sound preference pane (if applicable)
  

Back to Top


USB/FireWire
When submitting a bug report against USB or Firewire-related issues, be sure to provide the following additional information:

• Power Management (sleep/wake) issues):
  - Be aware of what is plugged into your machine.
  - Be sure to provide a System Profiler while the external drive is connected (if applicable).
  - Tell us the specific type of drive you have (i.e. USB drive, USB flash drive, USB zip, FireWire, FireWire800, etc....)
  - Tell us the specific make, model, and firmware of the drive

• If you have both Intel-based and PPC-based Macs, try to reproduce the issue on both machines and provide us with the pertinent data from both.

Additional information is required for issues specifically filed against AirPort and the iPod. See below for details of what information is required for each.

Back to Top


AirPort
When submitting a bug report against AirPort (for Client Mac or Wireless Base Station issues), be sure to provide the following additional information:

1. Type of encryption (WEP, WPA) if any in use.
2. Specify if the network is visible or hidden.
3. Provide Base station information:
   If there's a possibility that the bug has something to do with wireless base stations (even if your base station is an Apple AirPort Base Station), the make, model, firmware revision, and a summary of the configuration of the unit is required.
   1. To obtain the AirPort configuration file in Mac OS X, follow these steps:
      • Go to /Applications/Utilities
      • Launch the AirPort Admin Utility application
      • Highlight & double-click on the AirPort Base Station (the information should be displayed in the field to the right)
      • Save this configuration as a file, and upload it to your bug report
4. Provide AirPort-specific client Information:
   If there's a possibility that the problem has something to do with the client Mac, provide the version of the AirPort client software (the version of the Airport Admin Utility) you have, and how you have the AirPort tab in Network Preferences configured.
   1. The AirPort network settings in Mac OS X can be obtained by doing the following:
      
      • Select the Apple menu ->System Preferences

Back to Top

If you have experienced a crashing issue with an application on the iPhone, sync your iPhone with iTunes and check the following location on your host machine:

For Mac Users:
/Library/Logs/CrashReporter/MobileDevice/

For Windows Users:
Application Data/Apple Computer/Logs/CrashReporter/MobileDevice/

If you experienced a crash and you are not able to locate any pertinent crash report information, provide specific information including what you were doing, any URLs, or addresses that you were searching for at the time of the crash.

Back to Top


iPod
When submitting a bug report against the iPod product line, be sure to provide the following additional information:

• The iPod model against which you are filing a bug
  For help determining your iPod model, visit http://docs.info.apple.com/article.html?artnum=61688.

  
  

• The version of iPod software (firmware) currently installed on your iPod For help determining your iPod software version, visit http://docs.info.apple.com/article.html?artnum=60984.

Back to Top


iDVD
When submitting a bug report against an iDVD issues, be sure to provide the following additional information:

1. Media:
   • What DVD-R media was used? Include the brand and speed.
   • Have you tried using different media to burn your project? What happened?
2. Project Information:
   • How many menus are present?
   • Are these menus customized: yes/no?
   • How many slideshows?
   • How many images in total?
   • What image is the format/size?
   • Is there any DVD-ROM content? If so, what?
   • How many videos, format, source (iMove/FCP/Other Type)
   • Is this an old project you just continue to work on or is it a new project?
   • Was iDVD launched by you or it was launched from iMovie or iPhoto?
   • how did you create the files used in the project?
   • What version of iMovie was used (if any)?
   • What version of QuickTime?
3. Complete project file
4. Hardware drivers (if applicable)
   

Back to Top