From d72e6b3aedf32975d929920da7a5d704d71fa7f7 Mon Sep 17 00:00:00 2001 From: Ell Date: Thu, 30 Jul 2020 18:14:23 +0300 Subject: [PATCH] devel-docs: update documentation of performance-log parameters --- devel-docs/performance-logs/Makefile.am | 1 + .../performance-log-parameters.png | Bin 0 -> 7000 bytes .../performance-logs/performance-logs.md | 45 ++++++++++++++++-- 3 files changed, 43 insertions(+), 3 deletions(-) create mode 100644 devel-docs/performance-logs/performance-log-parameters.png diff --git a/devel-docs/performance-logs/Makefile.am b/devel-docs/performance-logs/Makefile.am index 4f400b25d8..9f97b4bb49 100644 --- a/devel-docs/performance-logs/Makefile.am +++ b/devel-docs/performance-logs/Makefile.am @@ -4,6 +4,7 @@ EXTRA_DIST = \ dashboard-add-marker.png \ dashboard-start-recording.png \ dashboard-stop-recording.png \ + performance-log-parameters.png \ new-performance-issue.png \ performance-log-viewer.png \ performance-logs.md diff --git a/devel-docs/performance-logs/performance-log-parameters.png b/devel-docs/performance-logs/performance-log-parameters.png new file mode 100644 index 0000000000000000000000000000000000000000..4ec2c8bb32a13a2b06e5149546735c9be4f2d700 GIT binary patch literal 7000 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 literal 0 HcmV?d00001 diff --git a/devel-docs/performance-logs/performance-logs.md b/devel-docs/performance-logs/performance-logs.md index 97f1108086..8e951a4422 100644 --- a/devel-docs/performance-logs/performance-logs.md +++ b/devel-docs/performance-logs/performance-logs.md @@ -11,6 +11,7 @@ report performance-related issues. - [1. Recording Performance Logs](#1-recording-performance-logs) - [1.1. Event Markers](#11-event-markers) + - [1.2. Log Parameters](#12-log-parameters) - [2. Reporting Performance-Related Issues](#2-reporting-performance-related-issues) - [3. What Information is Contained in the Log?](#3-what-information-is-contained-in-the-log) - [4. Viewing Performance Logs](#4-viewing-performance-logs) @@ -33,7 +34,6 @@ report performance-related issues. - [4.3.1. Searching Samples](#431-searching-samples) - [4.4. History Navigation](#44-history-navigation) - [4.5. Environment Variables](#45-environment-variables) - - [5. Performance-Log Parameters](#5-performance-log-parameters) ## 1. Recording Performance Logs @@ -69,6 +69,11 @@ At this point, GIMP will perform any necessary final steps, which may take a while (usually, no more than a few seconds). At the end of this process, the log is ready. +*Note:* +In situations where you can't cleanly stop recording the log, such as +when GIMP crashes or freezes in the middle of the process, make sure to record +a *progressive* log, as described in [section *1.2*](#12-log-parameters). + ### 1.1. Event Markers When the recorded task is made up of multiple steps, it is useful to have an @@ -95,6 +100,39 @@ number (this is especially useful for empty event markers.) The number of the next event marker (the one that will be added when the button is clicked) is displayed on the *Add Marker* button. +### 1.2. Log Parameters + +When creating a performance log, several parameters can be set at the bottom of +the file-selection dialog. +There should normally be no reason to change the parameters, unless noted +otherwise. + +![Performance-log parameters](log-parameters.png) + + - *Sample Frequency:* + The number of program-state samples per second. + Higher values improve the resolution of the log, while making the recording + itself more expensive. + + - *Backtrace:* + Whether or not to include backtraces in the log. + Backtraces capture the code-paths taken while recording the log, and should + normally be included. + + - *Progressive:* + Whether or not to record a progressive log. + + GIMP normally defers certain information to the end of the log, in order to + minimize the cost of recording. + If the log can't be cleanly finished -- for example, if GIMP crashes or + freezes while recording the log -- this information will be missing, + rendering the log of limited use. + In situations like these, a progressive log should be recorded; progressive + logs include all relevant information at each sample, allowing them to be + terminated at any time. + + Progressive logs may incur a higher overhead while recording. + ## 2. Reporting Performance-Related Issues ![Reporting a performance-related issue](new-performance-issue.png) @@ -119,7 +157,7 @@ also be very helpful. The log consists mainly of a series of periodic *samples* of the program state. (The default sampling rate is 10 samples per second; see -[section *5*](#5-performance-log-parameters) for a way to modify this value.) +[section *1.2*](#12-log-parameters) for a way to modify this value.) Each sample contains the values of all the *instrumentation variables* displayed in the Dashboard. Additionally, on supported platforms, each sample contains a full *program @@ -234,7 +272,7 @@ associated with any sample, including: - *Log Parameters*: Various parameters relating to the performance log itself. - See [section *5*](#5-performance-log-parameters) for more information. + See [section *1.2*](#12-log-parameters) for more information. - *GIMP Version*: Verbose GIMP version information, as reported by `gimp -v`. @@ -607,6 +645,7 @@ The following environment variables are used by the viewer: ## 5. Performance-Log Parameters + A number of parameters affect performance-log generation. They may be currently specified as environment variables for GIMP: