Documentation
¶
Overview ¶
Package zipkin_proto3 adds support for the Zipkin protobuf definition to allow Go applications to consume model.SpanModel from protobuf serialized data.
Package zipkin_proto3 is a generated protocol buffer package.
It is generated from these files:
proto/v2/zipkin.proto
It has these top-level messages:
Span Endpoint Annotation ListOfSpans
Index ¶
- Variables
- func ParseSpans(protoBlob []byte, debugWasSet bool) (zss []*zipkinmodel.SpanModel, err error)
- type Annotation
- type Endpoint
- type ListOfSpans
- type Span
- func (*Span) Descriptor() ([]byte, []int)
- func (m *Span) GetAnnotations() []*Annotation
- func (m *Span) GetDebug() bool
- func (m *Span) GetDuration() uint64
- func (m *Span) GetId() []byte
- func (m *Span) GetKind() Span_Kind
- func (m *Span) GetLocalEndpoint() *Endpoint
- func (m *Span) GetName() string
- func (m *Span) GetParentId() []byte
- func (m *Span) GetRemoteEndpoint() *Endpoint
- func (m *Span) GetShared() bool
- func (m *Span) GetTags() map[string]string
- func (m *Span) GetTimestamp() uint64
- func (m *Span) GetTraceId() []byte
- func (*Span) ProtoMessage()
- func (m *Span) Reset()
- func (m *Span) String() string
- type Span_Kind
Constants ¶
This section is empty.
Variables ¶
var Span_Kind_name = map[int32]string{
0: "SPAN_KIND_UNSPECIFIED",
1: "CLIENT",
2: "SERVER",
3: "PRODUCER",
4: "CONSUMER",
}
var Span_Kind_value = map[string]int32{
"SPAN_KIND_UNSPECIFIED": 0,
"CLIENT": 1,
"SERVER": 2,
"PRODUCER": 3,
"CONSUMER": 4,
}
Functions ¶
func ParseSpans ¶
func ParseSpans(protoBlob []byte, debugWasSet bool) (zss []*zipkinmodel.SpanModel, err error)
ParseSpans parses zipkinmodel.SpanModel values from data serialized by Protobuf3. debugWasSet is a boolean that toggles the Debug field of each Span. Its value is usually retrieved from the transport headers when the "X-B3-Flags" header has a value of 1.
Types ¶
type Annotation ¶
type Annotation struct {
// Epoch microseconds of this event.
//
// For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC
//
// This value should be set directly by instrumentation, using the most
// precise value possible. For example, gettimeofday or multiplying epoch
// millis by 1000.
Timestamp uint64 `protobuf:"fixed64,1,opt,name=timestamp" json:"timestamp,omitempty"`
// Usually a short tag indicating an event, like "error"
//
// While possible to add larger data, such as garbage collection details, low
// cardinality event names both keep the size of spans down and also are easy
// to search against.
Value string `protobuf:"bytes,2,opt,name=value" json:"value,omitempty"`
}
Associates an event that explains latency with a timestamp. Unlike log statements, annotations are often codes. Ex. "ws" for WireSend
The next id is 3.
func (*Annotation) Descriptor ¶
func (*Annotation) Descriptor() ([]byte, []int)
func (*Annotation) GetTimestamp ¶
func (m *Annotation) GetTimestamp() uint64
func (*Annotation) GetValue ¶
func (m *Annotation) GetValue() string
func (*Annotation) ProtoMessage ¶
func (*Annotation) ProtoMessage()
func (*Annotation) Reset ¶
func (m *Annotation) Reset()
func (*Annotation) String ¶
func (m *Annotation) String() string
type Endpoint ¶
type Endpoint struct {
// Lower-case label of this node in the service graph, such as "favstar".
// Leave absent if unknown.
//
// This is a primary label for trace lookup and aggregation, so it should be
// intuitive and consistent. Many use a name from service discovery.
ServiceName string `protobuf:"bytes,1,opt,name=service_name,json=serviceName" json:"service_name,omitempty"`
// 4 byte representation of the primary IPv4 address associated with this
// connection. Absent if unknown.
Ipv4 []byte `protobuf:"bytes,2,opt,name=ipv4,proto3" json:"ipv4,omitempty"`
// 16 byte representation of the primary IPv6 address associated with this
// connection. Absent if unknown.
//
// Prefer using the ipv4 field for mapped addresses.
Ipv6 []byte `protobuf:"bytes,3,opt,name=ipv6,proto3" json:"ipv6,omitempty"`
// Depending on context, this could be a listen port or the client-side of a
// socket. Absent if unknown.
Port int32 `protobuf:"varint,4,opt,name=port" json:"port,omitempty"`
}
The network context of a node in the service graph.
The next id is 5.
func (*Endpoint) Descriptor ¶
func (*Endpoint) GetServiceName ¶
func (*Endpoint) ProtoMessage ¶
func (*Endpoint) ProtoMessage()
type ListOfSpans ¶
type ListOfSpans struct {
Spans []*Span `protobuf:"bytes,1,rep,name=spans" json:"spans,omitempty"`
}
A list of spans with possibly different trace ids, in no particular order.
This is used for all transports: POST, Kafka messages etc. No other fields are expected, This message facilitates the mechanics of encoding a list, as a field number is required. The name of this type is the same in the OpenApi aka Swagger specification. https://zipkin.io/zipkin-api/#/default/post_spans
func (*ListOfSpans) Descriptor ¶
func (*ListOfSpans) Descriptor() ([]byte, []int)
func (*ListOfSpans) GetSpans ¶
func (m *ListOfSpans) GetSpans() []*Span
func (*ListOfSpans) ProtoMessage ¶
func (*ListOfSpans) ProtoMessage()
func (*ListOfSpans) Reset ¶
func (m *ListOfSpans) Reset()
func (*ListOfSpans) String ¶
func (m *ListOfSpans) String() string
type Span ¶
type Span struct {
// Randomly generated, unique identifier for a trace, set on all spans within
// it.
//
// This field is required and encoded as 8 or 16 opaque bytes.
TraceId []byte `protobuf:"bytes,1,opt,name=trace_id,json=traceId,proto3" json:"trace_id,omitempty"`
// The parent span ID or absent if this the root span in a trace.
ParentId []byte `protobuf:"bytes,2,opt,name=parent_id,json=parentId,proto3" json:"parent_id,omitempty"`
// Unique identifier for this operation within the trace.
//
// This field is required and encoded as 8 opaque bytes.
Id []byte `protobuf:"bytes,3,opt,name=id,proto3" json:"id,omitempty"`
// When present, used to interpret remote_endpoint
Kind Span_Kind `protobuf:"varint,4,opt,name=kind,enum=zipkin.proto3.Span_Kind" json:"kind,omitempty"`
// The logical operation this span represents in lowercase (e.g. rpc method).
// Leave absent if unknown.
//
// As these are lookup labels, take care to ensure names are low cardinality.
// For example, do not embed variables into the name.
Name string `protobuf:"bytes,5,opt,name=name" json:"name,omitempty"`
// Epoch microseconds of the start of this span, possibly absent if
// incomplete.
//
// For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC
//
// This value should be set directly by instrumentation, using the most
// precise value possible. For example, gettimeofday or multiplying epoch
// millis by 1000.
//
// There are three known edge-cases where this could be reported absent.
// - A span was allocated but never started (ex not yet received a timestamp)
// - The span's start event was lost
// - Data about a completed span (ex tags) were sent after the fact
Timestamp uint64 `protobuf:"fixed64,6,opt,name=timestamp" json:"timestamp,omitempty"`
// Duration in microseconds of the critical path, if known. Durations of less
// than one are rounded up. Duration of children can be longer than their
// parents due to asynchronous operations.
//
// For example 150 milliseconds is 150000 microseconds.
Duration uint64 `protobuf:"varint,7,opt,name=duration" json:"duration,omitempty"`
// The host that recorded this span, primarily for query by service name.
//
// Instrumentation should always record this. Usually, absent implies late
// data. The IP address corresponding to this is usually the site local or
// advertised service address. When present, the port indicates the listen
// port.
LocalEndpoint *Endpoint `protobuf:"bytes,8,opt,name=local_endpoint,json=localEndpoint" json:"local_endpoint,omitempty"`
// When an RPC (or messaging) span, indicates the other side of the
// connection.
//
// By recording the remote endpoint, your trace will contain network context
// even if the peer is not tracing. For example, you can record the IP from
// the "X-Forwarded-For" header or the service name and socket of a remote
// peer.
RemoteEndpoint *Endpoint `protobuf:"bytes,9,opt,name=remote_endpoint,json=remoteEndpoint" json:"remote_endpoint,omitempty"`
// Associates events that explain latency with the time they happened.
Annotations []*Annotation `protobuf:"bytes,10,rep,name=annotations" json:"annotations,omitempty"`
// Tags give your span context for search, viewing and analysis.
//
// For example, a key "your_app.version" would let you lookup traces by
// version. A tag "sql.query" isn't searchable, but it can help in debugging
// when viewing a trace.
Tags map[string]string `` /* 129-byte string literal not displayed */
// True is a request to store this span even if it overrides sampling policy.
//
// This is true when the "X-B3-Flags" header has a value of 1.
Debug bool `protobuf:"varint,12,opt,name=debug" json:"debug,omitempty"`
// different host).
Shared bool `protobuf:"varint,13,opt,name=shared" json:"shared,omitempty"`
}
A span is a single-host view of an operation. A trace is a series of spans (often RPC calls) which nest to form a latency tree. Spans are in the same trace when they share the same trace ID. The parent_id field establishes the position of one span in the tree.
The root span is where parent_id is Absent and usually has the longest duration in the trace. However, nested asynchronous work can materialize as child spans whose duration exceed the root span.
Spans usually represent remote activity such as RPC calls, or messaging producers and consumers. However, they can also represent in-process activity in any position of the trace. For example, a root span could represent a server receiving an initial client request. A root span could also represent a scheduled job that has no remote context.
Encoding notes:
Epoch timestamp are encoded fixed64 as varint would also be 8 bytes, and more expensive to encode and size. Duration is stored uint64, as often the numbers are quite small.
Default values are ok, as only natural numbers are used. For example, zero is an invalid timestamp and an invalid duration, false values for debug or shared are ignorable, and zero-length strings also coerce to null.
The next id is 14.
Note fields up to 15 take 1 byte to encode. Take care when adding new fields https://developers.google.com/protocol-buffers/docs/proto3#assigning-tags
func (*Span) Descriptor ¶
func (*Span) GetAnnotations ¶
func (m *Span) GetAnnotations() []*Annotation
func (*Span) GetDuration ¶
func (*Span) GetLocalEndpoint ¶
func (*Span) GetParentId ¶
func (*Span) GetRemoteEndpoint ¶
func (*Span) GetTimestamp ¶
func (*Span) GetTraceId ¶
func (*Span) ProtoMessage ¶
func (*Span) ProtoMessage()
type Span_Kind ¶
type Span_Kind int32
When present, kind clarifies timestamp, duration and remote_endpoint. When absent, the span is local or incomplete. Unlike client and server, there is no direct critical path latency relationship between producer and consumer spans.
const ( // Default value interpreted as absent. Span_SPAN_KIND_UNSPECIFIED Span_Kind = 0 // The span represents the client side of an RPC operation, implying the // following: // // timestamp is the moment a request was sent to the server. // duration is the delay until a response or an error was received. // remote_endpoint is the server. Span_CLIENT Span_Kind = 1 // The span represents the server side of an RPC operation, implying the // following: // // timestamp is the moment a client request was received. // duration is the delay until a response was sent or an error. // remote_endpoint is the client. Span_SERVER Span_Kind = 2 // The span represents production of a message to a remote broker, implying // the following: // // timestamp is the moment a message was sent to a destination. // duration is the delay sending the message, such as batching. // remote_endpoint is the broker. Span_PRODUCER Span_Kind = 3 // The span represents consumption of a message from a remote broker, not // time spent servicing it. For example, a message processor would be an // in-process child span of a consumer. Consumer spans imply the following: // // timestamp is the moment a message was received from an origin. // duration is the delay consuming the message, such as from backlog. // remote_endpoint is the broker. Span_CONSUMER Span_Kind = 4 )
Source Files