Reports

Pulse Save records a report for every save and load. A report says which models were processed, how it went for each of them, how long it took, and what the models wrote about it. Reports are PulseFoundation reports: you look at them on the Reports page of Tools > Debug > Pulse Debugger (plugin Save), next to the reports of the other Pulse plugins.

Settings

Project Settings > Pulse > Save > Report

Setting Default Meaning
ReportPolicy.EditorMode Always When reports are recorded in builds with the editor (PIE and standalone games started from the editor).
ReportPolicy.PackagedMode OnFailure When reports are recorded in a packaged development or test build. Shipping builds never record.
ReportPolicy.MaxStoredReports 50 How many report files are kept. The oldest are deleted when a new one is written. 0 keeps all.

The modes are PulseFoundation’s EPulseReportMode:

Value Behavior
Disabled Nothing is recorded. Models do not even store their messages.
OnFailure Every report shows in the Pulse Debugger; a file is written only if something failed (see below).
Always Every report shows in the Pulse Debugger and is written as a file.

A report counts as failed if the process did not succeed, a model failed or timed out, or a model wrote an error message (see Messages of a model). It counts as a warning if a model was skipped, wrote a warning or dropped messages. Note that FPulseSaveProcessReport::bWasSuccessful only reflects the last chunk of a process, so the report looks at every model.

What is reported

Report type Recorded when
Save, Load Once for every Save() / Load() of a save manager. Static models that take part are listed with it.
SingleObject.Save, SingleObject.Load For SaveSingleObject / LoadSingleObject, including calls that fail right away, e.g. because the object has no record.
StaticModel.Save, StaticModel.Load For operations on static models outside of a process: GetOrCreateStaticModel (only if it actually loads or creates a model), SaveStaticModel and Pulse::Save::ReadStaticModel (once it found the record).

Single-object and static-model operations are often numerous (think of actors that load themselves when they spawn). They are collected into one report after one second without a new operation. They are also submitted when the manager is destroyed or when you call UPulseSaveManager::FlushReports().

Every model of a report is one entry (category = name of the model class, object = path of the model class) with:

  • its result (ok, failed, timed out, skipped when the identifier is missing or duplicated or a load finds no object for the record), the reason, and the duration (waterfall column of the Reports page);
  • whether its record was migrated, and from which class and version (see Save migration);
  • the messages the model wrote, as child entries with their severity.

The report header names the slot, the context and the manager (Meta), and a summary of the models. A report never contains the saved data itself.

A report of a save into a slot or a load from a slot also holds the wait for the storage:

  • The Meta line Storage sums it up, e.g. 2 read(s) 14 ms, 1 write(s) 230 ms, queue 0 ms, waited 240 ms, slot call 251 ms: the reads and writes with their wait, the wait for the slot (other calls on the same slot), the wall time from the first request to the last answer (requests that run at the same time count once), and the whole slot call.
  • One entry per request to the storage (category Storage): the operation, the entry, the version, the bytes and ok or the reason, with its wait as the duration and the time it was asked from the slot call on. A request that failed for another reason than a missing entry is a warning and makes the report a warning.
  • The duration of the report stays the process: the wait for the storage is not in it.
  • The report of a slot save is held back until the write answered, so it holds the write. A failed write leaves the process a success; the report warns with the write.
  • A slot load that fails while it reads (a missing entry, a storage that cannot be reached, no sound version, a cancel) applies nothing and still sends a short failed Load report: the slot, the requests to the storage and an error entry Nothing was loaded: <reason>. GetLastLoadReport() stays the report of the last load that ran.

The same numbers are in the process report (StorageWaitMs, SlotQueueMs, SlotTotalMs, StorageRequestCount, StorageWaits, see Save manager workflow).

A load lists every record that found no object in the world as skipped (“the record stays”): the record is kept for later. Without object in the header counts them per kind of identifier (Pulse::Save::GetIdentifierKind, the first part: Player 2, Quest 1, Name 3; KeptWithoutObjectByKind of the process report). Players who are offline and cells that are not loaded are expected; a kind that should always find its objects points at identifiers that changed (an actor renamed, an id built from something that differs between sessions).

Save slot and context

A report carries the context of its manager: a free text that tells managers apart, because their object names are generated. The manager of the save game has the context PulseSaveGame, the manager of a profile PulseSaveProfile. Call UPulseSaveManager::SetReportContext("Player profile") (Blueprint: Set Report Context) to set another one. Unlike the slot it is kept when the save game is replaced, and it applies to reports that start afterwards.

A report also names the save slot the manager worked with (Slot in the report’s meta: name, and entry for slots with entries). Search for it on the Reports page.

  • SaveToSlot, SaveToSlotWithMeta and LoadFromSlot set it automatically.
  • A plugin that handles slots itself and calls Save() / Load() directly (C++) calls UPulseSaveManager::SetReportSlot(SlotName, EntryId) (Blueprint: Set Report Slot). GetReportSlotName() returns it.
  • The slot belongs to the save game: SetSaveGame and ClearSaveGame forget it, so call SetReportSlot after SetSaveGame. This keeps a report from showing the slot of a save game that is no longer loaded.
  • Single-object and static-model reports carry the slot that was set when they were collected. If the slot changes, what was collected before is submitted first.
  • Pulse::Save::ReadStaticModel has no manager, so its report names the slot and the entry it read from.

Messages of a model

A model can write messages into its report entry. This is also possible for models that succeed.

C++ / Blueprint Meaning
LogInfo(Message) Information that helps to understand what happened.
LogWarning(Message) Something unexpected that did not stop the model.
LogError(Message) Something went wrong.

They are available on every model (UPulseSaveModelBase). Call them from the hooks of a model, from IPulseSaveInterface::OnSave / OnPostLoad (they receive the model as a parameter), or from a migration (Context.NewModel). In Blueprint they are normal nodes (“Log Info”, “Log Warning”, “Log Error”).

  • The messages are also written to the log (LogPulseSave).
  • A model that wrote at least one error counts as faulty in the report and makes the report count as failed. It does not change the result of the process: bWasSuccessful and the completion callbacks stay as they are.
  • Infos and warnings never make a model faulty.
  • A model stores at most 100 messages per operation. The rest is counted (dropped messages entry).
  • Messages are only stored while reports are recorded (Pulse::Save::IsRecordingReports()).

Pulse Debugger

Open the Reports page with the console command PulseSave.OpenReports, or from Tools > Debug > Pulse Debugger.

  • Filter by plugin Save, by Problems, or search for a slot, context or model.
  • Select a report to see its models as entries; models that failed or wrote messages have child entries.
  • Select two reports and turn on Compare to see which models got slower or are new.
  • Files lists the report files of earlier sessions.

The Save page (module PulseSaveDebugger, a developer tool: in the editor and in Debug and Development builds of a game) shows one save manager of the shown world at a time; chips switch between managers when there are several, and without a pick it follows the manager whose process ran last:

  • Tiles with lights: Last save (slot, size of the whole save game, frames, time on the game thread, and for a save into a slot · n ms storage: the wait for the storage, which the light does not count), Tombstones and kept records (tombstones in the save game, records the last load found no object for, per kind), Last load (loading, checked and applied, backup loaded: the previous version of a damaged save, damaged and not applied, records without object).
  • Phases of the last save: phase 1 (asynchronous models, over frames) and phase 2 (the synchronous models in one frame), with the largest gap between their data.
  • Models, largest first: kind, record size, time (frames for asynchronous models) and a note (failures, kept records, large records).

Lights: a model is yellow above 256 KB and red above 2 MB; a save is yellow above 4 MB or 16.7 ms on the game thread and red above 32 MB, 50 ms or when it failed (Pulse::Save::Debug::Limits). The numbers come from the process reports of the manager (GetLastSaveReport, GetLastLoadReport, see Save manager workflow).

Pulse Save also uses the other debugging tools of PulseFoundation:

  • Save and load processes are events on the Timeline page (source Save): started, finished, failed, slot saves that were written (with the wait for the storage) or not written, and slot loads that loaded nothing.
  • Every save manager is a snapshot provider (category Save): the Live page and the gameplay debugger category Pulse show its state, report context, slot, collectors, running processors and the last process with its failed models and its wait for the storage (Storage wait (ms)).

Files

Report files are JSON files of PulseFoundation in <Project>/Saved/Pulse/Reports/Save, written in the background. In a packaged game they are written to the same folder of the installed game (by default only for failures). To look at one in the editor, copy it into that folder of your project and use Files on the Reports page.

In code, Pulse::Debug::OnReportSubmitted() fires for every report of every plugin (check Report.Plugin == "Save"), and Pulse::Debug::Reports::EnumerateReportFiles("Save") / LoadReportFromFile read the files again.


This site uses Just the Docs, a documentation theme for Jekyll.