Skip to content

Update some docs for 0.2 #879

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
eemcmullan wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update some docs for 0.2 #879

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 35 additions & 48 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,10 @@
# Configuring the Kai-IDE Plugin

## Running Kai RPC server

1. Users will land on the welcome page after installation as shown below. If the Welcome Page does not appear, proceed to the step 2.
![walkthrough](images/walkthrough-1.png)
If "Set up Konveyor" is not available in the list, click the More button for additional options.
![walkthrough](images/walkthrough-2.png)
2. If the welcome page does not appear, open the command palette by pressing Command + Shift + P. This will bring up a list of commands.
![walkthrough](images/walkthrough-3.png)
From the command palette, locate and select the "Set up Konveyor" option. This will guide you through the configuration process.
![walkthrough](images/walkthrough-4.png)
3. Configure Konveyor for your project.
- User has an option to override binaries and custom rules, however it comes with the default packaged binaries and custom rules.
![setup-konveyor](images/setup-konveyor.png)
- The Konveyor extension allows you to add custom rules to the analyzer. This is useful when you want to apply your own rules during analysis.
- Configuring analysis arguments is necessary to determine which rules apply to the project during analysis. Set up analysis arguments specific to your project by selecting the appropriate options and pressing "OK" or "Enter" to save the changes.
- To confirm your arguments, navigate to your project directory and open `/.vscode/settings.json`.
![setup-konveyor](images/setup-konveyor-2.png)
- Next, set up the Generative AI key for your project. This step will open the `provider-settings.yaml` file. By default, it is configured to use OpenAI. To change the model, update the anchor `&active` to the desired block. Modify this file with the required arguments, such as the model and API key, to complete the setup. Sample of the `provider-settings.yaml` can be found [here.](https://github.com/konveyor/editor-extensions/blob/main/vscode/resources/sample-provider-settings.yaml)
4. Once the configuration is done, click on start server button. Logs are collected at output channel named konveyor-analyzer.
![start-server](images/start-server.png)
For initial configuration, see the [configure analysis](./getting_started.md#configure-analysis) steps in the Getting Started guide.

## Advanced Configuration

To navigate to **Advanced Settings**, open:
**Settings** > **Settings...** > **Settings**
Access the Kai settings from `Extensions > Konveyor AI Extension for VS Code settings icon > Settings`.

This will bring you to the screen shown below.
![advancedConfig](images/advanced_config.png)
Expand All @@ -33,41 +13,48 @@ This will bring you to the screen shown below.

#### **Log Level**

Defines the logging level for server binaries. Logs can be found in your project directory under `/.vscode/konveyor-logs`. The verbosity of event logs can be increased or decreased using this option.

#### **Kai RPC Server Path**

Allows the user to specify a custom binary path. If not provided, the default binary will be used.
Defines the logging level for server binaries. Logs can be found in your project directory under `/.vscode/konveyor-logs`.
The verbosity of event logs can be increased or decreased using this option.

#### **Analyzer Path**

Allows the user to specify a custom analyzer binary path. If not provided, the default analyzer binary will be used.

### **Analysis Settings**
#### **Diff: Auto Accept on Save**

Allows users to automatically apply diff changes when saving files.

#### **Analysis: Analyze on Save**

Enables real-time analysis upon saving a file.
This is automatically enabled while using Agent Mode

#### **Genai: Agent Mode**

Use agentic flow for getting solutions using automatic analysis.
Read more about Agent Mode [here](./getting_started.md#agent-mode).

#### **Genai: Cache Dir**

Path to a directory containing cached responses

#### **Genai: Trace Dir**

Path to directory containing traces of LLM interactions

#### **Genai: Trace Enabled**

- **Use Default Rulesets**: Users can choose to **disable bundled rulesets** and customize them instead.
- **Custom Rules**: Allows users to define **custom rules** for more personalized analysis results.
- **Label Selector**: Defines source and target technologies to flag relevant incidents.
- **Analyze on Save**: Enables real-time analysis upon saving a file. Users can disable this feature if needed.
- **Analyzer Dependencies**: Kai can analyze dependency-related errors detected in LLM-generated responses.
- **Analyzer Known Libraries**: Allows Kai to analyze well-known open-source libraries.
- **Code Snippet Limit**: Sets the maximum number of code lines included in incident reports.
- **Context Lines**: Defines the number of context lines included in incident reports, which improves LLM accuracy.
- **Incident Limit**: Specifies the **maximum number of incidents** to be reported.
Enables tracing of communication with the model. If enabled, traces will be stored under `/.vscode/konveyor-logs/traces`.

### **Diff Editor Type**
#### **Genai: Demo Mode**

Allows users to change the **diff editor view** when resolving proposed solutions.
Enables Kai’s **demo mode**, which uses cached LLM responses for learning and testing functionality.
Click [here](./demo_mode.md) for more information on Demo Mode.

### **Kai Settings**
#### **Solution Server**

- **Get Solution Max Effort**: Defines the effort level for generating solutions. This can be adjusted depending on the type of incidents. Higher values **increase processing time**.
- **Get Solution Max LLM Queries**: Specifies the **maximum number of LLM queries** made per solution request.
- **Get Solution Max Priority**: Determines the **maximum priority level** of issues to be considered in a solution request.
- **Cache Directory**: Path to a directory containing **cached responses**.
- **Demo Mode**: Enables Kai’s **demo mode**, which uses cached LLM responses for learning and testing functionality.
- **Trace Enabled**: Enables tracing of communication with the model. If enabled, traces will be stored under `/.vscode/konveyor-logs/traces`.
Configuration for the solution server. Read more details [here](./getting_started.md#solution-server).

### **Logging Settings**
#### **Debug: Webview**

- **Trace Message Connection**: Enables tracing of JSON-RPC calls between the extension and the Kai server.
Debug logging for webview message handilng
69 changes: 31 additions & 38 deletions docs/custom_ruleset.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,71 +1,66 @@
# Custom Rules Integration

When you have written custom rules and would like to add them to your issues to be solved by Kai's reactive code plan you will need to take a few steps to make this work.
When you have written custom rules and would like to add them to your issues to be solved by Kai's reactive code plan.
You will need to take a few steps to make this work.

## Steps to Add Custom Rulesets

### Stop the Running Server

If the server is running you will need to stop it. To see if the server is running.
If the server is running you will need to stop it.
To see if the server is running, open the `Konveyor Analysis View`

![image](images/custom_rules/running_server.png)

You will need to click the `Stop` button here and see the server is not running.

![image](images/custom_rules/stopped_server.png)
You will need to click the `Stop` button here if the server is running.

Once the server is stopped, you can move on to the next step.

### Adding Custom Rulesets

To add your custom rulesets, you will need to have a directory, containing `ruleset.yaml` and the subsequent rule files. You can find good examples of that [here](https://github.com/konveyor/rulesets/tree/main/default/generated) as well as docs around [rules and rulesets](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md).
To add your custom rulesets, you will need to have a directory containing a `ruleset.yaml` file, and the subsequent rule files. You can find examples of that [here](https://github.com/konveyor/rulesets/tree/main/default/generated) as well as docs around [rules and rulesets](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md).

> [!IMPORTANT]
> For the next example of how to add, we will assume a ruleset at `/Users/user/rulesets/custom-ruleset` you will need to change this to point to your ruleset directory.

First you will need to open up the settings for the workspace. you can do this with `CMD + SHIFT + P` on mac and `CTRL + SHIFT + P` on Windows and Linux.

![image](images/open_settings.png)
> For the next example, we will assume a ruleset at `/Users/user/rulesets/custom-ruleset`. You will need to change this to point to your ruleset directory.

Next, search for the custom rules and find the `Konveyor > Analysis: Custom Rules` setting option.
First you will need to open up the `Profile Manager` in the `Get Ready to Analyze` view:

![image](images/custom_rules/search_custom_rules.png)

Then you can click `Add Item` and enter in your path, we will use the example path.
Then you can click `Select Custom Rules`, and select the custom rules in your path. We will use the example path.

![image](images/custom_rules/add_custom_ruleset.png)

Once you click `OK` the ruleset is added!

### Running Analysis

Now you will have to go back to the `Konveyor` view and start the server.
Now you can return to the `Konveyor Aanlysis View` page and start the server.

![image](images/custom_rules/running_server.png)

You can now click `Run Analysis` and your custom ruleset will be used.
Click `Run Analysis`, and your custom ruleset will be used.

> [!WARNING]
> You will need to make sure that the rules or rulesets have a target or source label that is selected. If the ruleset does not match a selected target or source, it will be filtered out and skipped.

## Creating Rules and Rulesets

### Creating Rules

To create your own rules, first, you need to know of a change that must happen to complete a migration. This could be because of a framework or library that you are using (either an internal one or external/open source one). For this section, I am going to create a rule and ruleset for an open source framework but the process should be similar for any custom rule.
### Determing rules

#### Finding A Rule
To create custom rules, you need to know of a change that must happen to complete a migration. This could be because of a framework or library that you are using (either an internal one or external/open source one).
For this section, I am going to create a rule and ruleset for an open source framework, but the process should be similar for any custom rule.

To find a place for a rule, we are going to look at the release notes of the Quarkus framework. If we see the [section](https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.18#kubernetes-client-fabric8) here. If we follow this to the migration guide for this dependency, we can see this [section](https://github.com/fabric8io/kubernetes-client/blob/main/doc/MIGRATION-v7.md#kubernetes-model-artifact-removed-).

> The Maven artifact io.fabric8:kubernetes-model has been removed from the project and is no longer published.
> This artifact was just an aggregator of some of the Kubernetes model artifacts and had no specific purpose. It is no longer published, the io.fabric8:kubernetes-client-api or io.fabric8:kubernetes-openshift-uberjar artifacts should be used instead.
> The Maven artifact `io.fabric8:kubernetes-model` has been removed from the project, and is no longer published.
> This artifact was an aggregator of some of the Kubernetes model artifacts, and had no specific purpose. `io.fabric8:kubernetes-client-api` or `io.fabric8:kubernetes-openshift-uberjar` artifacts should be used instead.

So for this, we will need to make sure that if the dependency `io.fabric8:kubernetes-model` is being used, that we alert the user, and tell them what they should be using instead.
We will need to make sure that if the dependency `io.fabric8:kubernetes-model` is being used, that we alert the user, and tell them what they should be using instead.

#### Creating a Rule
### Creating the custom rule

Now we need to look up the rules and what the java provider can do. The [rules](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md#rule-metadata) documentation states that we will need to set up the metadata first. In this case, we will use the below yaml for this.
Now we need to see how a rule is configured.

- The [rules](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md#rule-metadata) documentation states that we will need to set up the metadata first. In this case, we will use the below yaml for this.

```yaml
- ruleID: "fabric8-remove-kubernetes-model-00001"
Expand All @@ -75,7 +70,7 @@ Now we need to look up the rules and what the java provider can do. The [rules](
category: mandatory
```

Next, we will add a description. This description is going to be used by the front end to show the user what the issue entails, I think that the migration docs do a good job of describing this, so we can just use what they have.
- Next, we will add a description. This description will describe what issue entails. I think the migration docs do a good job of this, so we can use what is mentioned there:

```yaml
description: |
Expand All @@ -84,15 +79,14 @@ description: |
This artifact was just an aggregator of some of the Kubernetes model artifacts and had no specific purpose. It is no longer published, the io.fabric8:kubernetes-client-api or io.fabric8:kubernetes-openshift-uberjar artifacts should be used instead."
```

Next, we need to decide what `Action` to take. The [actions](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md#rule-actions) are very useful but it is worth noting that for Kai, the only action that will be used, is `message`.
- Next, we need to decide what [Action](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md#rule-actions) to take. It is worth noting that for Kai, the only action that will be used is `message`.
The message is used by the LLM to generate a fix for the issue.

> [!WARNING]
> If you use only the tag action, or if you don't set effort, then the rule's violations will not be used by Kai.

We need to note, that the message is used by the LLM to generate a fix for the issue. In this case, I still think the migration guide docs do a good job.

> [!NOTE]
> This process may require some iteration to determine the optimal message for generating the fix that you want for your issue and model.
> This process may require some iteration to determine the optimal message for generating the fix for your issue and model.

```yaml
message: |
Expand All @@ -101,19 +95,18 @@ We need to note, that the message is used by the LLM to generate a fix for the i
This artifact was just an aggregator of some of the Kubernetes model artifacts and had no specific purpose. It is no longer published, the io.fabric8:kubernetes-client-api or io.fabric8:kubernetes-openshift-uberjar artifacts should be used instead."
```

Now that we have all the information captured in our rule for using it in Kai, we need to add when this should be triggered. This is the `when` clause for a rule. We usually call these [conditions](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md#rule-conditions), you can do a lot of different things here based on providers. Today in Kai, we only have two providers, the `java` and `builtin` providers.

For this issue, we are looking at dependencies, and so we will choose to use the `java.dependency` [capability](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md#provider-condition).
- Now that we have all the information captured in our rule for using it in Kai, we need to add when this should be triggered. This is the `when` clause for a rule. We call these [conditions](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md#rule-conditions). Different providers will support different conditions. Today in Kai, we only have two providers, the `java` and `builtin` providers.
- For this issue, we are looking at dependencies, and so we will choose to use the `java.dependency` [capability](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md#provider-condition).

```yaml
when:
java.dependency:
name: io.fabric8.kubernetes-model
```

Now, we should save this file in a directory for this ruleset, and we will need to create a ruleset.yaml in the same directory.

Creating the [ruleset.yaml](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md#ruleset) is a special file that groups these rules together to help make their management easier. We will use this ruleset for this rule.
- Save this file in a directory for this ruleset, and create a `ruleset.yaml` in the same directory.
- The [ruleset.yaml](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md#ruleset) is a special file that groups these rules together to help make their management easier.
We will use this ruleset for this rule:

```yaml
name: quarkus-3-18
Expand All @@ -122,4 +115,4 @@ labels:
- "konveyor.io/target=quarkus"
```

This full rule should now be usable, you can see it [here](./custom-ruleset-example), with the ruleset.yaml that would be needed. To use this ruleset, now follow the [adding custom rules](#steps-to-add-custom-rulesets) section to use this ruleset!
This custom ruleset should now be usable for an analysis in Kai.
14 changes: 10 additions & 4 deletions docs/debug.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,16 @@
# Debug Kai And File Issues

Logs are divided into two separate files under your working directory at /.vscode/konveyor-logs:
## Helpful logs

- kai-analyzer-server.log: This file is useful for debugging issues related to running analysis. It provides details about the Java and Maven installation, the initialization of the Java connection, and the startup process of the analyzer server.
Under your working directory at `/.vscode/konveyor`:

- kai-rpc-server.log: This log is intended for debugging the RPC server and any communication with the AI system. It captures interactions involved in fixing incidents and retrieving results.
- `analysis_<>.json` is an analysis output file that gives details on the rules used during analysis.

Use `Ctrl + Shift + P` to open the command palette and search for: `Developer: Open Extension Logs Folder` with logs at `konveyor.konveyor/`

- `analyzer.log`: This file is useful for debugging issues related to running analysis. It provides details about the Java and Maven installation, the initialization of the Java connection, and the startup process of the analyzer server.

- `extension.log`: This log is intended for debugging the RPC server and solution server, and any communication with the AI system. It captures interactions involved in fixing incidents and retrieving results.

## File an Issue

Expand Down Expand Up @@ -45,4 +51,4 @@ Help us resolve your issue faster by providing detailed information. Please foll

- **No Incidents Found**: Check the `.vscode/settings.json` file in your working directory to ensure the targets are correctly recorded.

- **Failed to Run Initial Analysis**: Verify that the correct Java and Maven versions are set in the current environment. Detailed logs can be found in `kai-analyzer-server.log`.
- **Failed to Run Initial Analysis**: Verify that the correct Java and Maven versions are set in the current environment. Detailed logs can be found [above](#helpful-logs).
Loading
Loading