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
|
// Copyright 2017 Google Inc.
//
// 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.
syntax = "proto3";
package google.devtools.clouddebugger.v2;
import "google/api/annotations.proto";
import "google/devtools/clouddebugger/v2/data.proto";
import "google/protobuf/empty.proto";
option go_package = "google.golang.org/genproto/googleapis/devtools/clouddebugger/v2;clouddebugger";
option java_multiple_files = true;
option java_outer_classname = "ControllerProto";
option java_package = "com.google.devtools.clouddebugger.v2";
// The Controller service provides the API for orchestrating a collection of
// debugger agents to perform debugging tasks. These agents are each attached
// to a process of an application which may include one or more replicas.
//
// The debugger agents register with the Controller to identify the application
// being debugged, the Debuggee. All agents that register with the same data,
// represent the same Debuggee, and are assigned the same `debuggee_id`.
//
// The debugger agents call the Controller to retrieve the list of active
// Breakpoints. Agents with the same `debuggee_id` get the same breakpoints
// list. An agent that can fulfill the breakpoint request updates the
// Controller with the breakpoint result. The controller selects the first
// result received and discards the rest of the results.
// Agents that poll again for active breakpoints will no longer have
// the completed breakpoint in the list and should remove that breakpoint from
// their attached process.
//
// The Controller service does not provide a way to retrieve the results of
// a completed breakpoint. This functionality is available using the Debugger
// service.
service Controller2 {
// Registers the debuggee with the controller service.
//
// All agents attached to the same application should call this method with
// the same request content to get back the same stable `debuggee_id`. Agents
// should call this method again whenever `google.rpc.Code.NOT_FOUND` is
// returned from any controller method.
//
// This allows the controller service to disable the agent or recover from any
// data loss. If the debuggee is disabled by the server, the response will
// have `is_disabled` set to `true`.
rpc RegisterDebuggee(RegisterDebuggeeRequest) returns (RegisterDebuggeeResponse) {
option (google.api.http) = { post: "/v2/controller/debuggees/register" body: "*" };
}
// Returns the list of all active breakpoints for the debuggee.
//
// The breakpoint specification (location, condition, and expression
// fields) is semantically immutable, although the field values may
// change. For example, an agent may update the location line number
// to reflect the actual line where the breakpoint was set, but this
// doesn't change the breakpoint semantics.
//
// This means that an agent does not need to check if a breakpoint has changed
// when it encounters the same breakpoint on a successive call.
// Moreover, an agent should remember the breakpoints that are completed
// until the controller removes them from the active list to avoid
// setting those breakpoints again.
rpc ListActiveBreakpoints(ListActiveBreakpointsRequest) returns (ListActiveBreakpointsResponse) {
option (google.api.http) = { get: "/v2/controller/debuggees/{debuggee_id}/breakpoints" };
}
// Updates the breakpoint state or mutable fields.
// The entire Breakpoint message must be sent back to the controller
// service.
//
// Updates to active breakpoint fields are only allowed if the new value
// does not change the breakpoint specification. Updates to the `location`,
// `condition` and `expression` fields should not alter the breakpoint
// semantics. These may only make changes such as canonicalizing a value
// or snapping the location to the correct line of code.
rpc UpdateActiveBreakpoint(UpdateActiveBreakpointRequest) returns (UpdateActiveBreakpointResponse) {
option (google.api.http) = { put: "/v2/controller/debuggees/{debuggee_id}/breakpoints/{breakpoint.id}" body: "*" };
}
}
// Request to register a debuggee.
message RegisterDebuggeeRequest {
// Debuggee information to register.
// The fields `project`, `uniquifier`, `description` and `agent_version`
// of the debuggee must be set.
Debuggee debuggee = 1;
}
// Response for registering a debuggee.
message RegisterDebuggeeResponse {
// Debuggee resource.
// The field `id` is guranteed to be set (in addition to the echoed fields).
Debuggee debuggee = 1;
}
// Request to list active breakpoints.
message ListActiveBreakpointsRequest {
// Identifies the debuggee.
string debuggee_id = 1;
// A wait token that, if specified, blocks the method call until the list
// of active breakpoints has changed, or a server selected timeout has
// expired. The value should be set from the last returned response.
string wait_token = 2;
// If set to `true`, returns `google.rpc.Code.OK` status and sets the
// `wait_expired` response field to `true` when the server-selected timeout
// has expired (recommended).
//
// If set to `false`, returns `google.rpc.Code.ABORTED` status when the
// server-selected timeout has expired (deprecated).
bool success_on_timeout = 3;
}
// Response for listing active breakpoints.
message ListActiveBreakpointsResponse {
// List of all active breakpoints.
// The fields `id` and `location` are guaranteed to be set on each breakpoint.
repeated Breakpoint breakpoints = 1;
// A wait token that can be used in the next method call to block until
// the list of breakpoints changes.
string next_wait_token = 2;
// The `wait_expired` field is set to true by the server when the
// request times out and the field `success_on_timeout` is set to true.
bool wait_expired = 3;
}
// Request to update an active breakpoint.
message UpdateActiveBreakpointRequest {
// Identifies the debuggee being debugged.
string debuggee_id = 1;
// Updated breakpoint information.
// The field 'id' must be set.
Breakpoint breakpoint = 2;
}
// Response for updating an active breakpoint.
// The message is defined to allow future extensions.
message UpdateActiveBreakpointResponse {
}
|
