Merge pull request #7 from kyasbal/add-run-cloud-shell-button

Prepare README and user guide
GoogleCloudPlatform · Jan 28, 2025 · 8796ab0 · 8796ab0
2 parents d6008b1 + 42bbae5
commit 8796ab0
Show file tree

Hide file tree

Showing 15 changed files with 113 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -1,11 +1,11 @@
 # Kubernetes History Inspector
 
+![Header](./image/header.png)
+
 Kubernetes History Inspector (KHI) is a rich visualization tool for Kubernetes clusters on Google Cloud (e.g GKE, GKE on AWS/Azure, GDCV, etc).
 KHI transforms vast quantities of logs into an interactive, comprehensive timeline view.
 This makes it an invaluable tool for troubleshooting complex issues that span multiple components within your Kubernetes clusters.
 
-![Demo Image](https://github.com/GoogleCloudPlatform/khi/blob/main/image/demo.gif)
-
 ## KHI features and characteristics
 
 - **No Prior Setup Required:** KHI uses your existing Cloud Logging logs, so you don't need to install anything extra. This makes setup easier and saves you time. Furthermore, you can use KHI to troubleshoot even past issues as long as logs are still available in Cloud Logging.
@@ -35,12 +35,35 @@ This makes it an invaluable tool for troubleshooting complex issues that span mu
 - [GDCV for Baremetal](https://cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/concepts/about-bare-metal)
 - GDCV for VMWare
 
-## Get Started
+## Get Started (Run with Cloud Shell)
+
+1. Open [Cloud Shell](https://shell.cloud.google.com)
+1. Run `docker run -p 8080:8080 ghcr.io/googlecloudplatform/khi:latest`
+1. Click the link `http://localhost:8080` on the terminal and start working with KHI!
+
+> [!TIP]
+> If you want to run KHI with the other environment where the metadata server is not available,
+> you can pass the access token via the program argument.
+>
+>```
+>$ docker run -p 8080:8080 ghcr.io/googlecloudplatform/khi:latest -host 0.0.0.0 -access-token=`gcloud auth print-access-token`
+>```
+
+## Get Started (Run from source)
+
+<details>
+<summary>Get Started (Run from source)</summary>
 
 ### Prerequisites
 - Go 1.21.*
 - Node.js environment 18.19.*
 - [`gcloud` CLI](https://cloud.google.com/sdk/docs/install)
+- Latest Google Chrome
+
+
+> [!IMPORTANT]
+> We only test KHI with the latest Google Chrome. 
+> KHI may work with the other browser, but we will not support even if it won't work with the other browser.
 
 ### Initialization (one-time setup)
 1. Download or clone this repository   
@@ -55,9 +78,11 @@ This makes it an invaluable tool for troubleshooting complex issues that span mu
 1. Run `make build-web && KHI_FRONTEND_ASSET_FOLDER=./dist go run cmd/kubernetes-history-inspector/main.go` from the project root   
   Open `localhost:8080` and start working with KHI! 
 
-## Examples
+</details>
+
+## User Guide
 
-// TODO (b/391498707): add examples usage with screenshots
+Please check our [User Guide](./docs/user-guide.md).
 
 ## Contribute
 

diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -0,0 +1,83 @@
+# User guide
+
+> [!NOTE]
+> This document explains how to use KHI after running it. If you haven't run KHI, please check [README](../README.md).
+
+## Query logs with KHI
+
+Once you run KHI and open the page served by it, you will see the welcome page.
+You can query your logs with clicking the `New inspection` button, or you can open KHI file.
+After completing querying your logs with the later instruction, you would see the inspection list on right side.
+
+![User guide: start screen](../image/guide-start-screen.png)
+
+To query your cluster logs, you would need to fill few information with 3 steps.
+
+1. Select the cluster type
+1. Select log types to query
+1. Fill parameters needed for composing log filter
+
+![User guide: query logs](../image/guide-query.png)
+
+After clicking the `Run` button on the query dialog, you will see progress bars on the start screen.
+Once the query done, you can open the visualization result with hitting the `Open` button.
+
+## Understanding the visualization
+
+After opening the log, you will see a colorful visualization. 
+This is the main view of KHI, and you can see the timeline diagram on the left side, which reveals the macroscopic behavior of resources in your cluster.
+The right side is dedicated to details of each resource. You can see detailed information by selecting a resource in the timeline.
+
+![User guide timeline screens](../image/guide-timeline-screen.png)
+
+### Timeline view
+
+Timelines in the diagram are displayed in hierarchical order (Kind > Namespace > Resource name > Subresource).
+To scale the timeline diagram in or out, hold the Shift key and scroll your mouse. KHI will scale the view around the time point at your mouse pointer location.
+
+![User guide timeline diagram](../image/guide-timeline-diagram.png)
+
+The colorful belts on the timelines are called `revisions`. Each revision represents a state that continues from its left edge (start time) to its right edge (end time).
+You can see the meaning of each color by hovering your mouse pointer over the revision.
+
+KHI also shows several supplemental timelines as pseudo-subresource timelines. These pseudo-subresources are not actual subresources in Kubernetes, but KHI associates these complementary timelines with resources for better visualization. The color meanings of these pseudo-subresources may vary depending on their relationship with their parent resource.
+This relationship is indicated by a colorful chip next to the subresource name on the left side.
+
+![User guide timeline revisions](../image/guide-timelines-revisions.png)
+
+Diamond shapes on the timelines are called `events` in KHI (note that these are not Kubernetes events). These indicate that a log was associated with the resource at that specific time.
+The colors of the events indicate their severity and log type. Hover your mouse pointer over an event to see its details.
+
+![User guide timeline events](../image/guide-timelines-events.png)
+
+Clicking on a timeline's name or any element within it will select that timeline. The log view and history view on the right side of the timeline diagram will then display data corresponding to the selected timeline.
+
+![User guide timeline selection](../image/guide-timeline-selection.png)
+
+### Log view
+
+The log view automatically shows only the logs related to the selected timeline.
+
+![User guide log-view](../image/guide-log-view.png)
+
+### History view
+
+The history view shows the modification history of the selected timeline.
+
+![User guide history-view](../image/guide-history-view.png)
+
+### Filtering features
+
+You can filter timelines by Kind, Namespace, and Resource name using the input fields at the top left of the timeline diagram.
+This allows you to quickly narrow down the displayed timelines to only those relevant to your current investigation.
+
+You can also filter logs using a regular expression in the input field at the top right. This will also filter out timelines that do not have any logs matching the regex.
+
+![User guide filtering](../image/guide-filtering.png)
+
+### Topology view (alpha)
+
+The Topology view provides a visual representation of the relationships between different Kubernetes resources.
+This can be helpful for understanding the resource topology at a specific point in time within a log.
+
+![User guide topology-view](../image/guide-topology-view.png)
diff --git a/image/demo.gif b/image/demo.gif
diff --git a/image/guide-filtering.png b/image/guide-filtering.png
diff --git a/image/guide-history-view.png b/image/guide-history-view.png
diff --git a/image/guide-log-view.png b/image/guide-log-view.png
diff --git a/image/guide-query.png b/image/guide-query.png
diff --git a/image/guide-start-screen.png b/image/guide-start-screen.png
diff --git a/image/guide-timeline-diagram.png b/image/guide-timeline-diagram.png
diff --git a/image/guide-timeline-screen.png b/image/guide-timeline-screen.png
diff --git a/image/guide-timeline-selection.png b/image/guide-timeline-selection.png
diff --git a/image/guide-timelines-events.png b/image/guide-timelines-events.png
diff --git a/image/guide-timelines-revisions.png b/image/guide-timelines-revisions.png
diff --git a/image/guide-topology-view.png b/image/guide-topology-view.png
diff --git a/image/header.png b/image/header.png