SP-ENDURANCE INSTRUCTIONS
=========================

Collecting Endurance Snapshots
------------------------------

- Pre-requirements:
  - Kernel with SMAPS enabled and normal POSIX tools
    (like Maemo and about all normal Linux distributions)
  - sp-endurance package and its dependencies installed

1. If you don't want to have lot of uninteresting log data,
   clean the syslog (as root), e.g. with:
     echo "" > /var/log/syslog.old
     echo "" > /var/log/syslog
   (If your logs are in normal place)
2. Reboot the device
3. If you have X, DISPLAY is not set and needs to be something else
   than ":0", set it (its needed for xmeminfo run by the script):
     export DISPLAY=:1
4. Then run the following before first test round:
     endurance-snapshot usecase
  -> This will save data files under "usecase/XXX/" directory.
     Each time it's called, XXX increases (000, 001, 002, ...)
5. Repeat step 4) after each test round.
   Note: if you're going to do this many times for use-cases which
   write a lot of data to syslog, you might clean the syslog also
   after every step 4)

Note: The purpose of the first snapshot in step 4) is to have separate
values for state before tests and how much resources are used when
everything involved in the test round are initialized after that. 
Rest of the steps where the same use-case is repeated, are then about
catching resource leakage (e.g. inappropriate caching of resources).


With the "endurance-mem-overview" script one can quickly check from
the collected data whether there were (already) large differencies
in the whole system memory usage.  This way only individual process
leakage and the leakage of other (less frequently leaked) resources
needs to be investigated with the full post-processing tools.


Post-processing / visualizing the endurance data
------------------------------------------------

- Pre-requirements:
  - sp-endurance-postproc package and its dependencies installed
  - the contents of the "usecase" directory (collected endurance data)

1. Run:
     endurance-parse-snapshots usecase/[0-9]*
2. Run:
     endurance-plot usecase/[0-9]*

Step 1 produces:
- HTML endurance report to file "endurance-report.html". This file is
  self-contained, and can be easily attached to bug reports, emails, etc.
  The data is shown in numeric and bar graph formats.
- The syslogs from each endurance is processed for interesting entries, such as
  error or warning messages from the kernel or user space programs.
  endurance-report.html automatically contains links to each of these reports.

Step 2 produces:
- Endurance report in graphical format, that can be easily browsed by opening
  the resulting "index.html" file.

If you want also details memory usage information from the
applications, give additional --parse-smaps argument to the first
script. This will require sp-smaps-visualize package. Or just read
the smaps.cap.gz files directly (endurance-extract-process-smaps
extracts just the given process information from all rounds).


Files coming from the source package
------------------------------------

Files for the endurance data collection:
- measure/endurance-snapshot
  - saves one snapshot of endurance data under the given directory
    using the tools below, date, df, sp_smaps_snapshot etc
- measure/proc2csv
  - binary required by endurance-snapshot
  - outputs contents of /proc/ files as CSV data
- measure/xmeminfo
  - binary optionally used by endurance-snapshot
  - outputs X clients resource usage from the X server as CSV data
- endurance-mem-overview
  - show ASCII chart of system memory usage from the already
    collected endurance data

Files for the data post-processing:
- postproc/endurance-parse-snapshots
  - runs endurance-report with suitable options
- postproc/endurance-plot
  - creates a large variety of (RAM, swap, CPU, X resource usage, interrupt,
    context switch etc) graphs from endurance data collected with
    endurance-snapshot for trend analysis
- postproc/endurance-report
  - post-processes data files saved by endurance-snapshot
- postproc/syslog_parse.py
  - used by endurance-report
  - script for digging out known types of problems from syslogs
- postproc/endurance-split-snapshots
  - script for making several reports out of given data files
    (e.g. if device has booted in middle of testing, that invalidates
    the memory changes, so you want a separate report after that)
- postproc/endurance-extract-process-smaps
  - script for extracting just the given process SMAPS information
    from all the endurance rounds for comparising (diff -u ...)
- postproc/endurance-extract-process-cgroup
  - script for extracting Cgroup process information from endurance data.
  - generates output in either text or HTML format.

Other files:
- README
  - this file
- src/proc2csv.c
  - source code for proc2csv
- src/xmeminfo.c
  - source code for xmeminfo
- Makefile
  - compiles the above source files and installs them
- man/
  - manual pages for all binaries and scripts
- postproc-lib/
  - perl module required by some of the post processing tools