This is RenderMan 21 Documentation you are viewing. The Rmanwiki home page will redirect you to the current documentation.

Page tree

Contents

Entities

Tractor has 5 key entities which are tracked in its database and available for inspection in the Dashboard, the tq command-line utility, and Python API.

Job

job is a logical body of work that is submitted to the system for processing. It describes what needs to get done and in which order. It can be build to be arbitrarily large and complex, from rendering a single layer of a single frame to multiple layers over a range of frames. Its can comprise of rendering, compositing, administration, and any other process that can run on a host.

Task

task is a unit of work which partially completes a job. A task can run in parallel or in series with other tasks. Tasks and their order of operation constitute the struture of a job.

Command

command is a single program that is executed on a blade. It can be a render, a notification script, an administration command, or any other program that can execute on the host.

Invocation

An invocation is a set of metrics that describe the execution of a command on a blade. When a command runs multiple times, it will have multiple invocations to show when it ran, where it ran, and what memory and CPU resources were used.

Blade

blade is a remote execution server, a program that runs commands and reports the results of the command to the engine.
 

Attributes
 

Job Attributes

nametypedescription
jidintegerThe Job Identifier, the unique, numerical identifier of a job.
ownerstringThe user that submitted the job.
spoolhoststringThe host from which the job was submitted.
spoolfilestringThe path to filename of the spooled jobfile.
spoolcwdstringThe working directory of command that spooled the job.
spooladdrip adressThe IP address of the host that spooled the job.
titlestringThe title of the job.
assignmentsencoded stringThese are global job variable assignments, defined in the Assign section of a job file.
dirmapjson structureA map for translating paths according to architecture.
tierstringThe name of the tier. A tier is an ordered partitioning of the queue.
priorityfloatThe priority determines placement of the job in the queue.
crewsstring listThe list of crews of the job. This will restrict the job to run on blades which are configured to accept jobs running under those crews.
projectsstring lista list of designations which affects how the active tasks are counted in sharing limits
tagsstring listThe names of the limits that will govern all commands of the job. A limit will cap the number of concurrent executions of commands tagged with the limit name.
servicestringThe service key expression that will govern all commands of the job. The service key expression is a booean expression that allows commands to be matched with blades that have the capabilities or designation to run them.
envkeystring listA list of environment key names that establish the environment in which all commands of the job will run.
editpolicystringThe name of the policy affecting which users can manipulate job.
minslotsintegerThe minimum number of slots required to run a command of the job.
maxslotsintegerThe maximum number of slots required to run a command of the job.
etalevelintegerThe level of job graph used to estimate remaining time to completion (unused).
afterjidsstringThe list of ids of jobs that must finish before this job is started.
maxactiveintegerThe maximum number of concurrent active commands allowed for this job.
serialsubtasksbooleanA boolean value indicating whether subtasks are to be executed serially.
spooltimetimestampThe time the job was spooled.
pausetimetimestampThe time job was paused.
aftertimetimestampThe time after which job will be considered for scheduling.
starttimetimestampThe time job first had an active task.
stoptimetimestampThe last time the job had a task that completed.
deletetimetimestampThe time the job was deleted.
elapsedsecsintegerThe total elapsed seconds the job has been active.
esttotalsecsintegerThe estimated total elapsed task seconds for the job to complete.
numtasksintegerThe number of tasks in the job.
numblockedintegerThe number of blocked tasks in the job. A blocked task requires other tasks to finish before it can become ready, and later, active.
numreadyintegerThe number of ready tasks in this job. A ready task is a waiting task that does not need any other tasks to finish in order to become active.
numactiveintegerThe number of active tasks in the job.
numerrorintegerThe number of error tasks in the job.
numdoneintegerThe number of done tasks in this job.
maxtidintegerThe highest task id of all tasks of the job, including detached ones. This is used by the engine to manage task id assignment to newly created tasks from expand tasks. Detached tasks are tasks that are not considered for scheduling because they were produced by expand tasks and the job has since been restarted.
maxcidintegerThe highest command id of all commands of the job, including ones of detached tasks. This is used by the engine to manage command id assignement to newly created commands from expand tasks.
commentstringA user-defined job comment string.
metadatastringUser-defined metadata of the job.
pilintegerPlace In Line: ordering of job relative to other jobs of same priority; initially set to the jid.
lastnoteidintegerid of most recent note of job

 

Task Attributes

nametypedescription
jidintegerThe unique identifier of the job the task belongs to.
tidintegerThe Task Identifier, the unique identifier for the task within the job.
titlestringThe title of the task.
idstringThe unique string id for the task within the job.
servicestringThe service key expression that will govern all commands of the task. The service key expression is a booean expression that allows commands to be matched with blades that have the capabilities or designation to run them.
minslotsintegerThe minimum number of slots required to run a command of the task.
maxslotsintegerThe maximum number of slots required to run a command of the task.
cidsinteger listA list of command ids of the commands of the task.
serialsubtasksbooleanA boolean value indicating whether subtasks are to be executed serially.
ptidsinteger listA list of task ids of the parent tasks. Only a task with associated Instances has multiple parents. All child tasks must successfully finish before their parent can become active.
attachedbooleanA boolean value which, if false, indicates the task was result of an expand task that was retried.
statestringThe task state. It can be blocked, ready, active, error, or done.
statetimetimestampThe time the task became its current state.
readytimetimestampThe time the task became ready.
activetimetimestampThe time that the task became active.
currcidintegerCommand id of the command that will run next, or is currently running.
haslogbooleanA boolean indicating whether task has output in log.
previewstring listA list of command arguments (argv) of the preview command.
chaserstring listA list of command arguments (argv) of the chaser command.
progressfloatThe task progress, expressed as a percentage value between 0 and 100. This is set when tasks emit ALF_PROGRESS messages.
metadatastringUser-defined metadata of the task.
resumeblockbooleanA boolean indicating whether the task will automatically resume any resumable ancestor tasks.
retrycountintegerA counter of the number of passes the task will incur if the job is left to run to completion. A task retry or job restart will increment it if the task had become active at some point.

 

Command Attributes

nametypedescription
jidintegerThe unique identifier of the job the command belongs to.
tidintegerThe unique identifier of the task the command belongs to.
cidintegerThe Command Identifier, the unique identifier for the command within the job.
argvstring listThe list of command arguments representing command.
localbooleanA boolean that is true if command is to be run on spooling host.
expandbooleanA boolean that is true if the output of command emits script defining more tasks.
runtypestringThe type of command. Possible values include "normal" and "cleanup".
msgstringA string value which a blade emits to a pipe to the stdin of the command.
servicestringThe service key expression that will govern all commands of the task. The service key expression is a booean expression that allows commands to be matched with blades that have the capabilities or designation to run them.
tagsstring listThe names of the limits that will govern all commands of the job. A limit will cap the number of concurrent executions of commands tagged with the limit name.
idstringThe unique string id for the task within the job.
referstostringAn id of another task or command. Setting this causes the command to run on the same blade that ran the referred task or command ran on.
minslotsintegerThe minimum number of slots required to run the command.
maxslotsintegerThe maximum number of slots required to run the command.
envkeystring listA list of environment key names that establish the environment in which the command will run.
retryrcodesinteger listA list of return codes that will trigger auto-retry logic for the command.
metadatastringUser-defined metadata for the command.
resumewhilestring listA command argument list that is executed by a blade, or a list of special keywords; either of which determine whether the command is resumable.
resumepinbooleanA boolean value indicating whether the command should run on the same host when it is resumed.
minrunsecsfloatThe minimum number of second for command to run to not be considered an error.
maxrunsecsfloatThe maximum number of second for command to run before being killed.

 

Invocation Attributes

nametypedescription
jidintegerThe unique identifier of the job the invocation belongs to.
tidintegerThe unique identifier of the task the invocation belongs to.
cidintegerThe unique identifier of the command the invocation belongs to.
iidintegerThe Invocation Identifier, the unique identifier for the invocation within the command.
currentbooleanA boolean value that is true if this is the most recent invocation. When a task is retried, no existing invocations will be considered current.
numslotsintegerThe number of slots used by the invocation.
limitsstring listA list of limits in use by the invocation. This value is used to reconstruct the limit counters from currently running invocations should the engine be restarted.
starttimetimestampThe start time of the invocation.
stoptimetimestampThe stop time of the invocation.
pidintegerThe process id of the invocation.
rssfloatThe resident set size of the process, in GB.
memfloatThe memory usage of the process, in GB.
cpufloatThe current CPU utilization of the process.
elapsedappfloatThe elapsed user time of the process, in seconds.
elapsedsysfloatThe elapsed system time of the process, in seconds.
elapsedrealfloatThe elapsed wall-clock time of the process, in seconds.
rcodeintegerThe return code of the process.
retrycountintegerThe value of the task retry counter when he invocation ran. A task retry or job restart will increment it if the task had become active at some point.
resumecountintegerA number ordering an interation by its resume pass. iteration nu of times ( the resume of the task retry counter when he invocation ran. A task retry or job restart will increment it if the task had become active at some point.
resumablebooleanA boolean value that is true if the command can be resumed.
bladeididThe bladeid of the blade the invocation's command is running or ran on.

 

Blade Attributes

nametypedescription
namestringThe blade name. It is a unique identifier of the blade, and is typically the blade's hostname.
ipaddrstringThe IP address of the host.
portintegerThe number of the port on which the blade is listening.
osnamestringThe name of the operating system on which the blade is running.
osversionstringThe version of operating system on which the blade is running.
boottimetimestampThe boot time of the host.
numcpuintegerThe number of cpus/cores of the host.
loadavgfloatThe CPU load average of the host.
availmemoryfloatThe available memory of the host, in GB.
availdiskfloatThe availble disk space of the host, in GB.
versionstringThe Tractor blade version.
profilestringThe profile name used by the blade.
nimbystringThe NIMBY status of the blade.
starttimetimestampThe start time of the blade process.
numslotsintegerThe total number of slots on the blade.
udifloatThe Universal Desirability Index of the blade, which helps certain blades be assigned tasks sooner than other blades. A higher value means the higher the chance of the blade being assigned work.
statusstringA status note for the blade.
heartbeattimetimestampThe time the blade last contacted the engine.
bladeididA universally unique identifier for a blade. Over time, attributes such as hostname, port, and IP address may be reused by different hosts. This id is used when populating invocation records so that the particular blade that ran the command can be properly identified in perpetuity.
cleartimetimestampThe time a user requested the blade data be cleared. Only blades with a heartbeattime greater than the cleartime will be visible in the dashboard.
gpulabelstringBlade host GPU information.

 

Overriding Attributes

Jobs and tasks can specify attribute values that pertain to commands. These attributes are servicetagsmaxslots, and envkey. Values defined at the command level override those specified at the task and job level; values defined at the task level override those specified at the job level.