Skip to content

Commit 7d92e89

Browse files
vlopeziglesiasnr-cmorenoin
vlopeziglesias
and
nr-cmorenoin
authored
Add validation and documentation for compositeName in entity synthesis (#2337)
* Add validation and documentation for compositeName in entity synthesis * Add validation and documentation for compositeName in entity synthesis --------- Co-authored-by: nr-cmorenoin <[email protected]>
1 parent 1ad094b commit 7d92e89

File tree

2 files changed

+125
-30
lines changed

2 files changed

+125
-30
lines changed

‎docs/entities/synthesis.md‎

Lines changed: 50 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Synthesis is the process of creating entities from telemetry. Given some rules,
55
Synthesis rules should be defined in the `definition.yaml` file, under a `synthesis.rules` section.
66

77
A rule should define an `identifier` that will be a unique value for that domainType in one user account.
8-
It should also provide the attribute that defines the `name` of the entity.
8+
It should also provide the attribute that defines the `name` (or alternatively a `compositeName`) of the entity.
99

1010
These two attributes **must be always present** on the telemetry in order to create an entity.
1111

@@ -23,15 +23,56 @@ synthesis:
2323
disabled: true
2424
```
2525
26-
| **Name** | **Type** | **Required** | **Description** |
27-
| -------- | -------- | ------------ | ---------------- |
28-
| name | String | Yes | The attribute to use for the entity name. |
29-
| identifier| String| Yes | Telemetry attribute to use as the entity identifier.|
30-
| compositeIdentifier| String| No | Set of attributes that will identify the telemetry. When this one is used identifier is not required.|
31-
| encodeIdentifierInGUID | Boolean | No | If true, the identifier value will be hashed to respect the [GUID limits][guid_spec]. Defaults to `false`. |
32-
| conditions | List | No | The list of conditions to apply in the data point to match the rule. Defaults to an empty list. |
33-
| tags | List | No | The list of attributes to copy as entity tags if the rule matches. Defaults to an empty list. |
26+
| **Name** | **Type** | **Required** | **Description** |
27+
| -------- | -------- | ------------ |-------------------------------------------------------------------------------------------------------------------------------|
28+
| name | String | Yes | The attribute to use for the entity name. |
29+
| compositeName | Object | No | Set of attributes and literals that will be concatenated to form the entity name. When this one is used name is not required. |
30+
| identifier| String| Yes | Telemetry attribute to use as the entity identifier. |
31+
| compositeIdentifier| String| No | Set of attributes that will identify the telemetry. When this one is used identifier is not required. |
32+
| encodeIdentifierInGUID | Boolean | No | If true, the identifier value will be hashed to respect the [GUID limits][guid_spec]. Defaults to `false`. |
33+
| conditions | List | No | The list of conditions to apply in the data point to match the rule. Defaults to an empty list. |
34+
| tags | List | No | The list of attributes to copy as entity tags if the rule matches. Defaults to an empty list. |
35+
36+
### Name
37+
38+
The attribute from the telemetry to be used as the name of the entity. Either this or `compositeName` must be defined.
39+
The name does not need to be unique, different entities with the same entityType in the same account can have the same name, as long as their identifiers are different, they will be different entities.
40+
41+
#### Composite name
42+
43+
In some cases the name of the entity is not defined by a single attribute, but rather a combination of multiple attributes and literals.
44+
In these cases, `compositeName` can be used to define how these attributes and literals are combined to form the name.
45+
46+
The `compositeName` is formed from `fragments`, which is a non-empty list of objects, containing only one of the following properties:
47+
- `attribute`, which represents an attribute name that must be always present in the telemetry. The value of the given attribute in the telemetry data point will be added to the name.
48+
- `value`, that is a literal value to be concatenated to the name. It has to be delimited by double quotes.
49+
50+
The `attribute`s and `value`s will be concatenated in the order they are defined in the list to conform the final entity name.
51+
52+
```yaml
53+
synthesis:
54+
rules:
55+
- identifier: hostname
56+
compositeName:
57+
fragments:
58+
- value: "ks-broker: "
59+
- attribute: kafka.broker.name
60+
- value: " ("
61+
- attribute: kafka.cluster.name
62+
- value: ")"
63+
# Other rule properties...
64+
```
65+
66+
If we take as an example the following data point, and apply the above synthesis rule:
67+
68+
```json
69+
{
70+
"kafka.broker.name": "broker-1",
71+
"kafka.cluster.name": "my-cluster"
72+
}
73+
```
3474

75+
The `name` of the entity will be synthesized as: `ks-broker: broker-1 (my-cluster)`
3576

3677
### Identifier
3778

‎validator/schemas/entity-schema-v1.json‎

Lines changed: 75 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -60,18 +60,23 @@
6060
"identifier": "12345"
6161
}],
6262
"oneOf": [{
63-
"required": [
64-
"name",
65-
"identifier",
66-
"conditions"
67-
]
68-
},
69-
{
70-
"required": [
71-
"name",
72-
"compositeIdentifier",
73-
"conditions"
74-
]
63+
"allOf": [
64+
{
65+
"oneOf": [
66+
{ "required": ["name"] },
67+
{ "required": ["compositeName"] }
68+
]
69+
},
70+
{
71+
"oneOf": [
72+
{ "required": ["identifier"] },
73+
{ "required": ["compositeIdentifier"] }
74+
]
75+
},
76+
{
77+
"required": ["conditions"]
78+
}
79+
]
7580
},
7681
{
7782
"required": [
@@ -94,19 +99,21 @@
9499
"items": {
95100
"$id": "#/synthesis/rules/items",
96101
"type": "object",
97-
"oneOf": [{
98-
"required": [
99-
"name",
100-
"identifier",
101-
"conditions"
102+
"allOf": [
103+
{
104+
"oneOf": [
105+
{ "required": ["name"] },
106+
{ "required": ["compositeName"] }
102107
]
103108
},
104109
{
105-
"required": [
106-
"name",
107-
"compositeIdentifier",
108-
"conditions"
110+
"oneOf": [
111+
{ "required": ["identifier"] },
112+
{ "required": ["compositeIdentifier"] }
109113
]
114+
},
115+
{
116+
"required": ["conditions"]
110117
}
111118
],
112119
"properties": {
@@ -119,6 +126,50 @@
119126
"EntityName"
120127
]
121128
},
129+
"compositeName": {
130+
"$id": "#/synthesis/rules/items/compositeName",
131+
"type": "object",
132+
"title": "The composite entity name",
133+
"description": "Information used to synthesize the entity name using a combination of attributes and literals",
134+
"required": [ "fragments" ],
135+
"properties": {
136+
"fragments": {
137+
"$id": "#/synthesis/rules/items/compositeName/fragments",
138+
"type": "array",
139+
"title": "list of attributes and literals used to build the name",
140+
"description": "The list of attributes and literals to conform the name",
141+
"minItems": 1,
142+
"items": {
143+
"type": "object",
144+
"oneOf": [
145+
{
146+
"required": [ "attribute" ],
147+
"properties": {
148+
"attribute": {
149+
"type": "string",
150+
"title": "The attribute to use as part of the name",
151+
"examples": [ "kafka.cluster.name", "host", "pod_name" ]
152+
}
153+
},
154+
"additionalProperties": false
155+
},
156+
{
157+
"required": [ "value" ],
158+
"properties": {
159+
"value": {
160+
"type": "string",
161+
"title": "The literal string to use as part of the name",
162+
"minLength": 1,
163+
"examples": [ "-" , "_" , ":", " (", ")" ]
164+
}
165+
},
166+
"additionalProperties": false
167+
}
168+
]
169+
}
170+
}
171+
}
172+
},
122173
"identifier": {
123174
"$id": "#/synthesis/rules/items/identifier",
124175
"type": "string",
@@ -328,6 +379,9 @@
328379
"name": {
329380
"$ref": "#/synthesis/rules/items/name"
330381
},
382+
"compositeName": {
383+
"$ref": "#/synthesis/rules/items/compositeName"
384+
},
331385
"identifier": {
332386
"$ref": "#/synthesis/rules/items/identifier"
333387
},

0 commit comments

Comments
 (0)