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.

Below is an example of a simple configuration file that enables an end-of-render JSON report, including checkpoints:

checkpoint_stats.ini

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

# Stats processing log level.
# Range is 0 (none) to 5 (debug output). Default is 3 (warnings)
logLevel 3

# 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

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:

Order	Location	Default
1	`/stats/configpath` setting in `rendermn.ini`	`.:${RMANTREE}/etc`
2	`RMAN_STATS_CONFIG_PATH` environment variable override	none
3	`prman -statsconfig </path/to/filename.ini>`	`stats.ini`

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

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: ".")

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.

Configuration OpScript Node

<katana release="4.0v2" version="4.0.2.000001">
  <node name="__SAVE_exportedNodes" type="Group">
    <node baseType="OpScript" edited="true" name="StatsConfiguration" ns_colorb="0.050000" ns_colorg="0.260000" ns_colorr="0.090000" ns_errorGlow="0.000000" ns_fromContext="legacy" selected="true" type="OpScript" x="143.024861" y="-253.437185">
      <port name="i0" source="PrmanGlobalStatements.out" type="in"/>
      <port name="out" type="out"/>
      <group_parameter name="StatsConfiguration">
        <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;&#0010;-- Can be overriden with RMAN_STATS_CONFIG_PATH&#0010;local configSearchPath = Interface.GetOpArg(&apos;user.configSearchPath&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()&#0010;&#0010;Interface.SetAttr(&#0010;    &apos;prmanGlobalStatements.stats.sessionConfigFile&apos;,     &#0010;     StringAttribute(configFile))&#0010;&#0010;Interface.SetAttr(&#0010;     &apos;prmanGlobalStatements.stats.sessionConfigSearchPath&apos;, &#0010;     StringAttribute(configSearchPath))&#0010;&#0010;Interface.SetAttr(&#0010;    &apos;prmanGlobalStatements.stats.listenerSearchPath&apos;,&#0010;    StringAttribute(listenerSearchPath))&#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="stats.ini"/>
          <string_parameter expression="&apos;.:&apos;+getenv(&quot;RMANTREE&quot;, &quot;.&quot;)+&apos;/etc&apos;" hints="{}" name="configSearchPath"/>
          <string_parameter expression="getenv(&quot;RMANTREE&quot;, &quot;./&quot;)+&apos;/lib/plugins/listeners&apos;" hints="{}" name="listenerSearchPath"/>
        </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).

Listener Type	Description	Use	Notes
`jsonreport`	Write hierarchical metric data to a JSON file.	An end-of render JSON report, including checkpoint/resume support.	Default is currently to write all checkpoints but this can be disabled in the listener configuration. See JSON Report Listener reference
`print`	Write metric data to std::out.	Writes raw output to the console.	The "Hello World" of example listeners.
`snapshot`	Write a summary of render stats to the console.	An end-of-render summary that is comparable with the legacy stats summary, plus optional extra metric data. The summary is also available mid-render by specifying "trigger" events.	For RIB or Preview renders only, does not yet write a snapshot when Live/IPR renders are canceled.
`telemetry`	Stream of data or report to CSV	Benchmarks or debugging	Can be an end-of-render CSV report written to disk, or can be a live stream of metrics to the console as the render progresses.

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

The above command will set the log level to 5 ("debug") until a config file is found, at which point the log level specified in the config file will take precedence.

Page tree

Contents

Overview

Configuration File

Config File Search Order

DCC Configuration

Blender

Houdini

Katana

Maya

Solaris

Built-in Listeners

Troubleshooting

Config File Parsing

Stats System Diagnostics

Command-line Debug Flag

Pixar Animation Studios

Site

Resources

Company

Connect

Page tree

Getting Started

Contents

Overview

Configuration File

Config File Search Order

DCC Configuration

Blender

Houdini

Katana

Maya

Solaris

Built-in Listeners

Troubleshooting

Config File Parsing

Stats System Diagnostics

Command-line Debug Flag

Pixar Animation Studios

Site

Resources

Company

Connect