Skip to content

Commit 0204582

Browse files
author
Helen Koike
committed
DO NOT MERGE - wip: add automatching v0
See kcidb-automatching/README.md Signed-off-by: Helen Koike <[email protected]>
1 parent 97e5723 commit 0204582

File tree

2 files changed

+629
-0
lines changed

2 files changed

+629
-0
lines changed

‎kcidb-automatching/README.md

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
2+
# KCIDB Match Tool
3+
4+
## Overview
5+
6+
The KCIDB Match Tool is designed to manage and validate match patterns objects for issues in a KCIDB (Kernel CI Database) schema and generate incidents from kcidb_io objects when they match stored patterns.
7+
This tool is intended to be integrated with KCIDB to automatically create incidents based on existing issues with defined match patterns.
8+
This tool can add pattern objects from issues to an SQLite database and validate input objects against these pattern objects. The tool also provides functionalities to add, update, delete pattern objects, and generate incidents.
9+
10+
## Schema Explanation
11+
12+
### Pattern Object
13+
14+
The pattern object is extracted from a field called `pattern_object` under the `misc` field of an issue object.
15+
The pattern object follows the KCIDB-IO schema but without the required fields. This means the pattern object can have incomplete data as long as the data matches the structure of the KCIDB-IO schema.
16+
17+
The `--update-patterns` flag processes all issues, while running `./kcidb_match.py` without parameters assumes a maximum of 3 elements (one for checkout, one for build, and one for test) with parental conditions. If there are more elements in each list, only the first will be considered.
18+
19+
### SQLite Table
20+
21+
The SQLite table used to store pattern objects has the following structure:
22+
23+
```sql
24+
CREATE TABLE IF NOT EXISTS patterns (
25+
issue_id TEXT UNIQUE,
26+
issue_version INTEGER,
27+
pattern_object JSON
28+
);
29+
```
30+
31+
- `issue_id`: The unique identifier for the issue.
32+
- `issue_version`: The version of the issue.
33+
- `pattern_object`: The pattern object of the issue in JSON format.
34+
35+
36+
## Usage
37+
38+
### Adding Patterns
39+
40+
To add pattern objects to the database, use the `--update-patterns` flag. The input should be a JSON file with issues.
41+
42+
#### Example `issues.json`
43+
44+
```json
45+
{
46+
"version": {
47+
"major": 4,
48+
"minor": 3
49+
},
50+
"issues": [
51+
{
52+
"id": "kernelci_api:70d17807303641a9d6d2a8aeb1aee829221cefcf",
53+
"version": 0,
54+
"origin": "kernelci_api",
55+
"report_url": "https://linux-regtracking.leemhuis.info/regzbot/regression/lore/[email protected]/",
56+
"report_subject": "RIP: 0010:usercopy_abort+0x74/0x76 kernel panic",
57+
"culprit": {
58+
"code": true,
59+
"tool": false,
60+
"harness": false
61+
},
62+
"comment": "",
63+
"misc": {
64+
"author": {
65+
"name": "Laura Nao",
66+
"email": "[email protected]"
67+
},
68+
"pattern_object": {
69+
"checkouts": [
70+
{
71+
"tree_name": "next"
72+
}
73+
],
74+
"builds": [
75+
{
76+
"compiler": "gcc.*"
77+
}
78+
]
79+
}
80+
}
81+
}
82+
]
83+
}
84+
```
85+
86+
#### Adding Patterns Command
87+
88+
```sh
89+
cat issues.json | ./kcidb_match.py --update-patterns
90+
```
91+
92+
#### Removing Patterns
93+
94+
To delete a pattern entry from the database, submit the issue without the `pattern_object` under `misc`.
95+
96+
### Checking Matches
97+
98+
To check an input object against the stored patterns objects, simply run the script without any flags. The input should be a JSON file following the KCIDB schema with a node and its parent nodes.
99+
100+
#### Example `sample_single.json`
101+
102+
```json
103+
{
104+
"checkouts": [
105+
{
106+
"id": "ci-system:unique-checkout-id",
107+
"origin": "ci-system",
108+
"tree_name": "next"
109+
}
110+
],
111+
"builds": [
112+
{
113+
"checkout_id": "ci-system:unique-checkout-id",
114+
"id": "ci-system:unique-build-id",
115+
"origin": "ci-system",
116+
"compiler": "gcc-10"
117+
}
118+
]
119+
}
120+
```
121+
122+
#### Checking Matches Command
123+
124+
```sh
125+
cat sample_single.json | ./kcidb_match.py
126+
```
127+
128+
Output:
129+
130+
```sh
131+
Matched issue ID: kernelci_api:70d17807303641a9d6d2a8aeb1aee829221cefcf Version: 0
132+
```
133+
134+
### Generating Incidents
135+
136+
To generate incidents when a match is found, use the `--generate-incidents` flag. This will create an object following KCIDB schema with incidents objects.
137+
138+
#### Generating Incidents Command
139+
140+
```sh
141+
cat sample_single.json | ./kcidb_match.py --generate-incidents
142+
```
143+
144+
### Query Examples
145+
146+
#### Update Patterns Example
147+
148+
```sh
149+
kcidb-query -i "kernelci_api:70d17807303641a9d6d2a8aeb1aee829221cefcf" -d "postgresql:host=127.0.0.1 port=5432 sslmode=disable dbname=playground_kcidb [email protected]" | ./kcidb-match.py --update-patterns
150+
```
151+
152+
#### Checking Matches Example
153+
154+
```sh
155+
kcidb-query -t "maestro:6690dbfc7488a1b744200e82" -d "postgresql:host=127.0.0.1 port=5432 sslmode=disable dbname=playground_kcidb [email protected]" --parents | ./kcidb-match.py
156+
```
157+
158+
Output:
159+
160+
```sh
161+
Matched issue ID: kernelci_api:70d17807303641a9d6d2a8aeb1aee829221cefcf Version: 0
162+
```
163+
164+
### Generating Incidents with --ignore-db
165+
166+
The --ignore-db argument can be used to generate incidents based solely on the issues field in the KCIDB-IO object provided via stdin, ignoring the database. This is useful when you want to test patterns before saving them to the database.
167+
168+
169+
#### Example `sample_single_with_issue.json`
170+
171+
```json
172+
{
173+
"checkouts": [
174+
{
175+
"id": "ci-system:unique-checkout-id",
176+
"origin": "ci-system",
177+
"tree_name": "next"
178+
}
179+
],
180+
"builds": [
181+
{
182+
"checkout_id": "ci-system:unique-checkout-id",
183+
"id": "ci-system:unique-build-id",
184+
"origin": "ci-system",
185+
"compiler": "gcc-10"
186+
}
187+
],
188+
"issues": [
189+
{
190+
"misc": {
191+
"pattern_object": {
192+
"checkouts": [
193+
{
194+
"tree_name": "next"
195+
}
196+
],
197+
"builds": [
198+
{
199+
"compiler": "gcc.*"
200+
}
201+
]
202+
}
203+
}
204+
}
205+
}
206+
```
207+
208+
Example command:
209+
210+
```sh
211+
cat sample_single_with_issue | ./kcidb_match.py --ignore-db --generate-incidents
212+
```
213+
### Check Test ID or Build ID
214+
215+
The --check_test_id and --check_build_id arguments allow you to check a specific test or build ID against the provided issues in stdin, implying --ignore-db. It fetches those nodes from KCIDB using kcidb-query. These options require a database connection string provided with -d.
216+
217+
Example commands:
218+
219+
```sh
220+
cat issue.json | ./kcidb-match.py --check_test_id "maestro:6690dbfc7488a1b744200e82" -d "postgresql:host=127.0.0.1 port=5432 sslmode=disable dbname=playground_kcidb [email protected]"
221+
```
222+
223+
```sh
224+
cat issue.json | ./kcidb-match.py --check_test_id "maestro:6690dbfc7488a1b744200e82" -d "postgresql:host=127.0.0.1 port=5432 sslmode=disable dbname=playground_kcidb [email protected]"
225+
```
226+
227+
These commands fetch the KCIDB-IO object corresponding to the provided test or build ID, check it against the issues provided via stdin, and generate incidents accordingly.

0 commit comments

Comments
 (0)