-
Notifications
You must be signed in to change notification settings - Fork 67
/
healthz.proto
208 lines (172 loc) · 6.65 KB
/
healthz.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
//
// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// Generic Network Operation Interface, GNOI, defines a set of RPC's used for
// the operational aspects of network targets. These services are meant to be
// used in conjunction with GNMI for all target state and operational aspects
// of a network target. The gnoi.system.Service is the only mandatory vendor
// implementation.
syntax = "proto3";
package gnoi.healthz;
import "google/protobuf/any.proto";
import "google/protobuf/timestamp.proto";
import "types/types.proto";
option go_package = "github.com/openconfig/gnoi/healthz";
option (types.gnoi_version) = "1.3.0";
// The Healthz service provides access to the status of a path on the
// system. Addtitionally it allows the implementor to provide path specific
// diagnositic data into the status return.
//
// Healthz is expected to work in conjunction with the component OC model.
service Healthz {
// Get will get the latest health status for a gNMI path. If no status is
// available for the requested path an error will be returned.
rpc Get(GetRequest) returns (GetResponse) {}
// List returns all events for the provided component path.
rpc List(ListRequest) returns (ListResponse) {}
// Acknowledge will set the acknowledged field for the event.
// This is an idempotent operation.
rpc Acknowledge(AcknowledgeRequest) returns (AcknowledgeResponse) {}
// Artifact will stream the artifact contents for the provided artifact id.
rpc Artifact(ArtifactRequest) returns (stream ArtifactResponse) {}
// Check will invoke the healthz on the provided component path. This RPC
// can be expensive depending on the vendor implementation.
rpc Check(CheckRequest) returns (CheckResponse) {}
}
message GetRequest {
// Path defines the component to try to fetch healthz state for. Get
// retrieves the latest healthz results for a specific component
// that have been collected as a result of a call to Check, or by
// the target itself.
types.Path path = 1;
}
message GetResponse {
ComponentStatus component = 1;
}
enum Status {
STATUS_UNSPECIFIED = 0; // The path doesn't support healthz
STATUS_HEALTHY = 1; // The path is healthy
STATUS_UNHEALTHY = 2; // The path is unhealthy
}
message ArtifactHeader {
// ID of the artifact.
string id = 1;
// Artifact type describes data contents in the artifact.
// File artifacts should use the defined FileArtifactType.
// Proto artifacts should either use the generic ProtoArtifactType
// which means the artifact is made up a sequence of proto.Any
// messages which can be deserialized directly into thier message
// types. Otherwise the implementer can provide a specific artifact type
// which can add any additional metadata the implementor wants and define
// a custom format for the message stream.
oneof artifact_type {
FileArtifactType file = 101;
ProtoArtifactType proto = 102;
google.protobuf.Any custom = 103;
}
}
message ComponentStatus {
gnoi.types.Path path = 1; // path of subcomponent.
// Subcomponents that are aggregated by this status.
repeated ComponentStatus subcomponents = 2;
// Status of this component.
Status status = 3;
// Opaque data for how the healthcheck is implemented. This can be any proto
// defined by the vendor. This could be the equivalent to outputs like
// "show tech" or core files or any other diagnostic data.
google.protobuf.Any healthz = 4 [deprecated=true];
// Artifacts provides links to all artifacts contained in this event.
// The individual artifacts can be retrieved via the Artifact() RPC.
repeated ArtifactHeader artifacts = 5;
// ID is the unique key for this event in the system.
string id = 6;
// Acknowledged is set when at least one caller has processed the event.
bool acknowledged = 7;
// Created is the timestamp when this event was created.
google.protobuf.Timestamp created = 8;
// Expires is the timestamp when the system will clean up the
// artifact. If unset, the artifact is not scheduled for garbage
// collection.
google.protobuf.Timestamp expires = 9;
}
message ListRequest {
types.Path path = 1;
// By default only the unacknowledged events for the component will be
// returned.
bool include_acknowledged = 2;
}
message ListResponse {
repeated ComponentStatus statuses = 1;
}
message AcknowledgeRequest {
types.Path path = 1;
// Healthz event id.
string id = 2;
}
message AcknowledgeResponse {
ComponentStatus status = 1;
}
message ArtifactRequest {
// Artifact ID to be streamed.
string id = 1;
}
message ArtifactResponse {
oneof contents {
// Header is the first message in the stream. It contains
// the id of the artifact and metadata for the artifact
// based on the type of the artifact.
// OC defines FileArtifactType and ProtoArtifactType.
ArtifactHeader header = 1;
ArtifactTrailer trailer = 2;
bytes bytes = 3;
google.protobuf.Any proto = 4;
}
}
message FileArtifactType {
// Local file name of the artifact.
string name = 1;
// Path to file on the local file system. (optional)
string path = 2;
// Mimetype of the file.
string mimetype = 3;
// Size of the file.
int64 size = 4;
// Hash of the file.
gnoi.types.HashType hash = 5;
}
// Generic proto message artifact stream.
// This proto tells the caller that the artifact stream
// will be a stream of proto encoded messages that make up
// the artifact. Each message must be deserialized by the caller
// and there are no other assumptions about the number of
// messages or length of the stream or how those messages are to
// be reassembled.
message ProtoArtifactType {
}
// ArtifactTrailer is the last message in the artifact stream.
message ArtifactTrailer {
}
message CheckRequest {
gnoi.types.Path path = 1;
// When event_id is populated the check request refers to an
// event that has already been reported by the system. The
// device receiving the CheckRequest should populate artifacts
// that are relevant to the event that were not automatically
// collected. Previous artifacts MUST NOT be overwritten.
string event_id = 2;
}
message CheckResponse{
ComponentStatus status = 1;
}