<type>documentation</type>
<domain>install</domain>
<id>trouble-diagnostic</id>
<title>Obtaining Diagnostic Output</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

Wing and your debug code run in separate processes, each of which can independently be
configured to collect additional diagnostic log information.

**Diagnosing IDE Problems**

``Submit Bug Report`` in the ``Help`` menu is a quick way to diagnose problems seen while
working with Wing. Please include a description of the problem, your email address so we
can follow up, and leave the ``Include error log`` checkbox checked so we have the
information needed to diagnose and fix the problem. The error log is the file ``ide.log``
in your `Settings Directory <ref:install/user-settings-dir>`__ .

To diagnose failure to start, or if you can't submit a bug report directly from Wing, run
``console_wing.exe`` (on Windows) or ``~~FULL_EXECUTABLE~~ --verbose`` (on Linux and macOS)
from the command line to obtain diagnostic output that you can email to `support at
wingware.com <mailto:support@wingware.com>`__ along with your system type and version,
version of Wing, version of Python, and a description of the problem you are running into.

If Wing is crashing please provide the file ``segfault.log`` from the `User Settings
Directory <ref:install/user-settings-dir>`__ with any bug reports.

**Diagnosing Debugger Problems**

To diagnose debugger problems, set the `Debugger > Diagnostics > Debug Internals Log File
<script:show_preferences_gui#prefname="debug.logfile">`__ preference to the full path of a
file that the debugger will be able to create.  Then try debugging again.

If the file does not appear, instead set the `Debugger > Diagnostics > Debug Internals Log
File <script:show_preferences_gui#prefname="debug.logfile">`__ preference to ``Log to
sys.stderr`` and enable the `Debugger > I/O > Use External Console
<script:show_preferences_gui#prefname="debug.external-console">`__ and `Debugger > I/O >
External Console Waits on Exit
<script:show_preferences_gui#prefname="debug.persist-console">`__ preferences. When you
try again, Wing should display a debug console with diagnostics.

If you are using ``wingdbstub`` to start debug, instead set ``WINGDB_LOGFILE`` environment
variable to ``<stderr>`` (or alter ``kLogFile`` inside ``wingdbstub.py``), and try
launching the following script from the command line:

.. python::

   import wingdbstub
   print("test1")
   x = not_defined
   print("test2")

*Never* check the ``Extremely Verbose Internal Log`` preference unless Wingware Technical
Support asks you to. When this is enabled, it will drastically slow down the debugger.

Debugger diagnostic logs can be emailed to `support at wingware.com
<mailto:support@wingware.com>`__ together with the file ``ide.log`` in your `User Settings
Directory <ref:install/user-settings-dir>`__ , your system version, version of Wing,
version of Python, and a description of the problem you are seeing.

You will want to turn off diagnostic logging again after submitting your report since it
slows down debugging considerably.

**Diagnosing Debug Process Crashing**

If your debug process is crashing entirely while Wing is interacting with it, it may be
that Wing is exercising buggy code when it inspects data in the debug process. In this
case, it can be useful to capture the Python stack at the moment of the crash. You can do
this by installing `faulthandler <https://faulthandler.readthedocs.io/>`__ into the Python
that runs your debug process, and then adding the following to code that is executed
before the crash:

.. python::

  import faulthandler
  faulthandler.enable()

After that is done, the Python stack for each thread is written to ``stderr`` if the
process crashes.

If you can't access output sent to ``stderr``, you can send the stack to a file instead,
as follows:

.. python::

  import faulthandler
  segfault_fn = '/path/to/segfault.log'  # Change this to a valid path
  f = open(segfault_fn, 'a')
  faulthandler.enable(f)
  # IMPORTANT: Leave f open!!!

It is *very important* that you leave the file f open for the life of the process.
Otherwise faulthandler may corrupt another file opened later under the same file
descriptor, by writing the stack there instead. This is a design limitation imposed by the
nature of post-segfault processing.

Please send details of debugger crashes, including the Python stacks obtained by this
method, to `support@wingware.com <mailto:support@wingware.com>`__. We will try to change
Wing's data inspection to avoid the crash that you are seeing, and we may be able to offer
a work-around.

See also `Problems Handling Values <ref:debug/problems-handling-values>`__.
