Repository navigation
Expand file tree
/
Copy pathtrace.proto
More file actions
240 lines (210 loc) · 8.98 KB
/
Copy pathtrace.proto
File metadata and controls
240 lines (210 loc) · 8.98 KB
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
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
/** Service responsible for collecting metrics from Compass */
syntax = "proto3";
package workflow;
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
option go_package = "./pb";
service trace {
rpc Suspend (TraceSuspendRequest) returns (TraceSuspendResponse) {}
rpc Resume (TraceResumeRequest) returns (TraceResumeResponse) {}
rpc GetSuspended (TraceGetSuspendedRequest) returns (TraceGetSuspendedResponse) {}
rpc SetThreshold (TraceSetThresholdRequest) returns (TraceSetThresholdResponse) {}
rpc GetThreshold (TraceGetThresholdRequest) returns (TraceGetThresholdResponse) {}
rpc StreamTraces (StreamTracesRequest) returns (stream StreamTracesResponse) {}
}
/**
* Request that tracing is suspended for an environment
*/
message TraceSuspendRequest {
string Environment = 1; // Name of the environment
}
/**
* Response if the tracing suspend was successful
*/
message TraceSuspendResponse {}
/**
* Request that tracing be resumed
*/
message TraceResumeRequest {
string Environment = 1; // Name of the environment
}
/**
* Response if the tracing resume was successful
*/
message TraceResumeResponse {}
/**
* Request whether tracing is currently suspended for an environment
*/
message TraceGetSuspendedRequest {
string Environment = 1; // Name of the environment
}
/**
* Whether tracing is currently suspended for an environment
*/
message TraceGetSuspendedResponse {
bool Suspended = 1; // If tracing is suspended for the environment
}
/**
* Request that the tracing threshold be set for an environment
*/
message TraceSetThresholdRequest {
string Environment = 1; // Name of the environment
// Minimum duration a function call has to run for before it is traced.
//
// Compass only fires a probe for calls above this, so it is the main control
// over how much a traced environment pays for tracing. A threshold of zero
// traces every call, which is expensive on a busy environment.
google.protobuf.Duration Threshold = 2;
}
/**
* Response if setting the tracing threshold was successful
*/
message TraceSetThresholdResponse {}
/**
* Request the tracing threshold currently applied to an environment
*/
message TraceGetThresholdRequest {
string Environment = 1; // Name of the environment
}
/**
* The tracing threshold currently applied to an environment
*/
message TraceGetThresholdResponse {
// Minimum duration a function call has to run for before it is traced.
//
// An environment which has never had one set reports the default rather than
// zero, because zero is itself a meaningful threshold which traces every call.
google.protobuf.Duration Threshold = 1;
}
/**
* Input for StreamTraces.
*/
message StreamTracesRequest {
string environment = 1; // The environment to stream traces from.
}
/**
* Output for StreamTraces.
*/
message StreamTracesResponse {
repeated Trace Traces = 1; // List of traces.
}
// The invocation mechanism which produced the trace.
enum TraceSource {
TRACE_SOURCE_UNSPECIFIED = 0;
TRACE_SOURCE_HTTP = 1; // Trace was collected from a HTTP request.
TRACE_SOURCE_CLI = 2; // Trace was collected from the command line interface.
}
// The language runtime which produced the trace.
enum TraceRuntime {
TRACE_RUNTIME_UNSPECIFIED = 0;
TRACE_RUNTIME_PHP = 1; // Trace was collected from a PHP process.
TRACE_RUNTIME_NODE = 2; // Trace was collected from a Node.js process.
}
/**
* Trace data provided by Compass.
*/
message Trace {
TraceMetadata metadata = 1; // Metadata about the trace.
repeated TraceSpan spans = 2; // Function calls made by the request, aggregated into spans.
TraceResourceUtilisation resource_utilisation = 3; // Resources consumed by the request.
optional TraceDrupal drupal = 4; // Drupal specific data. Only populated for PHP traces which called into the Drupal APIs.
// How many function calls the request made, including any which no span
// represents. It is an exact count either way.
int64 calls = 5;
// How many of those calls no span represents, because the trace had already
// reached its span limit when they arrived. Reported so that a truncated
// trace is not mistaken for a complete one.
int64 calls_dropped = 6;
}
/**
* Metadata which contains information about the trace.
*/
message TraceMetadata {
// Request identifier for tracking.
//
// Compass sends "UNKNOWN" when the request carried no HTTP_X_REQUEST_ID
// header. That is a sentinel, not an identifier: two traces reading UNKNOWN
// are not the same request, so anything correlating on this must treat it as
// absent.
string request_id = 1;
google.protobuf.Timestamp start_time = 2; // Start time of the trace.
google.protobuf.Timestamp end_time = 3; // End time of the trace.
TraceSource source = 4; // How the traced request was invoked.
TraceRuntime runtime = 5; // Language runtime which produced the trace.
optional TraceMetadataHTTP http = 6; // Request details. Only set when source is TRACE_SOURCE_HTTP.
optional TraceMetadataCLI cli = 7; // Command details. Only set when source is TRACE_SOURCE_CLI.
}
/**
* Metadata for a trace which was invoked by a HTTP request.
*/
message TraceMetadataHTTP {
string method = 1; // HTTP method of the request (e.g., GET, POST).
string uri = 2; // URI of the request being traced.
}
/**
* Metadata for a trace which was invoked from the command line.
*/
message TraceMetadataCLI {
string command = 1; // Command which was executed.
}
/**
* Resources consumed over the course of the traced request.
*/
message TraceResourceUtilisation {
int64 max_memory = 1; // Peak memory used by the request, in bytes.
}
/**
* The calls of one function during one slice of a request.
*
* A request can make more than a million function calls, and no reader looks at
* those one at a time: what a reader asks of a trace is where the time went,
* which is an aggregate. Compass collects calls into spans as their events
* arrive, which is what lets a trace of a million calls stay a few hundred
* kilobytes.
*
* A span is placed by how far into the request it started rather than by the
* instant it started at, because an absolute time says nothing on its own -
* every consumer immediately subtracts the request start to get back to this.
*/
message TraceSpan {
string name = 1; // Name of the function which was called.
google.protobuf.Duration offset = 2; // Offset from the start of the request at which the earliest call in this span began.
google.protobuf.Duration elapsed = 3; // How long the longest single call in this span ran for.
google.protobuf.Duration total = 4; // How long the calls in this span ran for altogether. Exceeds the request duration where a function called its way back into itself.
int64 calls = 5; // How many calls were aggregated into this span.
int64 memory = 6; // The highest memory reported by any call in this span, in bytes.
}
// Which Drupal API produced a cache event.
enum TraceDrupalCacheOrigin {
TRACE_DRUPAL_CACHE_ORIGIN_UNSPECIFIED = 0;
TRACE_DRUPAL_CACHE_ORIGIN_RENDER_ARRAY = 1; // Cacheability was collected from a render array.
TRACE_DRUPAL_CACHE_ORIGIN_OBJECT = 2; // Cacheability was collected from an object.
}
/**
* Drupal specific data collected for a trace.
*
* Only populated for PHP traces where the application called into the Drupal
* APIs which Compass probes, so it is absent for Node traces, PHP CLI traces
* and non-Drupal PHP applications.
*/
message TraceDrupal {
repeated TraceDrupalCacheEvent cache_events = 1; // Cache events which occurred during this trace, aggregated by their contents.
int64 cache_events_dropped = 2; // How many distinct cache events were discarded because the trace reached its retention limit. Reported so that a truncated trace is not mistaken for a complete one.
}
/**
* Cacheability metadata that Drupal derived at a point in the request.
*
* Drupal derives cacheability far more often than a request has interesting
* function calls, so identical events are aggregated into a single entry with a
* call count rather than retained individually.
*/
message TraceDrupalCacheEvent {
TraceDrupalCacheOrigin origin = 1; // Origin of the cacheability metadata.
string caller = 2; // Caller which asked Drupal for the cacheability metadata.
string object_type = 3; // Type the metadata was derived from. Only set for TRACE_DRUPAL_CACHE_ORIGIN_OBJECT.
int64 max_age = 4; // Max age in seconds, where -1 means cacheable forever.
repeated string tags = 5; // Tags which the cached item is invalidated by.
repeated string contexts = 6; // Contexts which the cached item varies by.
google.protobuf.Duration offset = 7; // Offset from the start of the request at which the first of these events occurred.
int64 calls = 8; // How many identical events were aggregated into this one.
}