Status Files¶
Status Files¶
Every test run has a status file that tracks it’s progress. It’s one of the first things created (after the test directory itself) when creating a test object.
A test run will transition through several states (all available as part of the
status_file.STATES
object). These, along with a description and timestamp,
are saved as a ‘state’ in the status file. Each state is a single line of the
file with a max size of 4096 bytes to ensure atomic writes.
The state of a test run represents where that run is in its lifecycle. It does not represent whether a test passed or failed. States are ephemeral and asynchronous, and should generally not be used to decide to do something with a test run. (The only exception is the ‘SCHEDULED’ state, which tells Pavilion to ask the scheduler about its current state).
Usage:
status_file = StatusFile('/tmp/mystatus')
status.set(STATES.RUNNING, "I'm running!")
state = status.current()
state.note
-
class
pavilion.status_file.
StatusFile
(path)¶ Bases:
object
The wraps the status file that is used in each test, and manages the creation, reading, and modification of that file.
NOTE: The status file does not perform any locking to ensure that it’s created in an atomic manner. It does, however, limit it’s writes to appends of a size such that those writes should be atomic.
-
LINE_MAX
= 4096¶
-
LOGGER
= <Logger pav./home/docs/checkouts/readthedocs.org/user_builds/pavilion2/checkouts/2.1.1/lib/pavilion/status_file.py (WARNING)>¶
-
NOTE_MAX
= 4052¶
-
STATES
= <pavilion.status_file.TestStatesStruct object>¶
-
TIME_FORMAT
= '%Y-%m-%dT%H:%M:%S.%f'¶
-
TS_LEN
= 26¶
-
current
()¶ Return the most recent status object.
Return type: StatusInfo
-
has_state
(state)¶ Check if the given state is somewhere in the history of this status file.
-
history
()¶ Return a list of all statuses recorded.
Return type: list(StatusInfo)
-
set
(state, note)¶ Set the status.
Parameters: - state – The current state.
- note – A note about this particular instance of the state.
-
-
class
pavilion.status_file.
StatusInfo
(state, note, when=None)¶ Bases:
object
Represents a single status.
Variables: - state (str) – A state string (from STATES).
- note (str) – The note for this status update.
- when (datetime) – A datetime object representing when this state was saved.
-
as_dict
()¶ Convert to a dictionary.
Return type: dict
-
class
pavilion.status_file.
TestStatesStruct
¶ Bases:
object
A class containing the valid test state constants.
Rules:
- The value should be an ascii string of the constant name.
- The constants have a max length of 15 characters.
- The constants are in all caps.
- The constants must be a valid python identifier that starts with a letter.
- Error states should end in ‘_ERROR’. They should be the result of an OS level problem (like missing directories), or problems with Pavilion itself.
- Failure states should end in ‘_FAILED’. They should be the result of trying something, and it just not succeeding.
Note: The states are written in the class as
<state_name> = <help_text>
, however, on class init the help text is stored separately, and the state value is set to the name of the state itself. So STATES.ENV_FAILED will have a value of ‘ENV_FAILED’ when used.Known States:
-
ABORTED
= "The test run was aborted, through no fault of it's own."¶
-
BUILDING
= 'The test is currently being built.'¶
-
BUILD_CREATED
= 'The builder for this build was created.'¶
-
BUILD_DEFERRED
= 'The build will occur on nodes.'¶
-
BUILD_DONE
= 'The build step has completed.'¶
-
BUILD_ERROR
= 'An unexpected error occurred while setting up the build.'¶
-
BUILD_FAILED
= 'The build has failed.'¶
-
BUILD_REUSED
= 'The build was reused from a prior step.'¶
-
BUILD_TIMEOUT
= 'The build has timed out.'¶
-
BUILD_WAIT
= 'Waiting for the build lock.'¶
-
COMPLETE
= 'For when the test is completely complete.'¶
-
CREATED
= 'The test object/directory is being created.'¶
-
CREATION_ERROR
= 'The test object/directory could not be created.'¶
-
ENV_FAILED
= 'Unable to load the environment requested by the test.'¶
-
INFO
= 'This is for logging information about a test, and can occurwithin any state.'¶
-
INVALID
= 'The status given to set was invalid.'¶
-
PREPPING_RUN
= 'Performing final (on node) steps before the test run.'¶
-
RESULTS
= "For when we're getting the results."¶
-
RESULTS_ERROR
= 'A result parser raised an error.'¶
-
RUNNING
= "For when we're currently running the test."¶
-
RUN_DONE
= 'For when the run step is complete.'¶
-
RUN_ERROR
= 'An unexpected error has occurred when setting up the test run.'¶
-
RUN_TIMEOUT
= 'The test run went long without any output.'¶
-
RUN_USER
= 'Jobs can report extra status using pav set_status and this status value.'¶
-
SCHEDULED
= 'The test has been scheduled with a scheduler.'¶
-
SCHED_CANCELLED
= 'The job was cancelled.'¶
-
SCHED_ERROR
= 'There was a scheduler related error.'¶
-
UNKNOWN
= "We can't determine the status."¶
-
get
(key)¶ Get the value of the status key.
-
help
(state)¶ Get the help string for a state.
-
list
()¶ List all the known state names.
-
max_length
= 15¶
-
validate
(key)¶ Make sure the key conforms to the above rules.
-
exception
pavilion.status_file.
TestStatusError
¶ Bases:
RuntimeError
Error raised by any status file related problems.