Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/housekeeper.rst @ 981:937450f76f8d
hk tip
author | Alain Mazy <am@osimis.io> |
---|---|
date | Mon, 25 Sep 2023 16:07:04 +0200 |
parents | 7abb7c8ff544 |
children | c9125053f158 |
rev | line source |
---|---|
837
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
1 .. _housekeeper-plugin: |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
2 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
3 |
969 | 4 Housekeeper plugin |
5 ================== | |
837
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
6 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
7 This page describes the **official sample plugin** that performs |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
8 housekeeping in the Database and Storage. |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
9 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
10 When changing some configuration or when upgrading Orthanc, it |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
11 might be usefull to perform housekeeping operations to optmize |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
12 the DB or clean/compress/uncompress the storage. This can happen e.g: |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
13 |
846 | 14 * when changing the list of indexed :ref:`MainDicomTags <main-dicom-tags>` |
837
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
15 * when changing the ``StorageCompression`` configuration |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
16 * when changing the ``IngestTranscoding`` configuration |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
17 * to remove unnecessary attachments like the ``dicom-as-json`` that were |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
18 used in Orthanc prior to 1.9.1. |
969 | 19 * when upgrading the :ref:`DICOMweb plugin <dicomweb>` from 1.14 to a later version. |
837
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
20 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
21 Note that these housekeeping operations are not mandatory. Orthanc will |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
22 continue to work without these cleanups. However, running the plugin |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
23 might improve performances and storage usage. |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
24 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
25 The plugin detects any configuration changes that can trigger a cleanup |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
26 and will start process the studies one by one (in the order they have |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
27 been ingested in Orthanc). If Orthanc is stopped and restarted, the plugin |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
28 will resume where it stopped. |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
29 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
30 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
31 Configuration |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
32 ------------- |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
33 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
34 .. highlight:: json |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
35 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
36 Here's a sample configuration section for this plugin with its default values:: |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
37 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
38 { |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
39 "Housekeeper": { |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
40 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
41 // Enables/disables the plugin |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
42 "Enable": false, |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
43 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
44 // the Global Prooperty ID in which the plugin progress |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
45 // is stored. Must be > 1024 and must not be used by |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
46 // another plugin |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
47 "GlobalPropertyId": 1025, |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
48 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
49 // Forces execution even if the plugin did not detect |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
50 // any changes in configuration |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
51 "Force": false, |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
52 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
53 // Delay (in seconds) between reconstruction of 2 studies |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
54 // This avoids overloading Orthanc with the housekeeping |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
55 // process and leaves room for other operations. |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
56 "ThrottleDelay": 5, |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
57 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
58 // Runs the plugin only at certain period of time. |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
59 // If not specified, the plugin runs all the time |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
60 // Examples: |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
61 // to run between 0AM and 6AM everyday + every night |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
62 // from 8PM to 12PM and 24h a day on the weekend: |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
63 // "Schedule": { |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
64 // "Monday": ["0-6", "20-24"], |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
65 // "Tuesday": ["0-6", "20-24"], |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
66 // "Wednesday": ["0-6", "20-24"], |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
67 // "Thursday": ["0-6", "20-24"], |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
68 // "Friday": ["0-6", "20-24"], |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
69 // "Saturday": ["0-24"], |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
70 // "Sunday": ["0-24"] |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
71 // }, |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
72 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
73 // configure events that can trigger a housekeeping processing |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
74 "Triggers" : { |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
75 "StorageCompressionChange": true, |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
76 "MainDicomTagsChange": true, |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
77 "UnnecessaryDicomAsJsonFiles": true, |
969 | 78 "IngestTranscodingChange": true, |
79 "DicomWebCacheChange": true // new in 1.12.2 | |
837
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
80 } |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
81 } |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
82 } |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
83 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
84 Scheduling/throttling |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
85 --------------------- |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
86 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
87 Processing a whole database/storage might take a very long time (days, weeks |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
88 or even months) and can be I/O & CPU intensive. Therefore, the configuration offers |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
89 options to schedule and/or throttle the housekeeping operations. E.g, you can |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
90 run only the plugin during the night and week-end and, you can introduce a delay |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
91 between each processed study. |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
92 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
93 Triggers & internals |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
94 -------------------- |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
95 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
96 By default, all triggers are enabled. Depending on the detected change, |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
97 various operations will happen: |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
98 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
99 * if ``MainDicomTagsChange`` or ``UnnecessaryDicomAsJsonFiles`` is triggered, |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
100 the plugin will call the ``/studies/.../reconstruct`` route on every study |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
101 one by one. Orthanc will read the DICOM tags from the DICOM files again and update |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
102 their value in the DB. |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
103 |
969 | 104 * if ``DicomWebCacheChange`` is triggered (this happens when upgrading from |
105 the :ref:`DICOMweb plugin <dicomweb>` from 1.14 to a later version), the plugin will call the | |
106 ``/studies/../update-dicomweb-cache`` route on every study one by one. | |
107 | |
837
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
108 * if any other change is detected, the plugin will again call the ``reconstruct`` route |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
109 but, this time, with the ``ReconstructFiles`` option enabled. Orthanc will then, |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
110 read the DICOM file from the storage, compress/uncompress/transcode it and it will |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
111 save it again to disk. The new file will be stored using the new Storage settings |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
112 (``StorageCompression`` and ``IngestTranscoding``). |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
113 Note that, Orthanc will create a new ``Attachment`` that will be saved at a different |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
114 place as the previous one. |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
115 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
116 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
117 Status |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
118 ------ |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
119 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
120 You can get a progress status of the plugin by calling the ``/housekeeper/status`` API route. |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
121 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
122 |
981 | 123 Tips |
124 ---- | |
125 | |
126 * The housekeeper plugin saves its state in the Orthanc SQL database in the ``ServerProperties`` | |
127 table. When running the Housekeeper plugin in a Docker environment, it is mandatory to | |
128 set the ``DatabaseServerIdentifier`` configuration to make sure that an Orthanc container | |
129 keeps the same identifier over multiple runs which should prevent the Housekeeper plugin to | |
130 start again from scratch when Orthanc is restarted. | |
131 | |
132 | |
837
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
133 Compilation |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
134 ----------- |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
135 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
136 This plugin is part of the Orthanc core repository and is included in the Orthanc makefile. |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
137 It is compiled with Orthanc itself and is distributed together with Orthanc binaries. |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
138 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
139 |
66ff2f30afcc
added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff
changeset
|
140 |