Commit 9e19308b authored by Nils Christian Ehmke's avatar Nils Christian Ehmke

User Manual

parent 2b6e5f01
......@@ -29,6 +29,7 @@ import kieker.diagnosis.service.export.CSVData;
import kieker.diagnosis.service.export.ExportService;
import kieker.diagnosis.ui.about.AboutDialogView;
import kieker.diagnosis.ui.main.properties.LastImportPathProperty;
import kieker.diagnosis.ui.manual.ManualDialogView;
import kieker.diagnosis.ui.methods.MethodsView;
import kieker.diagnosis.ui.monitoring.MonitoringDialogView;
import kieker.diagnosis.ui.progress.ProgressDialog;
......@@ -47,6 +48,9 @@ public class MainController extends ControllerBase<MainViewModel> {
@Inject
MonitoringDialogView ivMonitoringDialogView;
@Inject
ManualDialogView ivDocumentationDialogView;
/**
* This action is performed, when the user wants to import a monitoring log.
*/
......@@ -213,4 +217,8 @@ public class MainController extends ControllerBase<MainViewModel> {
ivMonitoringDialogView.open( getViewModel( ).getWindow( ) );
}
public void performDocumentation( ) {
ivDocumentationDialogView.open( getViewModel( ).getWindow( ) );
}
}
......@@ -106,6 +106,20 @@ public class MainView extends ViewBase<MainController> {
final Menu menu = new Menu( );
menu.setText( getLocalizedString( "help" ) );
{
final MenuItem menuItem = new MenuItem( );
menuItem.setText( getLocalizedString( "documentation" ) );
menuItem.setOnAction( e -> getController( ).performDocumentation( ) );
menu.getItems( ).add( menuItem );
}
{
final SeparatorMenuItem separatorMenuItem = new SeparatorMenuItem( );
menu.getItems( ).add( separatorMenuItem );
}
{
final MenuItem menuItem = new MenuItem( );
menuItem.setText( getLocalizedString( "about" ) );
......
package kieker.diagnosis.ui.manual;
import java.net.URL;
import java.util.Locale;
import com.google.inject.Singleton;
import kieker.diagnosis.architecture.ui.ControllerBase;
@Singleton
public class ManualDialogController extends ControllerBase<ManualDialogViewModel> {
public void performRefresh( ) {
final Locale locale = Locale.getDefault( );
final String suffix = locale == Locale.GERMAN || locale == Locale.GERMANY ? "_de" : "";
final URL documentation = getClass( ).getClassLoader( ).getResource( "kieker/diagnosis/ui/manual/html/manual" + suffix + ".html" );
getViewModel( ).updatePresentation( documentation );
}
}
package kieker.diagnosis.ui.manual;
import java.io.InputStream;
import com.google.inject.Singleton;
import javafx.scene.Scene;
import javafx.scene.image.Image;
import javafx.scene.web.WebView;
import javafx.stage.Modality;
import javafx.stage.Stage;
import javafx.stage.StageStyle;
import javafx.stage.Window;
import kieker.diagnosis.architecture.ui.ViewBase;
@Singleton
public class ManualDialogView extends ViewBase<ManualDialogController> {
private final WebView ivWebView;
public ManualDialogView( ) {
ivWebView = new WebView( );
getChildren( ).add( ivWebView );
}
@Override
public void setParameter( final Object aParameter ) {
}
public void open( final Window aParent ) {
// Create a scene if necessary
Scene scene = getScene( );
if ( scene == null ) {
scene = new Scene( this );
}
// Load the icon
final String iconPath = getLocalizedString( "icon" );
final InputStream iconStream = getClass( ).getClassLoader( ).getResourceAsStream( iconPath );
final Image icon = new Image( iconStream );
// Prepare and show the stage
final Stage stage = new Stage( );
stage.setResizable( true );
stage.initModality( Modality.NONE );
stage.initStyle( StageStyle.DECORATED );
stage.initOwner( aParent );
stage.getIcons( ).add( icon );
stage.setTitle( getLocalizedString( "title" ) );
stage.setScene( scene );
getController( ).performRefresh( );
stage.showAndWait( );
}
WebView getWebView( ) {
return ivWebView;
}
}
package kieker.diagnosis.ui.manual;
import java.net.URL;
import com.google.inject.Singleton;
import javafx.scene.web.WebEngine;
import javafx.scene.web.WebView;
import kieker.diagnosis.architecture.ui.ViewModelBase;
@Singleton
public class ManualDialogViewModel extends ViewModelBase<ManualDialogView> {
public void updatePresentation( final URL aUrl ) {
final WebView webView = getView( ).getWebView( );
final WebEngine engine = webView.getEngine( );
engine.load( aUrl.toExternalForm( ) );
}
}
......@@ -5,6 +5,7 @@ monitoring=Monitoring settings
close=Close
help=Help
documentation=User manual
about=About Kieker Trace Diagnosis
favorites=Favorites
......
......@@ -5,6 +5,7 @@ monitoring=Monitoring Einstellungen
close=Beenden
help=Hilfe
documentation=Benutzerhandbuch
about=ber Kieker Trace Diagnosis
favorites=Favoriten
......
<h1>Kieker Trace Diagnosis - User Manual - ${version}</h1>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#requirementsAndInstallation">Requirements and Installation</a></li>
<li><a href="#license">License</a></li>
<li><a href="#views">Views</a></li>
<li><a href="#settings">Settings</a></li>
<li><a href="#monitoringSettings">Monitoring Settings</a></li>
<li><a href="#troubleshooting">Troubleshooting</a></li>
<li><a href="#bugs">Bugs und Featurewishes</a></li>
</ul>
<h2 id="introduction">Introduction</h2>
<i>Kieker Trace Diagnosis</i> is a tool that has been developed to tabularly prepare <i>Kieker</i> monitoring logs and make them searchable.
A focus has been put on memory usage and performance, which means that bigger logs in the range of several million method calls can still be opened.
<h2 id="requirementsAndInstallation">Requirements and Installation</h2>
The following requirements are necessary to use <i>Kieker Trace Diagnosis</i>.
<ul>
<li>Windows or Linux</li>
<li>Java Runtime Environment 8 Update 60 or higher</li>
</ul>
The usage of Oracle's JDK for the tool is recommended.
The troubleshooting for the usage of OpenJDK can be found in section <a href="#OpenJDK">OpenJDK</a>.
The memory usage of the tool depends on the size of the monitoring logs.
As guideline it is recommended to provide twice the size of the monitoring logs.</br></br>
For the installation, it is only necessary to unpack the archive <i>Kieker Trace Diagnosis-${version}-linux.tgz</i>, respectively <i>Kieker Trace Diagnosis-${version}-windows.zip</i>, into an abritary folder.
The application can subsequently be started with the star script <i>start.sh</i>, respectively <i>start.bat</i>, in the folder <i>bin</i>.
The application should have write permissions for the folder from which it has been started.
<h2 id="license">License</h2>
<i>Kieker Trace Diagnosis</i> is licensed under the Apache License Version 2.0.
The complete license text can be found in the provided file <i>LICENSE</i> .
The licenses of the uses libraries can be found in the <i>.license</i> files in the <i>lib</i> folder.
<h2 id="views">Views</h2>
<h3>Traces</h3>
This tab shows the single traces of the monitoring logs.
Incomplete traces are not shown here.
This view allows to search for various parameters.
Per default the filter is only applied on the top method call, which is the root node of the trace.
If necessary, the search can be widened to the whole trace by using the checkbox "Search in the whole trace".
If the checkbox "Search with regular expressions" is active, the filter masks "host", "class", "method", and "exceptions" can be filled with regular expressions with the default Java syntax.
<h3>Method Calls</h3>
This tab shows the single method calls of the monitoring logs.
Ignored methods and methods of incomplete traces are not shown.
This view allows to search for various parameters.
If the checkbox "Search with regular expressions" is active, the filter masks "host", "class", "method", and "exceptions" can be filled with regular expressions with the default Java syntax.
<h3>Aggregated Method Calls</h3>
This tab shows the method calls of the monitoring logs in aggregated form.
Methods with identical host, class, method, and exception are combined to a single aggregated method call.
Ignorierte Methoden und Methoden nicht rekonstruierter Traces werden hier nicht angezeigt.
Die Ansicht ermöglicht die Suche nach diversen Parametern.
Ist die Checkbox "Mit regulären Ausdrücken suchen" aktiv, so kann in den Filtermasken "Host", "Klasse", "Methode" und "Exception" ein regulärer Ausdruck nach Standard-Java-Syntax verwendet werden.
<h3>Statistics</h3>
This tab shows various statistics for the imported monitoring logs and the application.
The current (heap) memory usage of the application can be seen here as well.
<h2 id="settings">Settings</h2>
The settings allow to configure the tool.
</br></br>
The point "Appearance" allows to perform settings which has direct influence on the visual representation of the data.
For instance, the time unit or the representation of method calls can be changed.
The checkbox "Show non-monitored time" shows the time in the trace which has been used in the method call, but cannot be break down in detail due to missing monitoring.
</br></br>
With the help of the point "Aggregate method calls in traces" method calls can be combined in traces.
This is useful if a trace has several thousand method calls, but, for instance, only the slowest are important.
It can be choosen from various aggregation types.
<h2 id="monitoringSettings">Monitoring Settings</h2>
The monitoring settings can be used to enable and configure the monitoring for <i>Kieker Trace Diagnosis</i>.
Generally speaking this is only useful for the development of <i>Kieker Trace Diagnosis</i> or for teaching purposes.
The logs from this monitoring can be opened with the tool as well.
<h2 id="troubleshooting">Troubleshooting</h2>
<h3 id="OpenJDK">Usage of OpenJDK</h2>
The usage of OpenJDK instead of Oracle's JDK is basically possible.
However, it can be necessary to install OpenJFX explicitly.
<h3>Unable to create file logs/Kieker Trace Diagnosis.log</h3>
If this error message appears during the start, it is very likely that <i>Kieker Trace Diagnosis</i> does not have write permissions in the current working directory.
In this case the application can not write any log files, but can be used as usual.
<h3>OutOfMemoryError</h3>
Kommt es bei der Verwendung des Werkzeugs zu einem <i>OutOfMemoryError</i>, so ist das Monitoring Log zu groß, um von <i>Kieker Trace Diagnosis</i> geladen zu werden.
In diesem Fall sollte der Parameter <i>-Xmx</i> in dem Startscript auf einen höheren Wert gesetzt werden.
<h2 id="bugs">Bugs und Featurewishes</h2>
If any issues occur, which are not covered by this manual, or you find bugs or have feature wishes, you can create a ticket in our Gitlab under <a href="http://build.se.informatik.uni-kiel.de/gitlab/kieker/kieker-trace-diagnosis/issues/">http://build.se.informatik.uni-kiel.de/gitlab/kieker/kieker-trace-diagnosis/issues/<a>.
In case you do not have such an account, please send a mail to the Kieker mailing list under <a href="https://lists.sourceforge.net/lists/listinfo/kieker-users">https://lists.sourceforge.net/lists/listinfo/kieker-users</a>.
\ No newline at end of file
<h1>Kieker Trace Diagnosis - Benutzerhandbuch - ${version}</h1>
<ul>
<li><a href="#introduction">Einleitung</a></li>
<li><a href="#requirementsAndInstallation">Anforderungen und Installation</a></li>
<li><a href="#license">Lizenz</a></li>
<li><a href="#views">Ansichten</a></li>
<li><a href="#settings">Einstellungen</a></li>
<li><a href="#monitoringSettings">Monitoring Einstellungen</a></li>
<li><a href="#troubleshooting">Problembehandlung</a></li>
<li><a href="#bugs">Bugs und Featurewünsche</a></li>
</ul>
<h2 id="introduction">Einleitung</h2>
<i>Kieker Trace Diagnosis</i> ist eine Anwendung, die entwickelt wurde, um <i>Kieker</i> Monitoring Logs tabellarisch aufzubereiten und durchsuchbar zu machen.
Hierbei wurde ein Fokus auf Speicherverbrauch und Performance gelegt, sodass auch größere Logs im Bereich von einigen Millionen Methodenaufrufen noch geöffnet werden können.
<h2 id="requirementsAndInstallation">Anforderungen und Installation</h2>
Die folgenden Anforderungen sind notwendig, um <i>Kieker Trace Diagnosis</i> verwenden zu können.
<ul>
<li>Windows oder Linux</li>
<li>Java Runtime Environment 8 Update 60 oder höher</li>
</ul>
Für die Verwendung des Werkzeuges wird das Oracle JDK empfohlen. Die Problembehandlung bei Verwendung des OpenJDK findet sich in Abschnitt <a href="#OpenJDK">OpenJDK</a>.
Der Speicherbedarf des Werkzeuges hängt von der Größe der Monitoring Logs ab.
Als Richtlinie wird etwa das Zweifache der Größe des Monitoring Logs empfohlen.</br></br>
Zur Installation muss lediglich das Archiv <i>Kieker Trace Diagnosis-${version}-linux.tgz</i>, beziehungsweise <i>Kieker Trace Diagnosis-${version}-windows.zip</i>, in einen beliebigen Ordner entpackt werden.
Die Anwendung kann anschließend über das Startscript <i>start.sh</i>, beziehungsweise <i>start.bat</i>, im Ordner <i>bin</i> gestartet werden.
Die Anwendung sollte in dem Verzeichnis, aus welchem das Startscript heraus aufgerufen wird, Schreibrechte besitzen.
<h2 id="license">Lizenz</h2>
<i>Kieker Trace Diagnosis</i> ist unter der Apache License Version 2.0 lizenziert.
Der vollständige Lizenztext lässt sich der mitgelieferten Datei <i>LICENSE</i> entnehmen.
Die Lizenzen der verwendeten Blibliotheken lässt sich den <i>.license</i>-Dateien im <i>lib</i>-Ordner entnehmen.
<h2 id="views">Ansichten</h2>
<h3>Traces</h3>
Dieser Tab zeigt die Traces des Monitoring Logs einzeln an.
Nicht rekonstruierbare Traces werden hier nicht angezeigt.
Die Ansicht ermöglicht die Suche nach diversen Parametern, wobei der Filter standardmäßig nur innerhalb des obersten Methodenaufrufs sucht, d.h. in dem Wurzelknoten des Traces.
Bei Bedarf kann mittels der Checkbox "Im gesamten Trace suchen" die Suche auf den gesamten Trace ausgeweitet werden.
Ist die Checkbox "Mit regulären Ausdrücken suchen" aktiv, so kann in den Filtermasken "Host", "Klasse", "Methode" und "Exception" ein regulärer Ausdruck nach Standard-Java-Syntax verwendet werden.
<h3>Methodenaufrufe</h3>
Dieser Tab zeigt die Methodenaufrufe des Monitoring Logs einzeln an.
Ignorierte Methoden und Methoden nicht rekonstruierter Traces werden hier nicht angezeigt.
Die Ansicht ermöglicht die Suche nach diversen Parametern.
Ist die Checkbox "Mit regulären Ausdrücken suchen" aktiv, so kann in den Filtermasken "Host", "Klasse", "Methode" und "Exception" ein regulärer Ausdruck nach Standard-Java-Syntax verwendet werden.
<h3>Aggregierte Methodenaufrufe</h3>
Dieser Tab zeigt die Methodenaufrufe des Monitoring Logs in aggregierter Form an.
Aggregiert wird nach Host, Klasse, Methode und Exception, das heißt Methoden, bei denen alle vier Werte übereinstimmen werden zu einem aggregierten Methodenaufruf zusammengefasst.
Ignorierte Methoden und Methoden nicht rekonstruierter Traces werden hier nicht angezeigt.
Die Ansicht ermöglicht die Suche nach diversen Parametern.
Ist die Checkbox "Mit regulären Ausdrücken suchen" aktiv, so kann in den Filtermasken "Host", "Klasse", "Methode" und "Exception" ein regulärer Ausdruck nach Standard-Java-Syntax verwendet werden.
<h3>Statistiken</h3>
Dieser Tab zeigt diverse Statistiken über den importierten Monitoring Log und die Anwendung an.
Auch der aktuelle (Heap) Speicherbedarf der Anwendung kann hier abgelesen werden.
<h2 id="settings">Einstellungen</h2>
Die Einstellungen erlauben die Konfiguration des Werkzeugs.
</br></br>
Unter dem Überpunkt "Darstellung" lassen sich Einstellungen vornehmen, die sich direkt auf die visuelle Repräsentation der Daten auswirkt.
So kann die gewünschte Zeiteinheit oder die Darstellung von Methoden verändert werden.
Die Checkbox "Nicht gemonitorte Zeit anzeigen" blendet zusätzlich im Trace die Zeit ein, welche in dem Methodenaufruf verbraucht wurde, aber aufgrund eines nicht vorhandenen Monitorings nicht genauer aufgeschlüsselt werden kann.
</br></br>
Mittels des Überpunktes "Methodenaufrufe in Traces zusammenfassen" lassen sich Methodenaufrufe in Traces zusammenfassen.
Das ist dann nützlich, wenn ein Trace einige tausend Methodenaufrufe unter sich hat, von denen aber beispielsweise nur diejenigen interessant sind, welche die meiste Zeit verbraucht haben.
Zur Auswahl stehen mehrere Aggregationsarten.
<h2 id="monitoringSettings">Monitoring Einstellungen</h2>
In den Monitoring Einstellungen kann das Monitoring für <i>Kieker Trace Diagnosis</i> eingeschaltet und konfiguriert werden.
Das Monitoring ist im Allgemeinen nur für die Entwicklung von <i>Kieker Trace Diagnosis</i> oder für Leerzwecke erforderlich.
Die dabei entstehenden Logs können von dem Werkzeug ebenfalls eingelesen werden.
<h2 id="troubleshooting">Problembehandlung</h2>
<h3 id="OpenJDK">Verwendung von OpenJDK</h2>
Die Verwendung von OpenJDK anstelle des Oracle JDKs ist grundsätzlich möglich.
Es kann allerdings notwendig sein, OpenJFX explizit zu installieren.
<h3>Unable to create file logs/Kieker Trace Diagnosis.log</h3>
Kommt es beim Start zu dieser Fehlermeldung, so hat <i>Kieker Trace Diagnosis</i> vermutlich in dem aktuellen Arbeitsverzeichnis keine Schreibrechte.
Die Anwendung kann dann keine Log-Dateien schreiben, kann aber wie gehabt verwendet werden.
<h3>OutOfMemoryError</h3>
Kommt es bei der Verwendung des Werkzeugs zu einem <i>OutOfMemoryError</i>, so ist das Monitoring Log zu groß, um von <i>Kieker Trace Diagnosis</i> geladen zu werden.
In diesem Fall sollte der Parameter <i>-Xmx</i> in dem Startscript auf einen höheren Wert gesetzt werden.
<h2 id="bugs">Bugs und Featurewünsche</h2>
Wenn es zu Problemen kommt, die durch dieses Handbuch nicht abgedeckt sind, Sie Bugs finden oder einen Feature-Wunsch haben, können Sie in unserem GitLab unter <a href="http://build.se.informatik.uni-kiel.de/gitlab/kieker/kieker-trace-diagnosis/issues/">http://build.se.informatik.uni-kiel.de/gitlab/kieker/kieker-trace-diagnosis/issues/<a> ein Ticket anlegen.
Falls Sie keinen solchen Account haben, senden Sie gerne eine Mail an die Kieker Mailingliste unter <a href="https://lists.sourceforge.net/lists/listinfo/kieker-users">https://lists.sourceforge.net/lists/listinfo/kieker-users</a>.
\ No newline at end of file
......@@ -6,7 +6,7 @@ aggregatedMethods=Aggregated method calls:
traces=Traces:
ignoredRecords=Ignored records:
danglingRecords=Abandoned records:
incompleteTraces=Incomplete records:
incompleteTraces=Incomplete traces:
beginnOfMonitoring=Begin of monitoring:
endOfMonitoring=End of monitoring:
directory=Directory:
......
......@@ -14,13 +14,11 @@
</fileSet>
<fileSet>
<directory>example</directory>
</fileSet>
<fileSet>
<directory>manual</directory>
<directory>..\kieker-trace-diagnosis-application\src\main\resources\kieker\diagnosis\ui\manual\html</directory>
<outputDirectory>manual</outputDirectory>
<filtered>true</filtered>
<includes>
<include>*.pdf</include>
<include>*.html</include>
</includes>
</fileSet>
</fileSets>
......
......@@ -20,10 +20,6 @@
<exclude>**/.classpath</exclude>
<exclude>**/target/**</exclude>
<exclude>**/logs/**</exclude>
<exclude>**/img_DE/**</exclude>
<exclude>**/*.aux</exclude>
<exclude>**/*.log</exclude>
<exclude>**/*.pdf</exclude>
</excludes>
</fileSet>
</fileSets>
......
......@@ -75,5 +75,4 @@
</plugin>
</plugins>
</build>
</project>
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment