Overview

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 automatically available in a separate Live Stats panel.

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

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

Listener settings that specify a filename can include environment variables which will be expanded when processed by the Listener. Standard environment variable formats are supported, as well as Linux shell variable expansion syntax:

    $VAR
    ${VAR} 
    ${VAR:-fallback} 
    ${VAR:=fallback} 

For example:

    outputFilename "${HOME}/checkpoint_stats.json"

See JSON Report Listener reference page for JSON output configuration options.

Config File Search Order

The location of a stats configuration file is provided to the system with the use of an environment variable which directs the system to the location of a configuration file that must be named “stats.ini". The prman command line "-statsconfig” option can be used specify a relative path to a uniquely-named configuration file or can override the path entirely if given an absolute path.

Using the example above the command line might include:

prman -statsconfig /path/to/config/file/checkpoint_stats.ini /path/to/rib/scene.rib

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

The stats system will search for the 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"

DCC Configuration

A live stats configuration UI pane is available in all RenderMan bridge products. 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. Interactive configuration of live stats is available in the Blender preferences.

Katana

RenderMan for Katana will search for a configuration file with the following precedence:

1. The prmanGlobalStatements.stats options take precedence over all other options if they are configured (see OpScript below).
2. $RMAN_STATS_CONFIG_PATH/stats.ini if the environment variable is set.
3. $CWD/stats.ini
4. $RMANTREE/etc/stats/ini

Advanced configuration is available in RfK through the following attributes:

prmanGlobalStatements.stats.configPath (default: “.:$RMANTREE/etc")

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.

<katana release="6.5v1.010030b" version="6.0.1.000003">
  <node name="__SAVE_exportedNodes" type="Group">
    <node baseType="OpScript" edited="true" name="AdvancedStatsConfiguration" ns_colorb="0.05" ns_colorg="0.26" ns_colorr="0.09" ns_errorGlow="0.0" ns_fromContext="legacy" selected="true" type="OpScript" x="493.466" y="-240.278">
      <port name="i0" source="PrmanGlobalStatements.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=" -- 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;Interface.SetAttr(&apos;prmanGlobalStatements.stats.configFile&apos;, StringAttribute(configFile)) &#0010;Interface.SetAttr(&apos;prmanGlobalStatements.stats.configPath&apos;, StringAttribute(configPath)) &#0010;&#0010;"/>
        </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="telemetry_stats.ini"/>
          <string_parameter expression="&apos;.:&apos;+getenv(&apos;HOME&apos;, &apos;.&apos;)+&apos;/stats/configs&apos;" hints="{}" name="configPath"/>
        </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.

Houdini/Solaris

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.