Skip to content

Commit 4cfcb2f

Browse files
author
Clayton Pence
committed
Add proto for analysis messages
1 parent 3197d4d commit 4cfcb2f

File tree

2 files changed

+275
-0
lines changed

2 files changed

+275
-0
lines changed

‎analysis/v1alpha1/message.proto

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
// Copyright 2019 Istio Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
17+
// $title: Analysis Messages
18+
// $description: Describes the structure of messages generated by Istio analyzers.
19+
// $location: https://istio.io/docs/reference/config/istio.analysis.v1alpha1.html
20+
// $weight: 20
21+
22+
// Describes the structure of messages generated by Istio analyzers.
23+
package istio.analysis.v1alpha1;
24+
25+
import "google/protobuf/struct.proto";
26+
27+
option go_package="istio.io/api/analysis/v1alpha1";
28+
29+
// There are four messages described in this file. One of them is a struct
30+
// common to the other three: AnalysisMessageBase. Using this, we can construct
31+
// one of three different structures.
32+
// One is the AnalysisMessageWeakSchema, a YAML only description of a message
33+
// type intended to be used where strong API guarantees are not necessary.
34+
// One is the GenericAnalysisMessage, which is the struct that we guarantee that
35+
// you can deserialize any analysis message to. Istio internally uses generated
36+
// golang types from messages.yaml, so in order to reduce friction in creating
37+
// new analyzers we offer a path that doesn't require committing to two
38+
// different repos and solidifying the interface.
39+
// Finally, we can create a new proto message of a specific message type and
40+
// commit it to istio/api when we need a strong guarantee for cross platform
41+
// communication.
42+
43+
// AnalysisMessageBase describes some common information that is needed for all
44+
// messages. All information should be static with respect to the error code.
45+
message AnalysisMessageBase {
46+
// A human-readable name for the message type. e.g. "InternalError",
47+
// "PodMissingProxy". This should be the same for all messages of the same type.
48+
// Required.
49+
string name = 1;
50+
51+
// A 7 character code matching `^IST[0-9]{4}$` intended to uniquely identify
52+
// the message type. (e.g. "IST0001" is mapped to the "InternalError" message
53+
// type.) 0000-0100 are reserved. Required.
54+
string code = 2;
55+
56+
// The values here are chosen so that more severe messages get sorted higher,
57+
// as well as leaving space in between to add more later
58+
enum Level {
59+
UNKNOWN = 0; // invalid, but included for proto compatibility for 0 values
60+
ERROR = 3;
61+
WARNING = 8;
62+
INFO = 12;
63+
}
64+
65+
// Represents how severe a message is. Required.
66+
Level level = 3;
67+
68+
// A url pointing to the Istio documentation for this specific error type.
69+
// Should be of the form
70+
// `^http(s)?://(preliminary\.)?istio.io/docs/reference/config/analysis/`
71+
// Required.
72+
string documentation_url = 4;
73+
74+
}
75+
76+
// AnalysisMessageWeakSchema is the set of information that's needed to define a
77+
// weakly-typed schema. The purpose of this proto is to provide a mechanism for
78+
// validating istio/istio/galley/pkg/config/analysis/msg/messages.yaml to make
79+
// sure that we don't allow committing underspecified types.
80+
message AnalysisMessageWeakSchema {
81+
// Required
82+
AnalysisMessageBase message_base = 1;
83+
84+
// A human readable description of what the error means. Required.
85+
string description = 2;
86+
87+
// A go-style template string defining how to combine the args for a
88+
// particular message into a log line. Required.
89+
string template = 3;
90+
91+
message ArgType {
92+
// Required
93+
string name = 1;
94+
// Required. Should be a golang type, used in code generation
95+
string go_type = 2;
96+
}
97+
98+
// A description of the arguments for a particular message type
99+
repeated ArgType args = 4;
100+
}
101+
102+
// GenericAnalysisMessage is an instance of an AnalysisMessage defined by a
103+
// schema, whose metaschema is AnalysisMessageWeakSchema. (Names are hard.) Code
104+
// should be able to perform validation of arguments as needed by using the
105+
// message type information to look at the AnalysisMessageWeakSchema and examine the
106+
// list of args at runtime. Developers can also create stronger-typed versions
107+
// of GenericAnalysisMessage for well-known and stable message types.
108+
message GenericAnalysisMessage {
109+
// Required
110+
AnalysisMessageBase message_base = 1;
111+
112+
// Any message-type specific arguments that need to get codified. Optional.
113+
google.protobuf.Struct args = 2;
114+
115+
// A list of strings specifying the path for resources which were the cause of
116+
// message generation. At least one is required.
117+
repeated string resource_paths = 3;
118+
}
119+
120+
// InternalErrorAnalysisMessage is a strongly-typed message representing some
121+
// error in Istio code that prevented us from performing analysis at all.
122+
message InternalErrorAnalysisMessage {
123+
// Required
124+
AnalysisMessageBase message_base = 1;
125+
126+
// Any detail regarding specifics of the error. Should be human-readable.
127+
string detail = 2;
128+
}

‎proto.lock

+147
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,152 @@
11
{
22
"definitions": [
3+
{
4+
"protopath": "analysis:/:v1alpha1:/:message.proto",
5+
"def": {
6+
"enums": [
7+
{
8+
"name": "AnalysisMessageBase.Level",
9+
"enum_fields": [
10+
{
11+
"name": "UNKNOWN"
12+
},
13+
{
14+
"name": "ERROR",
15+
"integer": 3
16+
},
17+
{
18+
"name": "WARNING",
19+
"integer": 8
20+
},
21+
{
22+
"name": "INFO",
23+
"integer": 12
24+
}
25+
]
26+
}
27+
],
28+
"messages": [
29+
{
30+
"name": "AnalysisMessageBase",
31+
"fields": [
32+
{
33+
"id": 1,
34+
"name": "name",
35+
"type": "string"
36+
},
37+
{
38+
"id": 2,
39+
"name": "code",
40+
"type": "string"
41+
},
42+
{
43+
"id": 3,
44+
"name": "level",
45+
"type": "Level"
46+
},
47+
{
48+
"id": 4,
49+
"name": "documentation_url",
50+
"type": "string"
51+
}
52+
]
53+
},
54+
{
55+
"name": "AnalysisMessageWeakSchema",
56+
"fields": [
57+
{
58+
"id": 1,
59+
"name": "message_base",
60+
"type": "AnalysisMessageBase"
61+
},
62+
{
63+
"id": 2,
64+
"name": "description",
65+
"type": "string"
66+
},
67+
{
68+
"id": 3,
69+
"name": "template",
70+
"type": "string"
71+
},
72+
{
73+
"id": 4,
74+
"name": "args",
75+
"type": "ArgType",
76+
"is_repeated": true
77+
}
78+
],
79+
"messages": [
80+
{
81+
"name": "ArgType",
82+
"fields": [
83+
{
84+
"id": 1,
85+
"name": "name",
86+
"type": "string"
87+
},
88+
{
89+
"id": 2,
90+
"name": "go_type",
91+
"type": "string"
92+
}
93+
]
94+
}
95+
]
96+
},
97+
{
98+
"name": "GenericAnalysisMessage",
99+
"fields": [
100+
{
101+
"id": 1,
102+
"name": "message_base",
103+
"type": "AnalysisMessageBase"
104+
},
105+
{
106+
"id": 2,
107+
"name": "args",
108+
"type": "google.protobuf.Struct"
109+
},
110+
{
111+
"id": 3,
112+
"name": "resource_paths",
113+
"type": "string",
114+
"is_repeated": true
115+
}
116+
]
117+
},
118+
{
119+
"name": "InternalErrorAnalysisMessage",
120+
"fields": [
121+
{
122+
"id": 1,
123+
"name": "message_base",
124+
"type": "AnalysisMessageBase"
125+
},
126+
{
127+
"id": 2,
128+
"name": "detail",
129+
"type": "string"
130+
}
131+
]
132+
}
133+
],
134+
"imports": [
135+
{
136+
"path": "google/protobuf/struct.proto"
137+
}
138+
],
139+
"package": {
140+
"name": "istio.analysis.v1alpha1"
141+
},
142+
"options": [
143+
{
144+
"name": "go_package",
145+
"value": "istio.io/api/analysis/v1alpha1"
146+
}
147+
]
148+
}
149+
},
3150
{
4151
"protopath": "authentication:/:v1alpha1:/:policy.proto",
5152
"def": {

0 commit comments

Comments
 (0)