Mercurial > hg > orthanc-book
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 |
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 | 20 are high-level tasks to be processed by Orthanc. Jobs can be started |
21 synchronously or asynchronously (see the section below). All Jobs, | |
22 no matter how they were started, are first added | |
227 | 23 to a queue of pending tasks, and Orthanc will simultaneously execute a |
24 fixed number of jobs (check out :ref:`configuration option | |
25 <configuration>` ``ConcurrentJobs``). Once the jobs have been | |
26 processed, they are tagged as successful or failed, and kept in a | |
27 history (the size of this history is controlled by the | |
28 ``JobsHistorySize`` option). | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
29 |
227 | 30 By default, Orthanc saves the jobs into its database (check out the |
855 | 31 ``SaveJobs`` option). Jobs are saved within 100ms after their creation, |
32 and then, the whole jobs list, with their updated status, is saved every 10 seconds and when | |
854 | 33 Orthanc stops. If Orthanc is stopped then relaunched, the jobs whose |
34 processing was not finished are automatically put into the queue of | |
35 pending tasks or resumed if they were being processed when Orthanc stopped, | |
36 regardless of whether they were started synchronously or asynchronously | |
37 (see the section below). The command-line option ``--no-jobs`` can also be used to | |
798 | 38 prevent the loading of jobs from the database upon the launch of |
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 | 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 | 45 Synchronous vs. asynchronous calls |
46 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
47 | |
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 | 66 associated job. It is up to the caller to monitor the execution by |
67 calling the jobs API (e.g. to know whether the job has finished its | |
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 | 71 setting the ``Synchronous`` field (or indifferently the |
72 ``Asynchronous`` field) in the POST body of the call to the REST | |
73 API. Note that the :ref:`transfers accelerator <transfers>` only runs | |
74 in asynchronous mode. | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
75 |
227 | 76 An integer number (possibly negative) can be specified in the |
77 ``Priority`` field of the POST body. Jobs with higher priority will be | |
78 executed first. By default, the priority is set to zero. | |
79 | |
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 | 87 |
850 | 88 When generating archives asynchronously, you should take care of |
89 the ``MediaArchiveSize`` configuration that defines the maximum | |
90 number of ZIP/media archives that are maintained by Orthanc, as a | |
933 | 91 response to the asynchronous creation of archive. As of Orthanc |
1075 | 92 1.12.4, this value is ``1`` by default. |
227 | 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 | 96 Monitoring jobs |
97 ^^^^^^^^^^^^^^^ | |
98 | |
99 .. highlight:: bash | |
100 | |
101 The list of all jobs can be retrieved as follows:: | |
102 | |
103 $ curl http://localhost:8042/jobs | |
104 [ "e0d12aac-47eb-454f-bb7f-9857931e2904" ] | |
105 | |
106 Full details about each job can be retrieved:: | |
107 | |
108 $ curl http://localhost:8042/jobs/e0d12aac-47eb-454f-bb7f-9857931e2904 | |
109 { | |
110 "CompletionTime" : "20190306T095223.753851", | |
111 "Content" : { | |
112 "Description" : "REST API", | |
113 "InstancesCount" : 1, | |
114 "UncompressedSizeMB" : 0 | |
115 }, | |
116 "CreationTime" : "20190306T095223.750666", | |
117 "EffectiveRuntime" : 0.001, | |
118 "ErrorCode" : 0, | |
119 "ErrorDescription" : "Success", | |
120 "ID" : "e0d12aac-47eb-454f-bb7f-9857931e2904", | |
121 "Priority" : 0, | |
122 "Progress" : 100, | |
123 "State" : "Success", | |
124 "Timestamp" : "20190306T095408.556082", | |
125 "Type" : "Archive" | |
126 } | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
127 |
227 | 128 Note that the ``/jobs?expand`` URI will retrieve this information in |
129 one single REST query. The ``Content`` field contains the parameters | |
130 of the job, and is very specific to the ``Type`` of job. | |
131 | |
132 The ``State`` field can be: | |
133 | |
134 * ``Pending``: The job is waiting to be executed. | |
135 * ``Running``: The job is being executed. The ``Progress`` field will | |
136 be continuously updated to reflect the progression of the execution. | |
137 * ``Success``: The job has finished with success. | |
138 * ``Failure``: The job has finished with failure. Check out the | |
139 ``ErrorCode`` and ``ErrorDescription`` fields for more information. | |
140 * ``Paused``: The job has been paused. | |
141 * ``Retry``: The job has failed internally, and has been scheduled for | |
1075 | 142 re-submission after a delay. As of Orthanc 1.12.4, this feature is not |
227 | 143 used by any type of job. |
144 | |
145 In order to wait for the end of an asynchronous call, the caller will | |
847 | 146 typically have to poll the ``/jobs/...`` URI (i.e. make periodic |
227 | 147 calls), waiting for the ``State`` field to become ``Success`` or |
148 ``Failure``. | |
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 | 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 | 155 |
833 | 156 .. _jobs-priority: |
157 | |
158 Jobs priority | |
159 ^^^^^^^^^^^^^ | |
160 | |
161 When executing jobs, Orthanc will pick the jobs with the highest ``Priority`` | |
162 from the pending job list. An integer value is a valid ``Priority``. You may | |
163 also use negative number to lower the priority below the default one (``0``). | |
164 | |
165 Pending jobs are not ordered in the API response but they are picked up in the right order. | |
166 | |
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 | 170 Interacting with jobs |
171 ^^^^^^^^^^^^^^^^^^^^^ | |
172 | |
173 Given the ID of some job, one can: | |
174 | |
175 * Cancel the job by POST-ing to ``/jobs/.../cancel``. | |
176 * Pause the job by POST-ing to ``/jobs/.../pause``. | |
177 * Resume a job in ``Paused`` state by POST-ing to ``/jobs/.../resume``. | |
178 * Retry a job in ``Failed`` state by POST-ing to ``/jobs/.../resubmit``. | |
179 | |
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 | 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 | 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 | 269 Attaching PDF file as DICOM series |
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 | 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 | 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 | 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 | 309 And here's another sample `using python |
962 | 310 <https://github.com/orthanc-server/orthanc-setup-samples/tree/master/python-samples/attach-pdf-to-study.py>`__. |
907 | 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 | 314 |
315 | |
596 | 316 .. _private-tags: |
317 | |
318 Creating DICOM instance with private tags | |
319 ----------------------------------------- | |
320 | |
321 .. highlight:: json | |
322 | |
323 The ``/tools/create-dicom`` URI can be used to create DICOM instances | |
324 containing private tags. Those private tags must first be defined in | |
325 the ``Dictionary`` configuration option of Orthanc. Importantly, the | |
326 ``xxxx,0010`` tag must be defined to register the private creator, | |
327 where ``xxxx`` is the private group of interest. Here is a sample:: | |
328 | |
329 { | |
330 "Dictionary" : { | |
906 | 331 "0405,0010" : [ "LO", "PrivateCreatorForMyCompany", 1, 1, "My Company" ], // reserve 0405,10xx for "My Company" |
332 "0405,1001" : [ "ST", "MyPrivateXMLTag", 1, 1, "My Company" ] // all tags from "My Company" must start with 0405,10xx | |
596 | 333 } |
334 } | |
335 | |
336 Once Orthanc is started using this configuration file, it is possible | |
337 to create a DICOM instance using the following POST body on | |
338 ``/tools/create-dicom``:: | |
339 | |
340 { | |
905 | 341 "PrivateCreator" : "My Company", // private creator here |
596 | 342 "Tags" : |
343 { | |
344 "PatientName" : "Love^Sarah", | |
345 "PatientID" : "7", | |
905 | 346 "PrivateCreatorForMyCompany" : "My Company", // and here ! |
347 "MyPrivateXMLTag" : "<xml><test>Testing</test></xml>" | |
596 | 348 } |
349 } | |
350 | |
905 | 351 Which then gives this in Orthanc UI: |
352 | |
353 .. image:: ../images/PrivateTagsInCreateDicom.png | |
354 :align: center | |
355 :width: 400px | |
356 | |
808 | 357 Rob Oakes provides more a `detailed explanation about how to use |
358 private tags with Orthanc | |
359 <https://oak-tree.tech/blog/soandor-orthanc-private-headers>`__ on | |
360 Oak-Tree's homepage. | |
228 | 361 |
808 | 362 |
228 | 363 .. _prometheus: |
364 | |
365 Instrumentation with Prometheus | |
366 ------------------------------- | |
367 | |
368 .. highlight:: text | |
369 | |
370 Orthanc publishes its metrics according to the `text-based format of | |
371 Prometheus | |
372 <https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format>`__ | |
373 (check also the `OpenMetrics project <https://openmetrics.io/>`__), onto | |
374 the ``/tools/metrics-prometheus`` URI of the REST API. For instance:: | |
375 | |
376 $ curl http://localhost:8042/tools/metrics-prometheus | |
927 | 377 orthanc_count_instances 21741 1680083638028 |
378 orthanc_count_patients 86 1680083638028 | |
379 orthanc_count_series 239 1680083638028 | |
380 orthanc_count_studies 93 1680083638028 | |
381 orthanc_dicom_cache_count 2 1680083630571 | |
382 orthanc_dicom_cache_size 0.00191688538 1680083630571 | |
383 orthanc_disk_size_mb 16855.9629 1680083638028 | |
384 orthanc_jobs_completed 10 1680083638028 | |
385 orthanc_jobs_failed 0 1680083638028 | |
386 orthanc_jobs_pending 0 1680083638028 | |
387 orthanc_jobs_running 0 1680083638028 | |
388 orthanc_jobs_success 10 1680083638028 | |
389 orthanc_last_change 81062 1680083638028 | |
390 orthanc_rest_api_active_requests 1 1680083638027 | |
391 orthanc_rest_api_duration_ms 77 1680083630549 | |
392 orthanc_storage_create_duration_ms 2 1680083630565 | |
393 orthanc_storage_read_duration_ms 2 1680083630557 | |
394 orthanc_store_dicom_duration_ms 7 1680083630570 | |
395 orthanc_uncompressed_size_mb 16855.9629 1680083638028 | |
396 orthanc_up_time_s 64 1680083638028 | |
228 | 397 |
987 | 398 The metrics only appear in the response once they have been recorded at least once. Furthermore, some plugins |
399 may add their own metrics dynamically. | |
400 | |
401 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
402 | Metrics | Meaning | Origin | | |
403 +========================================================+=============================================================================+================================================================+ | |
404 | ``orthanc_up_time_s`` | The time [s] spent since Orthanc started | Orthanc | | |
405 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
406 | ``orthanc_last_change`` | The current id of the last `change` event | Orthanc | | |
407 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
408 | ``orthanc_memory_trimming_duration_ms`` | The max duration [ms] over the last 10 seconds of the last memory | Orthanc | | |
409 | | trimming duration | | | |
410 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
411 | ``orthanc_store_dicom_duration_ms`` | The max duration [ms] over the last 10 seconds needed to store a | Orthanc | | |
412 | | DICOM file (received from HTTP, DICOM protocol or from a plugin) | | | |
413 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
414 | ``orthanc_count_instances`` | The number of instances stored in DB | Orthanc DB | | |
415 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
416 | ``orthanc_count_series`` | The number of series stored in DB | Orthanc DB | | |
417 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
418 | ``orthanc_count_studies`` | The number of studies stored in DB | Orthanc DB | | |
419 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
420 | ``orthanc_count_patients`` | The number of patients stored in DB | Orthanc DB | | |
421 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
990 | 422 | ``orthanc_dicom_cache_count`` | The number of DICOM files currently stored in the DICOM cache | Orthanc DICOM cache | |
987 | 423 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ |
990 | 424 | ``orthanc_dicom_cache_size_mb`` | The size [MB] of all DICOM files currently stored in the DICOM cache | Orthanc DICOM cache | |
987 | 425 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ |
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 | | |
427 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
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 | | |
429 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
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 | | |
431 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
432 | ``orthanc_rest_api_active_requests`` | The maximum number of concurrent HTTP requests being handled by the | Orthanc HTTP server | | |
433 | | HTTP server over the last 10 seconds. | | | |
434 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
435 | ``orthanc_rest_api_duration_ms`` | The max duration [ms] over the last 10 seconds required to handle | Orthanc HTTP server | | |
436 | | an HTTP request | | | |
437 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
438 | ``orthanc_jobs_pending`` | The current number of jobs whose execution is currently pending | Orthanc Jobs engine | | |
439 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
440 | ``orthanc_jobs_running`` | The current number of jobs currently being executed | Orthanc Jobs engine | | |
441 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
442 | ``orthanc_jobs_completed`` | The current number of jobs completed (failed or success) | Orthanc Jobs engine | | |
443 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
444 | ``orthanc_jobs_success`` | The current number of jobs that have succeeded | Orthanc Jobs engine | | |
445 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
446 | ``orthanc_jobs_failed`` | The current number of jobs that have failed | Orthanc Jobs engine | | |
447 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
990 | 448 | ``orthanc_disk_size_mb`` | The size [MB] of all DICOM files currently stored in Orthanc | Orthanc Storage | |
987 | 449 | | (possibly compressed size) | | |
450 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
990 | 451 | ``orthanc_uncompressed_size_mb`` | The size [MB] of all DICOM files currently stored in Orthanc | Orthanc Storage | |
987 | 452 | | (uncompressed size) | | |
453 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
990 | 454 | ``orthanc_storage_cache_count`` | The number of files currently stored in the Storage cache | Orthanc Storage cache | |
455 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
456 | ``orthanc_storage_cache_size_mb`` | The size [MB] of all files currently stored in the Storage cache | Orthanc Storage cache | | |
457 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
987 | 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) | |
459 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
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) | | |
461 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
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) | | |
463 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
464 | ``orthanc_storage_read_bytes`` | The total number of bytes read from disk since Orthanc started | Orthanc Storage (default file system storage) | | |
465 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
466 | ``orthanc_storage_written_bytes`` | The total number of bytes written to disk since Orthanc started | Orthanc Storage (default file system storage) | | |
467 +--------------------------------------------------------+-----------------------------------------------------------------------------+----------------------------------------------------------------+ | |
468 | |
469 | |
228 | 470 |
471 .. highlight:: bash | |
472 | |
473 Note that the collection of metrics can be statically disabled by | |
474 setting the :ref:`global configuration option <configuration>` | |
475 ``MetricsEnabled`` to ``false``, or dynamically disabled by PUT-ing | |
476 ``0`` on ``/tools/metrics``:: | |
477 | |
478 $ curl http://localhost:8042/tools/metrics | |
479 1 | |
480 $ curl http://localhost:8042/tools/metrics -X PUT -d '0' | |
481 $ curl http://localhost:8042/tools/metrics | |
482 0 | |
483 | |
484 | |
485 .. highlight:: yaml | |
486 | |
487 Here is a sample configuration for Prometheus (in the `YAML format | |
488 <https://en.wikipedia.org/wiki/YAML>`__):: | |
489 | |
490 scrape_configs: | |
491 - job_name: 'orthanc' | |
492 scrape_interval: 10s | |
493 metrics_path: /tools/metrics-prometheus | |
494 basic_auth: | |
495 username: orthanc | |
496 password: orthanc | |
497 static_configs: | |
498 - targets: ['192.168.0.2:8042'] | |
499 | |
500 .. highlight:: bash | |
501 | |
502 Obviously, make sure to adapt this sample with your actual IP | |
503 address. Thanks to Docker, you can easily start a Prometheus server by | |
504 writing this configuration to, say, ``/tmp/prometheus.yml``, then | |
505 type:: | |
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 |