retrace docs: improved overview, updated Package repository and Task cleanup sections

1 files changed, 66 insertions, 57 deletions

diff --git a/doc/abrt-retrace-server.texi b/doc/abrt-retrace-server.texi
index 95dca232..647c120e 100644
--- a/doc/abrt-retrace-server.texi
+++ b/doc/abrt-retrace-server.texi
@@ -50,11 +50,18 @@ Debugger (GDB), that is commonly used to analyze coredumps on free
 operating systems, expects that the system analyzing the coredump is
 identical to the system where the program crashed. Software updates
 often break this assumption even on the system where the crash occured,
-making the coredump analyzable only with significant effort.
-
-Retrace server solves this problem for Fedora 14+ and RHEL 6+ operating
-systems, and allows developers to analyze coredumps without having
-access to the machine where the crash occurred.
+making the coredump analyzable only with significant
+effort. Furthermore, older versions of software packages are often
+removed from software repositories, including the packages with
+debugging symbols, so the package with debugging symbols is often not
+available when user needs to install it for coredump analysis. Packages
+with the debugging symbols are large, requiring a lot of free space and
+causing problems with downloading them via unreliable internet
+connection.
+
+Retrace server solves these problems for Fedora 14+ and RHEL 6+
+operating systems, and allows developers to analyze coredumps without
+having access to the machine where the crash occurred.
 
 Retrace server is usually run as a service on a local network, or on
 Internet. A user sends a coredump together with some additional
@@ -391,66 +398,42 @@ newest possible version which has its requirements satisfied.
 @node Task cleanup
 @chapter Task cleanup
 
-Tasks that were created more than 5 days ago are deleted, because tasks
-occupy disk space (not so much space, as the coredumps are deleted after
-the retrace, and only backtraces and configuration remain). A shell
-script @command{abrt-retrace-clean} must check the creation time and
-delete the directories in @file{/var/spool/abrt-retrace/}. It is
-supposed that the server administrator sets @command{cron} to call the
-script once a day. This assumption must be mentioned in the
-@command{abrt-retrace-clean} manual page.
-
-The database containing packages and processing times should also
-be regularly pruned to remain small and provide data quickly. The
-cleanup script should delete some rows for packages with too many
-entries:
-@enumerate
-@item
-get a list of packages from the database: @code{SELECT DISTINCT
-package, release FROM package_time}
-@item
-for every package, get the row count: @code{SELECT COUNT(*) FROM
-package_time WHERE package == '??' AND release == '??'}
-@item
-for every package with the row count larger than 100, some rows
-most be removed so that only the newest 100 rows remain in the
-database:
-@itemize
- @item
-  to get highest row id which should be deleted,
-  execute @code{SELECT id FROM package_time WHERE package == '??' AND
-  release == '??' ORDER BY id LIMIT 1 OFFSET ??}, where the
-  @code{OFFSET} is the total number of rows for that single
-  package minus 100
- @item
-  then all the old rows can be deleted by executing @code{DELETE
-  FROM package_time WHERE package == '??' AND release == '??' AND id
-  <= ??}
-@end itemize
-@end enumerate
+It is neccessary to watch and limit the resource usage of tasks for a
+retrace server to remain operational. This is performed by the
+@command{abrt-retrace-cleanup} tool. It is supposed that the server
+administrator sets @command{cron} to run the tool every hour.
+
+Tasks that were created more than 120 hours (5 days) ago are
+deleted. The limit can be changed by the @var{DeleteTaskAfter} option in
+the server configuration file. Coredumps are deleted when the retrace
+process is finished, and only backtraces, logs, and configuration remain
+available for every task until the cleanup. The
+@command{abrt-retrace-cleanup} checks the creation time and deletes the
+directories in @file{/var/spool/abrt-retrace/}.
+
+Tasks running for more than 1 hour are terminated and removed from the
+system. Tasks for which the @command{abrt-retrace-worker} crashed for
+some reason without marking the task as finished are also removed.
 
 @node Package repository
 @chapter Package repository
 
-We should support every Fedora release with all packages that ever
-made it to the updates and updates-testing repositories. In order to
-provide all that packages, a local repository is maintained for every
-supported operating system. The debuginfos might be provided by a
-debuginfo server in future (it will save the server disk space). We
-should support the usage of local debuginfo first, and add the
-debuginfofs support later.
+Retrace server is able to support every Fedora release with all packages
+that ever made it to the updates and updates-testing repositories. In
+order to provide all that packages, a local repository needs to be
+maintained for every supported operating system.
 
 A repository with Fedora packages must be maintained locally on the
 server to provide good performance and to provide data from older
-packages already removed from the official repositories. We need a
-package downloader, which scans Fedora servers for new packages, and
-downloads them so they are immediately available.
+packages already removed from the official repositories. Retrace server
+contains a tool @command{abrt-retrace-reposync}, which is a package
+downloader scanning Fedora servers for new packages, and downloading
+them so they are immediately available.
 
-Older versions of packages are regularly deleted from the updates
-and updates-testing repositories. We must support older versions of
-packages, because that is one of two major pain-points that the
-retrace server is supposed to solve (the other one is the slowness of
-debuginfo download and debuginfo disk space requirements).
+Older versions of packages are regularly deleted from the updates and
+updates-testing repositories. Retrace server supports older versions of
+packages, as this is one of major pain-points that the retrace server is
+supposed to solve.
 
 A script abrt-reposync must download packages from Fedora
 repositories, but it must not delete older versions of the
@@ -800,4 +783,30 @@ database provides good estimations after some time anyway
 (@ref{Task cleanup} chapter describes how the
 data are pruned).
 
+@section Keep the database with statistics small
+The database containing packages and processing times should also be
+regularly pruned to remain small and provide data quickly. The cleanup
+script should delete some rows for packages with too many entries:
+@enumerate
+@item
+get a list of packages from the database: @code{SELECT DISTINCT package,
+release FROM package_time}
+@item
+for every package, get the row count: @code{SELECT COUNT(*) FROM
+package_time WHERE package == '??' AND release == '??'}
+@item
+for every package with the row count larger than 100, some rows most be
+removed so that only the newest 100 rows remain in the database:
+@itemize
+@item
+to get highest row id which should be deleted, execute @code{SELECT id
+FROM package_time WHERE package == '??' AND release == '??' ORDER BY id
+LIMIT 1 OFFSET ??}, where the @code{OFFSET} is the total number of rows
+for that single package minus 100
+@item
+then all the old rows can be deleted by executing @code{DELETE FROM
+package_time WHERE package == '??' AND release == '??' AND id <= ??}
+@end itemize
+@end enumerate
+
 @bye