Mercurial > hg > orthanc-book
changeset 538:d18496f166b8
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 | 2c8f4eca3cd2 |
| children | c00d72b90ad5 d70347eecb91 |
| files | Sphinx/source/faq/log.rst Sphinx/source/users.rst Sphinx/source/users/man-orthanc.rst Sphinx/source/users/man-orthanc.txt |
| diffstat | 4 files changed, 157 insertions(+), 15 deletions(-) [+] |
line wrap: on
line diff
--- a/Sphinx/source/faq/log.rst Thu Nov 05 07:36:18 2020 +0100 +++ b/Sphinx/source/faq/log.rst Thu Nov 05 15:06:41 2020 +0100 @@ -25,23 +25,32 @@ Generating an exploitable debug log =================================== -By default, Orthanc logs only the `WARNING` and `ERROR` level -logs. For your log to be exploitable by the Orthanc community, you must -generate them with the ``--verbose`` or ``--trace`` to get the `INFO` -and `TRACE` information levels. If you are using -Orthanc at the command-line, simply add these flags and redirect the -standard outputs to some log file. +.. highlight:: bash + +By default, the Orthanc logs contain only the ``WARNING`` and +``ERROR`` information levels. For your logs to be exploitable by the +Orthanc community, you must include more information by adding the +``--verbose`` or ``--trace`` command-line options, which will add the +``INFO`` and ``TRACE`` information levels. If you are starting Orthanc +from the command-line, simply add these flags and redirect the +standard outputs to some log file. For instance:: -However, if you use packaged versions of Orthanc that runs the server -in background, you will have to manually start Orthanc. The sections -below explain how to achieve this goal with the officially supported -packages. + $ ./Orthanc --trace --logfile=orthanc.log + +Note that the Orthanc command-line tool has many other options related +to logging. Check out the :ref:`full manpage <manpage>`. + +However, if you use packaged versions of Orthanc that starts the +server in background (such as GNU/Linux packages or the Windows +installers by Osimis), you will have to manually start Orthanc. The +sections below explain how to achieve this goal with the officially +supported packages. Under Windows ^^^^^^^^^^^^^ -Under Windows, if you used the official installer: +Under Windows, if you used the official installer by Osimis: 1. Download the `precompiled command-line version <https://www.orthanc-server.com/download-windows.php>`__ of Orthanc. @@ -89,12 +98,65 @@ $ sudo docker run -a stderr -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc --verbose /etc/orthanc > Orthanc.log 2>&1 -Change the log level while Orthanc is running -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Changing the log level while Orthanc is running +=============================================== -Starting from Orthanc 1.6.0, you can also change the log level while Orthanc is running through the Rest API:: +Starting with Orthanc 1.6.0, you can dynamically change the log level +while Orthanc is running using the :ref:`REST API <rest>`:: $ curl -X PUT http://localhost:8042/tools/log-level -d "verbose" $ curl -X PUT http://localhost:8042/tools/log-level -d "trace" $ curl -X PUT http://localhost:8042/tools/log-level -d "default" + +Log categories +============== + +Starting with Orthanc 1.8.1, log messages are associated with a +**category**. The category indicates the subsystem of Orthanc from +which the message comes (such as the embedded HTTP server, the DICOM +communications, Lua scripts...). + +It is possible to choose a different log level for each category. This +can be done when starting Orthanc as follows:: + + $ ./Orthanc --verbose-http --trace-dicom + +This command would start Orthanc in verbose mode for HTTP-related +messages, and would enable debug messages related to DICOM. The full +list of the available log categories (``http``, ``dicom``, ``lua``, +``plugins``...) can be found in the :ref:`manpage of Orthanc +<manpage>` or by starting Orthanc with the ``--help`` flag. + +It is also possible to dynamically change the log level of a category +while Orthanc is running by using the :ref:`REST API <rest>`, for +instance:: + + $ curl -X PUT http://localhost:8042/tools/log-level-http -d "verbose" + $ curl -X PUT http://localhost:8042/tools/log-level-dicom -d "trace" + $ curl -X PUT http://localhost:8042/tools/log-level-plugins -d "default" + +The list of the available log categories is also available through the +REST API, by inspecting the URIs that are prefixed by +``/tools/log-level``:: + + $ curl http://localhost:8042/tools/ + [...] + "log-level", + "log-level-dicom", + "log-level-generic", + "log-level-http", + "log-level-jobs", + [...] + +**Remarks:** + +* Messages that are not associated with a well-identified category are + considered as belonging to the ``generic`` category. + +* Using the ``--verbose`` or ``-trace`` command-line options, or + changing the value of the ``/tools/log-level`` URI will reset the + log level of **all** the categories. Note that the command-line + options are applied from left to right. +
--- a/Sphinx/source/users.rst Thu Nov 05 07:36:18 2020 +0100 +++ b/Sphinx/source/users.rst Thu Nov 05 15:06:41 2020 +0100 @@ -23,4 +23,4 @@ :hidden: users/debian-packages.rst - + users/man-orthanc.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/users/man-orthanc.rst Thu Nov 05 15:06:41 2020 +0100 @@ -0,0 +1,7 @@ +.. _manpage: + +Manpage of Orthanc +================== + +.. include:: ./man-orthanc.txt + :literal:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/users/man-orthanc.txt Thu Nov 05 15:06:41 2020 +0100 @@ -0,0 +1,73 @@ +ORTHANC(1) User Commands ORTHANC(1) + +NAME + Orthanc - Lightweight, RESTful DICOM server for healthcare and medical + research + +SYNOPSIS + Orthanc [OPTION]... [CONFIGURATION] + +DESCRIPTION + Orthanc, lightweight, RESTful DICOM server for healthcare and medical + research. + + The "CONFIGURATION" argument can be a single file or a directory. In + the case of a directory, all the JSON files it contains will be merged. + If no configuration path is given on the command line, a set of default + parameters is used. Please refer to the Orthanc homepage for the full + instructions about how to use Orthanc <http://www.orthanc-server.com/>. + + Command-line options: + --help display this help and exit + + --logdir=[dir] + directory where to store the log files (by default, the log is + dumped to stderr) + + --logfile=[file] + file where to store the log of Orthanc (by default, the log is + dumped to stderr) + + --config=[file] + create a sample configuration file and exit (if file is "-", + dumps to stdout) + + --errors + print the supported error codes and exit + + --verbose + be verbose in logs + + --trace + highest verbosity in logs (for debug) + + --upgrade + allow Orthanc to upgrade the version of the database (beware + that the database will become incompatible with former versions + of Orthanc) + + --no-jobs + Don't restart the jobs that were stored during the last execu‐ + tion of Orthanc + + --version + output version information and exit + + Exit status: + 0 if success, + + -1 if error (have a look at the logs). + +AUTHOR + Written by Sebastien Jodogne <s.jodogne@orthanc-labs.com> + +COPYRIGHT + Copyright © 2012-2016 Sebastien Jodogne, Medical Physics Department, + University Hospital of Liege (Belgium) + Copyright © 2017-2020 Osimis S.A. (Belgium) Licensing GPLv3+: GNU GPL + version 3 or later <http://gnu.org/licenses/gpl.html>, with OpenSSL + exception. + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + +Orthanc 1.8.0 November 2020 ORTHANC(1)