From bec460b1d504ec8bc50a06e00d5fadbc4c018174 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Thu, 8 Jan 2026 22:09:49 -0600 Subject: [PATCH 1/5] Operator: Live-tail log stream rewrite Signed-off-by: Lee Calcote --- content/en/kanvas/operator/_index.md | 6 +- content/en/kanvas/operator/log-streaming.md | 73 +++++++++++++++++++++ 2 files changed, 74 insertions(+), 5 deletions(-) create mode 100644 content/en/kanvas/operator/log-streaming.md diff --git a/content/en/kanvas/operator/_index.md b/content/en/kanvas/operator/_index.md index cc422d35b..44e84f577 100644 --- a/content/en/kanvas/operator/_index.md +++ b/content/en/kanvas/operator/_index.md @@ -24,11 +24,7 @@ Using the search bar, you can search for specific resources and select them. The Operator supports connecting to Kubernetes pods via the following methods. -### Understanding Log Streamer - - - -![log-stream-sequence-diagram](images/log-stream-sequence-diagram.svg) +- [Log Streaming](/kanvas/operator/log-streaming): Learn how to live-tail logs from your Kubernetes pods and containers directly within the visual topology. ### Understanding Interactive Terminal diff --git a/content/en/kanvas/operator/log-streaming.md b/content/en/kanvas/operator/log-streaming.md new file mode 100644 index 000000000..8080cf80d --- /dev/null +++ b/content/en/kanvas/operator/log-streaming.md @@ -0,0 +1,73 @@ +--- +title: Log Streaming in Kanvas +weight: 5 +description: > + Learn about Log Streaming in Operator mode +categories: [Operator] +--- + +# Log Streaming in Kanvas + +Efficient troubleshooting requires immediate visibility into your application's behavior. The **Log Streamer** in Kanvas allows you to live-tail logs from your Kubernetes pods and containers directly within the visual topology. Unlike static log files, this feature provides a real-time, multiplexed view of your infrastructure's activities, enabling you to debug interactions between services without leaving the Kanvas interface. + +## Overview + +Kanvas Log Streaming is part of the **Operator** mode (Visualizer). It establishes a persistent, low-latency connection to your cluster resources, allowing you to stream `stdout` and `stderr` logs from one or multiple pods simultaneously. + +### Key Features + +* **Real-time Tailing:** Watch logs generation instantly as events occur in your cluster. +* **Multi-Pod Streaming:** Stream logs from a single specific pod or multiplex logs from several pods at once to correlate events across different services. +* **Keyword Filtering:** Apply search filters to the log stream to isolate specific error codes, transaction IDs, or warning messages. +* **Playback Controls:** Interactive controls to **Play**, **Pause**, **Stop**, and **Clear** the stream, giving you control over the flow of information during high-volume events. + +## How to Access Log Streaming + +To utilize the Log Streamer, ensure you are in **Operator Mode** and have a connected Kubernetes cluster with MeshSync active. + +1. **Navigate to Visualizer:** Open Kanvas and toggle to **Operator** mode (Visualizer) to view your running cluster topology. +2. **Select a Resource:** Click on a **Pod** or **Deployment** node within your design. +3. **Open the Log Stream:** + * **Via Context Menu:** Right-click the node and select **Stream Logs** from the context menu. + * **Via Details Panel:** With the node selected, expand the bottom panel or the **Details** drawer. Locate the **Log Stream** tab next to the Terminal and Performance tabs. + +## Using the Interface + +Once the stream is active, the Log Streamer panel will display the output. + +* **Search/Filter:** Use the search bar within the panel to highlight or filter lines containing specific strings (e.g., `Error`, `Exception`, or specific request IDs). +* **Toggle State:** Use the toggle switches to pause the live feed to inspect a specific log line without losing your place, then resume to catch up with the live tail. +* **Copy Logs:** Use the copy function to capture the current log buffer to your clipboard for external analysis or ticket submission. + +## Use Cases and Examples + +### 1. Troubleshooting CrashLoopBackOff + +**Scenario:** A newly deployed pod is failing to start, entering a `CrashLoopBackOff` state. +**Action:** Select the failing pod in Kanvas. The Log Streamer immediately captures the container's startup output. +**Benefit:** You can instantly see the specific runtime error or missing environment variable causing the crash without manually running `kubectl logs -f` commands in a separate terminal window. + +### 2. Correlating Microservice Interactions + +**Scenario:** A frontend service is returning a 500 error, but the issue likely originates in a backend dependency. +**Action:** Multi-select both the Frontend Pod and the Backend Pod in the visualizer and activate log streaming. +**Benefit:** Kanvas multiplexes the streams. You can watch the request leave the frontend and fail at the backend in a single view, allowing you to pinpoint exactly where the transaction breaks. + +### 3. Monitoring Real-time Traffic Patterns + +**Scenario:** You have applied a new canary rollout pattern and want to verify traffic distribution. +**Action:** Stream logs from the new version of your deployment while filtering for specific traffic headers or successful HTTP 200 codes. +**Benefit:** Visually verify that the application logic is processing requests as expected during the deployment window. + +## Technical Note + +The Log Streamer utilizes a robust architecture where the **Meshery Operator** signals the **MeshSync** controller to start the log flow. Data is streamed using **NATS** to the Meshery Broker, preprocessed, and then delivered to your browser via a **WebSocket** connection using GraphQL subscriptions. This ensures minimal latency and high performance, even when streaming data from multiple active containers. + +![log-stream-sequence-diagram](images/log-stream-sequence-diagram.svg) + +*** + +### See Also + +* **[Interactive Terminal](/kanvas/terminal):** Learn how to establish an interactive shell session with your containers. +* **[Performance Management](/kanvas/performance):** Run ad-hoc performance tests alongside your log monitoring. From d17c23ec90c28e137955205b3fee9743a292f8a4 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Thu, 8 Jan 2026 22:14:31 -0600 Subject: [PATCH 2/5] chore: rewrite interactive terminal in Operator Signed-off-by: Lee Calcote --- .../kanvas/operator/interactive-terminal.md | 73 +++++++++++++++++++ content/en/kanvas/operator/log-streaming.md | 5 +- 2 files changed, 74 insertions(+), 4 deletions(-) create mode 100644 content/en/kanvas/operator/interactive-terminal.md diff --git a/content/en/kanvas/operator/interactive-terminal.md b/content/en/kanvas/operator/interactive-terminal.md new file mode 100644 index 000000000..081733697 --- /dev/null +++ b/content/en/kanvas/operator/interactive-terminal.md @@ -0,0 +1,73 @@ +--- +title: Interactive Terminal +description: > + Learn about Interactive Terminal in Operator mode +categories: [Operator] +--- + +When operating cloud native infrastructure, deep diagnostics often require direct access to the container shell. The **Interactive Terminal** in Kanvas enables you to execute commands and inspect the filesystem of your running containers directly from the visual topology. By integrating terminal sessions into the Kanvas interface, you can troubleshoot issues, verify configurations, and test network connectivity without switching context to external CLI tools like `kubectl`. + +## Overview + +The Kanvas Interactive Terminal allows operators to establish a secure, low-latency shell session with one or more pods simultaneously. This feature is essential for "last mile" debugging where metrics and logs alone are insufficient. + +### Key Features + +* **Direct Shell Access:** Instantly `exec` into any running container within your Kubernetes cluster to run standard shell commands (e.g., `ls`, `curl`, `top`). +* **Multi-Session Support:** Open concurrent terminal sessions for different pods to compare environments or run simultaneous tests. +* **Integrated Workflow:** Debug specific nodes while maintaining visibility of the surrounding infrastructure topology. +* **Session Management:** Configure preferences such as "Auto-close Terminal Sessions" to manage resources efficiently. + +## How to Access the Terminal + +To use the Interactive Terminal, ensure you are in **Operator Mode** (Visualizer) and have a connected Kubernetes cluster. + +1. **Navigate to Visualizer:** Open Kanvas and switch to **Operator** mode to view your active cluster resources. +2. **Select a Workload:** Click on a **Pod** or **Deployment** node within your design. +3. **Launch the Session:** + * Expand the **Details** panel (bottom drawer). + * Select the **Terminal** tab (located alongside *Performance* and *Log Stream*). + * If the pod contains multiple containers, select the specific container you wish to access. + * Click **Connect** to initialize the session. + +## Use Cases and Examples + +### 1. Verifying Network Connectivity + +**Scenario:** A backend service is failing to connect to a database, but the service status appears green. +**Action:** Open a terminal in the backend pod and use `curl` or `nc` (netcat) to attempt a connection to the database endpoint. +**Benefit:** Confirms whether the issue is a network policy blocking traffic, a DNS resolution failure, or an application-layer configuration error, all while visualizing the connection in Kanvas. + +### 2. Inspecting Configuration Files + +**Scenario:** An application is behaving unexpectedly, and you suspect the mounted ConfigMap data is incorrect. +**Action:** Use the terminal to `cat` the configuration files located in the file system (e.g., `/etc/config/app.conf`). +**Benefit:** Verifies exactly what the application sees at runtime, ensuring that the latest ConfigMap updates have actually propagated to the pod. + +### 3. Real-Time Resource Monitoring + +**Scenario:** A specific pod is triggering high-memory alerts, but you need to know which process is the culprit. +**Action:** Exec into the container and run `top` or `ps aux`. +**Benefit:** Provides granular visibility into process-level resource consumption that aggregate metrics might miss. + +### 4. Environment Variable Validation + +**Scenario:** A deployment fails to authenticate with an external API. +**Action:** Run the `env` command within the container's terminal. +**Benefit:** Allows you to instantly verify if secret keys and API endpoints were injected correctly as environment variables during startup. + +## Technical Architecture + +The Interactive Terminal is built on an event-driven architecture designed for security and responsiveness: + +1. **Session Initiation:** When a user initiates a session, the Meshery Server receives the request via the GraphQL API. +2. **Orchestration:** The request is brokered to the **Meshery Operator**, which signals the **MeshSync** controller running inside the cluster to start the interactive session. +3. **Data Transport:** Input and output data are streamed via **NATS** through the Meshery Broker. Shell output is preprocessed and transcribed before being delivered to the UI. +4. **Session Isolation:** Each terminal session is mapped to a unique topic ID within the subscription, ensuring that data streams for multiple open terminals do not overlap. + +*** + +### See Also + +* **[Log Streaming](/kanvas/operator/log-streaming):** Learn how to live-tail logs for real-time application monitoring. + diff --git a/content/en/kanvas/operator/log-streaming.md b/content/en/kanvas/operator/log-streaming.md index 8080cf80d..d6b1d6517 100644 --- a/content/en/kanvas/operator/log-streaming.md +++ b/content/en/kanvas/operator/log-streaming.md @@ -1,13 +1,10 @@ --- -title: Log Streaming in Kanvas -weight: 5 +title: Log Streaming description: > Learn about Log Streaming in Operator mode categories: [Operator] --- -# Log Streaming in Kanvas - Efficient troubleshooting requires immediate visibility into your application's behavior. The **Log Streamer** in Kanvas allows you to live-tail logs from your Kubernetes pods and containers directly within the visual topology. Unlike static log files, this feature provides a real-time, multiplexed view of your infrastructure's activities, enabling you to debug interactions between services without leaving the Kanvas interface. ## Overview From 122fb7f75a231dd92d9ff068eb5eeed01a291318 Mon Sep 17 00:00:00 2001 From: hortison <160366376+hortison@users.noreply.github.com> Date: Thu, 8 Jan 2026 22:31:54 -0600 Subject: [PATCH 3/5] chore: update tools list and enhance interactive terminal documentation Signed-off-by: hortison <160366376+hortison@users.noreply.github.com> --- .github/agents/documentation.agent.md | 3 +-- content/en/kanvas/operator/_index.md | 13 +------------ content/en/kanvas/operator/interactive-terminal.md | 12 ++++++++++-- 3 files changed, 12 insertions(+), 16 deletions(-) diff --git a/.github/agents/documentation.agent.md b/.github/agents/documentation.agent.md index b1fa0e750..b560c3ee2 100644 --- a/.github/agents/documentation.agent.md +++ b/.github/agents/documentation.agent.md @@ -1,7 +1,6 @@ --- name: "Diátaxis Documentation Expert" -agent: 'agent' -tools: ['edit/editFiles', 'search', 'fetch'] +tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'vscode/extensions', 'web/fetch', 'web/githubRepo', 'vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/runCommand', 'vscode/openSimpleBrowser', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'execute/createAndRunTask', 'execute', 'execute/runTask', 'execute/runTests', 'search', 'search/searchResults', 'read/terminalLastCommand', 'read/terminalSelection', 'execute/testFailure', 'search/usages', 'vscode/vscodeAPI', 'github/*'] description: 'Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.' --- diff --git a/content/en/kanvas/operator/_index.md b/content/en/kanvas/operator/_index.md index 44e84f577..4bb2a4ecb 100644 --- a/content/en/kanvas/operator/_index.md +++ b/content/en/kanvas/operator/_index.md @@ -25,15 +25,4 @@ Using the search bar, you can search for specific resources and select them. The Operator supports connecting to Kubernetes pods via the following methods. - [Log Streaming](/kanvas/operator/log-streaming): Learn how to live-tail logs from your Kubernetes pods and containers directly within the visual topology. - -### Understanding Interactive Terminal - -The interactive terminal behaves in a fashion similar to similar to the behavior of the `kubectl exec` command, but web-based. - -{{< alert type="note" title="Distinct Capabilities" >}} Note that each component offers its own capabilities, and that these capabilities differ between Designer mode and Operator mode. For example, in operator mode, if you right-click (and hold) on a Kubernetes pod, you will see actions unique to the Pod component, which are to open either an interactive terminal to one or all of the containers in the pod or to start streaming logs from any/all of the containers in the pod. {{< /alert >}} - -While using using the interactive terminal, understand that you can only open one session per container. Each session's data is streamed via Meshery Broker (NATS) from MeshSync to Meshery Server / Kanvas. The GraphQL subscription between your web browser running Kanvas and Meshery Server provides isolation between other users who might be concurrently sharing an interactive terminal. Each connection established a unique session ID. - - - -![interactive-terminal-sequence-diagram](images/interactive-terminal-sequence-diagram.svg) +- [Interactive Terminal](/kanvas/operator/interactive-terminal): Learn how to establish an interactive shell session with your containers. diff --git a/content/en/kanvas/operator/interactive-terminal.md b/content/en/kanvas/operator/interactive-terminal.md index 081733697..609b6050d 100644 --- a/content/en/kanvas/operator/interactive-terminal.md +++ b/content/en/kanvas/operator/interactive-terminal.md @@ -9,7 +9,7 @@ When operating cloud native infrastructure, deep diagnostics often require direc ## Overview -The Kanvas Interactive Terminal allows operators to establish a secure, low-latency shell session with one or more pods simultaneously. This feature is essential for "last mile" debugging where metrics and logs alone are insufficient. +The Kanvas Interactive Terminal allows operators to establish a secure, low-latency shell session with one or more pods simultaneously. This feature is essential for "last mile" debugging where metrics and logs alone are insufficient. The interactive terminal behaves in a fashion similar to the behavior of the `kubectl exec` command, but web-based. ### Key Features @@ -20,7 +20,7 @@ The Kanvas Interactive Terminal allows operators to establish a secure, low-late ## How to Access the Terminal -To use the Interactive Terminal, ensure you are in **Operator Mode** (Visualizer) and have a connected Kubernetes cluster. +To use the Interactive Terminal, ensure you are in **Operator Mode** and have a connected Kubernetes cluster. 1. **Navigate to Visualizer:** Open Kanvas and switch to **Operator** mode to view your active cluster resources. 2. **Select a Workload:** Click on a **Pod** or **Deployment** node within your design. @@ -65,6 +65,14 @@ The Interactive Terminal is built on an event-driven architecture designed for s 3. **Data Transport:** Input and output data are streamed via **NATS** through the Meshery Broker. Shell output is preprocessed and transcribed before being delivered to the UI. 4. **Session Isolation:** Each terminal session is mapped to a unique topic ID within the subscription, ensuring that data streams for multiple open terminals do not overlap. +{{< alert type="note" title="Distinct Capabilities" >}} Note that each component offers its own capabilities, and that these capabilities differ between Designer mode and Operator mode. For example, in operator mode, if you right-click (and hold) on a Kubernetes pod, you will see actions unique to the Pod component, which are to open either an interactive terminal to one or all of the containers in the pod or to start streaming logs from any/all of the containers in the pod. {{< /alert >}} + +While using the interactive terminal, understand that you can only open one session per container. Each session's data is streamed via Meshery Broker (NATS) from MeshSync to Meshery Server / Kanvas. The GraphQL subscription between your web browser running Kanvas and Meshery Server provides isolation between other users who might be concurrently sharing an interactive terminal. Each connection establishes a unique session ID. + + + +![interactive-terminal-sequence-diagram](images/interactive-terminal-sequence-diagram.svg) + *** ### See Also From 33ccac6c2a9a3c9aeb455c354508abe1e22e2cb4 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Thu, 8 Jan 2026 22:34:17 -0600 Subject: [PATCH 4/5] Update content/en/kanvas/operator/log-streaming.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Lee Calcote --- content/en/kanvas/operator/log-streaming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/kanvas/operator/log-streaming.md b/content/en/kanvas/operator/log-streaming.md index d6b1d6517..920cd3d7b 100644 --- a/content/en/kanvas/operator/log-streaming.md +++ b/content/en/kanvas/operator/log-streaming.md @@ -33,7 +33,7 @@ To utilize the Log Streamer, ensure you are in **Operator Mode** and have a conn Once the stream is active, the Log Streamer panel will display the output. * **Search/Filter:** Use the search bar within the panel to highlight or filter lines containing specific strings (e.g., `Error`, `Exception`, or specific request IDs). -* **Toggle State:** Use the toggle switches to pause the live feed to inspect a specific log line without losing your place, then resume to catch up with the live tail. +* **Pause/Resume:** Use the playback toggle to pause the live feed to inspect a specific log line without losing your place, then resume to catch up with the live tail. * **Copy Logs:** Use the copy function to capture the current log buffer to your clipboard for external analysis or ticket submission. ## Use Cases and Examples From 60ffaed6917d613291f1d1f2ea54054f14ed5310 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Thu, 8 Jan 2026 22:34:23 -0600 Subject: [PATCH 5/5] Update content/en/kanvas/operator/log-streaming.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Lee Calcote --- content/en/kanvas/operator/log-streaming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/kanvas/operator/log-streaming.md b/content/en/kanvas/operator/log-streaming.md index 920cd3d7b..aad55237f 100644 --- a/content/en/kanvas/operator/log-streaming.md +++ b/content/en/kanvas/operator/log-streaming.md @@ -13,7 +13,7 @@ Kanvas Log Streaming is part of the **Operator** mode (Visualizer). It establish ### Key Features -* **Real-time Tailing:** Watch logs generation instantly as events occur in your cluster. +* **Real-time Tailing:** Watch log generation instantly as events occur in your cluster. * **Multi-Pod Streaming:** Stream logs from a single specific pod or multiplex logs from several pods at once to correlate events across different services. * **Keyword Filtering:** Apply search filters to the log stream to isolate specific error codes, transaction IDs, or warning messages. * **Playback Controls:** Interactive controls to **Play**, **Pause**, **Stop**, and **Clear** the stream, giving you control over the flow of information during high-volume events.