JSON Report

1 Description
2 Configuration
3 Report Format
4 Example Configurations

Reference for the end-of-render report listener. JSON file output, with checkpoint/resume support.

Description

Metric data gathered is written to a hierarchical JSON file. A final report is written at render termination, with intermediary stats written on checkpoint-exit events. Optionally (default: True) the data from each checkpoint will also be written.

The end-of-render report requires knowledge of a render's endpoint to write out the final report. With live renders (e.g. Solaris), there is no “end” to a render so the report isn’t written out until the live render is cancelled.

Configuration

Required type for configuring the JSON report listener from an ini file.

type "jsonreport"

Options

Listener Options	Type	Description	Required?	Default

Listener Options	Type	Description	Required?	Default
`type`	`string`	Must be "`jsonreport`"	y
`name`	`string`	Unique name of the listener	y	""
`outputFilename`	`string`	File name for the final JSON report	y	""
`keepAllCheckpoints`	`bool`	Turn this off to save space by only writing out JSON stats immediately before exit, otherwise, a block of stats is written on every checkpoint during the render.	n	y
Metric Rules
`regexp`	`string`	One or more metrics to be observed. If this is empty or missing no metric data will be written to the JSON file.	y	""
`samplingInterval`	`integer`	Sampling interval in MS for the metrics requested in the preceding `regexp` param.	n	1000ms

The outputFilename setting allows for the inclusion of environment variables, which will be expanded during processing by the Listener. It supports standard environment variable formats along with Linux shell variable expansion syntax such as the following:

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

For guidance on configuring a JSON report through render options and DCC settings, as well as insights into report data interpretation and analysis, please refer to the Diagnostic Report documentation.

Report Format

The JSON Report listener output file contains a single JSON object which contains a header object and a frame object.

{
  "header": { ... },
  "frame": { ... }
}

header

The JSON Report header will contain a version key/value pair plus several high-level metrics. For example:

"header": {
    "version": "26.0",
    "variant": { ... },
    "integrator": { ... },
    "maxsamples": { ... },
    "pixelvariance": { ... },
    "realTime": { ... },
}

frame

The frame object contains an array of one or more attempts. Each element of the attempts would be a checkpoint output or the final data. A non-checkpointed render would have a single metrics object in the attempts array.

{
  "header": { ... },
  "frame": {
    "attempts": [
      {
        "metrics": { ... }
      }
    ]
  }
}

If the render included one or more checkpoints, and the keepAllCheckpoints option was enabled, then the JSON Report output would contain a series of attempts containing metrics, iteration, and reason plus a final attempts entry with the end-of-render data.

{
  "header": { ... },
  "frame": {
    "attempts": [
      {
        "metrics": { ... },
        "iteration": <int: iteration count>,
        "reason": <one of "checkpoint"|"finalizing"|"exiting">
      },
      {
        "metrics": { ... }
      }
    ]
  }
}

metrics

The metrics object contains the bulk of the diagnostic data, where each metric is encapsulated within its own individual JSON object. Metric objects are organized hierarchically based on the namespace of each metric.

For example, an entry for the metric:

/rman/raytracing.numRays

Would be the following:

"metrics": {
  "rman": {
    "raytracing": {
      "numRays": {
        "description": "Total number of rays traced.",
        "timestamp": 6575431,
        "payload": [ 11412363 ]
      }
} } }

Example Configurations

Configuration Example: All lighting metrics

The following excerpt from a configuration file will enable the JSON report output, writing to: checkpoint_stats.json. The "MetricRules" section indicates that all metrics should be gathered, with data sampled once per second. See below for an example output for this configuration.

stats.ini

# Roz Stats default configuration file
# Copy this file to: /a/path/of/your/choosing
# set RMAN_STATS_CONFIG_PATH = /a/path/of/your/choosing
# or run prman -statsconfig thisfile.ini
version 0.1

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

# Session configuration
[Session]
name "JSON Report Session"
liveStatsEnabled 1

# List of listeners which the session should create and manage.
[ManagedListeners][Listener]
    type "jsonreport"
    name "jsonListener"
    outputFilename "checkpoint_stats.json"
	keepAllCheckpoints 1

[MetricRules]
    # Report lighting metrics to the JSON file, sampled once per second
    [Rule]
    regexp "/rman/lighting.*"
    samplingInterval 1000

Output Example

prman -statsconfig checkpoint_stats.ini -recover 1 scene.rib

The full metric data block has been omitted for brevity, however the header contains example metrics showing the metric description, time stamp at which the last value of the metric was reported, and the metric data payload.

checkpoint_stats.json

{
  "header": {
    "version": “26.0",
    "variant": {
      "description": "Riley render variant.",
      "timestamp": 178116,
      "payload": [
        "ris"
      ]
    },
    "maxsamples": {
      "description": "The maximum number of samples used by the integrator.",
      "timestamp": 2429320,
      "payload": [
        64
      ]
    },
   ...
   },
  "frame": {
    "attempts": [
      {
        "iteration": 20,
        "metrics": {...},
        "reason": "checkpoint"
      },
      {
        "iteration": 62,
        "metrics": {...},
        "reason": "checkpoint"
      },
      {
        "iteration": 83,
        "metrics": {...},
        "reason": "exiting"
      },
      {
        "metrics": {...},
      }
    ]
  }
}

Configuration Example: Memory tracking

The following excerpt from a configuration file will enable the JSON report output, writing to: checkpoint_stats.json. The [MetricRules] section indicates that all metrics should be gathered, with data sampled once per second. See below for an example output for this configuration.

stats.ini

# Roz Stats default configuration file
# Copy this file to: /a/path/of/your/choosing
# set RMAN_STATS_CONFIG_PATH = /a/path/of/your/choosing
# or run prman -statsconfig thisfile.ini
version 0.1

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

# Session configuration
[Session]
name "JSON Report Session"
liveStatsEnabled 1

# List of listeners which the session should create and manage.
[ManagedListeners]
[Listener]
    type "jsonreport"
    name "Memory Report"
    outputFilename "memory_report.json"
    keepAllCheckpoints 0

    [MetricRules]       
        [Rule]
        regexp "/system/memoryTracking.*"

Output Example

prman -statsconfig json_memory_report.ini -variant xpu scene.rib

The bulk of the data is omitted for brevity however the report below shows an example of the memory breakdown of an XPU render.

Each memory metric is comprised of an empty-string description, the time stamp at which the latest memory update was received, and the metric payload.

checkpoint_stats.json

{
  "header": {
    "version": "26.0"
  },
  "frame": {
    "attempts": [
      {
        "metrics": {
          "system": {
            "memoryTracking": {
              "system": {
                "rman": {
                    "geometry": {
                      "mem": {
                        "description": "",
                        "timestamp": 7769735,
                        "payload": [ [ 0, 123279324, 0 ] ]
                      },
                      "volumes": {
                        "mem": {
                          "description": "",
                          "timestamp": 7769735,
                          "payload": [ [ 0, 113004768, 0 ] ]
                        }
                      }
                    ...
                  }}
              },
              "gpu0": {
                "rman": {
                  "scene": {
                    "geometry": {...}
                    ...
                  }}
      } } } } }
    ]
} }

Renderman 26

JSON Report

Description

Configuration

Options

Report Format

header

frame

metrics

Example Configurations

Configuration Example: All lighting metrics

stats.ini

Output Example

checkpoint_stats.json

Configuration Example: Memory tracking

stats.ini

Output Example

checkpoint_stats.json

Related content