GT reports available for data collection
Reports collect data about a running image, to analyse problems later: slowdowns, stuck processes, garbage collections, memory use. Every report carries the image data (GtReportImageData
): the GT, GT VM, Pharo VM and Pharo image versions, and nothing that identifies the user or the machine. How to analyse stored reports is on Analysing stored GT reports; how the infrastructure works and how to add a report is on Report infrastructure for collecting data in GT.
Each section below has two or three snippets: the first creates the report (inspect it), the next stores it (#selector
). A report can also be stored from the inspector with its
Save locally
action (#selector
), and a recorder can record and store in one go (#selector
).
Where a report goes depends on the store:
- GtReportsLocalStore
#selector
: the gt-reports folder next to the image
- GtReportsLocalStore
#selector
: another folder, e.g. a memory file system for experiments
- GtReportsCompositeStore
#selector
: several stores at once, with the same folder name in each
- GtNoReportsStore
: keeps nothing, to record a report only to inspect it
A snapshot of all processes in the image, with their stacks (GtProcessesReport
, recorded by #selector
).
processesReport := GtProcessesReport recordNewReport.
processesReport storeIn: GtReportsLocalStore default.
Profiles the whole image for 30 seconds (#selector
) in a background process, so the UI stays usable and what you do in it is profiled (GtMessageTallyReport
, GtMessageTallyReportRecorder
). Inspect the recording (GtReportRecording
): the report shows up in it when the recording ends. It is stored as the text report plus a JSON file with the other data.
messageTallyRecording := (GtMessageTallyReportRecorder current duration: 30 seconds) recordInBackgroundWithoutStoring.
messageTallyRecording report storeIn: GtReportsLocalStore default.
The full garbage collections recorded since the recorder was activated, with how the VM parameters changed (GtGarbageCollectsReport
). The recorder (GtGarbageCollectsRecorder
) only sees garbage collections while it is active: activate it first (#selector
), deactivate it when done (#selector
).
GtGarbageCollectsRecorder defaultInstance activate.
garbageCollectsReport := GtGarbageCollectsRecorder defaultInstance createReport.
garbageCollectsReport storeIn: GtReportsLocalStore default.
The memory taken by the instances and the code of every class (GtSpaceTally
), together with the VM memory statistics (GtSpaceTallyReport
, GtSpaceTallyReportRecorder
). Recording takes a few seconds in a background process, and the image freezes while the VM walks the heap. Inspect the recording: the report shows up in it when the recording ends. The report is stored as gzipped STON, about 3 MB for a large image; storing takes about 40 seconds, and reading it back about a minute. Read a stored file back with GtSpaceTallyReport
#selector
.
spaceTallyRecording := GtSpaceTallyReportRecorder current recordInBackgroundWithoutStoring.
spaceTallyRecording report storeIn: GtReportsLocalStore default.
A recorder can also record in the background and store the report itself (#selector
, or #selector
for another store). The recording shows the report, the stored files (#selector
) and the written files themselves (#selector
) once it has ended.
processesRecording := GtProcessesReportRecorder current recordLocallyInBackground.
Each stored report is one folder <type>/<yyyy-mm-dd>/<storage id>/ (#selector
in GtReportsStore
). The storage id is the UTC time plus a short random part, for example 20261108T093015Z-c8538f0a (#selector
); the date folder is its UTC day. Files are named after the report type (#selector
), e.g. message-tally.txt and message-tally.json, or after their role when a report has several files of the same kind (picture-1.png, picture-2.png, written with #selector
).
meta.json (GtReportMetadata
) is written last, so a folder without it is incomplete. It holds three names: the report type (#selector
: the kind of data, used for the folders and for grouping), the report class (#selector
: how to read the report now) and the report alias (#selector
: how to read it after a class rename). It holds two ids: the report uid (#selector
), given to the report when it is created (#selector
), and the storage id of this copy (#selector
). Storing the same report again gives a new storage id but the same report uid, so copies can be recognised. meta.json also holds the UTC time, the image data, the data files with their sizes (#selector
, GtReportFileDescription
), the format version (#selector
) and a machine name, empty in plain GT (#selector
, #selector
).