Open rju opened 2 weeks ago
rju
commented
2 weeks ago author André van Hoorn -- Mon, 3 Sep 2012 12:38:08 +0200
See also
KIEKER-528
Done
rju
commented
2 weeks ago author nils-christian -- Fri, 19 Apr 2013 13:42:21 +0200
Add also
KIEKER-556
Open
during this task.
rju
commented
2 weeks ago author nils-christian -- Fri, 19 Apr 2013 20:04:02 +0200
I also think that the appendix is currently too big (almost half of the document).
Suggested structure:
Problem is that this would tear the JMS example in part.
Also:
rju
commented
2 weeks ago author rju -- Tue, 23 Apr 2013 09:29:20 +0200
I concur. A good structure should look like nie's example. However, I would define the toc as follows:
rju
commented
2 weeks ago author Jan Waller -- Tue, 23 Apr 2013 09:41:42 +0200
Replying to [rju|comment:9]:
> * Example analysis with a load generator
Even simpler. Load generator etc is far to complex for a real quickstart. Given the log prodcued in the example before, which is the one liner I have to click/type to get an analysis.
> * Basic structure
Even this one might be too much. The document should really start with complete monitoring + analysis on a single A4 page.
rju
commented
2 weeks ago author rju -- Tue, 23 Apr 2013 09:47:38 +0200
Replying to [jwa|comment:10]:
> Replying to [rju|comment:9]:
> > * Example analysis with a load generator
>
> Even simpler. Load generator etc is far to complex for a real quickstart. Given the log prodcued in the example before, which is the one liner I have to click/type to get an analysis.
My idea with the load generator was, to produce data which result in useful graphical results, but this might indeed be too complicated for a total noob. So maybe an advice to by some animals and then "pay" for them might suffice.
> > * Basic structure
>
> Even this one might be too much. The document should really start with complete monitoring + analysis on a single A4 page.
One page might be a little too short, especially in our style, but a two page limit would be possible. However, in such a case we should think about including the quick start guide into the introduction. Otherwise the document will become very unbalanced.
rju
commented
2 weeks ago author nils-christian -- Sat, 27 Apr 2013 11:54:11 +0200
So, based on [comment:9]
rju
commented
2 weeks ago author nils-christian -- Fri, 3 May 2013 15:12:46 +0200
More ideas for improvement? Otherwise I would start with this in a new branch and we can add further input later.
rju
commented
2 weeks ago author André van Hoorn -- Fri, 3 May 2013 15:40:48 +0200
Replying to [nie|comment:13]:
> More ideas for improvement? Otherwise I would start with this in a new branch and we can add further input later.
To be honest, I'm not sure if this is a good structure --- but don't ask me why 
However, I think it's good to get things started. So, yes: How about
1. starting with a new document
2. setting up the structure
3. identifying
a. parts that that can be reused from the old user guide (there should be quite some of them)
b. parts that need to be (re)written
As an alternative, the structure (and the anticipated lengths of contents) could also be planned using a mindmap (e.g., using FreeMind). (In order not to run into details but seeing the overall structure)
Nils Christian Ehmke: Would you present your progress on the [next Kieker meeting|Meetings/meeting-20130516]?
rju
commented
2 weeks ago author André van Hoorn -- Fri, 3 May 2013 15:49:08 +0200
> As an alternative, the structure (and the anticipated lengths of contents) could also be planned using a mindmap (e.g., using FreeMind). (In order not to run into details but seeing the overall structure)
Or a simple spread sheet.
rju
commented
2 weeks ago author André van Hoorn -- Fri, 3 May 2013 15:51:35 +0200
Replying to [avh|comment:15]:
> > As an alternative, the structure (and the anticipated lengths of contents) could also be planned using a mindmap (e.g., using FreeMind). (In order not to run into details but seeing the overall structure)
>
> Or a simple spread sheet.
Trac page with a table?
rju
commented
2 weeks ago author nils-christian -- Sat, 4 May 2013 13:56:37 +0200
I start with a more detailed mind map and
- depending on how quickly I get this done
- will either upload it here or present it at the meeting.
rju
commented
2 weeks ago author nils-christian -- Sat, 4 May 2013 17:04:24 +0200
Current mind map is attached to this ticket. Further suggestions?
rju
commented
2 weeks ago author nils-christian -- Mon, 6 May 2013 10:50:01 +0200
A first structure can be found in the branch bug-560 at changeset d1edd11a9b8bcc73f14ca12396e4a1786918150a.
rju
commented
2 weeks ago author Jan Waller -- Mon, 6 May 2013 13:08:57 +0200
looks good to me.
Maybe a first sentence like "Skip to ... for a quick start example."
rju
commented
2 weeks ago author nils-christian -- Mon, 6 May 2013 13:19:47 +0200
Replying to [jwa|comment:20]:
> Maybe a first sentence like "Skip to ... for a quick start example."
Sounds good. I added this between the introduction and the the "What is Kieker?" section as a notify box.
rju
commented
2 weeks ago author André van Hoorn -- Mon, 6 May 2013 13:23:47 +0200
Replying to [nie|comment:18]:
> Current mind map is attached to this ticket. Further suggestions?
Based on changeset:d1edd11a9b8bcc73f14ca12396e4a1786918150a/kieker-git:
We could also have a "Use Cases" or "Advanced Examples" Chapter with
1. Monitoring and Analyzing a Java EE Application (our JPetStore example + Live Demo Code)
1. Monitoring System-Level Metrics with Sigar
1. Monitoring and Analysis via JMS
What I would like to see (also in order to plan the writing/restructuring):
Table with
1. New structure (down to the lowest tocdepth level)
2. Old structure (down to the lowest tocdepth level)
3. Fill new structure with table cells (section number + name) from old structure and comment what needs to be changed
4. Make removed sections explicit
5. Decide which example projects we will have and assign to chapters
This could help to track overall progress/duties
rju
commented
2 weeks ago author nils-christian -- Mon, 6 May 2013 14:36:34 +0200
Current structure:
| Chapter | Name | |
| 1 | Introduction | |
| 1.1 | What is Kieker? | |
| 1.2 | Framework Components and Extension Points | |
| 1.3 | Licensing | |
| 1.4 | Citing Kieker | |
| 1.5 | Kieker is Recommended by the SPEC Research Group | |
| 1.6 | Structure of this User Guide | |
| 2 | Quick Start Example | |
| 2.1 | Download and Installation | |
| 2.2 | Bookstore Example Application | |
| 2.3 | Monitoring with Kieker.Monitoring | |
| 2.4 | Analysis with Kieker.Analysis | |
| 3 | Kieker.Monitoring Component | |
| 3.1 | Monitoring Controller | |
| 3.1.1 | Creating MonitoringController Instances | |
| 3.1.2 | Logging Monitoring Records | |
| 3.1.3 | Retrieving the Current Time and Using Custom Time Sources | |
| 3.1.4 | Scheduling and Removing Periodic Samplers | |
| 3.1.5 | Controlling the Monitoring State | |
| 3.1.6 | Adaptive Monitoring | |
| 3.1.7 | JMX MBean Access to MonitoringController | |
| 3.2 | Kieker.Monitoring Configuration | |
| 3.3 | Monitoring Records | |
| 3.4 | Monitoring Probes | |
| 3.5 | Monitoring Writers | |
| 4 | Kieker.Analysis Component | |
| 4.1 | Pipe-and-Filter Framework and Included Plugins | |
| 4.1.1 | Programmatic Creation of Pipe-and-Filter Architectures | |
| 4.1.2 | Monitoring Reader Plugins | |
| 4.1.3 | Filter Plugins | |
| 4.1.4 | Repositories | |
| 4.2 | Developing Analysis Plugins and Repositories | |
| 4.2.1 | Configuration | |
| 4.2.2 | Plugin Annotation and Output Ports | |
| 4.2.3 | Developing Monitoring Reader Plugins | |
| 4.2.4 | Developing Filter Plugins | |
| 4.2.5 | Developing and Accessing Required Repositories | |
| 5 | Kieker.TraceAnalysis Tool | |
| 5.1 | Monitoring Trace Information | |
| 5.1.1 | AspectJ-Based Instrumentation | |
| 5.1.2 | Servlet Filters | |
| 5.1.3 | Spring | |
| 5.1.4 | CXF SOAP Interceptors | |
| 5.2 | Trace Analysis and Visualization | |
| 5.3 | Example Kieker.TraceAnalysis Outputs | |
| 5.3.1 | Textual Trace and Equivalence Class Representations | |
| 5.3.2 | Sequence Diagrams | |
| 5.3.3 | Call Trees | |
| 5.3.4 | Dependency Graphs | |
| 5.3.5 | Response Times in Dependency Graphs | |
| 5.3.6 | HTML Output of the System Model | |
| Appendix | - |
|
| A | Wrapper Scripts | |
| A.1 | Script convertLoggingTimestamp.sh | bat |
| A.2 | Script logReplay.sh | bat |
| A.3 | Script kax-run.sh | bat |
| A.4 | Script kax-viz.sh | bat |
| A.5 | Script trace-analysis.sh | bat |
| A.6 | Script dotPic-fileConverter.sh | bat |
| B | Java EE Servlet Container Example | |
| B.1 | Setting | |
| C | Using the JMS Writer and Reader | |
| C.1 | ActiveMQ | |
| C.1.1 | Download and Prepare ActiveMQ | |
| C.1.2 | Copy Kieker and ActiveMQ Libraries | |
| C.1.3 | Kieker Monitoring Configuration for ActiveMQ | |
| C.1.4 | Running the Example | |
| C.2 | HornetQ | |
| C.2.1 | Download and Prepare HornetQ | |
| C.2.2 | Copy Kieker and HornetQ Libraries | |
| C.2.3 | Kieker Monitoring Configuration for HornetQ | |
| C.2.4. | Running the Example | |
| C.3 | OpenJMS | |
| C.3.1 | Download and Prepare OpenJMS | |
| C.3.2 | Copy Kieker and OpenJMS Libraries | |
| C.3.3 | Kieker Monitoring Configuration for OpenJMS | |
| C.3.4. | Running the Example | |
| D | Sigar-Based Samplers for System-Level Monitoring |
|
| D.1 | Preparation | |
| D.2 | Using the Sigar-Based Samplers | |
| D.3 | Executing the Example | |
| E | Kieker.Monitoring Default Configuration | |
| F | Additional Source Code Listings | |
| F.1 | MyNamedPipeManager and MyPipe | |
| G | Example Console Outputs | |
| G.1 | Quick Start Example (Chapter 2) | |
| G.2 | Trace Monitoring, Analysis & Visualization (Chapter 5) | |
| H | Ant Scripts | |
| H.1 | Quick Start Example (Chapter 2) | |
| H.2 | Custom Components (Chapters 3 and 4) | |
| H.3 | AspectJ-based Trace Monitoring (Chapter 5) |
rju
commented
2 weeks ago author nils-christian -- Mon, 6 May 2013 14:41:08 +0200
Replying to [avh|comment:22]:
> * Quick Start as a separate chapter rather than integrating it into the introduction
Wouldn't recommend. We wanted a really short example, right? A chapter for two pages?
> * Include TSLib + OPAD somewhere (e.g., as part of Tools?)
> * System model needs to be described (finally)
Which one? The one of Kieker or the one used for the SystemModelRepository?
> * JMS and Sigar should not be part of the Appendix but have a more prominent location
True. Technically it would be better to put them in Monitoring/Analysis, but that would also rip the example apart.
> * What are contents of the Appendix?
If we remove JMS and sigar? None, I would suggest. I am not even sure whether we need an appendix...
> * Where is the JPetStore example?
Would probably be part of the JavaEE Monitoring chapter.
>
> We could also have a "Use Cases" or "Advanced Examples" Chapter with
> 1. Monitoring and Analyzing a Java EE Application (our JPetStore example + Live Demo Code)
Well, the analysis won't be the problem. But the monitoring is. I would recommend to put this into the monitoring chapter instead of making a new chapter for every use case (because this is the reason for our current appendix...)
rju
commented
2 weeks ago author nils-christian -- Mon, 6 May 2013 14:50:25 +0200
Replying to [nie|comment:25]:
New structure (Still work in progress):
| Chapter | Name | Adopted from Old User Guide |
| 1 | Introduction | 1.0 |
| 1.1 | What is Kieker? | 1.1 (But a lot shorter. I don't think that it is useful to put the flow overview in this section. I would prefer only the first diagram as a first overview of the system) |
| 1.2 | Licensing | 1.2 |
| 1.3 | Citing Kieker | 1.3 |
| 1.4 | Kieker is Recommended by the SPEC Research Group | 1.4 (Maybe put this in the introduction?) |
| - |
Additional section: Download and Installation | |
| 1.5 | Quickstart Example | Completely new |
| 1.5.1 | Monitoring | Completely new |
| 1.5.2 | Analysis | Completely new |
| 1.6 | Outline of this User Guide | Has do be remade |
| 2 | Kieker Monitoring | |
| 2.1 | The Concept behind the Monitoring | 2.3, 3, 3.1, 1.1 (Overview), 3.1.1, 3.1.2 |
| 2.1.1 | Data Flow | 2.3, 3, 3.1, 1.1 (Overview), 3.1.1, 3.1.2 |
| 2.1.2 | Monitoring Components | |
| 2.2 | How to Monitor Applications | |
| 2.2.1 | Manual Probes | Partially from 2.3, partially new |
| 2.2.2 | Aspect Oriented Probes | Partially from 5.1.1, partially new |
| 2.2.3 | Monitoring within Java EE Applications | |
| 2.2.3.1 | Spring Probes | 5.1.3 (Is this even limited to JavaEE?), B? |
| 2.2.3.2 | Aspect Oriented Probes | 5.1.1, B |
| 2.2.3.3 | SOAP Interceptors | Partially 5.1.4, B? |
| 2.2.4 | Periodic Samplers | 3.1.4 |
| 2.2.4.1 | Sigar | D |
| 2.3 | Creating and Controlling the Monitoring | 3.1.5, 3.2 |
| 2.3.1 | Time Sources | 3.1.3 |
| 2.3.2 | Adaptive Monitoring | 3.1.6 |
| 2.3.3 | JMX MBean Access | 3.1.7 |
| 2.4 | Development of own Monitoring Components | |
| 2.4.1 | Records | 3.3 |
| 2.4.2 | Probes | 3.4 |
| 2.4.3 | Writers | 3.5 |
| 3 | Kieker Analysis | |
| 3.1 | The Concept behind the Analysis | 4.1, 2.4 |
| 3.1.1 | Data Flow | 4.1, 2.4 |
| 3.1.2 | Analysis Components | 4.1, 2.4 |
| 3.2 | Creating and Controlling the Analysis | 4.1, 2.4 |
| 3.3 | Development of own Analysis Components | |
| 2.3.1 | Readers | 4.2.3, 4.2.1 |
| 2.3.2 | Filters | 4.2.4, 4.2.1 |
| 2.3.3 | Repositories | 4.2.5, 4.2.1 |
| 4 | Kieker Tools | |
| 4.1 | Trace Analysis | A.5, Partially 5.1 |
| 4.1.1 | Visualizations | Partially 5.2, 5.3; This here will in fact contain all (sub)sections of 5.3 |
| 4.2 | Replay Monitoring Logs | A.2 |
| 4.3 | Convert Monitoring Timestamps | A.1 |
| 4.4 | KAX Viz | A.4 |
| 4.5 | KAX Runner | A.3 |
| 4.6 | TSLib & OPAD | Completely new? |
| 4.7 | Kieker WebGUI | Completely new |
| 4.7.1 | Features | Completely new |
| 4.7.2 | Quickstart Example | Completely new |
| 4.7.3 | Detailed Introduction | Completely new |
| Appendix | - |
|
| A | JMS | |
| A.1 | OpenJMS | C.3 |
| A.2 | ActiveMQ | C.1 |
| A.3 | HornetQ | C.2 |
Also:
| Sections to be Removed |
| E |
| F |
| F.1 |
| G |
| G.1 |
| G.2 |
| H |
| H.1 |
| H.2 |
| H.3 |
rju
commented
2 weeks ago author nils-christian -- Mon, 6 May 2013 16:21:52 +0200
My idea of Chapter 4 (Kieker Tools) was to present the tools we provide directly in Kieker. If we start to add TSLib + OPAD in this, we probably should also move Chapter 5 as section into said chapter.
Also: Where should we move the JMS part?
rju
commented
2 weeks ago author nils-christian -- Tue, 7 May 2013 14:11:27 +0200
N/A
rju
commented
2 weeks ago author nils-christian -- Fri, 10 May 2013 13:53:39 +0200
Suggested examples:
rju
commented
2 weeks ago author André van Hoorn -- Thu, 16 May 2013 13:03:57 +0200
Next steps as discussed [today|Meetings/meeting-20130516]:
KIEKER-1128
Done
)
KIEKER-556
Open
)rju
commented
2 weeks ago author nils-christian -- Sat, 18 May 2013 19:37:40 +0200
What exactly was our agreement related to the whole "Kieker as a Tool" and "Kieker as a Framework" thing? Did we want to mention the important chapters/sections in the introduction or did we want to make two parts within the user guide?
rju
commented
2 weeks ago author André van Hoorn -- Tue, 21 May 2013 10:08:56 +0200
Replying to [nie|comment:30]:
> What exactly was our agreement related to the whole "Kieker as a Tool" and "Kieker as a Framework" thing? Did we want to mention the important chapters/sections in the introduction or did we want to make two parts within the user guide?
I remember that our agreement was "we'll see after the scheduled chapters are written (quick start, web UI, tools)"
rju
commented
2 weeks ago author nils-christian -- Tue, 21 May 2013 10:25:55 +0200
Replying to [avh|comment:31]:
> I remember that our agreement was "we'll see after the scheduled chapters are written (quick start, web UI, tools)"
I understand.
The tools part can be (and already has been) copied from the old user guide for the most part. Only the TraceAnalysis tool section has to be modified (see table).
rju
commented
2 weeks ago author rju -- Tue, 3 Sep 2013 13:09:15 +0200
I propose to add 4.8 Kieker Data Bridge. The documentation found in the wiki and in other online sources could be used to fill this section quickly.
rju
commented
2 weeks ago author nils-christian -- Tue, 10 Sep 2013 10:47:49 +0200
Still missing: troubleshoot section
Related:
rju
commented
2 weeks ago author nils-christian -- Tue, 10 Sep 2013 13:43:10 +0200
We should mention the termination sequence in more detail (related to
JIRA Issue: KIEKER-977 Restructure user guide Original Reporter: Andre van Hoorn
We have talked about quite a couple of times already. Some issues are listed in
KIEKER-699
Done
, some where raised in the SPEC RG reviews
Restructure Quickstart Example (Use AOP instead)
See also
KIEKER-1128
Done