Formats: Reports

Every time OpenVox applies a catalog, it builds a Puppet::Transaction::Report object describing what happened during the run: the status of every resource, the events Puppet applied, the log messages it produced, and metrics about the run as a whole. That object is what report processors receive, and it is what OpenVox serializes when it sends a report to a server or writes one to disk.

This page describes report format 12, which OpenVox 8 produces. Use it when you write a custom report processor or consume reports from another tool. For an introduction to how reporting works, see About reporting.

How reports are serialized

A report is a nested structure of five object types:

• A Report at the top level.
• Metric objects, one per metric category, under metrics.
• ResourceStatus objects, one per resource, under resource_statuses.
• Event objects, under each resource status’s events.
• Log objects under logs.

When an agent sends a report to OpenVox Server, it serializes this structure as JSON. The built-in store processor instead writes it to reportdir as YAML containing Ruby object tags, so prefer the JSON form when you exchange reports between tools.

The canonical machine-readable definition is the report.json schema in the OpenVox source.

Report format versions

The report_format field identifies the structure of the report, not the version of OpenVox that produced it. It changes only when the objects that make up a report change.

Every OpenVox release produces format 12. OpenVox inherited that format from the Puppet 8 codebase it forked from, and the format has not changed since Puppet 7.0.0, so a tool that reads format 12 works across every OpenVox version.

Earlier formats come from Puppet releases that predate OpenVox. You encounter them only in reports from older Puppet agents:

Two of those changes still matter when you consume older reports. Format 11 added server_used and kept master_used as an alias, so reports in that format carry both fields. Format 12 removed master_used from the output, but OpenVox still reads it from incoming reports when server_used is absent, so older reports remain loadable.

Report

These fields are present in every report, although some values can be null when they do not apply to the run:

These fields appear only when OpenVox has a value for them, so consumers must treat them as optional:

Metric

Each entry in metrics is a Metric object with three fields:

Every entry in values is itself a three-element array of [name, label, value], for example ["changed", "Changed", 2].

The four categories measure:

• resources — counts of resources in each state: total, skipped, failed, failed_to_restart, restarted, changed, out_of_sync, scheduled, and corrective_change. All of these are present even when the count is zero.
• time — how long things took, in seconds. Contains one entry per resource type that OpenVox evaluated, named after the type in lowercase, plus config_retrieval, transaction_evaluation, catalog_application, and total.
• events — counts of events by status. total, success, and failure are always present; noop and audit appear only when the run produced events with those statuses.
• changes — a single total entry counting the changes in the transaction.

ResourceStatus

Each value in resource_statuses describes what happened to one resource:

The exclude_unchanged_resources setting, which defaults to true, omits resources that did not change from the serialized report. Resources that changed, failed, or were skipped are kept, so do not assume every resource in the catalog appears here. The resources metrics still count the whole catalog, which means resources.total is normally larger than the number of entries in resource_statuses.

Event

Each event records one property that OpenVox audited or attempted to change:

OpenVox converts event values to strings before serializing them, so rich data types arrive as strings rather than as their original Puppet types.

Log

Each entry in logs is a log message from the run:

Example

This report comes from a puppet apply run that created a file and evaluated a notify resource. Log entries and resource statuses are trimmed for length, and an agent run would also include server_used:

{
  "host": "web01.example.com",
  "time": "2026-07-20T06:16:41.086156000-04:00",
  "configuration_version": 1784542601,
  "transaction_uuid": "cf3624e9-744e-44d6-8c5c-057b812eb581",
  "report_format": 12,
  "puppet_version": "8.28.1",
  "status": "changed",
  "transaction_completed": true,
  "noop": false,
  "noop_pending": false,
  "environment": "production",
  "logs": [
    {
      "level": "notice",
      "message": "defined content as '{sha256}5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03'",
      "source": "/Stage[main]/Main/File[/etc/motd]/ensure",
      "tags": ["notice", "file", "class"],
      "time": "2026-07-20T06:16:41.087980000-04:00",
      "file": "/etc/puppetlabs/code/environments/production/manifests/site.pp",
      "line": 1
    },
    {
      "level": "notice",
      "message": "Applied catalog in 0.00 seconds",
      "source": "Puppet",
      "tags": ["notice"],
      "time": "2026-07-20T06:16:41.090383000-04:00",
      "file": null,
      "line": null
    }
  ],
  "metrics": {
    "resources": {
      "name": "resources",
      "label": "Resources",
      "values": [
        ["total", "Total", 9],
        ["skipped", "Skipped", 0],
        ["failed", "Failed", 0],
        ["failed_to_restart", "Failed to restart", 0],
        ["restarted", "Restarted", 0],
        ["changed", "Changed", 2],
        ["out_of_sync", "Out of sync", 2],
        ["scheduled", "Scheduled", 0],
        ["corrective_change", "Corrective change", 0]
      ]
    },
    "time": {
      "name": "time",
      "label": "Time",
      "values": [
        ["file", "File", 0.000751],
        ["notify", "Notify", 0.000333],
        ["config_retrieval", "Config retrieval", 0.071568],
        ["transaction_evaluation", "Transaction evaluation", 0.002611],
        ["catalog_application", "Catalog application", 0.004089],
        ["total", "Total", 0.004249]
      ]
    },
    "changes": {
      "name": "changes",
      "label": "Changes",
      "values": [
        ["total", "Total", 2]
      ]
    },
    "events": {
      "name": "events",
      "label": "Events",
      "values": [
        ["total", "Total", 2],
        ["failure", "Failure", 0],
        ["success", "Success", 2]
      ]
    }
  },
  "resource_statuses": {
    "File[/etc/motd]": {
      "title": "/etc/motd",
      "file": "/etc/puppetlabs/code/environments/production/manifests/site.pp",
      "line": 1,
      "resource": "File[/etc/motd]",
      "resource_type": "File",
      "provider_used": "posix",
      "containment_path": ["Stage[main]", "Main", "File[/etc/motd]"],
      "evaluation_time": 0.000751,
      "tags": ["file", "class"],
      "time": "2026-07-20T06:16:41.087274000-04:00",
      "failed": false,
      "failed_to_restart": false,
      "changed": true,
      "out_of_sync": true,
      "skipped": false,
      "change_count": 1,
      "out_of_sync_count": 1,
      "events": [
        {
          "audited": false,
          "property": "ensure",
          "previous_value": "absent",
          "desired_value": "file",
          "historical_value": null,
          "message": "defined content as '{sha256}5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03'",
          "name": "file_created",
          "status": "success",
          "time": "2026-07-20T06:16:41.087353000-04:00",
          "redacted": null,
          "corrective_change": false
        }
      ],
      "corrective_change": false
    }
  },
  "corrective_change": false,
  "catalog_uuid": "70898098-dd70-46af-a8a5-328fe921a5e9",
  "cached_catalog_status": "not_used"
}

To produce a report you can inspect yourself, run puppet apply with reporting enabled and read the YAML that the store processor writes to reportdir:

puppet apply --report --reports=store manifest.pp