Page tree



RenderMan diagnostics have a built-in configuration for live data that is always presented in the it tool, toggled on with the "V" (capital "vee") keyboard shortcut. For DCC plugins the live stats are also built-in but are not enabled by default. This is a prototype feature that may require manual configuration as explained in Live Statistics Configuration.

Advanced users may also configure other presentation Listeners through the use of an INI configuration file.

Live Statistics Configuration

Each 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 Stats

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


In the event multiple renders are attempting to run live stats, each render will need a unique port, configured manually. The default port is 9723.


When Enable Live Stats is active, the Attach to Render button becomes available for manually connecting and disconnecting from a running render.


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

Known Issue: Occasionally the system fails to initialize the live stats with one or both of the following messages:

WebSocket server bind error: Address already in use

ClientConnection connect failed (...)

This can sometimes happen if the port is used in multiple places, or hasn't finished shutting down from a previous run. Changing the port in the configuration UI will usually resolve the issue.

This UI is under active development and as such, configuration options are limited for live stats. As the system evolves, so too will the ability to interactively create custom configurations of live stats.

Advanced Configuration: INI File

The stats configuration file (default name: "stats.ini") holds the basic default settings for the stats session. It can also be utilized for advanced configuration to build a list of listeners to attach, and per-listener rules for metric data to be observed by each listener.

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
name "Checkpoint Session"

# List of listeners which the session should create and manage.
# JSON output report listener
    type "jsonreport"
    name "jsonListener"
    outputFilename "checkpoint_stats.json"
	keepAllCheckpoints 1

    # Save all metrics to the JSON file, sampled once per second
    regexp ".*"
    samplingInterval 1000

This example configuration file has both the verbose and logLevel settings dialed up for maximum verbosity when parsing the configuration file and starting the stats system, respectively. Once it is fully configured and working as expected these can be set back to their defaults of verbose 0 and logLevel 3.

The stats configuration file is provided to the prman command via the "-statsconfig" option:

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

If command-line prman is not provided a config file via the -statsconfig option then the default configuration filename "stats.ini" will be used. 

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

3prman -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:

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"

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.

Listener control and configuration are not yet dynamic. In most cases, a render must be restarted in order to see the configuration change. In the case of RfM and RfB, the application will need to be restarted.

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.


RfB uses the prman command-line mechanism as described above, including the use of the RMAN_STATS_CONFIG_PATH override environment variable. Interactive configuration of live stats is available in the Blender preferences.


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.

Interactive configuration of live stats is available in the Live Stats window UI.


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 (default: "stats.ini")

These attributes are currently not exposed in PrmanGlobalStatements, they must be set via AttributeSet or OpScript at the moment. 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.

Configuration OpScript
<katana release="4.0v2" version="">
  <node name="__SAVE_exportedNodes" type="Group">
    <node baseType="OpScript" edited="true" name="AdvancedStatsConfiguration" ns_colorb="0.050000" ns_colorg="0.260000" ns_colorr="0.090000" ns_errorGlow="0.000000" ns_fromContext="legacy" selected="true" type="OpScript" x="287.350171" y="-212.346316">
      <port name="i0" source="GafferThree.out" type="in"/>
      <port name="out" type="out"/>
      <group_parameter name="AdvancedStatsConfiguration">
        <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;.:${RMANTREE}/etc&apos;&#0010;-- Can be overriden with RMAN_STATS_CONFIG_PATH&#0010;local configPath = Interface.GetOpArg(&apos;user.configPath&apos;):getValue()&#0010;&#0010;Interface.SetAttr(&#0010;    &apos;prmanGlobalStatements.stats.configFile&apos;,     &#0010;     StringAttribute(configFile))&#0010;&#0010;Interface.SetAttr(&#0010;     &apos;prmanGlobalStatements.stats.configPath&apos;, &#0010;     StringAttribute(configPath))&#0010;&#0010;"/>
        <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="configPath"/>

RfK no longer allows interactive configuration of stats through the PrmanLiveStats Tab. Configuration will soon be allowed through exposed attributes, in the meantime all configuration must come from an INI configuration file as described above.


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.

Interactive configuration of live stats is available in the Live Stats window UI.


The new stats are not yet supported in Solaris.