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.

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: 

# 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:

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:

setenv RMAN_STATS_CONFIG_PATH /my/test/directory
prman -statsconfig debug_stats.ini complicatedScene.rib

Or by providing a full-path, absolute file name:

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" 

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.

# stats.ini
# Roz Stats farm configuration file
[Session]
name "Farm Stats Session"

# Disable the internal live stats server 
liveStatsEnabled 0

...

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:

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 

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.configFileprmanGlobalStatements.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.

<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="&#0010;-- Default: &apos;stats.ini&apos;&#0010;local configFile = Interface.GetOpArg(&apos;user.configFile&apos;):getValue()&#0010;&#0010;-- Default: &apos;.&apos:${RMANTREE}/etc&apos;&#0010;-- Can be overriden with RMAN_STATS_CONFIG_PATH&#0010;local configSearchPathconfigPath = Interface.GetOpArg(&apos;user.configSearchPathconfigPath&apos;):getValue()&#0010;&#0010;-- Default: $RMANTREE/lib/plugins/listeners &#0010;-- Can be overriden with RMAN_LISTENER_SEARCHPATH&#0010;local listenerSearchPath = Interface.GetOpArg(&apos;user.listenerSearchPath&apos;):getValue(Interface.SetAttr(&#0010;    &apos;prmanGlobalStatements.stats.configFile&apos;,     &#0010;     StringAttribute(configFile))&#0010;&#0010;Interface.SetAttr(&#0010;     &apos;prmanGlobalStatements.stats.sessionConfigFileconfigPath&apos;,     &#0010;     StringAttribute(configFileconfigPath))&#0010;&#0010;Interface.SetAttr(&#0010;"/>
     &apos;prmanGlobalStatements.stats.sessionConfigSearchPath&apos;, &#0010;  </group_parameter>
   StringAttribute(configSearchPath))&#0010;&#0010;Interface.SetAttr(&#0010;    &apos;prmanGlobalStatements.stats.listenerSearchPath&apos;,&#0010;    StringAttribute(listenerSearchPath))&#0010;&#0010; <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="{&apos;widget&apos;: &apos;fileInput&apos;}" name="configFile" value="stats.ini"/>
          <string_parameter expression="&apos;.:&apos;+getenv(&quot;RMANTREE&quot;, &quot;.&quot;)+&apos;/etc&apos;" hints="{}" name="configSearchPathconfigPath"/>
        </group_parameter>
     <string_parameter expression="getenv(&quot;RMANTREE&quot;, &quot;./&quot;)+&apos;/lib/plugins/listeners&apos;" 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.

...

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: 

# 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.

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.

# 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:

# 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:

prman -statsdebuglevel 5 ...

...