docs

Author: niesfisch

README-ELK.md

@@ -12,6 +12,7 @@ For stack analysis patterns (KQL, Dev Tools queries, trends, top classes/methods
 
 ## Table of Contents
 
+- [Architecture](#architecture)
 - [What You Get](#what-you-get)
 - [1) Start the ELK Stack](#1-start-the-elk-stack)
 - [2) Open Kibana UI](#2-open-kibana-ui)
@@ -23,6 +24,43 @@ For stack analysis patterns (KQL, Dev Tools queries, trends, top classes/methods
 - [Troubleshooting](#troubleshooting)
 - [Stop the Stack](#stop-the-stack)
 
+## Architecture
+
+```
+  Your JVM  (instrumented app)
+  ┌─────────────────────────────────────────────────────────────┐
+  │                                                             │
+  │  ┌──────────────────────┐     ┌───────────────────────┐     │
+  │  │      JCT Agent       │     │       Recorder        │     │
+  │  │  -javaagent:jct.jar  │────▶│  records call stacks  │     │
+  │  └──────────────────────┘     └─────────────┬─────────┘     │
+  │                                             │               │
+  │                          ┌──────────────────▼────────────┐  │
+  │                          │        Stack Processor        │  │
+  │                          │  AsyncUdpStackProcessor  or   │  │
+  │                          │  AsyncTcpStackProcessor       │  │
+  │                          └──────────────────┬────────────┘  │
+  └─────────────────────────────────────────────┼───────────────┘
+                                                │
+                                    UDP / TCP   ▼   port 9999
+                       ┌────────────────────────────────────────┐
+                       │           Docker Compose               │
+                       ├────────────────────────────────────────┤
+                       │                                        │
+                       │  ┌──────────────┐  ┌───────────────┐   │
+                       │  │   Logstash   │─▶│Elasticsearch  │   │
+                       │  │  UDP + TCP   │  │ jct-events-*  │   │
+                       │  │    :9999     │  │    :9200      │   │
+                       │  └──────────────┘  └───────┬───────┘   │
+                       │                            │           │
+                       │               ┌────────────▼────────┐  │
+                       │               │       Kibana        │  │
+                       │               │  Discover / Lens /  │  │
+                       │               │  Dev Tools  :5601   │  │
+                       │               └─────────────────────┘  │
+                       └────────────────────────────────────────┘
+```
+
 ## What You Get
 
 - Elasticsearch on `http://localhost:9200`

README.md

@@ -31,7 +31,18 @@ It helps answer one practical question in large systems: "Is this code path stil
 
 For local experimentation, the recommended setup is:
 
-- JCT -> UDP -> Logstash -> Elasticsearch -> Kibana
+```
+  -javaagent:jct.jar          Docker Compose
+  ┌─────────────────┐     ┌───────────────────────────────────┐
+  │   JCT Agent     │     │  Logstash :9999                   │
+  │   Recorder      │────▶│    │                              │
+  │   Stack         │     │    ▼                              │
+  │   Processor     │     │  Elasticsearch  (jct-events-*)    │
+  │  UDP / TCP      │     │    │                              │
+  └─────────────────┘     │    ▼                              │
+                          │  Kibana :5601                     │
+                          └───────────────────────────────────┘
+```
 
 This gives you a fast feedback loop with searchable traces and a UI for exploration.