annotate Sphinx/source/users/advanced-rest.rst @ 1113:a588960a72e5 default tip

spelling
author Alain Mazy <am@orthanc.team>
date Mon, 28 Oct 2024 09:23:08 +0100
parents d2be251975d1
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _rest-advanced:
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3 Advanced features of the REST API
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 =================================
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6 .. contents::
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 :depth: 3
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 This section of the Orthanc Book is a complement to the description of
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 the :ref:`REST API of Orthanc <rest>`. It explains some advanced uses
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11 of the API.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
13
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14 .. _jobs:
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
16 Jobs
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17 ----
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19 Since Orthanc 1.4.0, a jobs engine is embedded within Orthanc. Jobs
854
b569e93d1d45 jobs update
Alain Mazy <am@osimis.io>
parents: 850
diff changeset
20 are high-level tasks to be processed by Orthanc. Jobs can be started
b569e93d1d45 jobs update
Alain Mazy <am@osimis.io>
parents: 850
diff changeset
21 synchronously or asynchronously (see the section below). All Jobs,
b569e93d1d45 jobs update
Alain Mazy <am@osimis.io>
parents: 850
diff changeset
22 no matter how they were started, are first added
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
23 to a queue of pending tasks, and Orthanc will simultaneously execute a
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
24 fixed number of jobs (check out :ref:`configuration option
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
25 <configuration>` ``ConcurrentJobs``). Once the jobs have been
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
26 processed, they are tagged as successful or failed, and kept in a
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
27 history (the size of this history is controlled by the
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
28 ``JobsHistorySize`` option).
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
29
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
30 By default, Orthanc saves the jobs into its database (check out the
855
12f8932ee3a7 jobs update
Alain Mazy <am@osimis.io>
parents: 854
diff changeset
31 ``SaveJobs`` option). Jobs are saved within 100ms after their creation,
12f8932ee3a7 jobs update
Alain Mazy <am@osimis.io>
parents: 854
diff changeset
32 and then, the whole jobs list, with their updated status, is saved every 10 seconds and when
854
b569e93d1d45 jobs update
Alain Mazy <am@osimis.io>
parents: 850
diff changeset
33 Orthanc stops. If Orthanc is stopped then relaunched, the jobs whose
b569e93d1d45 jobs update
Alain Mazy <am@osimis.io>
parents: 850
diff changeset
34 processing was not finished are automatically put into the queue of
b569e93d1d45 jobs update
Alain Mazy <am@osimis.io>
parents: 850
diff changeset
35 pending tasks or resumed if they were being processed when Orthanc stopped,
b569e93d1d45 jobs update
Alain Mazy <am@osimis.io>
parents: 850
diff changeset
36 regardless of whether they were started synchronously or asynchronously
b569e93d1d45 jobs update
Alain Mazy <am@osimis.io>
parents: 850
diff changeset
37 (see the section below). The command-line option ``--no-jobs`` can also be used to
798
80b9ceeb4045 updated jobs doc
Alain Mazy <am@osimis.io>
parents: 763
diff changeset
38 prevent the loading of jobs from the database upon the launch of
80b9ceeb4045 updated jobs doc
Alain Mazy <am@osimis.io>
parents: 763
diff changeset
39 Orthanc.
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
40
821
d7c8c8f6cffb removed 'LimitJobs' that is unused
Alain Mazy <am@osimis.io>
parents: 817
diff changeset
41 Note that the queue of pending jobs has no size limit.
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
42
672
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 671
diff changeset
43 .. _jobs-synchronicity:
8bda16db46cf SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 671
diff changeset
44
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
45 Synchronous vs. asynchronous calls
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
46 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
47
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
48 Some calls to the REST API of Orthanc need time to be executed, and
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49 thus result in adding a job to the processing queue. This notably
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50 includes the following URIs:
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52 * :ref:`Modifying and anonymizing <anonymization>` DICOM instances.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
53 * Creating ZIP or media archives.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
54 * C-Move SCU (``/queries/.../retrieve``).
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55 * C-Store SCU (``/modalities/.../store``).
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
56 * Sending to an Orthanc peer (``/peers/.../store``).
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
57 * :ref:`Split/merge <split-merge>`.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
58 * Sending images using the :ref:`transfers accelerator <transfers>` plugin.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
59
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
60 Such REST API calls can be configured to be executed in a synchronous
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
61 or an asynchronous mode:
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
62
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
63 * **Synchronous calls** wait for the end of the execution of their
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
64 associated job. This is in general the default behavior.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65 * **Asynchronous calls** end immediately and return a handle to their
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
66 associated job. It is up to the caller to monitor the execution by
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
67 calling the jobs API (e.g. to know whether the job has finished its
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
68 execution).
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
69
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70 The choice between synchronous and asynchronous modes is done by
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
71 setting the ``Synchronous`` field (or indifferently the
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
72 ``Asynchronous`` field) in the POST body of the call to the REST
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
73 API. Note that the :ref:`transfers accelerator <transfers>` only runs
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
74 in asynchronous mode.
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
75
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
76 An integer number (possibly negative) can be specified in the
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
77 ``Priority`` field of the POST body. Jobs with higher priority will be
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
78 executed first. By default, the priority is set to zero.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
79
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
80 Despite being more complex to handle, the asynchronous mode is highly
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
81 recommended for jobs whose execution time can last over a dozen of
693
650100457193 SynchronousZipStream
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 678
diff changeset
82 seconds (typically, the creation of an archive if
650100457193 SynchronousZipStream
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 678
diff changeset
83 ``SynchronousZipStream`` :ref:`configuration option <configuration>`
650100457193 SynchronousZipStream
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 678
diff changeset
84 is set to ``false``, or a network transfer). Indeed, synchronous
650100457193 SynchronousZipStream
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 678
diff changeset
85 calls can be affected by timeouts in the HTTP protocol if they last
650100457193 SynchronousZipStream
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 678
diff changeset
86 too long.
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
87
850
989f00cd4dfa MediaArchiveSize
Alain Mazy <am@osimis.io>
parents: 847
diff changeset
88 When generating archives asynchronously, you should take care of
989f00cd4dfa MediaArchiveSize
Alain Mazy <am@osimis.io>
parents: 847
diff changeset
89 the ``MediaArchiveSize`` configuration that defines the maximum
989f00cd4dfa MediaArchiveSize
Alain Mazy <am@osimis.io>
parents: 847
diff changeset
90 number of ZIP/media archives that are maintained by Orthanc, as a
933
a5e7e7001316 Orthanc 1.12.0
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 927
diff changeset
91 response to the asynchronous creation of archive. As of Orthanc
1075
d2be251975d1 Orthanc 1.12.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1059
diff changeset
92 1.12.4, this value is ``1`` by default.
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
93
260
f9e7036d81d0 updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 253
diff changeset
94 .. _jobs-monitoring:
f9e7036d81d0 updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 253
diff changeset
95
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
96 Monitoring jobs
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
97 ^^^^^^^^^^^^^^^
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
98
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
99 .. highlight:: bash
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
100
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
101 The list of all jobs can be retrieved as follows::
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
102
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
103 $ curl http://localhost:8042/jobs
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
104 [ "e0d12aac-47eb-454f-bb7f-9857931e2904" ]
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
105
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
106 Full details about each job can be retrieved::
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
107
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
108 $ curl http://localhost:8042/jobs/e0d12aac-47eb-454f-bb7f-9857931e2904
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
109 {
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
110 "CompletionTime" : "20190306T095223.753851",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
111 "Content" : {
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
112 "Description" : "REST API",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
113 "InstancesCount" : 1,
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
114 "UncompressedSizeMB" : 0
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
115 },
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
116 "CreationTime" : "20190306T095223.750666",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
117 "EffectiveRuntime" : 0.001,
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
118 "ErrorCode" : 0,
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
119 "ErrorDescription" : "Success",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
120 "ID" : "e0d12aac-47eb-454f-bb7f-9857931e2904",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
121 "Priority" : 0,
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
122 "Progress" : 100,
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
123 "State" : "Success",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
124 "Timestamp" : "20190306T095408.556082",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
125 "Type" : "Archive"
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
126 }
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
127
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
128 Note that the ``/jobs?expand`` URI will retrieve this information in
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
129 one single REST query. The ``Content`` field contains the parameters
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
130 of the job, and is very specific to the ``Type`` of job.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
131
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
132 The ``State`` field can be:
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
133
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
134 * ``Pending``: The job is waiting to be executed.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
135 * ``Running``: The job is being executed. The ``Progress`` field will
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
136 be continuously updated to reflect the progression of the execution.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
137 * ``Success``: The job has finished with success.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
138 * ``Failure``: The job has finished with failure. Check out the
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
139 ``ErrorCode`` and ``ErrorDescription`` fields for more information.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
140 * ``Paused``: The job has been paused.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
141 * ``Retry``: The job has failed internally, and has been scheduled for
1075
d2be251975d1 Orthanc 1.12.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1059
diff changeset
142 re-submission after a delay. As of Orthanc 1.12.4, this feature is not
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
143 used by any type of job.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
144
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
145 In order to wait for the end of an asynchronous call, the caller will
847
Alain Mazy <am@osimis.io>
parents: 839
diff changeset
146 typically have to poll the ``/jobs/...`` URI (i.e. make periodic
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
147 calls), waiting for the ``State`` field to become ``Success`` or
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
148 ``Failure``.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
149
671
bc8fa2bf4cf7 asynchronous c-move
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
150 Note that the `integration tests of Orthanc
1075
d2be251975d1 Orthanc 1.12.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1059
diff changeset
151 <https://orthanc.uclouvain.be/hg/orthanc-tests/file/Orthanc-1.12.4/Tests/Toolbox.py>`__
671
bc8fa2bf4cf7 asynchronous c-move
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
152 give an example about how to monitor a job in Python using the REST
bc8fa2bf4cf7 asynchronous c-move
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
153 API (cf. function ``MonitorJob()``).
bc8fa2bf4cf7 asynchronous c-move
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 638
diff changeset
154
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
155
833
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
156 .. _jobs-priority:
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
157
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
158 Jobs priority
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
159 ^^^^^^^^^^^^^
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
160
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
161 When executing jobs, Orthanc will pick the jobs with the highest ``Priority``
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
162 from the pending job list. An integer value is a valid ``Priority``. You may
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
163 also use negative number to lower the priority below the default one (``0``).
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
164
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
165 Pending jobs are not ordered in the API response but they are picked up in the right order.
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
166
24a2ce71a161 job priority
Alain Mazy <am@osimis.io>
parents: 825
diff changeset
167
322
c5226c5509ca storage commitment scp
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 310
diff changeset
168 .. _jobs-controlling:
c5226c5509ca storage commitment scp
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 310
diff changeset
169
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
170 Interacting with jobs
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
171 ^^^^^^^^^^^^^^^^^^^^^
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
172
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
173 Given the ID of some job, one can:
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
174
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
175 * Cancel the job by POST-ing to ``/jobs/.../cancel``.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
176 * Pause the job by POST-ing to ``/jobs/.../pause``.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
177 * Resume a job in ``Paused`` state by POST-ing to ``/jobs/.../resume``.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
178 * Retry a job in ``Failed`` state by POST-ing to ``/jobs/.../resubmit``.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
179
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
180 The related state machine is depicted in the `implementation notes
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 990
diff changeset
181 <https://orthanc.uclouvain.be/hg/orthanc/raw-file/default/OrthancServer/Resources/ImplementationNotes/JobsEngineStates.pdf>`__.
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
182
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
183
487
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
184 Example: Asynchronous generation of an archive
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
185 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
186
487
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
187 .. highlight:: bash
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
188
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
189 Sucessful jobs are associated with a set of so-called "outputs" that
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
190 can be attached to the job.
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
191
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
192 Here is a sample bash session to ask Orthanc to generate a ZIP
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
193 archive, then to download it locally::
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
194
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
195 $ curl http://localhost:8042/studies/27f7126f-4f66fb14-03f4081b-f9341db2-53925988/archive -d '{"Asynchronous":true}'
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
196 {
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
197 "ID" : "82cc02d1-03fe-41f9-be46-a308d16ea94a",
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
198 "Path" : "/jobs/82cc02d1-03fe-41f9-be46-a308d16ea94a"
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
199 }
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
200 $ curl http://localhost:8042/jobs/82cc02d1-03fe-41f9-be46-a308d16ea94a
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
201 {
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
202 "CompletionTime" : "20200817T144700.401777",
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
203 "Content" : {
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
204 "Description" : "REST API",
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
205 "InstancesCount" : 232,
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
206 "UncompressedSizeMB" : 64
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
207 },
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
208 "CreationTime" : "20200817T144658.011824",
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
209 "EffectiveRuntime" : 2.3879999999999999,
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
210 "ErrorCode" : 0,
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
211 "ErrorDescription" : "Success",
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
212 "ID" : "82cc02d1-03fe-41f9-be46-a308d16ea94a",
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
213 "Priority" : 0,
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
214 "Progress" : 100,
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
215 "State" : "Success",
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
216 "Timestamp" : "20200817T144705.770825",
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
217 "Type" : "Archive"
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
218 }
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
219 $ curl http://localhost:8042/jobs/82cc02d1-03fe-41f9-be46-a308d16ea94a/archive > a.zip
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
220
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
221 Note how we retrieve the content of the archive by accessing the
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
222 ``archive`` output of the job (check out the virtual method
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
223 ``IJob::GetOutput()`` from the `source code
1075
d2be251975d1 Orthanc 1.12.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1059
diff changeset
224 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.4/OrthancServer/Sources/ServerJobs/ArchiveJob.cpp>`__
487
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
225 of Orthanc).
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
226
516
416581db306e sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 513
diff changeset
227 Here is the corresponding sequence of commands to generate a DICOMDIR
416581db306e sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 513
diff changeset
228 media::
416581db306e sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 513
diff changeset
229
416581db306e sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 513
diff changeset
230 $ curl http://localhost:8042/studies/27f7126f-4f66fb14-03f4081b-f9341db2-53925988/media -d '{"Asynchronous":true}'
416581db306e sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 513
diff changeset
231 $ curl http://localhost:8042/jobs/6332be8a-0052-44fb-8cc2-ac959aeccad9/archive > a.zip
416581db306e sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 513
diff changeset
232
1075
d2be251975d1 Orthanc 1.12.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1059
diff changeset
233 As of Orthanc 1.12.4, only the creation of a ZIP or a DICOMDIR archive
516
416581db306e sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 513
diff changeset
234 produces such "outputs".
487
13bb9af3df26 Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 461
diff changeset
235
1059
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
236
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
237 .. _image-dicomization:
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
238
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
239 DICOM-ization of an image
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
240 -------------------------
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
241
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
242 JPEG images or PNG images can be converted to DICOM using the
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
243 ``/tools/create-dicom`` `route in the REST API
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
244 <https://orthanc.uclouvain.be/api/#tag/System/paths/~1tools~1create-dicom/post>`__. The
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
245 procedure consists in providing Orthanc with the JPEG/PNG content
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
246 using `data URI scheme
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
247 <https://en.wikipedia.org/wiki/Data_URI_scheme>`__. Here is a minimal
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
248 working example in Python 3:
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
249
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
250 .. literalinclude:: code/image-dicomization.py
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
251 :language: python
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
252
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
253 Evidently, make sure to replace ``data:image/png;base64,%s`` by
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
254 ``data:image/jpeg;base64,%s`` if you need to DICOM-ize a JPEG image
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
255 instead of a PNG image.
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
256
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
257 The call to ``/tools/create-dicom`` will return the Orthanc instance
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
258 ID of the newly created DICOM resource. Orthanc will encode your
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
259 JPEG/PNG using an :ref:`uncompressed transfer syntax
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
260 <dicom-pixel-data>` to ensure maximal compatibility.
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
261
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
262 Importantly, the ``Parent`` field of the ``POST`` body can be set to
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
263 the :ref:`Orthanc identifier of some study <orthanc-ids>` in order to
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
264 attach the newly-created PDF series to the given parent study.
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
265
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
266
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
267 .. _pdf:
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
268
310
c13431b26e55 title about pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 297
diff changeset
269 Attaching PDF file as DICOM series
c13431b26e55 title about pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 297
diff changeset
270 ----------------------------------
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
271
226
eaae8d630277 proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 225
diff changeset
272 Among many different types of data, DICOM files can be used to store
1059
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
273 PDF files. Similarly to :ref:`JPEG/PNG <image-dicomization>`, the
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
274 ``/tools/create-dicom`` URI can be used to upload a PDF file to
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
275 Orthanc. The following scripts perform such a *DICOM-ization*: They
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
276 convert the ``HelloWorld2.pdf`` file to base64, then perform a
226
eaae8d630277 proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 225
diff changeset
277 ``POST`` request with JSON data containing the converted payload.
225
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
278
297
64d1ddab8246 Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents: 290
diff changeset
279 Using bash:
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
280
297
64d1ddab8246 Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents: 290
diff changeset
281 .. code-block:: bash
225
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
282
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
283 # create the json data, with the BASE64 data embedded in it
545
931052bd5a53 explain the "Parent" field in "/tools/create-dicom" for PDF
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 528
diff changeset
284 (echo -n '{"Parent": "b6e8436b-c5835b7b-cecc9576-0483e165-ab5c710b", "Tags" : {"Modality" : "CT"}, "Content" : "data:application/pdf;base64,'; base64 HelloWorld2.pdf; echo '"}') > /tmp/foo
225
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
285
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
286 # upload it to Orthanc
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
287 cat /tmp/foo | curl -H "Content-Type: application/json" -d @- http://localhost:8042/tools/create-dicom
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
288
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
289
1059
2d83e9ce6bf0 added DICOM-ization of an image
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1021
diff changeset
290 Using Microsoft PowerShell:
297
64d1ddab8246 Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents: 290
diff changeset
291
64d1ddab8246 Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents: 290
diff changeset
292 .. code-block:: perl
225
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
293
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
294 # create the BASE64 string data
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
295 $fileInBase64 = $([Convert]::ToBase64String((gc -Path "HelloWorld2.pdf" -Encoding Byte)))
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
296
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
297 # create the json data
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
298 $params = @{Tags = @{PatientName = "Benjamino";Modality = "CT"};Content= "data:application/pdf;base64,$fileInBase64"}
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
299
376
6d7a36447e21 Small rephrasing
Benjamin Golinvaux <bgo@osimis.io>
parents: 363
diff changeset
300 # disabling the progress bar makes the Invoke-RestMethod call MUCH faster
297
64d1ddab8246 Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents: 290
diff changeset
301 $ProgressPreference = 'SilentlyContinue'
64d1ddab8246 Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents: 290
diff changeset
302
64d1ddab8246 Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents: 290
diff changeset
303 # upload it to Orthanc
64d1ddab8246 Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents: 290
diff changeset
304 $reply = Invoke-RestMethod http://localhost:8042/tools/create-dicom -Method POST -Body ($params|ConvertTo-Json) -ContentType 'application/json'
225
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
305
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
306 # display the result
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
307 Write-Host "The instance can be retrieved in PDF at http://localhost:8042$($reply.Path)/pdf"
ced9dbf86de8 Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents: 224
diff changeset
308
907
7ccecfb76428 create pdf with python
Alain Mazy <am@osimis.io>
parents: 906
diff changeset
309 And here's another sample `using python
962
5df222ddd7d1 fix links to setup-samples
Alain Mazy <am@osimis.io>
parents: 947
diff changeset
310 <https://github.com/orthanc-server/orthanc-setup-samples/tree/master/python-samples/attach-pdf-to-study.py>`__.
907
7ccecfb76428 create pdf with python
Alain Mazy <am@osimis.io>
parents: 906
diff changeset
311
226
eaae8d630277 proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 225
diff changeset
312 You can use the ``/instances/.../pdf`` URI to retrieve an embedded PDF
eaae8d630277 proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 225
diff changeset
313 file.
228
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
314
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
315
596
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
316 .. _private-tags:
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
317
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
318 Creating DICOM instance with private tags
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
319 -----------------------------------------
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
320
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
321 .. highlight:: json
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
322
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
323 The ``/tools/create-dicom`` URI can be used to create DICOM instances
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
324 containing private tags. Those private tags must first be defined in
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
325 the ``Dictionary`` configuration option of Orthanc. Importantly, the
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
326 ``xxxx,0010`` tag must be defined to register the private creator,
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
327 where ``xxxx`` is the private group of interest. Here is a sample::
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
328
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
329 {
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
330 "Dictionary" : {
906
Alain Mazy <am@osimis.io>
parents: 905
diff changeset
331 "0405,0010" : [ "LO", "PrivateCreatorForMyCompany", 1, 1, "My Company" ], // reserve 0405,10xx for "My Company"
Alain Mazy <am@osimis.io>
parents: 905
diff changeset
332 "0405,1001" : [ "ST", "MyPrivateXMLTag", 1, 1, "My Company" ] // all tags from "My Company" must start with 0405,10xx
596
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
333 }
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
334 }
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
335
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
336 Once Orthanc is started using this configuration file, it is possible
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
337 to create a DICOM instance using the following POST body on
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
338 ``/tools/create-dicom``::
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
339
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
340 {
905
db62aa60a9b3 private tags
Alain Mazy <am@osimis.io>
parents: 872
diff changeset
341 "PrivateCreator" : "My Company", // private creator here
596
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
342 "Tags" :
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
343 {
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
344 "PatientName" : "Love^Sarah",
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
345 "PatientID" : "7",
905
db62aa60a9b3 private tags
Alain Mazy <am@osimis.io>
parents: 872
diff changeset
346 "PrivateCreatorForMyCompany" : "My Company", // and here !
db62aa60a9b3 private tags
Alain Mazy <am@osimis.io>
parents: 872
diff changeset
347 "MyPrivateXMLTag" : "<xml><test>Testing</test></xml>"
596
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
348 }
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
349 }
ef64d0769014 private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 568
diff changeset
350
905
db62aa60a9b3 private tags
Alain Mazy <am@osimis.io>
parents: 872
diff changeset
351 Which then gives this in Orthanc UI:
db62aa60a9b3 private tags
Alain Mazy <am@osimis.io>
parents: 872
diff changeset
352
db62aa60a9b3 private tags
Alain Mazy <am@osimis.io>
parents: 872
diff changeset
353 .. image:: ../images/PrivateTagsInCreateDicom.png
db62aa60a9b3 private tags
Alain Mazy <am@osimis.io>
parents: 872
diff changeset
354 :align: center
db62aa60a9b3 private tags
Alain Mazy <am@osimis.io>
parents: 872
diff changeset
355 :width: 400px
db62aa60a9b3 private tags
Alain Mazy <am@osimis.io>
parents: 872
diff changeset
356
808
1c3972c03c2a private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 798
diff changeset
357 Rob Oakes provides more a `detailed explanation about how to use
1c3972c03c2a private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 798
diff changeset
358 private tags with Orthanc
1c3972c03c2a private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 798
diff changeset
359 <https://oak-tree.tech/blog/soandor-orthanc-private-headers>`__ on
1c3972c03c2a private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 798
diff changeset
360 Oak-Tree's homepage.
228
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
361
808
1c3972c03c2a private tags
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 798
diff changeset
362
228
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
363 .. _prometheus:
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
364
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
365 Instrumentation with Prometheus
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
366 -------------------------------
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
367
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
368 .. highlight:: text
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
369
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
370 Orthanc publishes its metrics according to the `text-based format of
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
371 Prometheus
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
372 <https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format>`__
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
373 (check also the `OpenMetrics project <https://openmetrics.io/>`__), onto
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
374 the ``/tools/metrics-prometheus`` URI of the REST API. For instance::
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
375
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
376 $ curl http://localhost:8042/tools/metrics-prometheus
927
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
377 orthanc_count_instances 21741 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
378 orthanc_count_patients 86 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
379 orthanc_count_series 239 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
380 orthanc_count_studies 93 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
381 orthanc_dicom_cache_count 2 1680083630571
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
382 orthanc_dicom_cache_size 0.00191688538 1680083630571
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
383 orthanc_disk_size_mb 16855.9629 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
384 orthanc_jobs_completed 10 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
385 orthanc_jobs_failed 0 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
386 orthanc_jobs_pending 0 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
387 orthanc_jobs_running 0 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
388 orthanc_jobs_success 10 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
389 orthanc_last_change 81062 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
390 orthanc_rest_api_active_requests 1 1680083638027
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
391 orthanc_rest_api_duration_ms 77 1680083630549
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
392 orthanc_storage_create_duration_ms 2 1680083630565
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
393 orthanc_storage_read_duration_ms 2 1680083630557
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
394 orthanc_store_dicom_duration_ms 7 1680083630570
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
395 orthanc_uncompressed_size_mb 16855.9629 1680083638028
dfe96daba4f8 python in win installer
Alain Mazy <am@osimis.io>
parents: 914
diff changeset
396 orthanc_up_time_s 64 1680083638028
228
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
397
987
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
398 The metrics only appear in the response once they have been recorded at least once. Furthermore, some plugins
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
399 may add their own metrics dynamically.
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
400
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
401 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
402 | Metrics | Meaning | Origin |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
403 +========================================================+=============================================================================+================================================================+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
404 | ``orthanc_up_time_s`` | The time [s] spent since Orthanc started | Orthanc |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
405 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
406 | ``orthanc_last_change`` | The current id of the last `change` event | Orthanc |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
407 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
408 | ``orthanc_memory_trimming_duration_ms`` | The max duration [ms] over the last 10 seconds of the last memory | Orthanc |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
409 | | trimming duration | |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
410 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
411 | ``orthanc_store_dicom_duration_ms`` | The max duration [ms] over the last 10 seconds needed to store a | Orthanc |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
412 | | DICOM file (received from HTTP, DICOM protocol or from a plugin) | |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
413 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
414 | ``orthanc_count_instances`` | The number of instances stored in DB | Orthanc DB |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
415 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
416 | ``orthanc_count_series`` | The number of series stored in DB | Orthanc DB |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
417 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
418 | ``orthanc_count_studies`` | The number of studies stored in DB | Orthanc DB |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
419 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
420 | ``orthanc_count_patients`` | The number of patients stored in DB | Orthanc DB |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
421 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
990
27b75c653a8b metrics
Alain Mazy <am@osimis.io>
parents: 987
diff changeset
422 | ``orthanc_dicom_cache_count`` | The number of DICOM files currently stored in the DICOM cache | Orthanc DICOM cache |
987
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
423 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
990
27b75c653a8b metrics
Alain Mazy <am@osimis.io>
parents: 987
diff changeset
424 | ``orthanc_dicom_cache_size_mb`` | The size [MB] of all DICOM files currently stored in the DICOM cache | Orthanc DICOM cache |
987
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
425 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
426 | ``orthanc_find_scp_duration_ms`` | The max duration [ms] over the last 10 seconds of a C-Find SCP execution | Orthanc DICOM protocol server |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
427 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
428 | ``orthanc_get_scp_duration_ms`` | The max duration [ms] over the last 10 seconds of a C-Get SCP execution | Orthanc DICOM protocol server |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
429 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
430 | ``orthanc_move_scp_duration_ms`` | The max duration [ms] over the last 10 seconds of a C-Move SCP execution | Orthanc DICOM protocol server |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
431 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
432 | ``orthanc_rest_api_active_requests`` | The maximum number of concurrent HTTP requests being handled by the | Orthanc HTTP server |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
433 | | HTTP server over the last 10 seconds. | |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
434 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
435 | ``orthanc_rest_api_duration_ms`` | The max duration [ms] over the last 10 seconds required to handle | Orthanc HTTP server |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
436 | | an HTTP request | |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
437 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
438 | ``orthanc_jobs_pending`` | The current number of jobs whose execution is currently pending | Orthanc Jobs engine |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
439 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
440 | ``orthanc_jobs_running`` | The current number of jobs currently being executed | Orthanc Jobs engine |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
441 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
442 | ``orthanc_jobs_completed`` | The current number of jobs completed (failed or success) | Orthanc Jobs engine |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
443 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
444 | ``orthanc_jobs_success`` | The current number of jobs that have succeeded | Orthanc Jobs engine |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
445 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
446 | ``orthanc_jobs_failed`` | The current number of jobs that have failed | Orthanc Jobs engine |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
447 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
990
27b75c653a8b metrics
Alain Mazy <am@osimis.io>
parents: 987
diff changeset
448 | ``orthanc_disk_size_mb`` | The size [MB] of all DICOM files currently stored in Orthanc | Orthanc Storage |
987
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
449 | | (possibly compressed size) | |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
450 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
990
27b75c653a8b metrics
Alain Mazy <am@osimis.io>
parents: 987
diff changeset
451 | ``orthanc_uncompressed_size_mb`` | The size [MB] of all DICOM files currently stored in Orthanc | Orthanc Storage |
987
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
452 | | (uncompressed size) | |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
453 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
990
27b75c653a8b metrics
Alain Mazy <am@osimis.io>
parents: 987
diff changeset
454 | ``orthanc_storage_cache_count`` | The number of files currently stored in the Storage cache | Orthanc Storage cache |
27b75c653a8b metrics
Alain Mazy <am@osimis.io>
parents: 987
diff changeset
455 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
27b75c653a8b metrics
Alain Mazy <am@osimis.io>
parents: 987
diff changeset
456 | ``orthanc_storage_cache_size_mb`` | The size [MB] of all files currently stored in the Storage cache | Orthanc Storage cache |
27b75c653a8b metrics
Alain Mazy <am@osimis.io>
parents: 987
diff changeset
457 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
987
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
458 | ``orthanc_storage_create_duration_ms`` | The max duration [ms] over the last 10 seconds to save a file to disk | Orthanc Storage (default file system storage) |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
459 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
460 | ``orthanc_storage_read_duration_ms`` | The max duration [ms] over the last 10 seconds to read a file from disk | Orthanc Storage (default file system storage) |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
461 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
462 | ``orthanc_storage_remove_duration_ms`` | The max duration [ms] over the last 10 seconds to delete a file from disk | Orthanc Storage (default file system storage) |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
463 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
464 | ``orthanc_storage_read_bytes`` | The total number of bytes read from disk since Orthanc started | Orthanc Storage (default file system storage) |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
465 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
466 | ``orthanc_storage_written_bytes`` | The total number of bytes written to disk since Orthanc started | Orthanc Storage (default file system storage) |
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
467 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
468
759f7d5aca94 metrics table
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
469
228
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
470
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
471 .. highlight:: bash
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
472
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
473 Note that the collection of metrics can be statically disabled by
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
474 setting the :ref:`global configuration option <configuration>`
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
475 ``MetricsEnabled`` to ``false``, or dynamically disabled by PUT-ing
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
476 ``0`` on ``/tools/metrics``::
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
477
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
478 $ curl http://localhost:8042/tools/metrics
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
479 1
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
480 $ curl http://localhost:8042/tools/metrics -X PUT -d '0'
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
481 $ curl http://localhost:8042/tools/metrics
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
482 0
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
483
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
484
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
485 .. highlight:: yaml
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
486
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
487 Here is a sample configuration for Prometheus (in the `YAML format
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
488 <https://en.wikipedia.org/wiki/YAML>`__)::
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
489
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
490 scrape_configs:
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
491 - job_name: 'orthanc'
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
492 scrape_interval: 10s
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
493 metrics_path: /tools/metrics-prometheus
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
494 basic_auth:
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
495 username: orthanc
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
496 password: orthanc
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
497 static_configs:
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
498 - targets: ['192.168.0.2:8042']
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
499
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
500 .. highlight:: bash
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
501
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
502 Obviously, make sure to adapt this sample with your actual IP
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
503 address. Thanks to Docker, you can easily start a Prometheus server by
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
504 writing this configuration to, say, ``/tmp/prometheus.yml``, then
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
505 type::
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
506
363
9c28eeab2db6 removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 359
diff changeset
507 $ sudo run -p 9090:9090 -v /tmp/prometheus.yml:/etc/prometheus/prometheus.yml --rm prom/prometheus:v2.7.0