docs + sample application

Author: niesfisch

README-ELK.md

@@ -122,14 +122,20 @@ For TCP, use:
 
 Example run (hello world sample):
 
+```bash
+cd sample_application && mvn clean package
+```
+
+Then start with agent and UDP output:
+
 ```bash
 java \
   -javaagent:"${PWD}/target/java-code-tracer-1.0-SNAPSHOT-jar-with-dependencies.jar" \
   -Djct.loglevel=INFO \
   -Djct.config="${PWD}/doc/config-sample-helloworld-udp.yaml" \
   -Djct.logDir=/tmp/jct \
   -noverify \
-  -jar "${PWD}/doc/helloworld-loop.jar"
+  -jar "${PWD}/doc/java-code-tracer-sample-application.jar"
 ```
 
 To run over TCP, switch config file to:

README.md

@@ -22,6 +22,7 @@ If you work in a legacy app and ask things like "Can we remove this?" or "Is thi
 - [Hello World Walkthrough](#hello-world-walkthrough)
 - [Tools](#tools)
 - [ELK Integration Guide](#elk-integration-guide)
+- [Sample Application Screenshots](#sample-application-screenshots)
 - [Similar Projects](#similar-projects)
 - [IntelliJ JVM Options Example](#intellij-jvm-options-example)
 - [License](#license)
@@ -60,7 +61,7 @@ Minimum commands:
 ```bash
 mvn clean package
 mkdir -p "$HOME/.jct"
-cp doc/config-sample-file.yaml "$HOME/.jct/config-sample-file.yaml"
+cp doc/config-sample-application-file.yaml "$HOME/.jct/config-sample-file.yaml"
 java \
   -javaagent:"${PWD}/target/java-code-tracer-1.0-SNAPSHOT-jar-with-dependencies.jar" \
   -Djct.config="$HOME/.jct/config-sample-file.yaml" \
@@ -207,11 +208,20 @@ processor:
 
 ```json
 {
-  "stack": [
-    "de.example.Service.doWork()",
-    "de.example.Repository.findById()"
-  ],
-  "timestampMillis": "1528120883697"
+	"stack": [
+		"de.marcelsauer.sample.ClassA.methodA_1()",
+		"de.marcelsauer.sample.ClassB.methodB_2()",
+		"de.marcelsauer.sample.ClassB.methodB_3()",
+		"de.marcelsauer.sample.ClassC.methodC_4()",
+		"de.marcelsauer.sample.ClassD.methodD_5()",
+		"de.marcelsauer.sample.ClassE.methodE_6()",
+		"de.marcelsauer.sample.ClassF.methodF_7()",
+		"de.marcelsauer.sample.ClassG.methodG_8()",
+		"de.marcelsauer.sample.ClassH.methodH_9()",
+		"de.marcelsauer.sample.ClassI.methodI_10()",
+		"de.marcelsauer.sample.ClassJ.methodJ_11()"
+	],
+	"timestampMillis": "1528120883697"
 }
 ```
 
@@ -228,20 +238,30 @@ For more instrumentation details, increase log level:
 -Djct.loglevel=DEBUG
 ```
 
-## Hello World Walkthrough
+Hint: `DEBUG` is useful when you want to see what happens behind the scenes (for example class matching, instrumentation attempts, and skipped classes).
+
+## Sample Application Walkthrough
+
+Build the sample app jar to `doc/java-code-tracer-sample-application.jar`:
+
+```bash
+cd sample_application && mvn clean package && cd ..
+```
 
-Use the sample loop jar in `doc/helloworld-loop.jar`:
+Then run it with the agent from the repository root (`java-code-tracer`):
 
 ```bash
 java \
   -javaagent:"${PWD}/target/java-code-tracer-1.0-SNAPSHOT-jar-with-dependencies.jar" \
   -Djct.loglevel=INFO \
-  -Djct.config="${PWD}/doc/config-sample-helloworld-file.yaml" \
+  -Djct.config="${PWD}/doc/config-sample-application-file.yaml" \
   -Djct.logDir=/tmp/jct \
   -noverify \
-  -jar "${PWD}/doc/helloworld-loop.jar"
+  -jar "${PWD}/doc/java-code-tracer-sample-application.jar"
 ```
 
+> **Note on class patterns:** JCT emits a stack trace only when the *outermost* tracked frame returns. If you include a class whose method runs forever (like `main()` or an endless loop driver), no traces will ever be written. Use a pattern that targets the inner chain classes — see `doc/config-sample-application-file.yaml` for an example using `^de.marcelsauer.sample.Class.*`.
+
 Check agent logs:
 
 ```bash
@@ -253,7 +273,6 @@ cat /tmp/jct/jct_agent.log
 ### Stack Formatter (`tools/format_stack.py`)
 
 Pretty-prints a raw JCT `stack` array into an aligned, human-readable call sequence.
-Consecutive calls to the same class are grouped — package names are abbreviated.
 
 Requires Python 3.9+, no dependencies.
 
@@ -271,12 +290,19 @@ xclip -o | python3 tools/format_stack.py
 Example output:
 
 ```
-   #  package        class                  method
-  ──────────────────────────────────────────────────────
-   1  o.b.s.u.ldap   LdapConnectionFactory  .initialize(LdapConnectionConfigurationDTO)
-   2                                        .connect()
-   3  o.b.s.u.ldap   LdapConnectionConfigurationDTO  .getLdapServer1()
-  ...
+   #  package                class   method
+  ─────────────────────────────────────────────────────────────────────────
+   1  de.marcelsauer.sample  ClassA  .methodA_1()
+   2  de.marcelsauer.sample  ClassB  .methodB_2()
+   3                                 .methodB_3()
+   4  de.marcelsauer.sample  ClassC  .methodC_4()
+   5  de.marcelsauer.sample  ClassD  .methodD_5()
+   6  de.marcelsauer.sample  ClassE  .methodE_6()
+   7  de.marcelsauer.sample  ClassF  .methodF_7()
+   8  de.marcelsauer.sample  ClassG  .methodG_8()
+   9  de.marcelsauer.sample  ClassH  .methodH_9()
+  10  de.marcelsauer.sample  ClassI  .methodI_10()
+  11  de.marcelsauer.sample  ClassJ  .methodJ_11()
 ```
 
 ## ELK Integration Guide
@@ -286,6 +312,19 @@ For local Elasticsearch + Logstash + Kibana setup (Docker), UI access, data view
 - [README-ELK.md](README-ELK.md)
 - [README-analysis-ELK.md](README-ELK-analysys.md)
 
+## Sample Application Screenshots
+
+### Start with agent
+![Kibana Discover](doc/sample_app_start.png)
+### JCT logs after start
+![Kibana Discover](doc/sample_app_jct_log.png)
+### Captured stacks if AsyncFileWritingStackProcessor is configured
+![Kibana Discover](doc/sample_app_stacks.png)
+### Captured stacks in Kibana 'Discover' View if ELK stack is used 
+![Kibana Discover](doc/kibana_1.png)
+### Captured stacks in Kibana 'Visualization/Lens' View if ELK stack is used 
+![Kibana Visualization](doc/kibana_2.png)
+
 ## Similar Projects
 
 - [Datadog dd-trace-java](https://github.com/DataDog/dd-trace-java/)

doc/config-sample-helloworld-file.yaml doc/config-sample-application-file.yamldoc/config-sample-helloworld-file.yaml renamed to doc/config-sample-application-file.yaml

@@ -1,11 +1,14 @@
 # some comment
 classes:
     included:
-        - ^.*hell.*
-    excluded:
-        - .*HelloWorldLoop.*
+        - ^de.marcelsauer.sample.Class.*
+    excluded: []
 processor:
     fullQualifiedClass: de.marcelsauer.profiler.processor.file.AsyncFileWritingStackProcessor
     stackFolderName: /tmp/stacks/
+    # false = report every captured stack event
+    # true = report only new stacks in dedup time window (dedupResetIntervalMillis)
     enableStackDeduplication: false
+    # used in dedup mode (enableStackDeduplication: true)
     dedupResetIntervalMillis: 300000
+

doc/config-sample-helloworld-tcp.yaml doc/config-sample-application-tcp.yamldoc/config-sample-helloworld-tcp.yaml renamed to doc/config-sample-application-tcp.yaml

@@ -1,16 +1,16 @@
 # some comment
 classes:
     included:
-        - ^.*hell.*
-    excluded:
-        - .*HelloWorldLoop.*
+        - ^de.marcelsauer.sample.Class.*
+    excluded: []
 processor:
     fullQualifiedClass: de.marcelsauer.profiler.processor.tcp.AsyncTcpStackProcessor
     tcpHost: localhost
     tcpPort: 9999
     tcpConnectTimeoutMillis: 1000
     tcpReconnectDelayMillis: 1000
-    # true = report every captured stack event
+    # false = report every captured stack event
+    # true = report only new stacks in dedup time window (dedupResetIntervalMillis)
     enableStackDeduplication: false
     # used in dedup mode (enableStackDeduplication: true)
     dedupResetIntervalMillis: 300000

doc/config-sample-application-udp.yaml

@@ -0,0 +1,14 @@
+# some comment
+classes:
+    included:
+        - ^de.marcelsauer.sample.Class.*
+    excluded: []
+processor:
+    fullQualifiedClass: de.marcelsauer.profiler.processor.udp.AsyncUdpStackProcessor
+    udpHost: localhost
+    udpPort: 9999
+    # false = report every captured stack event
+    # true = report only new stacks in dedup time window (dedupResetIntervalMillis)
+    enableStackDeduplication: false
+    # used in dedup mode (enableStackDeduplication: true)
+    dedupResetIntervalMillis: 300000