Customize Logs and Statuses

log and status commands print information about wrapped repository annotated by performance profiles. perun log command lists the minor versions history for a major version (currently the checked out), along with the information about registered profiles, such as e.g. the minor version description, authors, statistics of profiles, etc. perun status commands shows the overview of given minor version of current major head and lists profiles associated to profiles and in pending directory (i.e. the .perun/jobs directory. List of profiles contains the types of profiles, numbers, configurations of profiling run, etc.

The format of outputs of both log and status can be customized by setting the formatting strings c.f. Customizing Logs and Customizing Statuses. Moreover, outputs are paged (currently using the less -R command) by default. To turn off the paging, run the perun with --no-pager option (see Command Line Interface) or set general.paging.

Customizing Statuses

The output of perun status is defined w.r.t. formatting string specified in configuration in format.status key (looked up recursively in the nearest local configuration, or in global configuration). The formatting string consists of raw delimiters and special tags, which serves as templates to output specific informations about concrete profiles, such as the profiling configuration, type of profile, creating timestamps, etc.

E.g. the following formatting string:

┃ %type% ┃ %cmd% ┃ %workload% ┃ %collector%  ┃ (%time%) ┃

will yield the following status when running perun status (both for stored and pending profiles):

══════════════════════════════════════════════════════════════════════▣
  id ┃   type  ┃  cmd   ┃ workload ┃ collector  ┃         time        ┃
══════════════════════════════════════════════════════════════════════▣
 0@p ┃ [mixed] ┃ target ┃ hello    ┃ complexity ┃ 2017-09-07 14:41:49 ┃
 1@p ┃ [time ] ┃ perun  ┃ status   ┃ time       ┃ 2017-10-19 12:30:29 ┃
 2@p ┃ [time ] ┃ perun  ┃ --help   ┃ time       ┃ 2017-10-19 12:30:31 ┃
══════════════════════════════════════════════════════════════════════▣

The first column of the perun status output, id, has a fixed position and defines a tag for the given profile, which can be used in add, rm, show and postprocessby commands as a quick wildcard for concrete profiles, e.g. perun add 0@p would register the first profile stored in the pending .perun/jobs directory to the index of current head. Tags are always in form of i@p (for pending profiles) and i@i for profiles registered in index, where i stands for position in the corresponding storage, index from zero.

The specification of the formatting string can contain the following special tags:

%type%:

Lists the most generic type of the profile according to the collected resources serving as quick tagging of similar profiles. Currently Perun supports memory, time, mixed.

%cmd%:

Lists the command for which the data was collected, this e.g. corresponds to the binary or script that was executed and profiled using collector/profiler. Refer to Overview of Jobs for more information about profiling jobs and commands.

%workload%:

List input workload which was passed to the profiled command, i.e. some inputs of the profiled program, script or binary. Refer to Overview of Jobs for more information about profiling jobs and command workloads.

%label%:

Lists the optional, user-defined string label associated with the profile. Labels may be used to further distinguish profiles, e.g., collected using different environment configuration or collected on differently configured machines.

%collector%:

Lists the collector which was used to obtain the given profile. Refer to Collectors Overview for list of supported collectors and more information about collection of profiles.

%time%:

Timestamp when the profile was last modified in format YEAR-MONTH-DAY HOURS:MINUTES:SECONDS.

%source%:

Original source of the profile. This corresponds to the name of the generated profile and the original path.

By default the profiles are sorted in ascending order according to the timestamp. The sort order can be modified by setting either the format.sort_profiles_by and format.sort_profiles_order configuration options, or the Command Line Interface options --sort-by and --sort-order to a valid profile information attribute and a valid sort order. Setting the command line options --sort-by and --sort-order have higher priority than the keys set in the format.sort_profiles_by and format.sort_profiles_order.

Customizing Logs

The output of perun log --short is defined w.r.t. formatting string specified in configuration in format.shortlog key (looked up recursively in the nearest local configuration, or in global configuration). The formatting string can contain both raw characters (such as delimiters, etc.) and special tags, which serves as templates to output information for concrete minor version such as minor version description, number of assigned profiles, etc.

E.g. the following formatting string:

'%checksum:6% (%stats%) %desc%'

will yield the following output when running perun log --short:

minor   (a|m|x|t profiles) info
53d35c  (2|0|2|0 profiles) Add deleted jobs directory
07f2b4  (1|0|1|0 profiles) Add necessary files for perun to work on this repo.
bd3dc3  ---no--profiles--- root

The specification of the formatting string can contain the following special tags:

%checksum:num%: Identification of the minor version (should be hash preferably). If we take

git as an example checksum will correspond to the SHA of one commit.

%stats%:

Lists short summary of overall number of profiles (a) and number of memory (m), mixed (x) and time (t) profiles assinged to given minor version.

%changes%:

Lists a short string of overall found changes for a given minor version. Found degradations are represented by red -, while found optimizations are represented by green +.

%desc:num%: Lists short description of the minor version, limiting to the first sentence of the

description. If we take git as an example this will correspond to the short commit message.

%date:num%:

Lists the date the minor version was commited (in the wrapped vcs).

%author:num%:

Lists the author of the minor version (not commiter).

%email:num%:

Lists the email of the author of the minor version.

%parents:num%:

Lists the parents of the given minor version. Note that one minor version can have potentially several parents, e.g. in git, when the merge of two commits happens.

Specifying num in the selected tags will shorten the displayed identification to num characters only. In case the specified num is smaller then the length of the attribute name, then the shortening will be limited to the lenght of the attribute name.