Skip to content

Commit 0764fc7

Browse files
BamiehBamieh
authored
[7.x] [telemetry] add schema guideline + schema_check new check for --path config (#75747) (#77358)
1 parent 62ee38a commit 0764fc7

File tree

2 files changed

+237
-1
lines changed

2 files changed

+237
-1
lines changed

‎packages/kbn-telemetry-tools/GUIDELINE.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# Collector Schema Guideline
2+
3+
Table of contents:
4+
- [Collector Schema Guideline](#collector-schema-guideline)
5+
- [Adding schema to your collector](#adding-schema-to-your-collector)
6+
- [1. Update the telemetryrc file](#1-update-the-telemetryrc-file)
7+
- [2. Type the `fetch` function](#2-type-the-fetch-function)
8+
- [3. Add a `schema` field](#3-add-a-schema-field)
9+
- [4. Run the telemetry check](#4-run-the-telemetry-check)
10+
- [5. Update the stored json files](#5-update-the-stored-json-files)
11+
- [Updating the collector schema](#updating-the-collector-schema)
12+
- [Writing the schema](#writing-the-schema)
13+
- [Basics](#basics)
14+
- [Allowed types](#allowed-types)
15+
- [Dealing with arrays](#dealing-with-arrays)
16+
- [Schema Restrictions](#schema-restrictions)
17+
- [Root of schema can only be an object](#root-of-schema-can-only-be-an-object)
18+
19+
20+
## Adding schema to your collector
21+
22+
To add a `schema` to the collector, follow these steps until the telemetry check passes.
23+
To check the next step needed simply run the telemetry check with the path of your collector:
24+
25+
```
26+
node scripts/telemetry_check.js --path=<relative_path_to_collector>.ts
27+
```
28+
29+
### 1. Update the telemetryrc file
30+
31+
Make sure your collector is not excluded in the `telemetryrc.json` files (located at the root of the kibana project, and another on in the `x-pack` dir).
32+
33+
```s
34+
[
35+
{
36+
...
37+
"exclude": [
38+
"<path_to_my_collector>"
39+
]
40+
}
41+
]
42+
```
43+
44+
Note that the check will fail if the collector in --path is excluded.
45+
46+
### 2. Type the `fetch` function
47+
1. Make sure the return of the `fetch` function is typed.
48+
49+
The function `makeUsageCollector` accepts a generic type parameter of the returned type of the `fetch` function.
50+
51+
```
52+
interface Usage {
53+
someStat: number;
54+
}
55+
56+
usageCollection.makeUsageCollector<Usage>({
57+
fetch: async () => {
58+
return {
59+
someStat: 3,
60+
}
61+
},
62+
...
63+
})
64+
```
65+
66+
The generic type passed to `makeUsageCollector` will automatically unwrap the `Promise` to check for the resolved type.
67+
68+
### 3. Add a `schema` field
69+
70+
Add a `schema` field to your collector. After passing the return type of the fetch function to the `makeUsageCollector` generic parameter. It will automaticallly figure out the correct type of the schema based on that provided type.
71+
72+
73+
```
74+
interface Usage {
75+
someStat: number;
76+
}
77+
78+
usageCollection.makeUsageCollector<Usage>({
79+
schema: {
80+
someStat: {
81+
type: 'long'
82+
}
83+
},
84+
...
85+
})
86+
```
87+
88+
For full details on writing the `schema` object, check the [Writing the schema](#writing-the-schema) section.
89+
90+
### 4. Run the telemetry check
91+
92+
To make sure your changes pass the telemetry check you can run the following:
93+
94+
```
95+
node scripts/telemetry_check.js --ignore-stored-json --path=<relative_path_to_collector>.ts
96+
```
97+
98+
### 5. Update the stored json files
99+
100+
The `--fix` flag will automatically update the persisted json files used by the telemetry team.
101+
102+
```
103+
node scripts/telemetry_check.js --fix
104+
```
105+
106+
Note that any updates to the stored json files will require a review by the kibana-telemetry team to help us update the telemetry cluster mappings and ensure your changes adhere to our best practices.
107+
108+
109+
## Updating the collector schema
110+
111+
Simply update the fetch function to start returning the updated fields back to our cluster. The update the schema to accomodate these changes.
112+
113+
Once youre run the changes to both the `fetch` function and the `schema` field run the following command
114+
115+
```
116+
node scripts/telemetry_check.js --fix
117+
```
118+
119+
The `--fix` flag will automatically update the persisted json files used by the telemetry team. Note that any updates to the stored json files will require a review by the kibana-telemetry team to help us update the telemetry cluster mappings and ensure your changes adhere to our best practices.
120+
121+
122+
## Writing the schema
123+
124+
We've designed the schema object to closely resemble elasticsearch mapping object to reduce any cognitive complexity.
125+
126+
### Basics
127+
128+
The function `makeUsageCollector` will automatically translate the returned `Usage` fetch type to the `schema` object. This way you'll have the typescript type checker helping you write the correct corrisponding schema.
129+
130+
```
131+
interface Usage {
132+
someStat: number;
133+
}
134+
135+
usageCollection.makeUsageCollector<Usage>({
136+
schema: {
137+
someStat: {
138+
type: 'long'
139+
}
140+
},
141+
...
142+
})
143+
```
144+
145+
146+
### Allowed types
147+
148+
Any field property in the schema accepts a `type` field. By default the type is `object` which accepts nested properties under it. Currently we accept the following property types:
149+
150+
```
151+
AllowedSchemaTypes =
152+
| 'keyword'
153+
| 'text'
154+
| 'number'
155+
| 'boolean'
156+
| 'long'
157+
| 'date'
158+
| 'float';
159+
```
160+
161+
162+
### Dealing with arrays
163+
164+
You can optionally define a property to be an array by setting the `isArray` to `true`. Note that the `isArray` property is not currently required.
165+
166+
167+
```
168+
interface Usage {
169+
arrayOfStrings: string[];
170+
arrayOfObjects: {key: string; value: number; }[];
171+
}
172+
173+
usageCollection.makeUsageCollector<Usage>({
174+
fetch: () => {
175+
return {
176+
arrayOfStrings: ['item_one', 'item_two'],
177+
arrayOfObjects: [
178+
{ key: 'key_one', value: 13 },
179+
]
180+
}
181+
}
182+
schema: {
183+
arrayOfStrings: {
184+
type: 'keyword',
185+
isArray: true,
186+
},
187+
arrayOfObjects: {
188+
isArray: true,
189+
key: {
190+
type: 'keyword',
191+
},
192+
value: {
193+
type: 'long',
194+
},
195+
}
196+
},
197+
...
198+
})
199+
```
200+
201+
Be careful adding arrays of objects due to the limitation in correlating the properties inside those objects inside kibana. It is advised to look for an alternative schema based on your use cases.
202+
203+
204+
## Schema Restrictions
205+
206+
We have enforced some restrictions to the schema object to adhere to our telemetry best practices. These practices are derived from the usablity of the sent data in our telemetry cluster.
207+
208+
209+
### Root of schema can only be an object
210+
211+
The root of the schema can only be an object. Currently any property must be nested inside the main schema object.

‎packages/kbn-telemetry-tools/src/cli/run_telemetry_check.ts‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ import {
3535

3636
export function runTelemetryCheck() {
3737
run(
38-
async ({ flags: { fix = false, path }, log }) => {
38+
async ({ flags: { fix = false, 'ignore-stored-json': ignoreStoredJson, path }, log }) => {
3939
if (typeof fix !== 'boolean') {
4040
throw createFailError(`${chalk.white.bgRed(' TELEMETRY ERROR ')} --fix can't have a value`);
4141
}
@@ -50,6 +50,14 @@ export function runTelemetryCheck() {
5050
);
5151
}
5252

53+
if (fix && typeof ignoreStoredJson !== 'undefined') {
54+
throw createFailError(
55+
`${chalk.white.bgRed(
56+
' TELEMETRY ERROR '
57+
)} --fix is incompatible with --ignore-stored-json flag.`
58+
);
59+
}
60+
5361
const list = new Listr([
5462
{
5563
title: 'Checking .telemetryrc.json files',
@@ -59,11 +67,28 @@ export function runTelemetryCheck() {
5967
title: 'Extracting Collectors',
6068
task: (context) => new Listr(extractCollectorsTask(context, path), { exitOnError: true }),
6169
},
70+
{
71+
enabled: () => typeof path !== 'undefined',
72+
title: 'Checking collectors in --path are not excluded',
73+
task: ({ roots }: TaskContext) => {
74+
const totalCollections = roots.reduce((acc, root) => {
75+
return acc + (root.parsedCollections?.length || 0);
76+
}, 0);
77+
const collectorsInPath = Array.isArray(path) ? path.length : 1;
78+
79+
if (totalCollections !== collectorsInPath) {
80+
throw new Error(
81+
'Collector specified in `path` is excluded; Check the telemetryrc.json files.'
82+
);
83+
}
84+
},
85+
},
6286
{
6387
title: 'Checking Compatible collector.schema with collector.fetch type',
6488
task: (context) => new Listr(checkCompatibleTypesTask(context), { exitOnError: true }),
6589
},
6690
{
91+
enabled: (_) => !!ignoreStoredJson,
6792
title: 'Checking Matching collector.schema against stored json files',
6893
task: (context) =>
6994
new Listr(checkMatchingSchemasTask(context, !fix), { exitOnError: true }),

0 commit comments

Comments
 (0)