Linux Certif

Toute la documentation sur la certification Linux LPI

beakerlib-logging

NAME

BeakerLib - logging - phase support, logging functions and metrics

DESCRIPTION

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

FUNCTIONS

Logging

rlLog

rlLogDebug

rlLogInfo

rlLogWarning

rlLogError

rlLogFatal

Create a time-labelled message in the log. There is a bunch of aliases which can create messages formated as DEBUG/INFO/WARNING/ERROR or FATAL (but you would probably want to use rlDie instead of the last one).

     rlLog message [logfile] [priority]
 
 

message

Message you want to show (use quotes when invoking).

logfile

Log file. If not supplied, OUTPUTFILE is assumed.

priority

Priority of the log.

rlDie

Create a time-labelled message in the log, report test result, upload logs, close unfinished phase and terminate the test.

     rlDie message [file...]
 
 

message

Message you want to show (use quotes when invoking) - this option is mandatory.

file

Files (logs) you want to upload as well. "rlBundleLogs" will be used for it. Files which are not readable will be excluded before calling "rlBundleLogs", so it is safe to call even with possibly not existent logs and it will succeed.

rlBundleLogs

Create a tarball of files (e.g. logs) and attach them to the test result.

     rlBundleLogs package file [file...]
 
 

package

Name of the package. Will be used as a part of the tar-ball name.

file

File(s) to be packed and submitted.

Returns result of submiting the tarball.

rlFileSubmit

Resolves absolute path to the file, replaces / for - and uploads this renamed file using rhts-submit-log. It also allows you to specify your custom name for the uploaded file.

     rlFileSubmit [-s sep] path_to_file [required_name]
 
 

-s sep

Sets separator (i.e. the replacement of the /) to sep.

path_to_file

Either absolute or relative path to file. Relative path is converted to absolute.

required_name

Default behavior renames file to full_path_to_file with / replaced for -, if this does not suit your needs, you can specify the name using this option.

Examples:

rlFileSubmit logfile.txt -> logfile.txt cd /etc; rlFileSubmit ./passwd -> etc-passwd rlFileSubmit /etc/passwd -> etc-passwd rlFileSubmit /etc/passwd my-top-secret_file -> my-top-secret-file rlFileSubmit -s '_' /etc/passwd -> etc_passwd

Info

rlShowPackageVersion

Shows a message about version of packages.

     rlShowPackageVersion package [package...]
 
 

package

Name of a package(s) you want to log.

rlGetArch

Return base arch for the current system (good when you need base arch on a multilib system).

     rlGetArch
 
 

On an i686 system you will get i386, on a ppc64 you will get ppc.

rlGetDistroRelease

rlGetDistroVariant

Return release or variant of the distribution on the system.

     rlGetDistroRelease
     rlGetDistroVariant
 
 

For example on the RHEL-4-AS you will get release 4 and variant AS, on the RHEL-5-Client you will get release 5 and variant Client.

rlShowRunningKernel

Log a message with version of the currently running kernel.

     rlShowRunningKernel
 
 

Phases

rlPhaseStart

Starts a phase of a specific type. The final phase result is based on all asserts included in the phase. Do not forget to end phase with "rlPhaseEnd" when you are done.

     rlPhaseStart type [name]
 
 

type

Type of the phase, one of the following:

ABORT

When assert fails in this phase, test will be aborted.

FAIL

When assert fails here, phase will report a FAIL.

WARN

When assert fails here, phase will report a WARN.

name

Optional name of the phase (if not provided, one will be generated).

If all asserts included in the phase pass, phase reports PASS.

rlPhaseEnd

End current phase, summarize asserts included and report phase result.

     rlPhaseEnd
 
 

Final phase result is based on included asserts and phase type.

rlPhaseStartSetup

rlPhaseStartTest

rlPhaseStartCleanup

Start a phase of the specified type: Setup -> ABORT, Test -> FAIL, Cleanup -> WARN.

     rlPhaseStartSetup [name]
     rlPhaseStartTest [name]
     rlPhaseStartCleanup [name]
 
 

name

Optional name of the phase. If not specified, default Setup/Test/Cleanup are used.

If you do not want these shortcuts, use plain "rlPhaseStart" function.

Metric

rlLogMetricLow

Log a metric, which should be as low as possible to the journal. (Example: memory consumption, run time)

     rlLogMetricLow name value [tolerance]
 
 

name

Name of the metric. It has to be unique in a phase.

value

Value of the metric.

tolerance

It is used when comparing via rcw. It means how larger can the second value be to not trigger a FAIL. Default is 0.2

When comparing FIRST, SECOND, then:

     FIRST >= SECOND means PASS
     FIRST+FIRST*tolerance >= SECOND means WARN
     FIRST+FIRST*tolerance < SECOND means FAIL
 
 

Example: Simple benchmark is compared via this metric type in rcw. It has a tolerance of 0.2. First run had 1 second. So:

     For PASS, second run has to be better or equal to first.
             So any value of second or less is a PASS.
     For WARN, second run can be a little worse than first.
             Tolerance is 0.2, so anything lower than 1.2 means WARN.
     For FAIL, anything worse than 1.2 means FAIL.
 
 

rlLogMetricHigh

Log a metric, which should be as high as possible to the journal. (Example: number of executions per second)

     rlLogMetricHigh name value [tolerance]
 
 

name

Name of the metric. It has to be unique in a phase.

value

Value of the metric.

tolerance

It is used when comparing via rcw. It means how lower can the second value be to not trigger a FAIL. Default is 0.2

When comparing FIRST, SECOND, then:

     FIRST <= SECOND means PASS
     FIRST+FIRST*tolerance <= SECOND means WARN
     FIRST+FIRST*tolerance > SECOND means FAIL
 
 

AUTHORS

*

Petr Muller <pmuller@redhat.com>

*

Jan Hutar <jhutar@redhat.com>

*

Ales Zelinka <azelinka@redhat.com>

*

Petr Splichal <psplicha@redhat.com>