-
Notifications
You must be signed in to change notification settings - Fork 0
/
Logging.html
301 lines (255 loc) · 18.5 KB
/
Logging.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Logging</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css?v=fadd4351" />
<link rel="stylesheet" type="text/css" href="_static/custom.css?v=77160d70" />
<script src="_static/documentation_options.js?v=a8da1a53"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Matplotlib in C++" href="MatplotlibInCpp.html" />
<link rel="prev" title="Load Algorithm Hook" href="LoadAlgorithmHook.html" />
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-59110517-1', 'auto');
ga('send', 'pageview');
</script>
</head><body>
<div id="navbar" class="navbar navbar-default ">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="http://www.mantidproject.org">
</a>
<span class="navbar-text navbar-version pull-left"><b>main</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="divider-vertical"></li>
<li><a href="index.html">Home</a></li>
<li><a href="https://download.mantidproject.org">Download</a></li>
<li><a href="https://docs.mantidproject.org">User Documentation</a></li>
<li><a href="http://www.mantidproject.org/contact">Contact Us</a></li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<p>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="nav-item nav-item-0"><a href="index.html">Documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Logging</a></li>
</ul>
</div> </p>
</div>
<div class="container">
<div class="row">
<div class="body col-md-12 content" role="main">
<section id="logging">
<span id="id1"></span><h1>Logging<a class="headerlink" href="#logging" title="Link to this heading">¶</a></h1>
<nav class="contents local" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#overview" id="id2">Overview</a></p></li>
<li><p><a class="reference internal" href="#logging-levels" id="id3">Logging Levels</a></p></li>
<li><p><a class="reference internal" href="#configuring-the-log-level" id="id4">Configuring the Log Level</a></p></li>
<li><p><a class="reference internal" href="#usage-example-in-c" id="id5">Usage Example in C++</a></p></li>
<li><p><a class="reference internal" href="#usage-example-in-python" id="id6">Usage Example in Python</a></p></li>
<li><p><a class="reference internal" href="#using-logging-in-python" id="id7">Using <code class="code docutils literal notranslate"><span class="pre">logging</span></code> in Python</a></p></li>
<li><p><a class="reference internal" href="#tips" id="id8">Tips</a></p></li>
</ul>
</nav>
<section id="overview">
<h2><a class="toc-backref" href="#id2" role="doc-backlink">Overview</a><a class="headerlink" href="#overview" title="Link to this heading">¶</a></h2>
<p>The Mantid logging system is a useful tool for garnering more information about the operation of the program.
It is used to output messages from the framework to a channel, for example a file or the screen.
Including calls to the logging system in your code can greatly aid in assessing its running - successful or otherwise.
Logging is provided by the <a class="reference external" href="http://doxygen.mantidproject.org/nightly/d2/d78/classMantid_1_1Kernel_1_1Logger.html">Mantid::Kernel::Logger</a> class, which is a thin wrapper around the <a class="reference external" href="https://pocoproject.org/docs/Poco.Logger.html">Poco::Logger</a>.</p>
</section>
<section id="logging-levels">
<h2><a class="toc-backref" href="#id3" role="doc-backlink">Logging Levels</a><a class="headerlink" href="#logging-levels" title="Link to this heading">¶</a></h2>
<p>There are 7 log levels supported with increasing priority and decreasing verboseness:</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Level</p></th>
<th class="head"><p>Description on what to log</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>DEBUG</p></td>
<td><p>Anything that may be useful to understand what the code has been doing for debugging purposes.
E.g. parameter values, milestones, internal variable values.
Log at this level often throughout your code.</p></td>
</tr>
<tr class="row-odd"><td><p>INFORMATION</p></td>
<td><p>Useful information to relay back to the user of the framework.</p></td>
</tr>
<tr class="row-even"><td><p>NOTICE</p></td>
<td><p>Really important information that should be displayed to the user, this should be minimal.
Algorithms log at this level when starting/finishing. This is the default logging level.</p></td>
</tr>
<tr class="row-odd"><td><p>WARNING</p></td>
<td><p>Something was wrong but the framework was able to continue despite the problem.</p></td>
</tr>
<tr class="row-even"><td><p>ERROR</p></td>
<td><p>An error has occurred but the framework is able to handle it and continue.</p></td>
</tr>
<tr class="row-odd"><td><p>CRITICAL</p></td>
<td><p>An important error has occurred, the framework can continue but it is advisable to restart.</p></td>
</tr>
<tr class="row-even"><td><p>FATAL</p></td>
<td><p>An unrecoverable error has occurred and the application will terminate.</p></td>
</tr>
</tbody>
</table>
</section>
<section id="configuring-the-log-level">
<h2><a class="toc-backref" href="#id4" role="doc-backlink">Configuring the Log Level</a><a class="headerlink" href="#configuring-the-log-level" title="Link to this heading">¶</a></h2>
<p>For the logging to work you will need to have configured the logging service. This will occur when you do either of the following:</p>
<ul class="simple">
<li><p>Call <code class="code docutils literal notranslate"><span class="pre">FrameworkManager.initialise()</span></code></p></li>
<li><p>Get a reference to the <code class="code docutils literal notranslate"><span class="pre">ConfigService</span></code> singleton</p></li>
</ul>
<p>When the framework is initialised, it attempts to read a file called <code class="code docutils literal notranslate"><span class="pre">Mantid.properties</span></code> that it assumes will be available in the current working directory.
This contains among other things the logging configuration. See the <a class="reference external" href="https://docs.mantidproject.org/nightly/concepts/PropertiesFile.html#properties-file" title="(in MantidProject v6.11)"><span class="xref std std-ref">properties file</span></a> overview for more information.</p>
<p>Here is an example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>logging.loggers.root.level = debug
logging.loggers.root.channel.class = SplitterChannel
logging.loggers.root.channel.channel1 = consoleChannel
logging.loggers.root.channel.channel2 = fileChannel
logging.channels.consoleChannel.class = ConsoleChannel
logging.channels.consoleChannel.formatter = f1
logging.channels.fileChannel.class = FileChannel
logging.channels.fileChannel.path = mantid.log
logging.channels.fileChannel.formatter.class = PatternFormatter
logging.channels.fileChannel.formatter.pattern = %Y-%m-%d %H:%M:%S,%i [%I] %p %s - %t
logging.formatters.f1.class = PatternFormatter
logging.formatters.f1.pattern = %s-[%p] %t
logging.formatters.f1.times = UTC
</pre></div>
</div>
<p>This specifies that the logging comments will go to the console as well as a file called <code class="code docutils literal notranslate"><span class="pre">mantid.log</span></code>.
In the example here the level is set to debug, so all the messages will be output.
In production this will usually be set to information.
One could also alter the logging level programmatically using <code class="code docutils literal notranslate"><span class="pre">ConfigService</span></code>.
For example, in <code class="code docutils literal notranslate"><span class="pre">python</span></code>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">cfg</span> <span class="o">=</span> <span class="n">ConfigService</span><span class="o">.</span><span class="n">Instance</span><span class="p">()</span>
<span class="n">cfg</span><span class="o">.</span><span class="n">setConsoleLogLevel</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span> <span class="c1"># notice</span>
</pre></div>
</div>
<p>Note, that this affects the current session only; to change the level permanently, one needs to save the configuration to the file.</p>
</section>
<section id="usage-example-in-c">
<h2><a class="toc-backref" href="#id5" role="doc-backlink">Usage Example in C++</a><a class="headerlink" href="#usage-example-in-c" title="Link to this heading">¶</a></h2>
<p>In the .h:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf">"Logger.h"</span>
<span class="k">class</span><span class="w"> </span><span class="nc">A</span>
<span class="p">{</span>
<span class="k">private</span><span class="o">:</span>
<span class="w"> </span><span class="c1">/// Static reference to the logger class</span>
<span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">Logger</span><span class="o">&</span><span class="w"> </span><span class="n">g_log</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>In the .cpp:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">A</span><span class="o">::</span><span class="n">func</span><span class="p">()</span>
<span class="p">{</span>
<span class="w"> </span><span class="n">g_log</span><span class="p">.</span><span class="n">error</span><span class="p">(</span><span class="s">"Log message"</span><span class="p">);</span>
<span class="w"> </span><span class="n">g_log</span><span class="p">.</span><span class="n">information</span><span class="p">()</span><span class="w"> </span><span class="o"><<</span><span class="w"> </span><span class="s">"Flightpath found to be "</span><span class="w"> </span><span class="o"><<</span><span class="w"> </span><span class="n">distance</span><span class="w"> </span><span class="o"><<</span><span class="w"> </span><span class="s">" metres.</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
<section id="usage-example-in-python">
<h2><a class="toc-backref" href="#id6" role="doc-backlink">Usage Example in Python</a><a class="headerlink" href="#usage-example-in-python" title="Link to this heading">¶</a></h2>
<p>Inside the algorithms:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="bp">self</span><span class="o">.</span><span class="n">log</span><span class="p">()</span><span class="o">.</span><span class="n">information</span><span class="p">(</span><span class="s1">'Number of scan steps is something'</span><span class="p">)</span>
</pre></div>
</div>
<p>In general (see <a class="reference external" href="https://docs.mantidproject.org/nightly/api/python/mantid/kernel/Logger.html#mantid.kernel.Logger" title="(in MantidProject v6.11)"><code class="xref py py-class docutils literal notranslate"><span class="pre">mantid.kernel.Logger</span></code></a>):</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mantid.kernel</span> <span class="kn">import</span> <span class="n">logger</span>
<span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">'this is a custom warning'</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="using-logging-in-python">
<h2><a class="toc-backref" href="#id7" role="doc-backlink">Using <code class="code docutils literal notranslate"><span class="pre">logging</span></code> in Python</a><a class="headerlink" href="#using-logging-in-python" title="Link to this heading">¶</a></h2>
<p>It is possible to forward Mantid’s log messages to Python’s <code class="code docutils literal notranslate"><span class="pre">logging</span></code> framework.
The simplest way to configure the logger is:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>
<span class="kn">from</span> <span class="nn">mantid.utils.logging</span> <span class="kn">import</span> <span class="n">log_to_python</span>
<span class="kn">from</span> <span class="nn">mantid.kernel</span> <span class="kn">import</span> <span class="n">logger</span>
<span class="c1"># Configure Mantid to send messages to Python</span>
<span class="n">log_to_python</span><span class="p">()</span>
<span class="n">log</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">'Mantid'</span><span class="p">)</span>
<span class="n">logger</span><span class="o">.</span><span class="n">information</span><span class="p">(</span><span class="s1">'This message is send to `log` defined above.'</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that <code class="code docutils literal notranslate"><span class="pre">log_to_python</span></code> overwrites the existing setup.
If you need more control, you can use <code class="code docutils literal notranslate"><span class="pre">'PythonLoggingChannel'</span></code> as a channel class in the config as described above.</p>
</section>
<section id="tips">
<h2><a class="toc-backref" href="#id8" role="doc-backlink">Tips</a><a class="headerlink" href="#tips" title="Link to this heading">¶</a></h2>
<ul>
<li><p>If logging data that takes significant resources to generate the message, use the <code class="code docutils literal notranslate"><span class="pre">is(priority)</span></code> function of the logger to check if the message would actually be output:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">g_log</span><span class="p">.</span><span class="n">is</span><span class="p">(</span><span class="n">Logger</span><span class="o">::</span><span class="n">PRIO_DEBUG</span><span class="p">))</span>
<span class="p">{</span>
<span class="w"> </span><span class="c1">// generate message and output to log.</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><p>If you need to dump binary data, use the dump method of the logger. Note that all dump messages are sent at debug level:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">/// Logs the given message at debug level, followed by the data in buffer.</span>
<span class="kt">void</span><span class="w"> </span><span class="nf">dump</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&</span><span class="w"> </span><span class="n">msg</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">buffer</span><span class="p">,</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="kt">size_t</span><span class="w"> </span><span class="n">length</span><span class="p">);</span>
</pre></div>
</div>
</li>
<li><p>Note, that logging can slow down code significantly, so avoid overusing it, especially in large and nested loops.</p></li>
<li><p>In workflow algorithms consider setting an offset to the child algorithm log levels, or disable them completely, otherwise the log output can be too verbose with the low priority levels, such as debug or information.</p></li>
<li><p>Note, that the <em>Results Log</em> widget in Mantid offers only five options to show the logs (from debug to error).</p></li>
<li><p>Note, that too verbose logs when shown in the <em>Results Log</em> can slow down and even freeze the Mantid GUI for some time. So choose wisely what log level to show.</p></li>
</ul>
</section>
</section>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<ul class="nav navbar-nav" style=" float: right;">
<li>
<a href="LoadAlgorithmHook.html" title="Previous Chapter: Load Algorithm Hook"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">« Load Algorithm Hook</span>
</a>
</li>
<li>
<a href="MatplotlibInCpp.html" title="Next Chapter: Matplotlib in C++"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Matplotlib in C++ »</span>
</a>
</li>
<li><a href="#">Back to top</a></li>
</ul>
<p>
</p>
</div>
</footer>
</body>
</html>