Mercurial > hg > orthanc-book

annotate Sphinx/source/plugins/housekeeper.rst @ 933:a5e7e7001316 Orthanc-1.12.0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Orthanc 1.12.0
author Sebastien Jodogne <s.jodogne@gmail.com>
date Sat, 15 Apr 2023 10:44:42 +0200
parents 2f8ee0aef0a6
children 7abb7c8ff544
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
839
c29ac12e3160 Orthanc-1.11.0
Alain Mazy <am@osimis.io>
parents: 837
diff changeset
4 Housekeeper plugin (new in Orthanc 1.11.0)
846
2f8ee0aef0a6 added uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 839
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.
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
19
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
20 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
21 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
22 might improve performances and storage usage.
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
23
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
24 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
25 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
26 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
27 will resume where it stopped.
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
28
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 Configuration
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
31 -------------
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 .. highlight:: json
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
34
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
35 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
36
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 "Housekeeper": {
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
39
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
40 // Enables/disables the plugin
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
41 "Enable": false,
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
42
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
43 // 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
44 // 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
45 // another plugin
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
46 "GlobalPropertyId": 1025,
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
47
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
48 // 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
49 // any changes in configuration
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
50 "Force": false,
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
51
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
52 // 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
53 // This avoids overloading Orthanc with the housekeeping
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
54 // process and leaves room for other operations.
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
55 "ThrottleDelay": 5,
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
56
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
57 // 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
58 // 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
59 // Examples:
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
60 // 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
61 // 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
62 // "Schedule": {
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
63 // "Monday": ["0-6", "20-24"],
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
64 // "Tuesday": ["0-6", "20-24"],
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
65 // "Wednesday": ["0-6", "20-24"],
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
66 // "Thursday": ["0-6", "20-24"],
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
67 // "Friday": ["0-6", "20-24"],
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
68 // "Saturday": ["0-24"],
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
69 // "Sunday": ["0-24"]
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
70 // },
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 // 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
73 "Triggers" : {
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
74 "StorageCompressionChange": true,
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
75 "MainDicomTagsChange": true,
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
76 "UnnecessaryDicomAsJsonFiles": true,
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
77 "IngestTranscodingChange": true
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
78 }
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
79 }
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 Scheduling/throttling
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
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
85 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
86 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
87 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
88 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
89 between each processed study.
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
90
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
91 Triggers & internals
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
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
94 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
95 various operations will happen:
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
96
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
97 * if ``MainDicomTagsChange`` or ``UnnecessaryDicomAsJsonFiles`` is triggered,
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
98 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
99 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
100 their value in the DB.
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
101
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
102 * 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
103 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
104 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
105 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
106 (``StorageCompression`` and ``IngestTranscoding``).
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
107 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
108 place as the previous one.
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
109
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
110
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
111 Status
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
112 ------
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
113
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
114 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
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 Compilation
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 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
121 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
122
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
123
66ff2f30afcc added new features from next upcoming Orthanc release
Alain Mazy <am@osimis.io>
parents:
diff changeset
124