Mercurial > hg > orthanc-book
annotate Sphinx/source/users/advanced-rest.rst @ 253:a64197133114
Orthanc 1.5.7
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Wed, 26 Jun 2019 08:11:01 +0200 |
| parents | 972900443cf8 |
| children | f9e7036d81d0 |
| 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 |
| 227 | 20 are high-level tasks to be processed by Orthanc. Jobs are first added |
| 21 to a queue of pending tasks, and Orthanc will simultaneously execute a | |
| 22 fixed number of jobs (check out :ref:`configuration option | |
| 23 <configuration>` ``ConcurrentJobs``). Once the jobs have been | |
| 24 processed, they are tagged as successful or failed, and kept in a | |
| 25 history (the size of this history is controlled by the | |
| 26 ``JobsHistorySize`` option). | |
|
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
27 |
| 227 | 28 By default, Orthanc saves the jobs into its database (check out the |
| 29 ``SaveJobs`` option). If Orthanc is stopped then relaunched, the jobs | |
| 30 whose processing was not finished are automatically put into the queue | |
| 31 of pending tasks. The command-line option ``--no-jobs`` can also be | |
| 32 used to prevent the loading of jobs from the database upon the launch | |
| 33 of Orthanc. | |
|
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
34 |
| 227 | 35 Note that the queue of pending jobs has a maximum size (check out the |
| 36 ``LimitJobs`` option). When this limit is reached, the addition of new | |
| 37 jobs is blocked until some job finishes. | |
| 38 | |
| 39 | |
| 40 | |
| 41 Synchronous vs. asynchronous calls | |
| 42 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 43 | |
| 44 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
|
45 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
|
46 includes the following URIs: |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
47 |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
48 * :ref:`Modifying and anonymizing <anonymization>` DICOM instances. |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
49 * Creating ZIP or media archives. |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
50 * C-Move SCU (``/queries/.../retrieve``). |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
51 * C-Store SCU (``/modalities/.../store``). |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
52 * Sending to an Orthanc peer (``/peers/.../store``). |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
53 * :ref:`Split/merge <split-merge>`. |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
54 * Sending images using the :ref:`transfers accelerator <transfers>` plugin. |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
55 |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
56 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
|
57 or an asynchronous mode: |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
58 |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
59 * **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
|
60 associated job. This is in general the default behavior. |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
61 * **Asynchronous calls** end immediately and return a handle to their |
| 227 | 62 associated job. It is up to the caller to monitor the execution by |
| 63 calling the jobs API (e.g. to know whether the job has finished its | |
| 64 execution). | |
|
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
65 |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
66 The choice between synchronous and asynchronous modes is done by |
| 227 | 67 setting the ``Synchronous`` field (or indifferently the |
| 68 ``Asynchronous`` field) in the POST body of the call to the REST | |
| 69 API. Note that the :ref:`transfers accelerator <transfers>` only runs | |
| 70 in asynchronous mode. | |
|
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
71 |
| 227 | 72 An integer number (possibly negative) can be specified in the |
| 73 ``Priority`` field of the POST body. Jobs with higher priority will be | |
| 74 executed first. By default, the priority is set to zero. | |
| 75 | |
| 76 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
|
77 recommended for jobs whose execution time can last over a dozen of |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
78 seconds (typically, the creation of an archive or a network transfer). |
| 227 | 79 Indeed, synchronous calls can be affected by timeouts in the HTTP |
| 80 protocol if they last too long. | |
| 81 | |
| 82 | |
| 83 Monitoring jobs | |
| 84 ^^^^^^^^^^^^^^^ | |
| 85 | |
| 86 .. highlight:: bash | |
| 87 | |
| 88 The list of all jobs can be retrieved as follows:: | |
| 89 | |
| 90 $ curl http://localhost:8042/jobs | |
| 91 [ "e0d12aac-47eb-454f-bb7f-9857931e2904" ] | |
| 92 | |
| 93 Full details about each job can be retrieved:: | |
| 94 | |
| 95 $ curl http://localhost:8042/jobs/e0d12aac-47eb-454f-bb7f-9857931e2904 | |
| 96 { | |
| 97 "CompletionTime" : "20190306T095223.753851", | |
| 98 "Content" : { | |
| 99 "Description" : "REST API", | |
| 100 "InstancesCount" : 1, | |
| 101 "UncompressedSizeMB" : 0 | |
| 102 }, | |
| 103 "CreationTime" : "20190306T095223.750666", | |
| 104 "EffectiveRuntime" : 0.001, | |
| 105 "ErrorCode" : 0, | |
| 106 "ErrorDescription" : "Success", | |
| 107 "ID" : "e0d12aac-47eb-454f-bb7f-9857931e2904", | |
| 108 "Priority" : 0, | |
| 109 "Progress" : 100, | |
| 110 "State" : "Success", | |
| 111 "Timestamp" : "20190306T095408.556082", | |
| 112 "Type" : "Archive" | |
| 113 } | |
|
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
114 |
| 227 | 115 Note that the ``/jobs?expand`` URI will retrieve this information in |
| 116 one single REST query. The ``Content`` field contains the parameters | |
| 117 of the job, and is very specific to the ``Type`` of job. | |
| 118 | |
| 119 The ``State`` field can be: | |
| 120 | |
| 121 * ``Pending``: The job is waiting to be executed. | |
| 122 * ``Running``: The job is being executed. The ``Progress`` field will | |
| 123 be continuously updated to reflect the progression of the execution. | |
| 124 * ``Success``: The job has finished with success. | |
| 125 * ``Failure``: The job has finished with failure. Check out the | |
| 126 ``ErrorCode`` and ``ErrorDescription`` fields for more information. | |
| 127 * ``Paused``: The job has been paused. | |
| 128 * ``Retry``: The job has failed internally, and has been scheduled for | |
| 253 | 129 re-submission after a delay. As of Orthanc 1.5.7, this feature is not |
| 227 | 130 used by any type of job. |
| 131 | |
| 132 In order to wait for the end of an asynchronous call, the caller will | |
| 133 typically have to poll the ``/jobs/...` URI (i.e. make periodic | |
| 134 calls), waiting for the ``State`` field to become ``Success`` or | |
| 135 ``Failure``. | |
| 136 | |
| 137 | |
| 138 Interacting with jobs | |
| 139 ^^^^^^^^^^^^^^^^^^^^^ | |
| 140 | |
| 141 Given the ID of some job, one can: | |
| 142 | |
| 143 * Cancel the job by POST-ing to ``/jobs/.../cancel``. | |
| 144 * Pause the job by POST-ing to ``/jobs/.../pause``. | |
| 145 * Resume a job in ``Paused`` state by POST-ing to ``/jobs/.../resume``. | |
| 146 * Retry a job in ``Failed`` state by POST-ing to ``/jobs/.../resubmit``. | |
| 147 | |
| 148 The related state machine is depicted in the `implementation notes | |
| 253 | 149 <https://bitbucket.org/sjodogne/orthanc/raw/Orthanc-1.5.7/Resources/ImplementationNotes/JobsEngineStates.pdf>`__. |
| 227 | 150 |
|
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
151 |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
152 |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
153 |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
154 .. _pdf: |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
155 |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
156 PDF |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
157 --- |
|
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
158 |
|
226
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
159 Among many different types of data, DICOM files can be used to store |
|
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
160 PDF files. The ``/tools/create-dicom`` URI can be used to upload a PDF |
|
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
161 file to Orthanc. The following scripts perform such a *DICOM-ization*; |
|
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
162 They convert the ``HelloWorld2.pdf`` file to base64, then perform a |
|
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
163 ``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
|
164 |
| 227 | 165 .. highlight:: bash |
| 166 | |
|
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
|
167 Using bash:: |
|
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
|
168 |
|
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
|
169 # create the json data, with the BASE64 data embedded in it |
|
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
|
170 (echo -n '{"Tags" : {"PatientName" : "Benjamino", "Modality" : "CT"},"Content" : "data:application/pdf;base64,'; base64 HelloWorld2.pdf; echo '"}') > /tmp/foo |
|
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
|
171 |
|
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
|
172 # 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
|
173 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
|
174 |
| 227 | 175 .. highlight:: powershell |
| 176 | |
|
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
|
177 Using Powershell:: |
|
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
|
178 |
|
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
|
179 # 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
|
180 $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
|
181 |
|
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
|
182 # 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
|
183 $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
|
184 |
|
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
|
185 # upload it to Orthanc and convert the result to json |
|
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
|
186 $reply = Invoke-WebRequest -Uri http://localhost:8042/tools/create-dicom -Method POST -Body ($params|ConvertTo-Json) -ContentType "application/json" | ConvertFrom-Json |
|
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
|
187 |
|
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
|
188 # 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
|
189 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
|
190 |
|
226
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
191 Please note that the ``/tools/create-dicom`` API call will return the |
|
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
192 Orthanc instance ID of the newly created DICOM resource. |
|
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
193 |
|
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
194 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
|
195 file. |
| 228 | 196 |
| 197 | |
| 198 | |
| 199 .. _prometheus: | |
| 200 | |
| 201 Instrumentation with Prometheus | |
| 202 ------------------------------- | |
| 203 | |
| 204 .. highlight:: text | |
| 205 | |
| 206 Orthanc publishes its metrics according to the `text-based format of | |
| 207 Prometheus | |
| 208 <https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format>`__ | |
| 209 (check also the `OpenMetrics project <https://openmetrics.io/>`__), onto | |
| 210 the ``/tools/metrics-prometheus`` URI of the REST API. For instance:: | |
| 211 | |
| 212 $ curl http://localhost:8042/tools/metrics-prometheus | |
| 213 orthanc_count_instances 1 1551868380543 | |
| 214 orthanc_count_patients 1 1551868380543 | |
| 215 orthanc_count_series 1 1551868380543 | |
| 216 orthanc_count_studies 1 1551868380543 | |
| 217 orthanc_disk_size_mb 0.0135002136 1551868380543 | |
| 218 orthanc_jobs_completed 1 1551868380543 | |
| 219 orthanc_jobs_failed 0 1551868380543 | |
| 220 orthanc_jobs_pending 0 1551868380543 | |
| 221 orthanc_jobs_running 0 1551868380543 | |
| 222 orthanc_jobs_success 1 1551868380543 | |
| 223 orthanc_rest_api_active_requests 1 1551868380543 | |
| 224 orthanc_rest_api_duration_ms 0 1551868094265 | |
| 225 orthanc_storage_create_duration_ms 0 1551865919315 | |
| 226 orthanc_storage_read_duration_ms 0 1551865943752 | |
| 227 orthanc_store_dicom_duration_ms 5 1551865919319 | |
| 228 orthanc_uncompressed_size_mb 0.0135002136 1551868380543 | |
| 229 | |
| 230 | |
| 231 .. highlight:: bash | |
| 232 | |
| 233 Note that the collection of metrics can be statically disabled by | |
| 234 setting the :ref:`global configuration option <configuration>` | |
| 235 ``MetricsEnabled`` to ``false``, or dynamically disabled by PUT-ing | |
| 236 ``0`` on ``/tools/metrics``:: | |
| 237 | |
| 238 $ curl http://localhost:8042/tools/metrics | |
| 239 1 | |
| 240 $ curl http://localhost:8042/tools/metrics -X PUT -d '0' | |
| 241 $ curl http://localhost:8042/tools/metrics | |
| 242 0 | |
| 243 | |
| 244 | |
| 245 .. highlight:: yaml | |
| 246 | |
| 247 Here is a sample configuration for Prometheus (in the `YAML format | |
| 248 <https://en.wikipedia.org/wiki/YAML>`__):: | |
| 249 | |
| 250 scrape_configs: | |
| 251 - job_name: 'orthanc' | |
| 252 scrape_interval: 10s | |
| 253 metrics_path: /tools/metrics-prometheus | |
| 254 basic_auth: | |
| 255 username: orthanc | |
| 256 password: orthanc | |
| 257 static_configs: | |
| 258 - targets: ['192.168.0.2:8042'] | |
| 259 | |
| 260 .. highlight:: bash | |
| 261 | |
| 262 Obviously, make sure to adapt this sample with your actual IP | |
| 263 address. Thanks to Docker, you can easily start a Prometheus server by | |
| 264 writing this configuration to, say, ``/tmp/prometheus.yml``, then | |
| 265 type:: | |
| 266 | |
| 267 $ sudo docker run -p 9090:9090 -v /tmp/prometheus.yml:/etc/prometheus/prometheus.yml --rm prom/prometheus:v2.7.0 |