Documentation
¶
Index ¶
- Constants
- Variables
- type Annotation
- func (p *Annotation) GetHost() *Endpoint
- func (p *Annotation) GetTimestamp() int64
- func (p *Annotation) GetValue() string
- func (p *Annotation) IsSetHost() bool
- func (p *Annotation) Read(iprot thrift.TProtocol) error
- func (p *Annotation) String() string
- func (p *Annotation) Write(oprot thrift.TProtocol) error
- type AnnotationType
- type BinaryAnnotation
- func (p *BinaryAnnotation) GetAnnotationType() AnnotationType
- func (p *BinaryAnnotation) GetHost() *Endpoint
- func (p *BinaryAnnotation) GetKey() string
- func (p *BinaryAnnotation) GetValue() []byte
- func (p *BinaryAnnotation) IsSetHost() bool
- func (p *BinaryAnnotation) Read(iprot thrift.TProtocol) error
- func (p *BinaryAnnotation) String() string
- func (p *BinaryAnnotation) Write(oprot thrift.TProtocol) error
- type Endpoint
- type Span
- func (p *Span) GetAnnotations() []*Annotation
- func (p *Span) GetBinaryAnnotations() []*BinaryAnnotation
- func (p *Span) GetDebug() bool
- func (p *Span) GetDuration() int64
- func (p *Span) GetID() int64
- func (p *Span) GetName() string
- func (p *Span) GetParentID() int64
- func (p *Span) GetTimestamp() int64
- func (p *Span) GetTraceID() int64
- func (p *Span) IsSetDebug() bool
- func (p *Span) IsSetDuration() bool
- func (p *Span) IsSetParentID() bool
- func (p *Span) IsSetTimestamp() bool
- func (p *Span) Read(iprot thrift.TProtocol) error
- func (p *Span) String() string
- func (p *Span) Write(oprot thrift.TProtocol) error
Constants ¶
const CLIENT_ADDR = "ca"
const CLIENT_RECV = "cr"
const CLIENT_RECV_FRAGMENT = "crf"
const CLIENT_SEND = "cs"
const CLIENT_SEND_FRAGMENT = "csf"
const LOCAL_COMPONENT = "lc"
const SERVER_ADDR = "sa"
const SERVER_RECV = "sr"
const SERVER_RECV_FRAGMENT = "srf"
const SERVER_SEND = "ss"
const SERVER_SEND_FRAGMENT = "ssf"
const WIRE_RECV = "wr"
const WIRE_SEND = "ws"
Variables ¶
var GoUnusedProtection__ int
var Span_Debug_DEFAULT bool = false
var Span_Duration_DEFAULT int64
var Span_ParentID_DEFAULT int64
var Span_Timestamp_DEFAULT int64
Functions ¶
This section is empty.
Types ¶
type Annotation ¶
type Annotation struct {
Timestamp int64 `thrift:"timestamp,1" json:"timestamp"`
Value string `thrift:"value,2" json:"value"`
Host *Endpoint `thrift:"host,3" json:"host,omitempty"`
}
Associates an event that explains latency with a timestamp.
Unlike log statements, annotations are often codes: for example "sr".
Attributes:
- Timestamp: Microseconds from epoch.
This value should use the most precise value possible. For example, gettimeofday or syncing nanoTime against a tick of currentTimeMillis.
- Value: Usually a short tag indicating an event, like "sr" or "finagle.retry".
- Host: The host that recorded the value, primarily for query by service name.
func NewAnnotation ¶
func NewAnnotation() *Annotation
func (*Annotation) GetHost ¶
func (p *Annotation) GetHost() *Endpoint
func (*Annotation) GetTimestamp ¶
func (p *Annotation) GetTimestamp() int64
func (*Annotation) GetValue ¶
func (p *Annotation) GetValue() string
func (*Annotation) IsSetHost ¶
func (p *Annotation) IsSetHost() bool
func (*Annotation) String ¶
func (p *Annotation) String() string
type AnnotationType ¶
type AnnotationType int64
A subset of thrift base types, except BYTES.
const ( AnnotationType_BOOL AnnotationType = 0 AnnotationType_BYTES AnnotationType = 1 AnnotationType_I16 AnnotationType = 2 AnnotationType_I32 AnnotationType = 3 AnnotationType_I64 AnnotationType = 4 AnnotationType_DOUBLE AnnotationType = 5 AnnotationType_STRING AnnotationType = 6 )
func AnnotationTypeFromString ¶
func AnnotationTypeFromString(s string) (AnnotationType, error)
func AnnotationTypePtr ¶
func AnnotationTypePtr(v AnnotationType) *AnnotationType
func (AnnotationType) MarshalText ¶
func (p AnnotationType) MarshalText() ([]byte, error)
func (AnnotationType) String ¶
func (p AnnotationType) String() string
func (*AnnotationType) UnmarshalText ¶
func (p *AnnotationType) UnmarshalText(text []byte) error
type BinaryAnnotation ¶
type BinaryAnnotation struct {
Key string `thrift:"key,1" json:"key"`
Value []byte `thrift:"value,2" json:"value"`
AnnotationType AnnotationType `thrift:"annotation_type,3" json:"annotation_type"`
Host *Endpoint `thrift:"host,4" json:"host,omitempty"`
}
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.
Attributes:
- Key: Name used to lookup spans, such as "http.uri" or "finagle.version".
- Value: Serialized thrift bytes, in TBinaryProtocol format.
For legacy reasons, byte order is big-endian. See THRIFT-3217.
- AnnotationType: The thrift type of value, most often STRING.
annotation_type shouldn't vary for the same key.
- Host: The host that recorded value, allowing query by service name or address.
There are two exceptions: when key is "ca" or "sa", this is the source or destination of an RPC. This exception allows zipkin to display network context of uninstrumented services, such as browsers or databases.
func NewBinaryAnnotation ¶
func NewBinaryAnnotation() *BinaryAnnotation
func (*BinaryAnnotation) GetAnnotationType ¶
func (p *BinaryAnnotation) GetAnnotationType() AnnotationType
func (*BinaryAnnotation) GetHost ¶
func (p *BinaryAnnotation) GetHost() *Endpoint
func (*BinaryAnnotation) GetKey ¶
func (p *BinaryAnnotation) GetKey() string
func (*BinaryAnnotation) GetValue ¶
func (p *BinaryAnnotation) GetValue() []byte
func (*BinaryAnnotation) IsSetHost ¶
func (p *BinaryAnnotation) IsSetHost() bool
func (*BinaryAnnotation) String ¶
func (p *BinaryAnnotation) String() string
type Endpoint ¶
type Endpoint struct {
Ipv4 int32 `thrift:"ipv4,1" json:"ipv4"`
Port int16 `thrift:"port,2" json:"port"`
ServiceName string `thrift:"service_name,3" json:"service_name"`
}
Indicates the network context of a service involved in a span.
Attributes:
- Ipv4: 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
- Port: IPv4 port or 0, if unknown.
Note: this is to be treated as an unsigned integer, so watch for negatives.
- ServiceName: Classifier of a source or destination in lowercase, such as "zipkin-web".
Conventionally, when the service name isn't known, service_name = "unknown".
This is the primary parameter for trace lookup, so should be intuitive as possible, for example, matching names in service discovery.
Particularly clients may not have a reliable service name at ingest. One approach is to set service_name to "unknown" at ingest, and later assign a better label based on binary annotations, such as user agent.
var Annotation_Host_DEFAULT *Endpoint
var BinaryAnnotation_Host_DEFAULT *Endpoint
func NewEndpoint ¶
func NewEndpoint() *Endpoint
func (*Endpoint) GetServiceName ¶
type Span ¶
type Span struct {
TraceID int64 `thrift:"trace_id,1" json:"trace_id"`
// unused field # 2
Name string `thrift:"name,3" json:"name"`
ID int64 `thrift:"id,4" json:"id"`
ParentID *int64 `thrift:"parent_id,5" json:"parent_id,omitempty"`
Annotations []*Annotation `thrift:"annotations,6" json:"annotations"`
// unused field # 7
BinaryAnnotations []*BinaryAnnotation `thrift:"binary_annotations,8" json:"binary_annotations"`
Debug bool `thrift:"debug,9" json:"debug,omitempty"`
Timestamp *int64 `thrift:"timestamp,10" json:"timestamp,omitempty"`
Duration *int64 `thrift:"duration,11" json:"duration,omitempty"`
}
A trace is a series of spans (often RPC calls) which form a latency tree.
Spans are usually created by instrumentation in RPC clients or servers, but can also represent in-process activity. Annotations in spans are similar to log statements, and are sometimes created directly by application developers to indicate events of interest, such as a cache miss.
The root span is where parent_id = Nil; it usually has the longest duration in the trace.
Span identifiers are packed into i64s, but should be treated opaquely. String encoding is fixed-width lower-hex, to avoid signed interpretation.
Attributes:
- TraceID: Unique 8-byte identifier for a trace, set on all spans within it.
- Name: Span name in lowercase, rpc method for example. Conventionally, when the
span name isn't known, name = "unknown".
- ID: Unique 8-byte identifier of this span within a trace. A span is uniquely
identified in storage by (trace_id, id).
- ParentID: The parent's Span.id; absent if this the root span in a trace.
- Annotations: Associates events that explain latency with a timestamp. Unlike log
statements, annotations are often codes: for example SERVER_RECV("sr"). Annotations are sorted ascending by timestamp.
- BinaryAnnotations: Tags a span with context, usually to support query or aggregation. For
example, a binary annotation key could be "http.uri".
- Debug: True is a request to store this span even if it overrides sampling policy.
- Timestamp: Epoch microseconds of the start of this span, absent if this an incomplete
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 compatibilty 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.
Timestamp is nullable for input only. Spans without a timestamp cannot be presented in a timeline: Span stores should not output spans missing a timestamp.
There are two known edge-cases where this could be absent: both cases exist when a collector receives a span in parts and a binary annotation precedes a timestamp. This is possible when..
- The span is in-flight (ex not yet received a timestamp)
- The span's start event was lost
- Duration: Measurement in microseconds of the critical path, if known.
This value should be set directly, as opposed to implicitly via annotation timestamps. Doing so encourages precision 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.
func (*Span) GetAnnotations ¶
func (p *Span) GetAnnotations() []*Annotation
func (*Span) GetBinaryAnnotations ¶
func (p *Span) GetBinaryAnnotations() []*BinaryAnnotation
Source Files