Mercurial > hg > orthanc-book

annotate Sphinx/source/plugins/housekeeper.rst @ 969:7abb7c8ff544

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc for upcoming dicomweb 1.15
author Alain Mazy <am@osimis.io>
date Wed, 23 Aug 2023 18:58:43 +0200
parents 2f8ee0aef0a6
children 937450f76f8d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
7abb7c8ff544 doc for upcoming dicomweb 1.15
Alain Mazy <am@osimis.io>
parents: 846
diff changeset
4 Housekeeper plugin
7abb7c8ff544 doc for upcoming dicomweb 1.15
Alain Mazy <am@osimis.io>
parents: 846
diff changeset
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
2f8ee0aef0a6 added uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 839
diff changeset
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
7abb7c8ff544 doc for upcoming dicomweb 1.15
Alain Mazy <am@osimis.io>
parents: 846
diff changeset
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
7abb7c8ff544 doc for upcoming dicomweb 1.15
Alain Mazy <am@osimis.io>
parents: 846
diff changeset
78 "IngestTranscodingChange": true,
7abb7c8ff544 doc for upcoming dicomweb 1.15
Alain Mazy <am@osimis.io>
parents: 846
diff changeset
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
7abb7c8ff544 doc for upcoming dicomweb 1.15
Alain Mazy <am@osimis.io>
parents: 846
diff changeset
104 * if ``DicomWebCacheChange`` is triggered (this happens when upgrading from
7abb7c8ff544 doc for upcoming dicomweb 1.15
Alain Mazy <am@osimis.io>
parents: 846
diff changeset
105 the :ref:`DICOMweb plugin <dicomweb>` from 1.14 to a later version), the plugin will call the
7abb7c8ff544 doc for upcoming dicomweb 1.15
Alain Mazy <am@osimis.io>
parents: 846
diff changeset
106 ``/studies/../update-dicomweb-cache`` route on every study one by one.
7abb7c8ff544 doc for upcoming dicomweb 1.15
Alain Mazy <am@osimis.io>
parents: 846
diff changeset
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
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
123 Compilation
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
124 -----------
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
125
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
126 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
127 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
128
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
129
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
130