NAME¶

pj_dump - dumps a paje trace file in a CSV-like textual format

SYNOPSIS¶

pj_dump [OPTIONS] [FILE]

DESCRIPTION¶

The pj_dump(1) command translates the paje trace file FILE to a CSV-like textual format (described below). It is a useful program to analyze the behavior of parallel and distributed applications that were traced using some library that generates trace files in the Paje file format. Once you dump the contents of the Paje trace file in a CSV-like manner, you are free to analyze the contents of the trace the way you want. You can use R for example to draw scatter plots and gantt charts. If FILE is not provided, then the standard input is used.

By default, pj_dump will read the trace file from the beginning until the end of file is found. During this process, pj_dump relies on the Paje library to recreate in memory the behavior that is registered in the trace files. This means that pj_dump will put in memory all the contents of the trace file, even if the input is very large. Once all the contents of the trace file are simulated, pj_dump dumps the information in the CSV-like textual format described below in the OUTPUT DESCRIPTION section.

You can change the default behavior of pj_dump by providing the parameters --start=START and --end=END where START and END are valid timestamps of the input trace. If provided, it dumps only the contents of the trace between START and END. Note that even if used, pj_dump will simulate the whole trace file to keep the same semantic of behavior. Another way to change the default behavior is through the --stop-at=TIME parameter. If provided, pj_dump will read the trace file up to timestamp TIME (considering that the trace file is completely time ordered) and dumps what has been simulated until then. The --no-strict switch should be avoided and can be used only with old Paje trace files with old field names in event definitions. The --ignore-incomplete-links switch make pj_dump ignore incomplete links silently. More details on this switch below, in the OUTPUT DESCRIPTION section.

OPTIONS¶

pj_dump accepts the following options:

-a, --stop-at=TIME

-s, --start=START

-e, --end=END

-n, --no-strict

-z, --ignore-incomplete-links

-u, --user-defined

--type-hierarchy=FILE

--entity-hierarchy=FILE

-f, --flex

-?, --help

--usage

INPUT DESCRIPTION¶

The pj_dump(1) command expects an input that follows the Paje file format (as described in the PDF document listed in the RESOURCES section of this page). If FILE is not provided, pj_dump(1) will try to read from the standard input.

OUTPUT DESCRIPTION¶

It’s easier to understand what is written here if you are acquainted to the Paje terminology (Container, State, Variable, Link, Event and the information attached to each of these). Take a look to the description of the Paje File Format (link below in the RESOURCES section) for further details.

The contents of the lines generated by the pj_dump(1) command are separated by commas, defining the columns. So, a line like this:

Container, 0, LINK, 0, 4.48514, 4.48514, 9

has seven columns. The first column is always one of: Container, State, Variable, Event or Link. The remaining columns of the line have specific information depending on the first column. Here’s a synthetic description of the five different types of lines you’ll find as output of pj_dump(1):

Container, parentContainer, containerType, startTime, endTime, duration, name
State, container, stateType, startTime, endTime, duration, imbrication, value
Variable, container, variableType, startTime, endTime, duration, value
Event, container, eventType, time, value
Link, container, linkType, startTime, endTime, duration, value, startContainer, endContainer

See below a detailed description with examples for each of them.

Container, 0, HOST, 0, 4.48514, 4.48514, Tremblay

State, node48, SERVICE, 691, 692, 1, 0, booked

Variable, Tremblay, pcompute, 2.15357, 2.17013, 0.016554, 9.8095e+07

Event, Tremblay, msmark, 3.4286, finish_send_tasks

Link, 0, 0-HOST1-LINK4, 0, 0, 0, G, Tremblay, 9, mpi_123

$ pj_dump  ~/tracefile.paje
List of incomplete links in container '0':
Link, 0, MSG_PROCESS_TASK_LINK, 0, -1, 0, SR, broadcaster-12, NULL
Link, 0, MSG_PROCESS_TASK_LINK, 0.00013, -1, 0, SR, broadcaster-13, NULL
Link, 0, MSG_PROCESS_TASK_LINK, 0.002868, -1, 0, SR, broadcaster-13, NULL
(...)
PajeLinkException: Incomplete links at the end of container with name '0'

USER-DEFINED FIELDS¶

User-defined fields is a feature of the Paje trace file format to add additional information in the trace that does not belong to the traditional fields of each event definition. An event definition with four user-defined fields (Size, Params, Footprint and Tag) looks like this:

%EventDef PajeSetState 20
%  Time      date
%  Container string
%  Type      string
%  Value     string
%  Size      string
%  Params    string
%  Footprint string
%  Tag       string
%EndEventDef

The dump of user-defined fields are disable by default in pj_dump. The user can activate them by passing -u (or --user-defined) as argument. When doing so, the CSV-like output of pj_dump will be altered from the definition above (see OUTPUT DESCRIPTION). Besides dumping the default fields for each entity and container of the trace, the CSV will have additional fields that correspond to user-defined fields. The order in which they appear in the output obeys the order of the corresponding event definition. So a State defined with the event definition 20 above will have four additional fields in the CSV-like output.

RESOURCES¶

Description of the Paje trace file: https://github.com/schnorr/pajeng/blob/master/doc/lang-paje/lang-paje.pdf

Main web site: http://github.com/schnorr/pajeng/

REPORTING BUGS¶

Report pj_dump bugs to <http://github.com/schnorr/pajeng/issues>

COPYRIGHT¶

Copyright (C) 2012-2014 Lucas M. Schnorr. Free use of this software is granted under the terms of the GNU General Public License (GPL).

SEE ALSO¶

pj_validate(1)