.\" Man page generated from reStructuredText.
.
.TH "PLAINBOX-SESSION-STRUCTURE" "7" "January 05, 2016" "0.25" "Plainbox"
.SH NAME
plainbox-session-structure \- structure of per-session directory
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
This page documents the structure of the Plainbox per\-session directory.
.SH DESCRIPTION
.sp
Each session is represented by a directory. Typically all sessions are stored
in the \fB$XDG_CACHE_HOME/plainbox/sessions/\fP directory.  Each directory there
is a randomly\-named session comprised of the following files and directories.
.INDENT 0.0
.TP
.B session:
A state with the serialized state of the session.  Currently it is a JSON
document compressed with the gzip compression scheme. You can preview the
contents of this file with \fBzcat session | json_pp\fP where \fBzcat\fP (1)
and \fIjson_pp\(ga\fP (1) are external system utilities.
.sp
The session file stores the \fIstate\fP of the session. State is represented by
several structures which are further documented in
\fBplainbox\-session\-state\fP\&. This file is essential for resuming a
session but is also useful for debugging.
.TP
.B io\-logs:
A directory with files representing input\-output operations performed by
particular jobs. There are three files for each job. One for Plainbox
itself and two more for human\-readable debugging. The files are:
.INDENT 7.0
.TP
.B *.record.gz:
A file internal to Plainbox, containing representation of all of the
input\-output operations performed by the specified job definition\(aqs
command process.
.sp
The format for this file is a gzip\-compressed sequence of records,
represented as separate lines, terminated with the newline character.
Each record is a small JSON list of exactly three elements. The first
element is a JSON number representing the delay since the previous
element was generated OR the delay before the process startup time, for
the first record. The second name is the name of the communication
stream. Currently only \fIstdout\fP and \fIstderr\fP are used. The third and
last element of each record is a base\-64 encoded binary string
representing the communication that took place.
.sp
The leading part of the filename is currently the identifier of the job
definition but this is subject to change to allow for multiple log
files associated with a single job in a given session.
.sp
To figure out which log file is associated with each job definition,
refer to the state file (\fBsession\fP).
.TP
.B *.stdout:
Plain\-text representation of the entire \fIstdout\fP stream as it was
printed by the command process. This file is purely for debugging and
is ignored by Plainbox. It may cease to be generated at some future
time.
.TP
.B *.stderr:
Similarly to \fB\&.stdout\fP but for the \fIstderr\fP stream.
.UNINDENT
.TP
.B CHECKBOX_DATA:
A directory associated with the \fBPLAINBOX_SESSION_SHARE\fP per\-session
runtime directory where jobs may deposit files to perform a primitive form
of IJC (inter\-job\-communication).
.UNINDENT
.SH AUTHOR
Zygmunt Krynicki & Checkbox Contributors
.SH COPYRIGHT
2012-2014 Canonical Ltd
.\" Generated by docutils manpage writer.
.