Mercurial > hg > orthanc-book

comparison Sphinx/source/faq/log.rst @ 538:d18496f166b8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documenting the log categories, and manpage of Orthanc
author Sebastien Jodogne <s.jodogne@gmail.com>
date Thu, 05 Nov 2020 15:06:41 +0100
parents 50bdd7c7e9b9
children 4f3a6145ae34
comparison
equal deleted inserted replaced
537:2c8f4eca3cd2 538:d18496f166b8
23 23
24 24
25 Generating an exploitable debug log 25 Generating an exploitable debug log
26 =================================== 26 ===================================
27 27
28 By default, Orthanc logs only the `WARNING` and `ERROR` level 28 .. highlight:: bash
29 logs. For your log to be exploitable by the Orthanc community, you must
30 generate them with the ``--verbose`` or ``--trace`` to get the `INFO`
31 and `TRACE` information levels. If you are using
32 Orthanc at the command-line, simply add these flags and redirect the
33 standard outputs to some log file.
34 29
35 However, if you use packaged versions of Orthanc that runs the server 30 By default, the Orthanc logs contain only the ``WARNING`` and
36 in background, you will have to manually start Orthanc. The sections 31 ``ERROR`` information levels. For your logs to be exploitable by the
37 below explain how to achieve this goal with the officially supported 32 Orthanc community, you must include more information by adding the
38 packages. 33 ``--verbose`` or ``--trace`` command-line options, which will add the
34 ``INFO`` and ``TRACE`` information levels. If you are starting Orthanc
35 from the command-line, simply add these flags and redirect the
36 standard outputs to some log file. For instance::
37
38 $ ./Orthanc --trace --logfile=orthanc.log
39
40 Note that the Orthanc command-line tool has many other options related
41 to logging. Check out the :ref:`full manpage <manpage>`.
42
43 However, if you use packaged versions of Orthanc that starts the
44 server in background (such as GNU/Linux packages or the Windows
45 installers by Osimis), you will have to manually start Orthanc. The
46 sections below explain how to achieve this goal with the officially
47 supported packages.
39 48
40 49
41 Under Windows 50 Under Windows
42 ^^^^^^^^^^^^^ 51 ^^^^^^^^^^^^^
43 52
44 Under Windows, if you used the official installer: 53 Under Windows, if you used the official installer by Osimis:
45 54
46 1. Download the `precompiled command-line version 55 1. Download the `precompiled command-line version
47 <https://www.orthanc-server.com/download-windows.php>`__ of Orthanc. 56 <https://www.orthanc-server.com/download-windows.php>`__ of Orthanc.
48 57
49 2. Stop the Orthanc service. The actual process depends on your 58 2. Stop the Orthanc service. The actual process depends on your
87 96
88 The command-line to be used is:: 97 The command-line to be used is::
89 98
90 $ sudo docker run -a stderr -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc --verbose /etc/orthanc > Orthanc.log 2>&1 99 $ sudo docker run -a stderr -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc --verbose /etc/orthanc > Orthanc.log 2>&1
91 100
92 Change the log level while Orthanc is running 101
93 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 102 Changing the log level while Orthanc is running
103 ===============================================
94 104
95 Starting from Orthanc 1.6.0, you can also change the log level while Orthanc is running through the Rest API:: 105 Starting with Orthanc 1.6.0, you can dynamically change the log level
106 while Orthanc is running using the :ref:`REST API <rest>`::
96 107
97 $ curl -X PUT http://localhost:8042/tools/log-level -d "verbose" 108 $ curl -X PUT http://localhost:8042/tools/log-level -d "verbose"
98 $ curl -X PUT http://localhost:8042/tools/log-level -d "trace" 109 $ curl -X PUT http://localhost:8042/tools/log-level -d "trace"
99 $ curl -X PUT http://localhost:8042/tools/log-level -d "default" 110 $ curl -X PUT http://localhost:8042/tools/log-level -d "default"
100 111
112
113 Log categories
114 ==============
115
116 Starting with Orthanc 1.8.1, log messages are associated with a
117 **category**. The category indicates the subsystem of Orthanc from
118 which the message comes (such as the embedded HTTP server, the DICOM
119 communications, Lua scripts...).
120
121 It is possible to choose a different log level for each category. This
122 can be done when starting Orthanc as follows::
123
124 $ ./Orthanc --verbose-http --trace-dicom
125
126 This command would start Orthanc in verbose mode for HTTP-related
127 messages, and would enable debug messages related to DICOM. The full
128 list of the available log categories (``http``, ``dicom``, ``lua``,
129 ``plugins``...) can be found in the :ref:`manpage of Orthanc
130 <manpage>` or by starting Orthanc with the ``--help`` flag.
131
132 It is also possible to dynamically change the log level of a category
133 while Orthanc is running by using the :ref:`REST API <rest>`, for
134 instance::
135
136 $ curl -X PUT http://localhost:8042/tools/log-level-http -d "verbose"
137 $ curl -X PUT http://localhost:8042/tools/log-level-dicom -d "trace"
138 $ curl -X PUT http://localhost:8042/tools/log-level-plugins -d "default"
139
140 The list of the available log categories is also available through the
141 REST API, by inspecting the URIs that are prefixed by
142 ``/tools/log-level``::
143
144 $ curl http://localhost:8042/tools/
145 [...]
146 "log-level",
147 "log-level-dicom",
148 "log-level-generic",
149 "log-level-http",
150 "log-level-jobs",
151 [...]
152
153 **Remarks:**
154
155 * Messages that are not associated with a well-identified category are
156 considered as belonging to the ``generic`` category.
157
158 * Using the ``--verbose`` or ``-trace`` command-line options, or
159 changing the value of the ``/tools/log-level`` URI will reset the
160 log level of **all** the categories. Note that the command-line
161 options are applied from left to right.
162