zipkin_proto3

package
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 10, 2023 License: Apache-2.0 Imports: 11 Imported by: 7

Documentation

Overview

Package zipkin_proto3 adds support for the Zipkin protobuf definition to allow Go applications to consume model.SpanModel from protobuf serialized data.

Index

Constants

This section is empty.

Variables

View Source
var (
	Span_Kind_name = map[int32]string{
		0: "SPAN_KIND_UNSPECIFIED",
		1: "CLIENT",
		2: "SERVER",
		3: "PRODUCER",
		4: "CONSUMER",
	}
	Span_Kind_value = map[string]int32{
		"SPAN_KIND_UNSPECIFIED": 0,
		"CLIENT":                1,
		"SERVER":                2,
		"PRODUCER":              3,
		"CONSUMER":              4,
	}
)

Enum value maps for Span_Kind.

View Source
var File_proto_zipkin_proto3_zipkin_proto protoreflect.FileDescriptor

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,proto3" 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,proto3" json:"value,omitempty"`
	// contains filtered or unexported fields
}

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 deprecated

func (*Annotation) Descriptor() ([]byte, []int)

Deprecated: Use Annotation.ProtoReflect.Descriptor instead.

func (*Annotation) GetTimestamp

func (x *Annotation) GetTimestamp() uint64

func (*Annotation) GetValue

func (x *Annotation) GetValue() string

func (*Annotation) ProtoMessage

func (*Annotation) ProtoMessage()

func (*Annotation) ProtoReflect

func (x *Annotation) ProtoReflect() protoreflect.Message

func (*Annotation) Reset

func (x *Annotation) Reset()

func (*Annotation) String

func (x *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,proto3" 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,proto3" json:"port,omitempty"`
	// contains filtered or unexported fields
}

The network context of a node in the service graph.

The next id is 5.

func (*Endpoint) Descriptor deprecated

func (*Endpoint) Descriptor() ([]byte, []int)

Deprecated: Use Endpoint.ProtoReflect.Descriptor instead.

func (*Endpoint) GetIpv4

func (x *Endpoint) GetIpv4() []byte

func (*Endpoint) GetIpv6

func (x *Endpoint) GetIpv6() []byte

func (*Endpoint) GetPort

func (x *Endpoint) GetPort() int32

func (*Endpoint) GetServiceName

func (x *Endpoint) GetServiceName() string

func (*Endpoint) ProtoMessage

func (*Endpoint) ProtoMessage()

func (*Endpoint) ProtoReflect

func (x *Endpoint) ProtoReflect() protoreflect.Message

func (*Endpoint) Reset

func (x *Endpoint) Reset()

func (*Endpoint) String

func (x *Endpoint) String() string

type ListOfSpans

type ListOfSpans struct {
	Spans []*Span `protobuf:"bytes,1,rep,name=spans,proto3" json:"spans,omitempty"`
	// contains filtered or unexported fields
}

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 deprecated

func (*ListOfSpans) Descriptor() ([]byte, []int)

Deprecated: Use ListOfSpans.ProtoReflect.Descriptor instead.

func (*ListOfSpans) GetSpans

func (x *ListOfSpans) GetSpans() []*Span

func (*ListOfSpans) ProtoMessage

func (*ListOfSpans) ProtoMessage()

func (*ListOfSpans) ProtoReflect

func (x *ListOfSpans) ProtoReflect() protoreflect.Message

func (*ListOfSpans) Reset

func (x *ListOfSpans) Reset()

func (*ListOfSpans) String

func (x *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,proto3,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,proto3" 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,proto3" 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,proto3" 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,proto3" 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,proto3" json:"remote_endpoint,omitempty"`
	// Associates events that explain latency with the time they happened.
	Annotations []*Annotation `protobuf:"bytes,10,rep,name=annotations,proto3" 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 `` /* 150-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,proto3" json:"debug,omitempty"`
	// True if we are contributing to a span started by another tracer (ex on a
	// different host).
	Shared bool `protobuf:"varint,13,opt,name=shared,proto3" json:"shared,omitempty"`
	// contains filtered or unexported fields
}

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 deprecated

func (*Span) Descriptor() ([]byte, []int)

Deprecated: Use Span.ProtoReflect.Descriptor instead.

func (*Span) GetAnnotations

func (x *Span) GetAnnotations() []*Annotation

func (*Span) GetDebug

func (x *Span) GetDebug() bool

func (*Span) GetDuration

func (x *Span) GetDuration() uint64

func (*Span) GetId

func (x *Span) GetId() []byte

func (*Span) GetKind

func (x *Span) GetKind() Span_Kind

func (*Span) GetLocalEndpoint

func (x *Span) GetLocalEndpoint() *Endpoint

func (*Span) GetName

func (x *Span) GetName() string

func (*Span) GetParentId

func (x *Span) GetParentId() []byte

func (*Span) GetRemoteEndpoint

func (x *Span) GetRemoteEndpoint() *Endpoint

func (*Span) GetShared

func (x *Span) GetShared() bool

func (*Span) GetTags

func (x *Span) GetTags() map[string]string

func (*Span) GetTimestamp

func (x *Span) GetTimestamp() uint64

func (*Span) GetTraceId

func (x *Span) GetTraceId() []byte

func (*Span) ProtoMessage

func (*Span) ProtoMessage()

func (*Span) ProtoReflect

func (x *Span) ProtoReflect() protoreflect.Message

func (*Span) Reset

func (x *Span) Reset()

func (*Span) String

func (x *Span) String() string

type SpanSerializer

type SpanSerializer struct{}

SpanSerializer implements http.SpanSerializer

func (SpanSerializer) ContentType

func (SpanSerializer) ContentType() string

ContentType returns the ContentType needed for this encoding.

func (SpanSerializer) Serialize

func (SpanSerializer) Serialize(sms []*zipkinmodel.SpanModel) (protoBlob []byte, err error)

Serialize takes an array of zipkin SpanModel objects and serializes it to a protobuf blob.

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
)

func (Span_Kind) Descriptor

func (Span_Kind) Descriptor() protoreflect.EnumDescriptor

func (Span_Kind) Enum

func (x Span_Kind) Enum() *Span_Kind

func (Span_Kind) EnumDescriptor deprecated

func (Span_Kind) EnumDescriptor() ([]byte, []int)

Deprecated: Use Span_Kind.Descriptor instead.

func (Span_Kind) Number

func (x Span_Kind) Number() protoreflect.EnumNumber

func (Span_Kind) String

func (x Span_Kind) String() string

func (Span_Kind) Type

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL