Permalink
Cannot retrieve contributors at this time
Name already in use
A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
jaeger-idl/thrift/zipkincore.thrift
Go to fileThis commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
346 lines (334 sloc)
13.4 KB
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
# Copyright 2012 Twitter 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. | |
namespace cpp twitter.zipkin.thrift | |
namespace java com.twitter.zipkin.thriftjava | |
#@namespace scala com.twitter.zipkin.thriftscala | |
namespace rb Zipkin | |
namespace php Jaeger.Thrift.Agent.Zipkin | |
namespace netstd Jaeger.Thrift.Agent.Zipkin | |
namespace lua jaeger.thrift.agent | |
#************** Annotation.value ************** | |
/** | |
* The client sent ("cs") a request to a server. There is only one send per | |
* span. For example, if there's a transport error, each attempt can be logged | |
* as a WIRE_SEND annotation. | |
* | |
* If chunking is involved, each chunk could be logged as a separate | |
* CLIENT_SEND_FRAGMENT in the same span. | |
* | |
* Annotation.host is not the server. It is the host which logged the send | |
* event, almost always the client. When logging CLIENT_SEND, instrumentation | |
* should also log the SERVER_ADDR. | |
*/ | |
const string CLIENT_SEND = "cs" | |
/** | |
* The client received ("cr") a response from a server. There is only one | |
* receive per span. For example, if duplicate responses were received, each | |
* can be logged as a WIRE_RECV annotation. | |
* | |
* If chunking is involved, each chunk could be logged as a separate | |
* CLIENT_RECV_FRAGMENT in the same span. | |
* | |
* Annotation.host is not the server. It is the host which logged the receive | |
* event, almost always the client. The actual endpoint of the server is | |
* recorded separately as SERVER_ADDR when CLIENT_SEND is logged. | |
*/ | |
const string CLIENT_RECV = "cr" | |
/** | |
* The server sent ("ss") a response to a client. There is only one response | |
* per span. If there's a transport error, each attempt can be logged as a | |
* WIRE_SEND annotation. | |
* | |
* Typically, a trace ends with a server send, so the last timestamp of a trace | |
* is often the timestamp of the root span's server send. | |
* | |
* If chunking is involved, each chunk could be logged as a separate | |
* SERVER_SEND_FRAGMENT in the same span. | |
* | |
* Annotation.host is not the client. It is the host which logged the send | |
* event, almost always the server. The actual endpoint of the client is | |
* recorded separately as CLIENT_ADDR when SERVER_RECV is logged. | |
*/ | |
const string SERVER_SEND = "ss" | |
/** | |
* The server received ("sr") a request from a client. There is only one | |
* request per span. For example, if duplicate responses were received, each | |
* can be logged as a WIRE_RECV annotation. | |
* | |
* Typically, a trace starts with a server receive, so the first timestamp of a | |
* trace is often the timestamp of the root span's server receive. | |
* | |
* If chunking is involved, each chunk could be logged as a separate | |
* SERVER_RECV_FRAGMENT in the same span. | |
* | |
* Annotation.host is not the client. It is the host which logged the receive | |
* event, almost always the server. When logging SERVER_RECV, instrumentation | |
* should also log the CLIENT_ADDR. | |
*/ | |
const string SERVER_RECV = "sr" | |
/** | |
* Message send ("ms") is a request to send a message to a destination, usually | |
* a broker. This may be the only annotation in a messaging span. If WIRE_SEND | |
* exists in the same span, it follows this moment and clarifies delays sending | |
* the message, such as batching. | |
* | |
* Unlike RPC annotations like CLIENT_SEND, messaging spans never share a span | |
* ID. For example, "ms" should always be the parent of "mr". | |
* | |
* Annotation.host is not the destination, it is the host which logged the send | |
* event: the producer. When annotating MESSAGE_SEND, instrumentation should | |
* also tag the MESSAGE_ADDR. | |
*/ | |
const string MESSAGE_SEND = "ms" | |
/** | |
* A consumer received ("mr") a message from a broker. This may be the only | |
* annotation in a messaging span. If WIRE_RECV exists in the same span, it | |
* precedes this moment and clarifies any local queuing delay. | |
* | |
* Unlike RPC annotations like SERVER_RECV, messaging spans never share a span | |
* ID. For example, "mr" should always be a child of "ms" unless it is a root | |
* span. | |
* | |
* Annotation.host is not the broker, it is the host which logged the receive | |
* event: the consumer. When annotating MESSAGE_RECV, instrumentation should | |
* also tag the MESSAGE_ADDR. | |
*/ | |
const string MESSAGE_RECV = "mr" | |
/** | |
* Optionally logs an attempt to send a message on the wire. Multiple wire send | |
* events could indicate network retries. A lag between client or server send | |
* and wire send might indicate queuing or processing delay. | |
*/ | |
const string WIRE_SEND = "ws" | |
/** | |
* Optionally logs an attempt to receive a message from the wire. Multiple wire | |
* receive events could indicate network retries. A lag between wire receive | |
* and client or server receive might indicate queuing or processing delay. | |
*/ | |
const string WIRE_RECV = "wr" | |
/** | |
* Optionally logs progress of a (CLIENT_SEND, WIRE_SEND). For example, this | |
* could be one chunk in a chunked request. | |
*/ | |
const string CLIENT_SEND_FRAGMENT = "csf" | |
/** | |
* Optionally logs progress of a (CLIENT_RECV, WIRE_RECV). For example, this | |
* could be one chunk in a chunked response. | |
*/ | |
const string CLIENT_RECV_FRAGMENT = "crf" | |
/** | |
* Optionally logs progress of a (SERVER_SEND, WIRE_SEND). For example, this | |
* could be one chunk in a chunked response. | |
*/ | |
const string SERVER_SEND_FRAGMENT = "ssf" | |
/** | |
* Optionally logs progress of a (SERVER_RECV, WIRE_RECV). For example, this | |
* could be one chunk in a chunked request. | |
*/ | |
const string SERVER_RECV_FRAGMENT = "srf" | |
#***** BinaryAnnotation.key ****** | |
/** | |
* The value of "lc" is the component or namespace of a local span. | |
* | |
* BinaryAnnotation.host adds service context needed to support queries. | |
* | |
* Local Component("lc") supports three key features: flagging, query by | |
* service and filtering Span.name by namespace. | |
* | |
* While structurally the same, local spans are fundamentally different than | |
* RPC spans in how they should be interpreted. For example, zipkin v1 tools | |
* center on RPC latency and service graphs. Root local-spans are neither | |
* indicative of critical path RPC latency, nor have impact on the shape of a | |
* service graph. By flagging with "lc", tools can special-case local spans. | |
* | |
* Zipkin v1 Spans are unqueryable unless they can be indexed by service name. | |
* The only path to a service name is by (Binary)?Annotation.host.serviceName. | |
* By logging "lc", a local span can be queried even if no other annotations | |
* are logged. | |
* | |
* The value of "lc" is the namespace of Span.name. For example, it might be | |
* "finatra2", for a span named "bootstrap". "lc" allows you to resolves | |
* conflicts for the same Span.name, for example "finatra/bootstrap" vs | |
* "finch/bootstrap". Using local component, you'd search for spans named | |
* "bootstrap" where "lc=finch" | |
*/ | |
const string LOCAL_COMPONENT = "lc" | |
#***** BinaryAnnotation.key where value = [1] and annotation_type = BOOL ****** | |
/** | |
* Indicates a client address ("ca") in a span. Most likely, there's only one. | |
* Multiple addresses are possible when a client changes its ip or port within | |
* a span. | |
*/ | |
const string CLIENT_ADDR = "ca" | |
/** | |
* Indicates a server address ("sa") in a span. Most likely, there's only one. | |
* Multiple addresses are possible when a client is redirected, or fails to a | |
* different server ip or port. | |
*/ | |
const string SERVER_ADDR = "sa" | |
/** | |
* Indicates the remote address of a messaging span, usually the broker. | |
*/ | |
const string MESSAGE_ADDR = "ma" | |
/** | |
* Indicates the network context of a service recording an annotation with two | |
* exceptions. | |
* | |
* When a BinaryAnnotation, and key is CLIENT_ADDR or SERVER_ADDR, | |
* the endpoint indicates the source or destination of an RPC. This exception | |
* allows zipkin to display network context of uninstrumented services, or | |
* clients such as web browsers. | |
*/ | |
struct Endpoint { | |
/** | |
* IPv4 host address packed into 4 bytes. | |
* | |
* Ex for the ip 1.2.3.4, it would be (1 << 24) | (2 << 16) | (3 << 8) | 4 | |
*/ | |
1: i32 ipv4 | |
/** | |
* IPv4 port | |
* | |
* Note: this is to be treated as an unsigned integer, so watch for negatives. | |
* | |
* Conventionally, when the port isn't known, port = 0. | |
*/ | |
2: i16 port | |
/** | |
* Service name in lowercase, such as "memcache" or "zipkin-web" | |
* | |
* Conventionally, when the service name isn't known, service_name = "unknown". | |
*/ | |
3: string service_name | |
/** | |
* IPv6 host address packed into 16 bytes. Ex Inet6Address.getBytes() | |
*/ | |
4: optional binary ipv6 | |
} | |
/** | |
* An annotation is similar to a log statement. It includes a host field which | |
* allows these events to be attributed properly, and also aggregatable. | |
*/ | |
struct Annotation { | |
/** | |
* Microseconds from epoch. | |
* | |
* This value should use the most precise value possible. For example, | |
* gettimeofday or syncing nanoTime against a tick of currentTimeMillis. | |
*/ | |
1: i64 timestamp | |
2: string value // what happened at the timestamp? | |
/** | |
* Always the host that recorded the event. By specifying the host you allow | |
* rollup of all events (such as client requests to a service) by IP address. | |
*/ | |
3: optional Endpoint host | |
// don't reuse 4: optional i32 OBSOLETE_duration // how long did the operation take? microseconds | |
} | |
enum AnnotationType { BOOL, BYTES, I16, I32, I64, DOUBLE, STRING } | |
/** | |
* Binary annotations are tags applied to a Span to give it context. For | |
* example, a binary annotation of "http.uri" could the path to a resource in a | |
* RPC call. | |
* | |
* Binary annotations of type STRING are always queryable, though more a | |
* historical implementation detail than a structural concern. | |
* | |
* Binary annotations can repeat, and vary on the host. Similar to Annotation, | |
* the host indicates who logged the event. This allows you to tell the | |
* difference between the client and server side of the same key. For example, | |
* the key "http.uri" might be different on the client and server side due to | |
* rewriting, like "/api/v1/myresource" vs "/myresource. Via the host field, | |
* you can see the different points of view, which often help in debugging. | |
*/ | |
struct BinaryAnnotation { | |
1: string key, | |
2: binary value, | |
3: AnnotationType annotation_type, | |
/** | |
* The host that recorded tag, which allows you to differentiate between | |
* multiple tags with the same key. There are two exceptions to this. | |
* | |
* When the key is CLIENT_ADDR or SERVER_ADDR, host indicates the source or | |
* destination of an RPC. This exception allows zipkin to display network | |
* context of uninstrumented services, or clients such as web browsers. | |
*/ | |
4: optional Endpoint host | |
} | |
/** | |
* A trace is a series of spans (often RPC calls) which form a latency tree. | |
* | |
* The root span is where trace_id = id and parent_id = Nil. The root span is | |
* usually the longest interval in the trace, starting with a SERVER_RECV | |
* annotation and ending with a SERVER_SEND. | |
*/ | |
struct Span { | |
1: i64 trace_id # unique trace id, use for all spans in trace | |
/** | |
* Span name in lowercase, rpc method for example | |
* | |
* Conventionally, when the span name isn't known, name = "unknown". | |
*/ | |
3: string name, | |
4: i64 id, # unique span id, only used for this span | |
5: optional i64 parent_id, # parent span id | |
6: list<Annotation> annotations, # all annotations/events that occured, sorted by timestamp | |
8: list<BinaryAnnotation> binary_annotations # any binary annotations | |
9: optional bool debug = 0 # if true, we DEMAND that this span passes all samplers | |
/** | |
* Microseconds from epoch of the creation of this span. | |
* | |
* This value should be set directly by instrumentation, using the most | |
* precise value possible. For example, gettimeofday or syncing nanoTime | |
* against a tick of currentTimeMillis. | |
* | |
* For compatibility with instrumentation that precede this field, collectors | |
* or span stores can derive this via Annotation.timestamp. | |
* For example, SERVER_RECV.timestamp or CLIENT_SEND.timestamp. | |
* | |
* This field is optional for compatibility with old data: first-party span | |
* stores are expected to support this at time of introduction. | |
*/ | |
10: optional i64 timestamp, | |
/** | |
* Measurement of duration in microseconds, used to support queries. | |
* | |
* This value should be set directly, where possible. Doing so encourages | |
* precise measurement decoupled from problems of clocks, such as skew or NTP | |
* updates causing time to move backwards. | |
* | |
* For compatibility with instrumentation that precede this field, collectors | |
* or span stores can derive this by subtracting Annotation.timestamp. | |
* For example, SERVER_SEND.timestamp - SERVER_RECV.timestamp. | |
* | |
* If this field is persisted as unset, zipkin will continue to work, except | |
* duration query support will be implementation-specific. Similarly, setting | |
* this field non-atomically is implementation-specific. | |
* | |
* This field is i64 vs i32 to support spans longer than 35 minutes. | |
*/ | |
11: optional i64 duration | |
/** | |
* Optional unique 8-byte additional identifier for a trace. If non zero, this | |
* means the trace uses 128 bit traceIds instead of 64 bit. | |
*/ | |
12: optional i64 trace_id_high | |
} | |
# define TChannel service | |
struct Response { | |
1: required bool ok | |
} | |
service ZipkinCollector { | |
list<Response> submitZipkinBatch(1: list<Span> spans) | |
} |