opencensus-jaeger 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. checksums.yaml +7 -0
  2. data/.circleci/config.yml +77 -0
  3. data/.gitignore +15 -0
  4. data/.gitmodules +3 -0
  5. data/.rspec +3 -0
  6. data/.rubocop.yml +36 -0
  7. data/.travis.yml +7 -0
  8. data/CHANGELOG.md +6 -0
  9. data/CODEOWNERS +13 -0
  10. data/CODE_OF_CONDUCT.md +43 -0
  11. data/Gemfile +3 -0
  12. data/LICENSE +201 -0
  13. data/README.md +72 -0
  14. data/Rakefile +6 -0
  15. data/bin/console +14 -0
  16. data/bin/setup +8 -0
  17. data/examples/.byebug_history +97 -0
  18. data/examples/Gemfile +9 -0
  19. data/examples/Gemfile.lock +46 -0
  20. data/examples/config.ru +15 -0
  21. data/examples/example.rb +25 -0
  22. data/lib/opencensus-jaeger.rb +4 -0
  23. data/lib/opencensus/jaeger.rb +12 -0
  24. data/lib/opencensus/jaeger/version.rb +5 -0
  25. data/lib/opencensus/logging.rb +24 -0
  26. data/lib/opencensus/trace/exporters/jaeger_driver.rb +125 -0
  27. data/lib/opencensus/trace/exporters/jaeger_driver/intermediate_transport.rb +25 -0
  28. data/lib/opencensus/trace/exporters/jaeger_driver/udp_sender.rb +28 -0
  29. data/lib/opencensus/trace/exporters/jaeger_driver/udp_transport.rb +43 -0
  30. data/lib/opencensus/trace/exporters/jaeger_exporter.rb +108 -0
  31. data/opencensus-jaeger.gemspec +45 -0
  32. data/scripts/publish.rb +7 -0
  33. data/scripts/rename_collectors.rb +88 -0
  34. data/thrift/agent.thrift +27 -0
  35. data/thrift/gen-rb/jaeger/thrift/agent.rb +117 -0
  36. data/thrift/gen-rb/jaeger/thrift/agent_constants.rb +13 -0
  37. data/thrift/gen-rb/jaeger/thrift/agent_types.rb +14 -0
  38. data/thrift/gen-rb/jaeger/thrift/collector.rb +82 -0
  39. data/thrift/gen-rb/jaeger/thrift/jaeger_constants.rb +13 -0
  40. data/thrift/gen-rb/jaeger/thrift/jaeger_types.rb +213 -0
  41. data/thrift/gen-rb/zipkin/zipkin_collector.rb +80 -0
  42. data/thrift/gen-rb/zipkin/zipkincore_constants.rb +43 -0
  43. data/thrift/gen-rb/zipkin/zipkincore_types.rb +223 -0
  44. data/thrift/jaeger.thrift +86 -0
  45. data/thrift/zipkincore.thrift +345 -0
  46. metadata +161 -0
@@ -0,0 +1,223 @@
1
+ #
2
+ # Autogenerated by Thrift Compiler (0.11.0)
3
+ #
4
+ # DO NOT EDIT UNLESS YOU ARE SURE THAT YOU KNOW WHAT YOU ARE DOING
5
+ #
6
+
7
+ require 'thrift'
8
+
9
+ module Zipkin
10
+ module AnnotationType
11
+ BOOL = 0
12
+ BYTES = 1
13
+ I16 = 2
14
+ I32 = 3
15
+ I64 = 4
16
+ DOUBLE = 5
17
+ STRING = 6
18
+ VALUE_MAP = {0 => "BOOL", 1 => "BYTES", 2 => "I16", 3 => "I32", 4 => "I64", 5 => "DOUBLE", 6 => "STRING"}
19
+ VALID_VALUES = Set.new([BOOL, BYTES, I16, I32, I64, DOUBLE, STRING]).freeze
20
+ end
21
+
22
+ # Indicates the network context of a service recording an annotation with two
23
+ # exceptions.
24
+ #
25
+ # When a BinaryAnnotation, and key is CLIENT_ADDR or SERVER_ADDR,
26
+ # the endpoint indicates the source or destination of an RPC. This exception
27
+ # allows zipkin to display network context of uninstrumented services, or
28
+ # clients such as web browsers.
29
+ class Endpoint
30
+ include ::Thrift::Struct, ::Thrift::Struct_Union
31
+ IPV4 = 1
32
+ PORT = 2
33
+ SERVICE_NAME = 3
34
+ IPV6 = 4
35
+
36
+ FIELDS = {
37
+ # IPv4 host address packed into 4 bytes.
38
+ #
39
+ # Ex for the ip 1.2.3.4, it would be (1 << 24) | (2 << 16) | (3 << 8) | 4
40
+ IPV4 => {:type => ::Thrift::Types::I32, :name => 'ipv4'},
41
+ # IPv4 port
42
+ #
43
+ # Note: this is to be treated as an unsigned integer, so watch for negatives.
44
+ #
45
+ # Conventionally, when the port isn't known, port = 0.
46
+ PORT => {:type => ::Thrift::Types::I16, :name => 'port'},
47
+ # Service name in lowercase, such as "memcache" or "zipkin-web"
48
+ #
49
+ # Conventionally, when the service name isn't known, service_name = "unknown".
50
+ SERVICE_NAME => {:type => ::Thrift::Types::STRING, :name => 'service_name'},
51
+ # IPv6 host address packed into 16 bytes. Ex Inet6Address.getBytes()
52
+ IPV6 => {:type => ::Thrift::Types::STRING, :name => 'ipv6', :binary => true, :optional => true}
53
+ }
54
+
55
+ def struct_fields; FIELDS; end
56
+
57
+ def validate
58
+ end
59
+
60
+ ::Thrift::Struct.generate_accessors self
61
+ end
62
+
63
+ # An annotation is similar to a log statement. It includes a host field which
64
+ # allows these events to be attributed properly, and also aggregatable.
65
+ class Annotation
66
+ include ::Thrift::Struct, ::Thrift::Struct_Union
67
+ TIMESTAMP = 1
68
+ VALUE = 2
69
+ HOST = 3
70
+
71
+ FIELDS = {
72
+ # Microseconds from epoch.
73
+ #
74
+ # This value should use the most precise value possible. For example,
75
+ # gettimeofday or syncing nanoTime against a tick of currentTimeMillis.
76
+ TIMESTAMP => {:type => ::Thrift::Types::I64, :name => 'timestamp'},
77
+ VALUE => {:type => ::Thrift::Types::STRING, :name => 'value'},
78
+ # Always the host that recorded the event. By specifying the host you allow
79
+ # rollup of all events (such as client requests to a service) by IP address.
80
+ HOST => {:type => ::Thrift::Types::STRUCT, :name => 'host', :class => ::Zipkin::Endpoint, :optional => true}
81
+ }
82
+
83
+ def struct_fields; FIELDS; end
84
+
85
+ def validate
86
+ end
87
+
88
+ ::Thrift::Struct.generate_accessors self
89
+ end
90
+
91
+ # Binary annotations are tags applied to a Span to give it context. For
92
+ # example, a binary annotation of "http.uri" could the path to a resource in a
93
+ # RPC call.
94
+ #
95
+ # Binary annotations of type STRING are always queryable, though more a
96
+ # historical implementation detail than a structural concern.
97
+ #
98
+ # Binary annotations can repeat, and vary on the host. Similar to Annotation,
99
+ # the host indicates who logged the event. This allows you to tell the
100
+ # difference between the client and server side of the same key. For example,
101
+ # the key "http.uri" might be different on the client and server side due to
102
+ # rewriting, like "/api/v1/myresource" vs "/myresource. Via the host field,
103
+ # you can see the different points of view, which often help in debugging.
104
+ class BinaryAnnotation
105
+ include ::Thrift::Struct, ::Thrift::Struct_Union
106
+ KEY = 1
107
+ VALUE = 2
108
+ ANNOTATION_TYPE = 3
109
+ HOST = 4
110
+
111
+ FIELDS = {
112
+ KEY => {:type => ::Thrift::Types::STRING, :name => 'key'},
113
+ VALUE => {:type => ::Thrift::Types::STRING, :name => 'value', :binary => true},
114
+ ANNOTATION_TYPE => {:type => ::Thrift::Types::I32, :name => 'annotation_type', :enum_class => ::Zipkin::AnnotationType},
115
+ # The host that recorded tag, which allows you to differentiate between
116
+ # multiple tags with the same key. There are two exceptions to this.
117
+ #
118
+ # When the key is CLIENT_ADDR or SERVER_ADDR, host indicates the source or
119
+ # destination of an RPC. This exception allows zipkin to display network
120
+ # context of uninstrumented services, or clients such as web browsers.
121
+ HOST => {:type => ::Thrift::Types::STRUCT, :name => 'host', :class => ::Zipkin::Endpoint, :optional => true}
122
+ }
123
+
124
+ def struct_fields; FIELDS; end
125
+
126
+ def validate
127
+ unless @annotation_type.nil? || ::Zipkin::AnnotationType::VALID_VALUES.include?(@annotation_type)
128
+ raise ::Thrift::ProtocolException.new(::Thrift::ProtocolException::UNKNOWN, 'Invalid value of field annotation_type!')
129
+ end
130
+ end
131
+
132
+ ::Thrift::Struct.generate_accessors self
133
+ end
134
+
135
+ # A trace is a series of spans (often RPC calls) which form a latency tree.
136
+ #
137
+ # The root span is where trace_id = id and parent_id = Nil. The root span is
138
+ # usually the longest interval in the trace, starting with a SERVER_RECV
139
+ # annotation and ending with a SERVER_SEND.
140
+ class Span
141
+ include ::Thrift::Struct, ::Thrift::Struct_Union
142
+ TRACE_ID = 1
143
+ NAME = 3
144
+ ID = 4
145
+ PARENT_ID = 5
146
+ ANNOTATIONS = 6
147
+ BINARY_ANNOTATIONS = 8
148
+ DEBUG = 9
149
+ TIMESTAMP = 10
150
+ DURATION = 11
151
+ TRACE_ID_HIGH = 12
152
+
153
+ FIELDS = {
154
+ TRACE_ID => {:type => ::Thrift::Types::I64, :name => 'trace_id'},
155
+ # Span name in lowercase, rpc method for example
156
+ #
157
+ # Conventionally, when the span name isn't known, name = "unknown".
158
+ NAME => {:type => ::Thrift::Types::STRING, :name => 'name'},
159
+ ID => {:type => ::Thrift::Types::I64, :name => 'id'},
160
+ PARENT_ID => {:type => ::Thrift::Types::I64, :name => 'parent_id', :optional => true},
161
+ ANNOTATIONS => {:type => ::Thrift::Types::LIST, :name => 'annotations', :element => {:type => ::Thrift::Types::STRUCT, :class => ::Zipkin::Annotation}},
162
+ BINARY_ANNOTATIONS => {:type => ::Thrift::Types::LIST, :name => 'binary_annotations', :element => {:type => ::Thrift::Types::STRUCT, :class => ::Zipkin::BinaryAnnotation}},
163
+ DEBUG => {:type => ::Thrift::Types::BOOL, :name => 'debug', :default => false, :optional => true},
164
+ # Microseconds from epoch of the creation of this span.
165
+ #
166
+ # This value should be set directly by instrumentation, using the most
167
+ # precise value possible. For example, gettimeofday or syncing nanoTime
168
+ # against a tick of currentTimeMillis.
169
+ #
170
+ # For compatibilty with instrumentation that precede this field, collectors
171
+ # or span stores can derive this via Annotation.timestamp.
172
+ # For example, SERVER_RECV.timestamp or CLIENT_SEND.timestamp.
173
+ #
174
+ # This field is optional for compatibility with old data: first-party span
175
+ # stores are expected to support this at time of introduction.
176
+ TIMESTAMP => {:type => ::Thrift::Types::I64, :name => 'timestamp', :optional => true},
177
+ # Measurement of duration in microseconds, used to support queries.
178
+ #
179
+ # This value should be set directly, where possible. Doing so encourages
180
+ # precise measurement decoupled from problems of clocks, such as skew or NTP
181
+ # updates causing time to move backwards.
182
+ #
183
+ # For compatibilty with instrumentation that precede this field, collectors
184
+ # or span stores can derive this by subtracting Annotation.timestamp.
185
+ # For example, SERVER_SEND.timestamp - SERVER_RECV.timestamp.
186
+ #
187
+ # If this field is persisted as unset, zipkin will continue to work, except
188
+ # duration query support will be implementation-specific. Similarly, setting
189
+ # this field non-atomically is implementation-specific.
190
+ #
191
+ # This field is i64 vs i32 to support spans longer than 35 minutes.
192
+ DURATION => {:type => ::Thrift::Types::I64, :name => 'duration', :optional => true},
193
+ # Optional unique 8-byte additional identifier for a trace. If non zero, this
194
+ # means the trace uses 128 bit traceIds instead of 64 bit.
195
+ TRACE_ID_HIGH => {:type => ::Thrift::Types::I64, :name => 'trace_id_high', :optional => true}
196
+ }
197
+
198
+ def struct_fields; FIELDS; end
199
+
200
+ def validate
201
+ end
202
+
203
+ ::Thrift::Struct.generate_accessors self
204
+ end
205
+
206
+ class Response
207
+ include ::Thrift::Struct, ::Thrift::Struct_Union
208
+ OK = 1
209
+
210
+ FIELDS = {
211
+ OK => {:type => ::Thrift::Types::BOOL, :name => 'ok'}
212
+ }
213
+
214
+ def struct_fields; FIELDS; end
215
+
216
+ def validate
217
+ raise ::Thrift::ProtocolException.new(::Thrift::ProtocolException::UNKNOWN, 'Required field ok is unset!') if @ok.nil?
218
+ end
219
+
220
+ ::Thrift::Struct.generate_accessors self
221
+ end
222
+
223
+ end
@@ -0,0 +1,86 @@
1
+ # Copyright (c) 2016 Uber Technologies, 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
+
15
+ namespace cpp jaegertracing.thrift
16
+ namespace java io.jaegertracing.thriftjava
17
+ namespace php Jaeger.Thrift
18
+ namespace netcore Jaeger.Thrift
19
+ namespace rb Jaeger.Thrift
20
+
21
+ # TagType denotes the type of a Tag's value.
22
+ enum TagType { STRING, DOUBLE, BOOL, LONG, BINARY }
23
+
24
+ # Tag is a basic strongly typed key/value pair. It has been flattened to reduce the use of pointers in golang
25
+ struct Tag {
26
+ 1: required string key
27
+ 2: required TagType vType
28
+ 3: optional string vStr
29
+ 4: optional double vDouble
30
+ 5: optional bool vBool
31
+ 6: optional i64 vLong
32
+ 7: optional binary vBinary
33
+ }
34
+
35
+ # Log is a timed even with an arbitrary set of tags.
36
+ struct Log {
37
+ 1: required i64 timestamp
38
+ 2: required list<Tag> fields
39
+ }
40
+
41
+ enum SpanRefType { CHILD_OF, FOLLOWS_FROM }
42
+
43
+ # SpanRef describes causal relationship of the current span to another span (e.g. 'child-of')
44
+ struct SpanRef {
45
+ 1: required SpanRefType refType
46
+ 2: required i64 traceIdLow
47
+ 3: required i64 traceIdHigh
48
+ 4: required i64 spanId
49
+ }
50
+
51
+ # Span represents a named unit of work performed by a service.
52
+ struct Span {
53
+ 1: required i64 traceIdLow # the least significant 64 bits of a traceID
54
+ 2: required i64 traceIdHigh # the most significant 64 bits of a traceID; 0 when only 64bit IDs are used
55
+ 3: required i64 spanId # unique span id (only unique within a given trace)
56
+ 4: required i64 parentSpanId # since nearly all spans will have parents spans, CHILD_OF refs do not have to be explicit
57
+ 5: required string operationName
58
+ 6: optional list<SpanRef> references # causal references to other spans
59
+ 7: required i32 flags # a bit field used to propagate sampling decisions. 1 signifies a SAMPLED span, 2 signifies a DEBUG span.
60
+ 8: required i64 startTime
61
+ 9: required i64 duration
62
+ 10: optional list<Tag> tags
63
+ 11: optional list<Log> logs
64
+ 12: optional bool incomplete # indicates whether this is the final span or an intermediate (incomplete) span
65
+ }
66
+
67
+ # Process describes the traced process/service that emits spans.
68
+ struct Process {
69
+ 1: required string serviceName
70
+ 2: optional list<Tag> tags
71
+ }
72
+
73
+ # Batch is a collection of spans reported out of process.
74
+ struct Batch {
75
+ 1: required Process process
76
+ 2: required list<Span> spans
77
+ }
78
+
79
+ # BatchSubmitResponse is the response on submitting a batch.
80
+ struct BatchSubmitResponse {
81
+ 1: required bool ok # The Collector's client is expected to only log (or emit a counter) when not ok equals false
82
+ }
83
+
84
+ service Collector {
85
+ list<BatchSubmitResponse> submitBatches(1: list<Batch> batches)
86
+ }
@@ -0,0 +1,345 @@
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
+ namespace netcore Jaeger.Thrift.Agent.Zipkin
21
+
22
+ #************** Annotation.value **************
23
+ /**
24
+ * The client sent ("cs") a request to a server. There is only one send per
25
+ * span. For example, if there's a transport error, each attempt can be logged
26
+ * as a WIRE_SEND annotation.
27
+ *
28
+ * If chunking is involved, each chunk could be logged as a separate
29
+ * CLIENT_SEND_FRAGMENT in the same span.
30
+ *
31
+ * Annotation.host is not the server. It is the host which logged the send
32
+ * event, almost always the client. When logging CLIENT_SEND, instrumentation
33
+ * should also log the SERVER_ADDR.
34
+ */
35
+ const string CLIENT_SEND = "cs"
36
+ /**
37
+ * The client received ("cr") a response from a server. There is only one
38
+ * receive per span. For example, if duplicate responses were received, each
39
+ * can be logged as a WIRE_RECV annotation.
40
+ *
41
+ * If chunking is involved, each chunk could be logged as a separate
42
+ * CLIENT_RECV_FRAGMENT in the same span.
43
+ *
44
+ * Annotation.host is not the server. It is the host which logged the receive
45
+ * event, almost always the client. The actual endpoint of the server is
46
+ * recorded separately as SERVER_ADDR when CLIENT_SEND is logged.
47
+ */
48
+ const string CLIENT_RECV = "cr"
49
+ /**
50
+ * The server sent ("ss") a response to a client. There is only one response
51
+ * per span. If there's a transport error, each attempt can be logged as a
52
+ * WIRE_SEND annotation.
53
+ *
54
+ * Typically, a trace ends with a server send, so the last timestamp of a trace
55
+ * is often the timestamp of the root span's server send.
56
+ *
57
+ * If chunking is involved, each chunk could be logged as a separate
58
+ * SERVER_SEND_FRAGMENT in the same span.
59
+ *
60
+ * Annotation.host is not the client. It is the host which logged the send
61
+ * event, almost always the server. The actual endpoint of the client is
62
+ * recorded separately as CLIENT_ADDR when SERVER_RECV is logged.
63
+ */
64
+ const string SERVER_SEND = "ss"
65
+ /**
66
+ * The server received ("sr") a request from a client. There is only one
67
+ * request per span. For example, if duplicate responses were received, each
68
+ * can be logged as a WIRE_RECV annotation.
69
+ *
70
+ * Typically, a trace starts with a server receive, so the first timestamp of a
71
+ * trace is often the timestamp of the root span's server receive.
72
+ *
73
+ * If chunking is involved, each chunk could be logged as a separate
74
+ * SERVER_RECV_FRAGMENT in the same span.
75
+ *
76
+ * Annotation.host is not the client. It is the host which logged the receive
77
+ * event, almost always the server. When logging SERVER_RECV, instrumentation
78
+ * should also log the CLIENT_ADDR.
79
+ */
80
+ const string SERVER_RECV = "sr"
81
+ /**
82
+ * Message send ("ms") is a request to send a message to a destination, usually
83
+ * a broker. This may be the only annotation in a messaging span. If WIRE_SEND
84
+ * exists in the same span, it follows this moment and clarifies delays sending
85
+ * the message, such as batching.
86
+ *
87
+ * Unlike RPC annotations like CLIENT_SEND, messaging spans never share a span
88
+ * ID. For example, "ms" should always be the parent of "mr".
89
+ *
90
+ * Annotation.host is not the destination, it is the host which logged the send
91
+ * event: the producer. When annotating MESSAGE_SEND, instrumentation should
92
+ * also tag the MESSAGE_ADDR.
93
+ */
94
+ const string MESSAGE_SEND = "ms"
95
+ /**
96
+ * A consumer received ("mr") a message from a broker. This may be the only
97
+ * annotation in a messaging span. If WIRE_RECV exists in the same span, it
98
+ * precedes this moment and clarifies any local queuing delay.
99
+ *
100
+ * Unlike RPC annotations like SERVER_RECV, messaging spans never share a span
101
+ * ID. For example, "mr" should always be a child of "ms" unless it is a root
102
+ * span.
103
+ *
104
+ * Annotation.host is not the broker, it is the host which logged the receive
105
+ * event: the consumer. When annotating MESSAGE_RECV, instrumentation should
106
+ * also tag the MESSAGE_ADDR.
107
+ */
108
+ const string MESSAGE_RECV = "mr"
109
+ /**
110
+ * Optionally logs an attempt to send a message on the wire. Multiple wire send
111
+ * events could indicate network retries. A lag between client or server send
112
+ * and wire send might indicate queuing or processing delay.
113
+ */
114
+ const string WIRE_SEND = "ws"
115
+ /**
116
+ * Optionally logs an attempt to receive a message from the wire. Multiple wire
117
+ * receive events could indicate network retries. A lag between wire receive
118
+ * and client or server receive might indicate queuing or processing delay.
119
+ */
120
+ const string WIRE_RECV = "wr"
121
+ /**
122
+ * Optionally logs progress of a (CLIENT_SEND, WIRE_SEND). For example, this
123
+ * could be one chunk in a chunked request.
124
+ */
125
+ const string CLIENT_SEND_FRAGMENT = "csf"
126
+ /**
127
+ * Optionally logs progress of a (CLIENT_RECV, WIRE_RECV). For example, this
128
+ * could be one chunk in a chunked response.
129
+ */
130
+ const string CLIENT_RECV_FRAGMENT = "crf"
131
+ /**
132
+ * Optionally logs progress of a (SERVER_SEND, WIRE_SEND). For example, this
133
+ * could be one chunk in a chunked response.
134
+ */
135
+ const string SERVER_SEND_FRAGMENT = "ssf"
136
+ /**
137
+ * Optionally logs progress of a (SERVER_RECV, WIRE_RECV). For example, this
138
+ * could be one chunk in a chunked request.
139
+ */
140
+ const string SERVER_RECV_FRAGMENT = "srf"
141
+
142
+ #***** BinaryAnnotation.key ******
143
+ /**
144
+ * The value of "lc" is the component or namespace of a local span.
145
+ *
146
+ * BinaryAnnotation.host adds service context needed to support queries.
147
+ *
148
+ * Local Component("lc") supports three key features: flagging, query by
149
+ * service and filtering Span.name by namespace.
150
+ *
151
+ * While structurally the same, local spans are fundamentally different than
152
+ * RPC spans in how they should be interpreted. For example, zipkin v1 tools
153
+ * center on RPC latency and service graphs. Root local-spans are neither
154
+ * indicative of critical path RPC latency, nor have impact on the shape of a
155
+ * service graph. By flagging with "lc", tools can special-case local spans.
156
+ *
157
+ * Zipkin v1 Spans are unqueryable unless they can be indexed by service name.
158
+ * The only path to a service name is by (Binary)?Annotation.host.serviceName.
159
+ * By logging "lc", a local span can be queried even if no other annotations
160
+ * are logged.
161
+ *
162
+ * The value of "lc" is the namespace of Span.name. For example, it might be
163
+ * "finatra2", for a span named "bootstrap". "lc" allows you to resolves
164
+ * conflicts for the same Span.name, for example "finatra/bootstrap" vs
165
+ * "finch/bootstrap". Using local component, you'd search for spans named
166
+ * "bootstrap" where "lc=finch"
167
+ */
168
+ const string LOCAL_COMPONENT = "lc"
169
+
170
+ #***** BinaryAnnotation.key where value = [1] and annotation_type = BOOL ******
171
+ /**
172
+ * Indicates a client address ("ca") in a span. Most likely, there's only one.
173
+ * Multiple addresses are possible when a client changes its ip or port within
174
+ * a span.
175
+ */
176
+ const string CLIENT_ADDR = "ca"
177
+ /**
178
+ * Indicates a server address ("sa") in a span. Most likely, there's only one.
179
+ * Multiple addresses are possible when a client is redirected, or fails to a
180
+ * different server ip or port.
181
+ */
182
+ const string SERVER_ADDR = "sa"
183
+ /**
184
+ * Indicates the remote address of a messaging span, usually the broker.
185
+ */
186
+ const string MESSAGE_ADDR = "ma"
187
+
188
+ /**
189
+ * Indicates the network context of a service recording an annotation with two
190
+ * exceptions.
191
+ *
192
+ * When a BinaryAnnotation, and key is CLIENT_ADDR or SERVER_ADDR,
193
+ * the endpoint indicates the source or destination of an RPC. This exception
194
+ * allows zipkin to display network context of uninstrumented services, or
195
+ * clients such as web browsers.
196
+ */
197
+ struct Endpoint {
198
+ /**
199
+ * IPv4 host address packed into 4 bytes.
200
+ *
201
+ * Ex for the ip 1.2.3.4, it would be (1 << 24) | (2 << 16) | (3 << 8) | 4
202
+ */
203
+ 1: i32 ipv4
204
+ /**
205
+ * IPv4 port
206
+ *
207
+ * Note: this is to be treated as an unsigned integer, so watch for negatives.
208
+ *
209
+ * Conventionally, when the port isn't known, port = 0.
210
+ */
211
+ 2: i16 port
212
+ /**
213
+ * Service name in lowercase, such as "memcache" or "zipkin-web"
214
+ *
215
+ * Conventionally, when the service name isn't known, service_name = "unknown".
216
+ */
217
+ 3: string service_name
218
+ /**
219
+ * IPv6 host address packed into 16 bytes. Ex Inet6Address.getBytes()
220
+ */
221
+ 4: optional binary ipv6
222
+ }
223
+
224
+ /**
225
+ * An annotation is similar to a log statement. It includes a host field which
226
+ * allows these events to be attributed properly, and also aggregatable.
227
+ */
228
+ struct Annotation {
229
+ /**
230
+ * Microseconds from epoch.
231
+ *
232
+ * This value should use the most precise value possible. For example,
233
+ * gettimeofday or syncing nanoTime against a tick of currentTimeMillis.
234
+ */
235
+ 1: i64 timestamp
236
+ 2: string value // what happened at the timestamp?
237
+ /**
238
+ * Always the host that recorded the event. By specifying the host you allow
239
+ * rollup of all events (such as client requests to a service) by IP address.
240
+ */
241
+ 3: optional Endpoint host
242
+ // don't reuse 4: optional i32 OBSOLETE_duration // how long did the operation take? microseconds
243
+ }
244
+
245
+ enum AnnotationType { BOOL, BYTES, I16, I32, I64, DOUBLE, STRING }
246
+
247
+ /**
248
+ * Binary annotations are tags applied to a Span to give it context. For
249
+ * example, a binary annotation of "http.uri" could the path to a resource in a
250
+ * RPC call.
251
+ *
252
+ * Binary annotations of type STRING are always queryable, though more a
253
+ * historical implementation detail than a structural concern.
254
+ *
255
+ * Binary annotations can repeat, and vary on the host. Similar to Annotation,
256
+ * the host indicates who logged the event. This allows you to tell the
257
+ * difference between the client and server side of the same key. For example,
258
+ * the key "http.uri" might be different on the client and server side due to
259
+ * rewriting, like "/api/v1/myresource" vs "/myresource. Via the host field,
260
+ * you can see the different points of view, which often help in debugging.
261
+ */
262
+ struct BinaryAnnotation {
263
+ 1: string key,
264
+ 2: binary value,
265
+ 3: AnnotationType annotation_type,
266
+ /**
267
+ * The host that recorded tag, which allows you to differentiate between
268
+ * multiple tags with the same key. There are two exceptions to this.
269
+ *
270
+ * When the key is CLIENT_ADDR or SERVER_ADDR, host indicates the source or
271
+ * destination of an RPC. This exception allows zipkin to display network
272
+ * context of uninstrumented services, or clients such as web browsers.
273
+ */
274
+ 4: optional Endpoint host
275
+ }
276
+
277
+ /**
278
+ * A trace is a series of spans (often RPC calls) which form a latency tree.
279
+ *
280
+ * The root span is where trace_id = id and parent_id = Nil. The root span is
281
+ * usually the longest interval in the trace, starting with a SERVER_RECV
282
+ * annotation and ending with a SERVER_SEND.
283
+ */
284
+ struct Span {
285
+ 1: i64 trace_id # unique trace id, use for all spans in trace
286
+ /**
287
+ * Span name in lowercase, rpc method for example
288
+ *
289
+ * Conventionally, when the span name isn't known, name = "unknown".
290
+ */
291
+ 3: string name,
292
+ 4: i64 id, # unique span id, only used for this span
293
+ 5: optional i64 parent_id, # parent span id
294
+ 6: list<Annotation> annotations, # all annotations/events that occured, sorted by timestamp
295
+ 8: list<BinaryAnnotation> binary_annotations # any binary annotations
296
+ 9: optional bool debug = 0 # if true, we DEMAND that this span passes all samplers
297
+ /**
298
+ * Microseconds from epoch of the creation of this span.
299
+ *
300
+ * This value should be set directly by instrumentation, using the most
301
+ * precise value possible. For example, gettimeofday or syncing nanoTime
302
+ * against a tick of currentTimeMillis.
303
+ *
304
+ * For compatibilty with instrumentation that precede this field, collectors
305
+ * or span stores can derive this via Annotation.timestamp.
306
+ * For example, SERVER_RECV.timestamp or CLIENT_SEND.timestamp.
307
+ *
308
+ * This field is optional for compatibility with old data: first-party span
309
+ * stores are expected to support this at time of introduction.
310
+ */
311
+ 10: optional i64 timestamp,
312
+ /**
313
+ * Measurement of duration in microseconds, used to support queries.
314
+ *
315
+ * This value should be set directly, where possible. Doing so encourages
316
+ * precise measurement decoupled from problems of clocks, such as skew or NTP
317
+ * updates causing time to move backwards.
318
+ *
319
+ * For compatibilty with instrumentation that precede this field, collectors
320
+ * or span stores can derive this by subtracting Annotation.timestamp.
321
+ * For example, SERVER_SEND.timestamp - SERVER_RECV.timestamp.
322
+ *
323
+ * If this field is persisted as unset, zipkin will continue to work, except
324
+ * duration query support will be implementation-specific. Similarly, setting
325
+ * this field non-atomically is implementation-specific.
326
+ *
327
+ * This field is i64 vs i32 to support spans longer than 35 minutes.
328
+ */
329
+ 11: optional i64 duration
330
+ /**
331
+ * Optional unique 8-byte additional identifier for a trace. If non zero, this
332
+ * means the trace uses 128 bit traceIds instead of 64 bit.
333
+ */
334
+ 12: optional i64 trace_id_high
335
+ }
336
+
337
+ # define TChannel service
338
+
339
+ struct Response {
340
+ 1: required bool ok
341
+ }
342
+
343
+ service ZipkinCollector {
344
+ list<Response> submitZipkinBatch(1: list<Span> spans)
345
+ }