| Table of Contents | ||
|---|---|---|
|
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.
The end-of-render JSON Report must be explicitly enabled in a similar manner to the legacy XML Report, by providing a path to the output filename in the render options which is available in all DCCs.
Option "statistics” "jsonFilename" [ "filename.json" ]Advanced configuration of the JSON report and presentation Listeners is available through Advanced users may also configure other presentation Listeners through the use of an INI ini-style configuration file.
...
Configuration
...
File
The stats configuration file (default name: "stats.ini") holds defines the basic default settings for the stats session . It (i.e. the collection of stats in a single render). The ini file 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.
Most of the high-level settings can be left at their default values. Custom sessions should be given their own names, and the stats verbosity level can be adjusted for troubleshooting issues with Listeners or other stats processing.
Any number of listeners can be added in the Managed Listeners section, following the examples below and in the individual Listeners documentation.
File Format
The configuration file is broken out into sections. Currently it supports only a single Session with any number of Listener blocks. Each Listener block can have any number of Metric Rules. Lines that start with a ‘#’ character are ignored.
Expand the code block below for 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 General Options 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 53 # Session configurationOptions [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 |
| Note |
|---|
This example configuration file has both the |
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.
...
General Options
These appear at the beginning of the file, before the Session Properties.
| Option | Meaning | Type | Default | Required? |
|---|---|---|---|---|
version | File format version. Allows backward compatibility should we change the syntax of session config files. | float | 0.1 | No |
verbose | Parser output verbosity level. 0 = quiet, 1 = verbose. | int | 0 | No |
logLevel | Sets the verbosity of the stats system. The available values range from 0-5: None, Error, Warn, Info, Debug | int | 3 (Warn) | No |
Session Options
The following table shows the options which can be set for a stats session (i.e. the diagnostics for a single render).
Session options are specified immediately following the [Session] section heading in the configuration file.
| Option | Meaning | Type | Default | Required? |
|---|---|---|---|---|
name | The name of the session. It’s recommended to set this to a unique string when doing advanced configuration. | string | “Default Session" | Yes |
| Enables or disables the internal live stats server. | int (0/1) | 1 | No |
Listener Options
The [ManagedListeners] section can contain one or more [Listener] blocks. All Listeners have a common set of required options, and each listener will have unique options to control their behavior. Some Listeners require no options.
Listener options are specified immediately following the [Listener] section heading. Each listener must have a type and a name. Any options added after those will be interpreted by the listener when it starts up. Unrecognized options will be ignored, while missing options will be defaulted to safe values.
| Property | Meaning | Type | Required? |
|---|---|---|---|
type | The type of Listener. Will be matched to a built-in listener type from the known list. If unmatched, will be assumed to be a plugin .so filename. | string | yes |
name | The name of this Listener. Must be unique. | string | yes |
Metric Rules
The [MetricRules] section follows the Listener options and can contain one or more [Rule] blocks. Each rule block must contain a regex property indicating which metrics that listener should be observing. Sampling options may be adjusted as well, as follows.
| Property | Meaning | Type | Default | Required? |
|---|---|---|---|---|
regexp | Specifies a regular expression which will be used to match metric names for this rule. | String | yes | |
samplingInterval | Specifies the number of milliseconds between samples of metrics which match this rule. | int | 1000ms (once per sec) | no |
sampleImmediately | Specifies whether metrics which match this rule should be sampled immediately. | int | 0 | no |
Search Order
The location of a stats configuration file is can be 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 Use the example configuration file described above, the command line might include:
...
Both of these methods will load the stats configuration from "/my/test/directory/debug_stats.ini"
Filename expansion
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.
| Warning |
|---|
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. |
...
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.
| Expand | ||
|---|---|---|
| ||
<katana release="6.5v1.010030b" version="6.0.1.000003"> |
...