1LOGGING.SH(1)         User Contributed Perl Documentation        LOGGING.SH(1)
2
3
4

NAME

6       BeakerLib - logging - phase support, logging functions and metrics
7

DESCRIPTION

9       Routines for creating various types of logs inside BeakerLib tests.
10       Implements also phase support with automatic assert evaluation.
11

FUNCTIONS

13   Logging
14       rlLog
15
16       rlLogDebug
17
18       rlLogInfo
19
20       rlLogWarning
21
22       rlLogError
23
24       rlLogFatal
25
26       Create a time/priority-labelled message in the log. There is a bunch of
27       aliases which can create messages formated as DEBUG/INFO/WARNING/ERROR
28       or FATAL (but you would probably want to use rlDie instead of the last
29       one).
30
31           rlLog message [logfile] [priority] [label]
32
33       message
34           Message you want to show (use quotes when invoking).
35
36       logfile
37           Log file. If not supplied, OUTPUTFILE is assumed.
38
39       priority
40           Priority of the log.
41
42       label
43           Print this text instead of time in log label.
44
45       rlDie
46
47       Create a time-labelled message in the log, report test result, upload
48       logs, close unfinished phase and terminate the test.
49
50           rlDie message [file...]
51
52       message
53           Message you want to show (use quotes when invoking) - this option
54           is mandatory.
55
56       file
57           Files (logs) you want to upload as well. "rlBundleLogs" will be
58           used for it. Files which are not readable will be excluded before
59           calling "rlBundleLogs", so it is safe to call even with possibly
60           nonexistent logs and it will succeed.
61
62       rlBundleLogs
63
64       Create a tarball of files (e.g. logs) and attach them to the test
65       result.
66
67           rlBundleLogs package file [file...]
68
69       package
70           Name of the package. Will be used as part of the tarball name.
71
72       file
73           File(s) to be packed and submitted.
74
75       Returns result of submitting the tarball.
76
77       rlFileSubmit
78
79       Resolves absolute path to the file, replaces / with - and uploads this
80       renamed file using rhts-submit-log.  It also allows you to specify your
81       custom name for the uploaded file.
82
83           rlFileSubmit [-s sep] path_to_file [required_name]
84
85       -s sep
86           Sets separator (i.e. the replacement of the /) to sep.
87
88       path_to_file
89           Either absolute or relative path to file. Relative path is
90           converted to absolute.
91
92       required_name
93           Default behavior renames file to full_path_to_file with / replaced
94           for -, if this does not suit your needs, you can specify the name
95           using this option.
96
97           Examples:
98
99           rlFileSubmit logfile.txt -> logfile.txt cd /etc; rlFileSubmit
100           ./passwd -> etc-passwd rlFileSubmit /etc/passwd -> etc-passwd
101           rlFileSubmit /etc/passwd my-top-secret_file -> my-top-secret-file
102           rlFileSubmit -s '_' /etc/passwd -> etc_passwd
103
104   Info
105       rlShowPackageVersion
106
107       Shows a message about version of packages.
108
109           rlShowPackageVersion package [package...]
110
111       package
112           Name of a package(s) you want to log.
113
114       rlGetArch
115
116       Sanitize architecture for simplier matching.
117
118       Return base arch for the current system (good when you need base arch
119       on a multilib system).
120
121           rlGetArch
122
123       On any 32-bit Intel (i386, i486, i586, ...) system you will get i386.
124
125       rlGetPrimaryArch
126
127       Return primary arch for the current system (good when you need base
128       arch on a multilib system).
129
130           rlGetPrimaryArch
131
132       On non-RHEL systems if the primary/secondary sedicision fails a
133       fallback to rlGetArch is done.
134
135       rlGetSecondaryArch
136
137       Return base arch for the current system (good when you need base arch
138       on a multilib system).
139
140           rlGetSecondaryArch
141
142       rlGetDistroRelease
143
144       rlGetDistroVariant
145
146       Return release or variant of the distribution on the system.
147
148           rlGetDistroRelease
149           rlGetDistroVariant
150
151       For example on the RHEL-4-AS you will get release 4 and variant AS, on
152       the RHEL-5-Client you will get release 5 and variant Client.
153
154       rlShowRunningKernel
155
156       Log a message with version of the currently running kernel.
157
158           rlShowRunningKernel
159
160   Phases
161       rlPhaseStart
162
163       Starts a phase of a specific type. The final phase result is based on
164       all asserts included in the phase.  Do not forget to end phase with
165       "rlPhaseEnd" when you are done.
166
167           rlPhaseStart type [name]
168
169       type
170           Type of the phase, one of the following:
171
172           FAIL
173               When assert fails here, phase will report a FAIL.
174
175           WARN
176               When assert fails here, phase will report a WARN.
177
178       name
179           Optional name of the phase (if not provided, one will be
180           generated).
181
182       If all asserts included in the phase pass, phase reports PASS.
183
184       rlPhaseEnd
185
186       End current phase, summarize asserts included and report phase result.
187
188           rlPhaseEnd
189
190       Final phase result is based on included asserts and phase type.
191
192       rlPhaseStartSetup
193
194       rlPhaseStartTest
195
196       rlPhaseStartCleanup
197
198       Start a phase of the specified type: Setup -> WARN, Test -> FAIL,
199       Cleanup -> WARN.
200
201           rlPhaseStartSetup [name]
202           rlPhaseStartTest [name]
203           rlPhaseStartCleanup [name]
204
205       name
206           Optional name of the phase. If not specified, default
207           Setup/Test/Cleanup are used.
208
209       If you do not want these shortcuts, use plain "rlPhaseStart" function.
210
211   Reboot
212       Controlled reboot must not be executed inside of an open phase.
213       Otherwise it is possible the Overall result of the test will be
214       reported incorrectly.
215
216   Metric
217       rlLogMetricLow
218
219       Log a metric, which should be as low as possible to the journal.
220       (Example: memory consumption, run time)
221
222           rlLogMetricLow name value [tolerance]
223
224       name
225           Name of the metric. It has to be unique in a phase.
226
227       value
228           Value of the metric.
229
230       tolerance
231           It is used when comparing via rcw. It means how larger can the
232           second value be to not trigger a FAIL. Default is 0.2
233
234       When comparing FIRST, SECOND, then:
235
236           FIRST >= SECOND means PASS
237           FIRST+FIRST*tolerance >= SECOND means WARN
238           FIRST+FIRST*tolerance < SECOND means FAIL
239
240       Example: Simple benchmark is compared via this metric type in rcw.  It
241       has a tolerance of 0.2. First run had 1 second. So:
242
243           For PASS, second run has to be better or equal to first.
244                   So any value of second or less is a PASS.
245           For WARN, second run can be a little worse than first.
246                   Tolerance is 0.2, so anything lower than 1.2 means WARN.
247           For FAIL, anything worse than 1.2 means FAIL.
248
249       rlLogMetricHigh
250
251       Log a metric, which should be as high as possible to the journal.
252       (Example: number of executions per second)
253
254           rlLogMetricHigh name value [tolerance]
255
256       name
257           Name of the metric. It has to be unique in a phase.
258
259       value
260           Value of the metric.
261
262       tolerance
263           It is used when comparing via rcw. It means how lower can the
264           second value be to not trigger a FAIL. Default is 0.2
265
266       When comparing FIRST, SECOND, then:
267
268           FIRST <= SECOND means PASS
269           FIRST+FIRST*tolerance <= SECOND means WARN
270           FIRST+FIRST*tolerance > SECOND means FAIL
271

AUTHORS

273       ·   Petr Muller <pmuller@redhat.com>
274
275       ·   Jan Hutar <jhutar@redhat.com>
276
277       ·   Ales Zelinka <azelinka@redhat.com>
278
279       ·   Petr Splichal <psplicha@redhat.com>
280
281       ·   Dalibor Pospisil <dapospis@redhat.com>
282
283       ·   Jakub Heger <jheger@redhat.com>
284
285
286
287perl v5.32.1                      2021-03-25                     LOGGING.SH(1)