annotate Sphinx/source/faq/debugging.rst @ 278:9bf644571511

fix doc wrt recycling order
author amazy
date Mon, 09 Sep 2019 12:34:27 +0200
parents a64197133114
children 6cbcdb965ad3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _debugging:
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3 Debugging Orthanc
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 =================
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6 If you experience an error within Orthanc (or one of its plugins), that
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 the troubleshooting sections (cf. :ref:`here <troubleshooting>` and
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8 :ref:`here <dicom>`) do not help, and that you can't provide a robust
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 way to reproduce your issue by third-party developers, you'll have to
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 analyze the backtrace of Orthanc.
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12 If you observe a **fatal crash** of Orthanc, where Orthanc stops
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
13 abruptly (e.g. by creating a so-called "core dumped" or reporting an
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14 invalid memory access), which rarely occurs, please check the
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15 :ref:`dedicated section <crash>`). The present FAQ entry is rather
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
16 about C++ exceptions that are thrown by Orthanc, typically as a
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17 consequence of invalid inputs, and that result in an error message
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18 reported by Orthanc (not in a crash), and for which the :ref:`log
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19 files in verbose mode <log>` do not provide meaningful information.
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
20
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
21 **Important reminder:** Most issues with Orthanc can be solved by
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
22 carefully looking at the :ref:`Orthanc logs <log>` in ``--verbose``
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
23 mode!
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
24
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
25
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
26 Any system
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
27 ----------
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
28
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
29 First :ref:`compile Orthanc by yourself <compiling>`, in debug mode by
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
30 setting ``-DCMAKE_BUILD_TYPE=Debug`` when invoking CMake.
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
31
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
32 Then, learn how to use the debugger that is best suited to your
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
33 platform (e.g. Microsoft Visual Studio, gdb or Xcode).
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
34
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
35
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
36 GNU/Linux system using gdb
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
37 --------------------------
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
38
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
39 .. highlight:: bash
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
40
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
41 The Orthanc project provides precompiled debug binaries that can be
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
42 run on almost any recent GNU/Linux system (generated thanks to the
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
43 `LSB - Linux Standard Base SDK
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
44 <https://en.wikipedia.org/wiki/Linux_Standard_Base>`__). This allows
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
45 to debug Orthanc without compiling from sources. Here is a sample
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
46 debug session::
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
47
253
a64197133114 Orthanc 1.5.7
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 245
diff changeset
48 $ wget http://lsb.orthanc-server.com/orthanc/debug/1.5.7/Orthanc
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49 $ chmod +x ./Orthanc
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50 $ gdb ./Orthanc Configuration.json
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51 (gdb) catch throw
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52 Catchpoint 1 (throw)
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
53 (gdb) run
253
a64197133114 Orthanc 1.5.7
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 245
diff changeset
54 W0513 15:24:42.374349 main.cpp:1436] Orthanc version: 1.5.7
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55 ---> Reproduce your error case <---
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
56 Thread 15 "Orthanc" hit Catchpoint 1 (exception thrown), 0x00007ffff6de68bd in __cxa_throw () from /usr/lib/x86_64-linux-gnu/libstdc++.so.6
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
57 (gdb) backtrace
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
58 #0 0x00007ffff6de68bd in __cxa_throw ()
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
59 from /usr/lib/x86_64-linux-gnu/libstdc++.so.6
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
60 ...
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
61
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
62 If you are unable to analyze such a backtrace by yourself, feel free
245
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 244
diff changeset
63 to post your backtrace on the `Orthanc forum
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
64 <https://groups.google.com/forum/#!forum/orthanc-users>`__.
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
66 **Plugins:** Besides the Orthanc core, debug binaries of the official
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
67 plugins precompiled using the LSB are also available at the following
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
68 locations:
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
69
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70 * `Orthanc core <http://lsb.orthanc-server.com/orthanc/debug/>`__
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
71 * `DICOMweb plugin <http://lsb.orthanc-server.com/plugin-dicom-web/debug/>`__
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
72 * `MySQL plugin <http://lsb.orthanc-server.com/plugin-mysql/debug/>`__
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
73 * `Orthanc Web viewer <http://lsb.orthanc-server.com/plugin-webviewer/debug/>`__
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
74 * `PostgreSQL plugin <http://lsb.orthanc-server.com/plugin-postgresql/debug/>`__
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
75 * `Transfers accelerator plugin <http://lsb.orthanc-server.com/plugin-transfers/debug/>`__
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
76 * `Whole-slide imaging <http://lsb.orthanc-server.com/whole-slide-imaging/debug/>`__
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
77
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
78
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
79 Docker
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
80 ------
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
81
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
82 To be written.