LOGGING.SH(1)

💖 LOGGING.SH(1) — BeakerLib logging, phase support, and metrics 💖

okay bestie, welcome to the LOGGING.SH(1) page 🫶 this is the BeakerLib logging manual, and it’s literally about making logs inside BeakerLib tests. It also does phase support with automatic assert evaluation. Slay.

🌸 NAME 🌸

BeakerLib - logging - phase support, logging functions and metrics

💖 DESCRIPTION 💖

Routines for creating various types of logs inside BeakerLib tests. It also implements phase support with automatic assert evaluation. That’s the whole vibe. ✨

✨ FUNCTIONS ✨

🪵 Logging 🪵

Here’s the logging squad:

• rlLog
• rlLogDebug
• rlLogInfo
• rlLogWarning
• rlLogError
• rlLogFatal

Together they create a time/priority-labelled message in the log. There’s a bunch of aliases that 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] [label]

• message — the message you want to show (use quotes when invoking).
• logfile — the log file. If not supplied, OUTPUTFILE is assumed.
• priority — the priority of the log.
• label — print this text instead of time in log label.

rlDie

Creates a time-labelled message in the log, reports test result, uploads logs, closes unfinished phase, and terminates the test. It’s giving “final boss exit” 😭

rlDie message [file...]

• message — the 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 nonexistent logs and it will succeed.

rlBundleLogs

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

rlBundleLogs package file [file...]

• package — name of the package. Will be used as part of the tarball name.
• file — file(s) to be packed and submitted.

Returns result of submitting the tarball.

rlFileSubmit

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

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

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

rlGetArch

On any 32-bit Intel (i386, i486, i586, ...) system you will get i386.

rlGetPrimaryArch

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

rlGetPrimaryArch

On non-RHEL systems if the primary/secondary sedicision fails a fallback to rlGetArch is done.

rlGetSecondaryArch

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

rlGetSecondaryArch

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:
  • 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 -> WARN, 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.

🔁 Reboot 🔁

Controlled reboot must not be executed inside of an open phase. Otherwise it is possible the Overall result of the test will be reported incorrectly.

📈 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>
• Dalibor Pospisil <dapospis@redhat.com>
• Jakub Heger <jheger@redhat.com>

ok bye bestie — this page is from perl v5.32.1, dated 2026-04-07, and it’s the LOGGING.SH(1) manual page. periodt 💅🫶