Overview
The stats system is split into two distinct categories:
- Instrumentation of the renderer, bridge, or plugin code.
- Observation and presentation of specific metrics at a specific cadence.
Nothing needs to be done to turn on instrumentation. Data collection starts when the system is initialized and continues until shutdown (Roz is "Always Watching").
However, in order to see the results of the instrumentation, we need to turn on the observation of stats. Specifically, we need to enable Listeners
that will pull data out of the system for presentation or analysis. Depending on the listener(s) that are enabled you may see output to a data file or live stats to an in-app HUD, or anything in between.
Currently, the system does not have any listeners configured by default but they can be enabled using a configuration file. In future releases, there will be one or more listeners configured by default and there will be configuration UI in each bridge product.
Configuration File
The stats configuration file (default name: stats.ini
) holds the basic default settings for the stats session, a list of listeners to attach, and per-listener rules for metric data to be observed by each listener.
Configuration of RenderMan diagnostics primarily affects the presentation and reporting of data. There is no need to configure the gathering of stats; it is built into the renderer and cannot be disabled. The presentation of stats, however, is configurable through the use of an INI-style configuration file.
Live Stats
Live stats are enabled by default, which means that the system will automatically set up an internal server (the Live Stats Server) for reporting live stats for any running render. The it
tool displays the tracked metrics as part of its HUD, and each DCC plugin also has a built-in "Live Stats" presentation panel. The Live Stats Server can be toggled on/off through prefs or the configuration file but the set of metrics collected by the system is currently not configurable.
Note |
---|
Stats presentation for live interaction is enabled in RenderMan by default. The ability to attach to a render running on a farm is a feature planned for the future but not currently supported. The live stats system will spawn a background process |
Anchor | ||||
---|---|---|---|---|
|
Configuration File
Default Configuration
The stats configuration file (default name: "stats.ini") holds the basic default settings for a stats session. Below is the default configuration for the stats system, equivalent to the default behavior of the system if there were no configuration file specified:Below is an example of a simple configuration file that enables an end-of-render JSON report, including checkpoints:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
# checkpoint_stats.ini # Roz Stats default configuration file # # Copy this file to: /a/path/of/your/choosing/stats.ini # then run: # prman -statsconfigset RMAN_STATS_CONFIG_PATH = /a/path/of/your/choosing/checkpoint_stats.ini version 0.1 # Set this to 1 for extra information when parsing this file verbose 0 # Stats processing log level. # Range is 0 (none) to 5 (debug output). Default is 3 (warnings) logLevel 3 # Session configuration [Session] # Distinguishing name "Checkpointfor this session configuration name "RMANTREE Session" # Enable the internal live stats server liveStatsEnabled 1 # List of listeners which the session should create and manage. [ManagedListeners] # JSON output report listener [Listener] type "jsonreport" name "jsonListener" outputFilename "checkpoint_stats.json" keepAllCheckpoints 1 [MetricRules] # Save all metrics to the JSON file, sampled once per second [Rule] regexp ".*" samplingInterval 1000 |
The stats configuration file is provided to the prman
command via the option -statsconfig <filename>
:
prman -statsconfig /path/to/checkpoint_stats.ini /path/to/rib/scene.rib
See JSON Report Listener reference page for JSON output configuration options.
Config File Search Order
The default configuration filename is "stats.ini"
. If prman
is not provided a config file via the -statsconfig
option, or if the filename given is a relative filename, then the stats configuration search path order will be used to attempt to find a configuration file.
The stats system will search for the configuration file in the following order:
...
/stats/configpath
setting in rendermn.ini
...
RMAN_STATS_CONFIG_PATH
environment variable override
...
#[ManagedListeners] |
This file can be found in the RenderMan distribution at $RMANTREE/etc/stats.ini
Config File Search Order
Command-line prman
will search for the stats configuration file in the following order:
Order | Location | Default |
---|---|---|
1 | /stats/configpath setting in rendermn.ini | .:${RMANTREE}/etc |
2 |
| none |
3 | prman -statsconfig </path/to/filename.ini> | stats.ini |
If you specify an absolute path on the command line it will override any requested search paths. This is a convenient way to do quick testing without having to modify an existing config file. For example, suppose you normally run with a certain configuration of listeners, but then want to do a render with details printed to the console about a specific metric or group of metrics. You could do a debugging run that temporarily overrides the default configuration in one of two ways - either by setting/pre-pending the environment variable override:
Code Block |
---|
setenv RMAN_STATS_CONFIG_PATH /my/test/directory
prman -statsconfig debug_stats.ini complicatedScene.rib |
Or by providing a full-path, absolute file name:
Code Block |
---|
prman -statsconfig /my/test/directory/debug_stats.ini complicatedScene.rib |
Both of these methods will load the stats configuration from "/my/test/directory/debug_stats.ini"
Note |
---|
If a configuration file name is not specified via the |
Note |
---|
Currently, configuration files are not merged if more than one is found. The last one found wins. Future releases will include advanced configuration mechanisms, including the merging of configuration files. |
Anchor | ||||
---|---|---|---|---|
|
Disabling Live Stats for Farm Renders
The ability to attach to a render running on a farm is a feature planned for the future but not currently supported. The live stats system will spawn a background process sbrokerd
which can interfere with process lifetime and cgroup management of farm processes therefore it is recommended that live stats be explicitly disabled for farm renders using a bespoke pipeline configuration file.
In a nutshell, an explicit configuration file is needed that sets the config option liveStatsEnabled
to 0
.
The following example is the minimum configuration file needed to turn live stats off. Place the config file in a known location and either add the prman -statsconfig
command-line option or set the RMAN_STATS_CONFIG_PATH
accordingly.
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
# stats.ini
# Roz Stats farm configuration file
[Session]
name "Farm Stats Session"
# Disable the internal live stats server
liveStatsEnabled 0 |
Warning |
---|
It is not recommended to disable this option in the default $RMANTREE/etc/stats.ini file as that will disable live stats for all renders, including DCC interactive renders. Please pass RenderMan the new |
...
Anchor | ||||
---|---|---|---|---|
|
DCC Configuration
A live stats configuration UI pane is available in all RenderMan bridge products, with the exception of Solaris which does not yet have support for the new stats system. In addition, advanced configuration with an INI file is also available through the use of the config environment variable. See below for DCC-specific details.
Blender
RfB uses the prman
command-line mechanism as described above, including the use of the RMAN_STATS_CONFIG_PATH
override environment variable.
Houdini
If the RMAN_STATS_CONFIG_PATH
environment variable is set RfH
Configuration files are not merged if more than one is found. The last one found wins.
In other words, if you specify an absolute path on the command line it will override any requested search paths. This is a convenient way to do quick testing without having to modify an existing config file. Maybe you normally run with a certain configuration of listeners but then want to do a render with details printed to the console about a specific metric or group of metrics.
For example, if you'd like to do a debugging run that temporarily overrides the default configuration:
Code Block |
---|
setenv RMAN_STATS_CONFIG_PATH /my/test/directory
prman -statsconfig debug_stats.ini complicatedScene.rib |
Which will load the stats configuration from /my/test/directory/debug_stats.ini
Note |
---|
Listener control and configuration are not yet dynamic. You are able to enable and disable listeners without recompiling, but you need to restart the render in order to see the configuration change. The same applies to changing which metrics a listener is observing. We are still polishing the mechanisms for enabling and disabling listeners and metrics mid-render, and eventually a front-end configuration UI. |
DCC Configuration
Blender
RfB uses the prman
command-line mechanism as described above.
Houdini
If the RMAN_STATS_CONFIG_PATH
environment variable is set RfH will use that search path to look for a file named stats.ini.
If no file is found, or if that environment variable is not set then the default configuration will be used.
Katana
If the RMAN_STATS_CONFIG_PATH
environment variable is set RfK will use that search path to look for a file named stats.ini.
If no file is found, or if that environment variable is not set then the default configuration will be used.
Additional configuration is also available in RfK through the following attributes:
prmanGlobalStatements.stats.sessionConfigSearchPath
(default: "."
)
Katana
If the RMAN_STATS_CONFIG_PATH
environment variable is set RfK will use that search path to look for a file named stats.ini.
If no file is found, or if that environment variable is not set then the default configuration will be used.
Additional configuration is also available in RfK through the following attributes:
prmanGlobalStatements.stats.configPath
(default: "."
)
prmanGlobalStatements.stats.configFile
prmanGlobalStatements.stats.sessionConfigFile
(default: "stats.ini"
)
These attributes are currently not exposed in PrmanGlobalStatements, they must be set via AttributeSet or OpScript at the moment. Attribute names are subject to change.Below is an OpScript which exposes these two attributes as user args with defaults as listed above. Copy and paste into your Katana scene and modify the path and config file name as needed.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
Code Block | ||||||
| ||||||
<katana release="4.0v2" version="4.0.2.000001"> <node name="__SAVE_exportedNodes" type="Group"> <node baseType="OpScript" edited="true" name="StatsConfigurationAdvancedStatsConfiguration" ns_colorb="0.050000" ns_colorg="0.260000" ns_colorr="0.090000" ns_errorGlow="0.000000" ns_fromContext="legacy" selected="true" type="OpScript" x="143287.024861350171" y="-253212.437185346316"> <port name="i0" source="PrmanGlobalStatementsGafferThree.out" type="in"/> <port name="out" type="out"/> <group_parameter name="StatsConfigurationAdvancedStatsConfiguration"> <string_parameter name="CEL" value="((/root))"/> <string_parameter name="location" value="/root/world/location"/> <group_parameter name="script"> <string_parameter name="lua" value="
-- Default: 'stats.ini'
local configFile = Interface.GetOpArg('user.configFile'):getValue()

-- Default: '.&apos:${RMANTREE}/etc'
-- Can be overriden with RMAN_STATS_CONFIG_PATH
local configSearchPathconfigPath = Interface.GetOpArg('user.configSearchPathconfigPath'):getValue()

-- Default: $RMANTREE/lib/plugins/listeners 
-- Can be overriden with RMAN_LISTENER_SEARCHPATH
local listenerSearchPath = Interface.GetOpArg('user.listenerSearchPath'):getValue(Interface.SetAttr(
 'prmanGlobalStatements.stats.configFile', 
 StringAttribute(configFile))

Interface.SetAttr(
 'prmanGlobalStatements.stats.sessionConfigFileconfigPath', 
 StringAttribute(configFileconfigPath))

Interface.SetAttr(
"/> 'prmanGlobalStatements.stats.sessionConfigSearchPath', 
 </group_parameter> StringAttribute(configSearchPath))

Interface.SetAttr(
 'prmanGlobalStatements.stats.listenerSearchPath',
 StringAttribute(listenerSearchPath))

 <string_parameter name="executionMode" value="immediate"/> </group_parameter> <string_parameter name="executionMode" value="immediate"/> <string_parameter name="applyWhere" value="at locations matching CEL"/> <string_parameter name="applyWhen" value="during op resolve"/> <string_parameter name="modifierNameMode" value="node name"/> <string_parameter name="modifierName" value="modifier"/> <string_parameter name="resolveIds" value=""/> <number_parameter name="recursiveEnable" value="0"/> <string_parameter name="disableAt" value=""/> <string_parameter name="inputBehavior" value="by index"/> <number_parameter name="multisampleUserOpArgs" value="0"/> <group_parameter hints="{}" name="user"> <string_parameter hints="{'widget': 'fileInput'}" name="configFile" value="stats.ini"/> <string_parameter expression="'.:'+getenv("RMANTREE", ".")+'/etc'" hints="{}" name="configSearchPathconfigPath"/> </group_parameter> <string_parameter expression="getenv("RMANTREE", "./")+'/lib/plugins/listeners'" hints="{}" name="listenerSearchPath"/> </group_parameter> </node> </group_parameter> </group_parameter> </node> </node> </katana> |
Maya
If the RMAN_STATS_CONFIG_PATH
environment variable is set RfM will use that search path to look for a file named stats.ini.
If no file is found, or if that environment variable is not set then the default configuration will be used.
Solaris
The new stats are not yet supported in Solaris.
Built-in Listeners
Below is a table of currently available listeners and their use case(s).
...
If the RMAN_STATS_CONFIG_PATH
environment variable is set RfH will use that search path to look for a file named stats.ini.
If no file is found, or if that environment variable is not set then the default configuration will be used.
Warning |
---|
Houdini/Solaris Known Issue: Live stats will only work properly with either Solaris or Classic Houdini. If a scene is being rendered in one and then switched to the other the live stats will no longer work reliably. If this happens the scene must be closed and reopened, or the application must be restarted. |
...
Diagnostic Reports
Advanced users may also use the configuration file to build and configure a list of presentation Listeners, each with a set of rules for metric data to be observed by that listener.
Checkpoint Render Report
For example, below is an example of a configuration file that enables an end-of-render JSON report, including checkpoints:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
# checkpoint_stats.ini
# Stats default configuration file
#
# Copy this file to: /a/path/of/your/choosing
# then run:
# prman -statsconfig /a/path/of/your/choosing/checkpoint_stats.ini
version 0.1
# Set this to 1 for extra information when parsing this file
verbose 1
# Stats processing log level.
# Range is 0 (none) to 5 (debug output). Default is 3 (warnings)
logLevel 5
# Session configuration
[Session]
name "Checkpoint Session"
# List of listeners which the session should create and manage.
[ManagedListeners]
# JSON output report listener
[Listener]
type "jsonreport"
name "jsonListener"
outputFilename "checkpoint_stats.json"
keepAllCheckpoints 1
[MetricRules]
# Save all metrics to the JSON file, sampled once per second
[Rule]
regexp ".*"
samplingInterval 1000 |
See JSON Report Listener reference page for JSON output configuration options.
Comment |
---|
OLD CONFIGURATION, TO BE PORTED TO NEW CONFIG UILive Statistics ConfigurationEach DCC has a window dedicated to Live Statistics presentation. When available (RfM, RfH) the window also includes basic configuration options. Below is a snapshot of the configuration options as seen in RenderMan for Maya: Enable Live StatsToggle this on to enable the built-in WebSocket server and connect the DCC's client window to the live data stream. This works best if only one render is connected at a time, on the default port. PortIn the event multiple renders are attempting to run live stats, each render will need a unique port, configured manually. The default port is Connect/DisconnectWhen Enable Live Stats is active, the Attach to Render button becomes available for manually connecting and disconnecting from a running render. StatusThe bottom line of the configuration portion of the Live Statistics window is the current state of the connection if the Live Stats Server is enabled |
Troubleshooting
Normally the stats system does its work silently, however for those situations when things aren't working as expected there are built-in mechanisms to get diagnostics on the diagnostics system.
Config File Parsing
When getting started it can be useful to see more information about the parsing of the configuration file. Enabling the verbose
option will print detailed config file parsing diagnostics to the console.
Code Block |
---|
# Set this to 1 for extra information when parsing this file
verbose 1
|
This will automatically be enabled when the log level is set to Debug (5).
Stats System Diagnostics
Stats has its own logging mechanism that can be dialed up for more information about what's happening internally. This can be set in the configuration file using the following option:
Code Block |
---|
# Stats processing log level.
# Range is 0 (none) to 5 (debug output). Default is 3 (warnings)
logLevel 3 |
The default (3) is set to output warnings and errors only. Set this to 4
for high-level informational messages, or 5
for detailed debugging messages.
Note: this log level is independent from prman's log level, as a means to separate renderer diagnostic logging from the diagnostic logging of the statistic system itself.
Command-line Debug Flag
If a problem is occurring before the configuration file is read, or if it's unclear if a configuration file is being read at all, there is a hidden command-line option for adjusting the level of pre-config file logging:
Code Block |
---|
prman -statsdebuglevel 5 ... |
...
. |