.. _cha:submitbug:

Submitting a bug report
=======================

Whenever encountering that |TRACE| fails while instrumenting an application or
generating a trace-file, you may consider to submit a bug report to
tools@bsc.es.

Before submitting a bug report, consider looking at the Frequently Asked
Questions in appendix :ref:`cha:FAQ` because it may contain valuable information
to address the failure you observe.

In any case, if you find that |TRACE| fails and you want to submit a bug report,
please collect as much as information possible to ease the bug-hunting process.

The information required depen whether the bug refers to a compilation or an
execution issue.


.. _sec:bugcompilation:

Reporting a compilation issue
-----------------------------

The following list of items are valuable when reporting a compilation problem:

* |TRACE| version (this information appears in the first messages of the
  execution).
* |TRACE| configuration information, such as:

  * the configure output and the generated :file:`config.log` file.
  * versions of any additional libraries (PAPI, libunwind, DynInst, CUDA,
    OpenCL, libxml2, libdwarf, libelf, ...)

* The compilation error itself as reported by invoking :command:`make V=1`.


.. _sec:bugexecution:

Reporting an execution issue
----------------------------

The following list of items are valuable when reporting an execution problem:

* |TRACE| version (this information appears in the first messages of the
  execution).
* |TRACE| configuration information, such as:

  * the configure output and the generated :file:`config.log` file,
  * versions of any additional libraries (PAPI, libunwind, DynInst, CUDA,
    OpenCL, libxml2, libdwarf, libelf, ...), and/or
  * the :command:`${EXTRAE_HOME}/etc/configured.sh` output.

* The result of the :command:`make check` command after the |TRACE| compilation
  process.
* Does the application successfully executes with and without |TRACE|?
* Any valuable information from the system (type of processor, network, ...).
* Which type of parallel programming paradigm does the application use: MPI,
  OpenMP, OmpSs, pthreads, ..., hybrid?
* How do you execute the application? Which instrumentation library do you use?
* The |TRACE| configuration file used.
* Any output generated by the application execution (in either the output or
  error channels).
* If the execution generates a core dump, a backtrace of the dump using the
  :command:`where` command of the ``gdb`` debugger.