]>
Commit | Line | Data |
---|---|---|
f67539c2 TL |
1 | # Copyright 2012 Twitter Inc. |
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 | namespace cpp twitter.zipkin.thrift | |
15 | namespace java com.twitter.zipkin.thriftjava | |
16 | #@namespace scala com.twitter.zipkin.thriftscala | |
17 | namespace rb Zipkin | |
18 | namespace php Jaeger.Thrift.Agent.Zipkin | |
19 | namespace netcore Jaeger.Thrift.Agent.Zipkin | |
20 | ||
21 | #************** Annotation.value ************** | |
22 | /** | |
23 | * The client sent ("cs") a request to a server. There is only one send per | |
24 | * span. For example, if there's a transport error, each attempt can be logged | |
25 | * as a WIRE_SEND annotation. | |
26 | * | |
27 | * If chunking is involved, each chunk could be logged as a separate | |
28 | * CLIENT_SEND_FRAGMENT in the same span. | |
29 | * | |
30 | * Annotation.host is not the server. It is the host which logged the send | |
31 | * event, almost always the client. When logging CLIENT_SEND, instrumentation | |
32 | * should also log the SERVER_ADDR. | |
33 | */ | |
34 | const string CLIENT_SEND = "cs" | |
35 | /** | |
36 | * The client received ("cr") a response from a server. There is only one | |
37 | * receive per span. For example, if duplicate responses were received, each | |
38 | * can be logged as a WIRE_RECV annotation. | |
39 | * | |
40 | * If chunking is involved, each chunk could be logged as a separate | |
41 | * CLIENT_RECV_FRAGMENT in the same span. | |
42 | * | |
43 | * Annotation.host is not the server. It is the host which logged the receive | |
44 | * event, almost always the client. The actual endpoint of the server is | |
45 | * recorded separately as SERVER_ADDR when CLIENT_SEND is logged. | |
46 | */ | |
47 | const string CLIENT_RECV = "cr" | |
48 | /** | |
49 | * The server sent ("ss") a response to a client. There is only one response | |
50 | * per span. If there's a transport error, each attempt can be logged as a | |
51 | * WIRE_SEND annotation. | |
52 | * | |
53 | * Typically, a trace ends with a server send, so the last timestamp of a trace | |
54 | * is often the timestamp of the root span's server send. | |
55 | * | |
56 | * If chunking is involved, each chunk could be logged as a separate | |
57 | * SERVER_SEND_FRAGMENT in the same span. | |
58 | * | |
59 | * Annotation.host is not the client. It is the host which logged the send | |
60 | * event, almost always the server. The actual endpoint of the client is | |
61 | * recorded separately as CLIENT_ADDR when SERVER_RECV is logged. | |
62 | */ | |
63 | const string SERVER_SEND = "ss" | |
64 | /** | |
65 | * The server received ("sr") a request from a client. There is only one | |
66 | * request per span. For example, if duplicate responses were received, each | |
67 | * can be logged as a WIRE_RECV annotation. | |
68 | * | |
69 | * Typically, a trace starts with a server receive, so the first timestamp of a | |
70 | * trace is often the timestamp of the root span's server receive. | |
71 | * | |
72 | * If chunking is involved, each chunk could be logged as a separate | |
73 | * SERVER_RECV_FRAGMENT in the same span. | |
74 | * | |
75 | * Annotation.host is not the client. It is the host which logged the receive | |
76 | * event, almost always the server. When logging SERVER_RECV, instrumentation | |
77 | * should also log the CLIENT_ADDR. | |
78 | */ | |
79 | const string SERVER_RECV = "sr" | |
80 | /** | |
81 | * Message send ("ms") is a request to send a message to a destination, usually | |
82 | * a broker. This may be the only annotation in a messaging span. If WIRE_SEND | |
83 | * exists in the same span, it follows this moment and clarifies delays sending | |
84 | * the message, such as batching. | |
85 | * | |
86 | * Unlike RPC annotations like CLIENT_SEND, messaging spans never share a span | |
87 | * ID. For example, "ms" should always be the parent of "mr". | |
88 | * | |
89 | * Annotation.host is not the destination, it is the host which logged the send | |
90 | * event: the producer. When annotating MESSAGE_SEND, instrumentation should | |
91 | * also tag the MESSAGE_ADDR. | |
92 | */ | |
93 | const string MESSAGE_SEND = "ms" | |
94 | /** | |
95 | * A consumer received ("mr") a message from a broker. This may be the only | |
96 | * annotation in a messaging span. If WIRE_RECV exists in the same span, it | |
97 | * precedes this moment and clarifies any local queuing delay. | |
98 | * | |
99 | * Unlike RPC annotations like SERVER_RECV, messaging spans never share a span | |
100 | * ID. For example, "mr" should always be a child of "ms" unless it is a root | |
101 | * span. | |
102 | * | |
103 | * Annotation.host is not the broker, it is the host which logged the receive | |
104 | * event: the consumer. When annotating MESSAGE_RECV, instrumentation should | |
105 | * also tag the MESSAGE_ADDR. | |
106 | */ | |
107 | const string MESSAGE_RECV = "mr" | |
108 | /** | |
109 | * Optionally logs an attempt to send a message on the wire. Multiple wire send | |
110 | * events could indicate network retries. A lag between client or server send | |
111 | * and wire send might indicate queuing or processing delay. | |
112 | */ | |
113 | const string WIRE_SEND = "ws" | |
114 | /** | |
115 | * Optionally logs an attempt to receive a message from the wire. Multiple wire | |
116 | * receive events could indicate network retries. A lag between wire receive | |
117 | * and client or server receive might indicate queuing or processing delay. | |
118 | */ | |
119 | const string WIRE_RECV = "wr" | |
120 | /** | |
121 | * Optionally logs progress of a (CLIENT_SEND, WIRE_SEND). For example, this | |
122 | * could be one chunk in a chunked request. | |
123 | */ | |
124 | const string CLIENT_SEND_FRAGMENT = "csf" | |
125 | /** | |
126 | * Optionally logs progress of a (CLIENT_RECV, WIRE_RECV). For example, this | |
127 | * could be one chunk in a chunked response. | |
128 | */ | |
129 | const string CLIENT_RECV_FRAGMENT = "crf" | |
130 | /** | |
131 | * Optionally logs progress of a (SERVER_SEND, WIRE_SEND). For example, this | |
132 | * could be one chunk in a chunked response. | |
133 | */ | |
134 | const string SERVER_SEND_FRAGMENT = "ssf" | |
135 | /** | |
136 | * Optionally logs progress of a (SERVER_RECV, WIRE_RECV). For example, this | |
137 | * could be one chunk in a chunked request. | |
138 | */ | |
139 | const string SERVER_RECV_FRAGMENT = "srf" | |
140 | ||
141 | #***** BinaryAnnotation.key ****** | |
142 | /** | |
143 | * The value of "lc" is the component or namespace of a local span. | |
144 | * | |
145 | * BinaryAnnotation.host adds service context needed to support queries. | |
146 | * | |
147 | * Local Component("lc") supports three key features: flagging, query by | |
148 | * service and filtering Span.name by namespace. | |
149 | * | |
150 | * While structurally the same, local spans are fundamentally different than | |
151 | * RPC spans in how they should be interpreted. For example, zipkin v1 tools | |
152 | * center on RPC latency and service graphs. Root local-spans are neither | |
153 | * indicative of critical path RPC latency, nor have impact on the shape of a | |
154 | * service graph. By flagging with "lc", tools can special-case local spans. | |
155 | * | |
156 | * Zipkin v1 Spans are unqueryable unless they can be indexed by service name. | |
157 | * The only path to a service name is by (Binary)?Annotation.host.serviceName. | |
158 | * By logging "lc", a local span can be queried even if no other annotations | |
159 | * are logged. | |
160 | * | |
161 | * The value of "lc" is the namespace of Span.name. For example, it might be | |
162 | * "finatra2", for a span named "bootstrap". "lc" allows you to resolves | |
163 | * conflicts for the same Span.name, for example "finatra/bootstrap" vs | |
164 | * "finch/bootstrap". Using local component, you'd search for spans named | |
165 | * "bootstrap" where "lc=finch" | |
166 | */ | |
167 | const string LOCAL_COMPONENT = "lc" | |
168 | ||
169 | #***** BinaryAnnotation.key where value = [1] and annotation_type = BOOL ****** | |
170 | /** | |
171 | * Indicates a client address ("ca") in a span. Most likely, there's only one. | |
172 | * Multiple addresses are possible when a client changes its ip or port within | |
173 | * a span. | |
174 | */ | |
175 | const string CLIENT_ADDR = "ca" | |
176 | /** | |
177 | * Indicates a server address ("sa") in a span. Most likely, there's only one. | |
178 | * Multiple addresses are possible when a client is redirected, or fails to a | |
179 | * different server ip or port. | |
180 | */ | |
181 | const string SERVER_ADDR = "sa" | |
182 | /** | |
183 | * Indicates the remote address of a messaging span, usually the broker. | |
184 | */ | |
185 | const string MESSAGE_ADDR = "ma" | |
186 | ||
187 | /** | |
188 | * Indicates the network context of a service recording an annotation with two | |
189 | * exceptions. | |
190 | * | |
191 | * When a BinaryAnnotation, and key is CLIENT_ADDR or SERVER_ADDR, | |
192 | * the endpoint indicates the source or destination of an RPC. This exception | |
193 | * allows zipkin to display network context of uninstrumented services, or | |
194 | * clients such as web browsers. | |
195 | */ | |
196 | struct Endpoint { | |
197 | /** | |
198 | * IPv4 host address packed into 4 bytes. | |
199 | * | |
200 | * Ex for the ip 1.2.3.4, it would be (1 << 24) | (2 << 16) | (3 << 8) | 4 | |
201 | */ | |
202 | 1: i32 ipv4 | |
203 | /** | |
204 | * IPv4 port | |
205 | * | |
206 | * Note: this is to be treated as an unsigned integer, so watch for negatives. | |
207 | * | |
208 | * Conventionally, when the port isn't known, port = 0. | |
209 | */ | |
210 | 2: i16 port | |
211 | /** | |
212 | * Service name in lowercase, such as "memcache" or "zipkin-web" | |
213 | * | |
214 | * Conventionally, when the service name isn't known, service_name = "unknown". | |
215 | */ | |
216 | 3: string service_name | |
217 | /** | |
218 | * IPv6 host address packed into 16 bytes. Ex Inet6Address.getBytes() | |
219 | */ | |
220 | 4: optional binary ipv6 | |
221 | } | |
222 | ||
223 | /** | |
224 | * An annotation is similar to a log statement. It includes a host field which | |
225 | * allows these events to be attributed properly, and also aggregatable. | |
226 | */ | |
227 | struct Annotation { | |
228 | /** | |
229 | * Microseconds from epoch. | |
230 | * | |
231 | * This value should use the most precise value possible. For example, | |
232 | * gettimeofday or syncing nanoTime against a tick of currentTimeMillis. | |
233 | */ | |
234 | 1: i64 timestamp | |
235 | 2: string value // what happened at the timestamp? | |
236 | /** | |
237 | * Always the host that recorded the event. By specifying the host you allow | |
238 | * rollup of all events (such as client requests to a service) by IP address. | |
239 | */ | |
240 | 3: optional Endpoint host | |
241 | // don't reuse 4: optional i32 OBSOLETE_duration // how long did the operation take? microseconds | |
242 | } | |
243 | ||
244 | enum AnnotationType { BOOL, BYTES, I16, I32, I64, DOUBLE, STRING } | |
245 | ||
246 | /** | |
247 | * Binary annotations are tags applied to a Span to give it context. For | |
248 | * example, a binary annotation of "http.uri" could the path to a resource in a | |
249 | * RPC call. | |
250 | * | |
251 | * Binary annotations of type STRING are always queryable, though more a | |
252 | * historical implementation detail than a structural concern. | |
253 | * | |
254 | * Binary annotations can repeat, and vary on the host. Similar to Annotation, | |
255 | * the host indicates who logged the event. This allows you to tell the | |
256 | * difference between the client and server side of the same key. For example, | |
257 | * the key "http.uri" might be different on the client and server side due to | |
258 | * rewriting, like "/api/v1/myresource" vs "/myresource. Via the host field, | |
259 | * you can see the different points of view, which often help in debugging. | |
260 | */ | |
261 | struct BinaryAnnotation { | |
262 | 1: string key, | |
263 | 2: binary value, | |
264 | 3: AnnotationType annotation_type, | |
265 | /** | |
266 | * The host that recorded tag, which allows you to differentiate between | |
267 | * multiple tags with the same key. There are two exceptions to this. | |
268 | * | |
269 | * When the key is CLIENT_ADDR or SERVER_ADDR, host indicates the source or | |
270 | * destination of an RPC. This exception allows zipkin to display network | |
271 | * context of uninstrumented services, or clients such as web browsers. | |
272 | */ | |
273 | 4: optional Endpoint host | |
274 | } | |
275 | ||
276 | /** | |
277 | * A trace is a series of spans (often RPC calls) which form a latency tree. | |
278 | * | |
279 | * The root span is where trace_id = id and parent_id = Nil. The root span is | |
280 | * usually the longest interval in the trace, starting with a SERVER_RECV | |
281 | * annotation and ending with a SERVER_SEND. | |
282 | */ | |
283 | struct Span { | |
284 | 1: i64 trace_id # unique trace id, use for all spans in trace | |
285 | /** | |
286 | * Span name in lowercase, rpc method for example | |
287 | * | |
288 | * Conventionally, when the span name isn't known, name = "unknown". | |
289 | */ | |
290 | 3: string name, | |
291 | 4: i64 id, # unique span id, only used for this span | |
292 | 5: optional i64 parent_id, # parent span id | |
293 | 6: list<Annotation> annotations, # all annotations/events that occured, sorted by timestamp | |
294 | 8: list<BinaryAnnotation> binary_annotations # any binary annotations | |
295 | 9: optional bool debug = 0 # if true, we DEMAND that this span passes all samplers | |
296 | /** | |
297 | * Microseconds from epoch of the creation of this span. | |
298 | * | |
299 | * This value should be set directly by instrumentation, using the most | |
300 | * precise value possible. For example, gettimeofday or syncing nanoTime | |
301 | * against a tick of currentTimeMillis. | |
302 | * | |
303 | * For compatibilty with instrumentation that precede this field, collectors | |
304 | * or span stores can derive this via Annotation.timestamp. | |
305 | * For example, SERVER_RECV.timestamp or CLIENT_SEND.timestamp. | |
306 | * | |
307 | * This field is optional for compatibility with old data: first-party span | |
308 | * stores are expected to support this at time of introduction. | |
309 | */ | |
310 | 10: optional i64 timestamp, | |
311 | /** | |
312 | * Measurement of duration in microseconds, used to support queries. | |
313 | * | |
314 | * This value should be set directly, where possible. Doing so encourages | |
315 | * precise measurement decoupled from problems of clocks, such as skew or NTP | |
316 | * updates causing time to move backwards. | |
317 | * | |
318 | * For compatibilty with instrumentation that precede this field, collectors | |
319 | * or span stores can derive this by subtracting Annotation.timestamp. | |
320 | * For example, SERVER_SEND.timestamp - SERVER_RECV.timestamp. | |
321 | * | |
322 | * If this field is persisted as unset, zipkin will continue to work, except | |
323 | * duration query support will be implementation-specific. Similarly, setting | |
324 | * this field non-atomically is implementation-specific. | |
325 | * | |
326 | * This field is i64 vs i32 to support spans longer than 35 minutes. | |
327 | */ | |
328 | 11: optional i64 duration | |
329 | /** | |
330 | * Optional unique 8-byte additional identifier for a trace. If non zero, this | |
331 | * means the trace uses 128 bit traceIds instead of 64 bit. | |
332 | */ | |
333 | 12: optional i64 trace_id_high | |
334 | } | |
335 | ||
336 | # define TChannel service | |
337 | ||
338 | struct Response { | |
339 | 1: required bool ok | |
340 | } | |
341 | ||
342 | service ZipkinCollector { | |
343 | list<Response> submitZipkinBatch(1: list<Span> spans) | |
344 | } |