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

AUTHORS

248       ·   Petr Muller <pmuller@redhat.com>
249
250       ·   Jan Hutar <jhutar@redhat.com>
251
252       ·   Ales Zelinka <azelinka@redhat.com>
253
254       ·   Petr Splichal <psplicha@redhat.com>
255
256
257
258perl v5.10.1                      2010-05-12                     LOGGING.SH(1)