[KIEKER-359] Changes to user guide for release 1.8

[rju]

JIRA Issue: KIEKER-359 Changes to user guide for release 1.8 Original Reporter: Andre van Hoorn

---

We decided to postpone the big project of restructuring the user guide ( KIEKER-977 Open ) to 1.9

Just to sum up what should be and what has been done for release 1.8.

Please complete the list and strike resolved item.

Specific

• -Fig. 2.5: Package name of OperationExecutionRecord -
• is: kieker.common.record
• should be: kieker.common.record.controlflow
• Section 2.4 includes "Currently, Kieker.Analysis pipe-and-filter configurations can only be created programmatically, i.e., by configuring, instantiating, and connecting the plugins in a Java program. [...]"
• Could refer to Web GUI
• Fig. 3.1:
• does not include API for adaptive monitoring
• Fig 3.4:
• is missing the TCPWriter
• Fig. 4.2:
• Hardly readable (could be re-arranged just a little to increase font size)
• Fig. 5.1: Package name of OperationExecutionRecord (just like for Fig. 2.5; see above)
• is: kieker.common.record
• should be: kieker.common.record.controlflow
• Fig. 5.11:
• Update screenshot of HTML system model
• Update jconsole SCreenshots
• Appendix
• -List sections in the table of contents (currently suppressed but makes sense because useful-content included)
• -Section A.2: -
• Update Usage output of logReplay.(sh|bat)
• Appendix H (Ant Scripts)
• Remove?
• Update Ref [3] (Kieker User Guide 1.8)

Examples:

• Test all examples under Win/UNIX-like systems/Mac? (After Library Updates! KIEKER-991 Done )
• Particularly, JMS Writer/Reader example (Appendix C) to be tested
• For Win: consider test results by Nils from comment:7
• <...>

General:

• -Double-check listings and references to these -
• Correct parts of the source code included?
• Listing 4.3 is broken
• Listing B.3 is broken
• References to specific lines
• Page breaks (add/remove hard breaks and {{\enlargethispage}}s) etc. (in the very end)

Not considered:

• Add trouble shooting section (only short?)
• warning box to the adaptive monitoring like "currently slow".

Checklist:

[rju]

author nils-christian -- Tue, 17 Sep 2013 11:26:41 +0200

I suggest to add some kind of warning box to the adaptive monitoring like "currently slow".

[rju]

author nils-christian -- Tue, 17 Sep 2013 11:29:35 +0200

Fig 3.4 is missing the TCPWriter

[rju]

author André van Hoorn -- Tue, 17 Sep 2013 12:47:44 +0200

Replying to [nie|comment:2]:
> I suggest to add some kind of warning box to the adaptive monitoring like "currently slow".

Replying to [nie|comment:3]:
> Fig 3.4 is missing the TCPWriter

Both added to list above

[rju]

author André van Hoorn -- Tue, 17 Sep 2013 13:52:30 +0200

Resolved some items from above in changeset:6f66a147695c5204882416010199f1e820da8e65/kieker-git

[rju]

author nils-christian -- Tue, 17 Sep 2013 14:18:40 +0200

I just finished my tests of the examples under Windows. To put it briefly, nearly everything works.

Some details:

- Very often we list the additional step to copy the kieker libs. This is no longer necessary, as we already copy them into the correct folders during the release build.
- Example "ch2-bookstore-example" works.
- Example "ch2-manual-instrumentation" works.
- For "ch2-manual-instrumentation" it could be confusing that we refer to the usual kieker jar, although we copy the emf version into the lib folder (this is necessary as the emf version is needed for the second part of the example)
- Example in Chapter 5 works as well.
- The Sigar example works. However, it seems like the analysis part does not like spaces in paths. Possible solution: Replace {{<arg line="${analysis.directory}"/> }} with {{<arg value="${analysis.directory}"/> }} in the build script.
- JMS examples are working.

Tested with:

- Kieker Nightly Build No. 1511 (17.09.2013 00:06:41)
- Windows 7, Java 1.7.0_25, Ant 1.9.2
- ActiveMQ 5.8.0
- HornetQ 2.4.0.Beta1
- OpenJMS openjms-0.7.7-beta-1

Edit: JPetStore seems to work as well.

[rju]

author André van Hoorn -- Tue, 17 Sep 2013 14:46:44 +0200

Replying to [nie|comment:7]:
> I just finished my tests of the examples under Windows. To put it briefly, nearly everything works.
>
> Some details: [...]
>

Thanks a lot, Nils! I will resolve the remaining issues (and just put a reminder to the list above)

[rju]

author André van Hoorn -- Tue, 17 Sep 2013 15:52:22 +0200

Some more fixes in changeset:722a4a01fd2b3a4e14273e144a13ef76eafc828f/kieker-git

[rju]

author Jan Waller -- Tue, 17 Sep 2013 15:55:12 +0200

> warning box to the adaptive monitoring like "currently slow"

not really needed in the userguide.

[rju]

author André van Hoorn -- Mon, 7 Oct 2013 20:32:59 +0200

Some fixes (listings, page breaks, mentioning web ui) committed in changeset:0195019a11bbcd59e300b72dfa9c5a9b1b22844e/kieker-git

[rju]

author André van Hoorn -- Mon, 7 Oct 2013 20:41:57 +0200

Fine from my perspective.