Documentation ¶
Index ¶
Constants ¶
const ( // HTTPHeaders represents SpanContexts as HTTP header string pairs. // // Unlike TextMap, the HTTPHeaders format requires that the keys and values // be valid as HTTP headers as-is (i.e., character casing may be unstable // and special characters are disallowed in keys, values should be // URL-escaped, etc). // // For Tracer.Inject(): the carrier must be a `TextMapWriter`. // // For Tracer.Extract(): the carrier must be a `TextMapReader`. // // See HTTPHeaderCarrier for an implementation of both TextMapWriter // and TextMapReader that defers to an http.Header instance for storage. // For example, Inject(): // // carrier := ctrace.HTTPHeadersCarrier(httpReq.Header) // err := span.Tracer().Inject( // span, ctrace.HTTPHeaders, carrier) // // Or Extract(): // // carrier := ctrace.HTTPHeadersCarrier(httpReq.Header) // span, err := tracer.Extract( // ctrace.HTTPHeaders, carrier) // HTTPHeaders = opentracing.HTTPHeaders // TextMap represents SpanContexts as key:value string pairs. // // Unlike HTTPHeaders, the TextMap format does not restrict the key or // value character sets in any way. // // For Tracer.Inject(): the carrier must be a `TextMapWriter`. // // For Tracer.Extract(): the carrier must be a `TextMapReader`. TextMap = opentracing.TextMap )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Extractor ¶
type Extractor interface { // Extract decodes a SpanContext instance from the given `carrier`, // or (nil, opentracing.ErrSpanContextNotFound) if no context could // be found in the `carrier`. Extract(carrier interface{}) (opentracing.SpanContext, error) }
Extractor is responsible for extracting SpanContext instances from a format-specific "carrier" object. Typically the extraction will take place on the server side of an RPC boundary, but message queues and other IPC mechanisms are also reasonable places to use an Extractor.
type HTTPHeadersCarrier ¶
type HTTPHeadersCarrier opentracing.HTTPHeadersCarrier
HTTPHeadersCarrier satisfies both TextMapWriter and TextMapReader.
Example usage for server side:
carrier := opentracing.HttpHeadersCarrier(httpReq.Header) spanContext, err := tracer.Extract(opentracing.HttpHeaders, carrier)
Example usage for client side:
carrier := opentracing.HTTPHeadersCarrier(httpReq.Header) err := tracer.Inject( span.Context(), opentracing.HttpHeaders, carrier)
func (HTTPHeadersCarrier) Set ¶
func (c HTTPHeadersCarrier) Set(key, val string)
Set implements Set() of ctrace.TextMapWriter
type Injector ¶
type Injector interface { // Inject takes `SpanContext` and injects it into `carrier`. The actual type // of `carrier` depends on the `format` passed to `Tracer.Inject()`. // // Implementations may return opentracing.ErrInvalidCarrier or any other // implementation-specific error if injection fails. Inject(ctx opentracing.SpanContext, carrier interface{}) }
Injector is responsible for injecting SpanContext instances in a manner suitable for propagation via a format-specific "carrier" object. Typically the injection will take place across an RPC boundary, but message queues and other IPC mechanisms are also reasonable places to use an Injector.
type Span ¶
type Span interface { opentracing.Span RawContext() SpanContext RawTracer() Tracer }
Span represents an active, un-finished span in the OpenTracing system.
Spans are created by the Tracer interface.
type SpanContext ¶
type SpanContext interface { opentracing.SpanContext TraceID() string SpanID() string BaggageItem(key string) string }
SpanContext represents Span state that must propagate to descendant Spans and across process boundaries (e.g., a <trace_id, span_id, sampled> tuple).
func NewSpanContext ¶
func NewSpanContext( traceID uint64, spanID uint64, baggage map[string]string, ) SpanContext
NewSpanContext creates a new SpanContext
type SpanEncoder ¶
type SpanEncoder interface { // Return the encoder to the appropriate sync.Pool. Unpooled encoder // implementations can no-op this method. Encode(opentracing.Span) []byte }
SpanEncoder is a format-agnostic interface for encoding span events.
func NewSpanEncoder ¶
func NewSpanEncoder() SpanEncoder
NewSpanEncoder creates a fast, low-allocation JSON encoder.
type SpanModel ¶
type SpanModel struct { TraceID string `json:"traceId"` SpanID string `json:"spanId"` ParentID string `json:"parentId"` Operation string `json:"operation"` Start int64 `json:"start"` Finish int64 `json:"finish"` Duration int64 `json:"duration"` Tags map[string]interface{} `json:"tags"` Logs [](map[string]interface{}) `json:"logs"` Baggage map[string]string `json:"baggage"` }
SpanModel is used for testing
type SpanReporter ¶
type SpanReporter interface {
Report(opentracing.Span)
}
SpanReporter reports the current state of a Span. It is intended to reports Start-Span, Log, and Finish-Span events.
func NewSpanReporter ¶
func NewSpanReporter(w io.Writer, e SpanEncoder) SpanReporter
NewSpanReporter creates a new default SpanReporter.
type TextMapCarrier ¶
type TextMapCarrier opentracing.TextMapCarrier
TextMapCarrier allows the use of regular map[string]string as both TextMapWriter and TextMapReader.
func (TextMapCarrier) Set ¶
func (c TextMapCarrier) Set(key, val string)
Set implements Set() of ctrace.TextMapWriter
type TextMapWriter ¶
type TextMapWriter opentracing.TextMapWriter
TextMapWriter is the Inject() carrier for the TextMap builtin format. With it, the caller can encode a SpanContext for propagation as entries in a map of unicode strings.
type Tracer ¶
type Tracer interface { opentracing.Tracer StartSpanWithOptions(string, opentracing.StartSpanOptions) opentracing.Span }
Tracer is a simple, thin interface for Span creation and SpanContext propagation.
func NewWithOptions ¶
func NewWithOptions(opts TracerOptions) Tracer
NewWithOptions creates a customized Tracer.
type TracerOptions ¶
type TracerOptions struct { // MultiEvent tells whether the tracer outputs in Single-Event or Multi-Event Mode. // See [Canonical Events](https://github.com/Nordstrom/ctrace/tree/new#canonical-events). // If MultiEvent=true, the tracer is using Multi-Event Mode which means Start-Span, Log, // and Finish-Span events are output with each containing a single log. // If MultiEvent=false (default), the tracer is using Single-Event Mode which // means only Finish-Span events are output with a collectionn of all logs for that Span. MultiEvent bool // Writer is used to write serialized trace events. It defaults to os.Stdout. Writer io.Writer // ServiceName allows the configuration of the "service" tag for the entire Tracer. // If not specified here, it can also be specified using environment variable "CTRACE_SERVICE" ServiceName string // DebugAssertSingleGoroutine internally records the ID of the goroutine // creating each Span and verifies that no operation is carried out on // it on a different goroutine. // Provided strictly for development purposes. // Passing Spans between goroutine without proper synchronization often // results in use-after-Finish() errors. For a simple example, consider the // following pseudocode: // // func (s *Server) Handle(req http.Request) error { // sp := s.StartSpan("server") // defer sp.Finish() // wait := s.queueProcessing(opentracing.ContextWithSpan(context.Background(), sp), req) // select { // case resp := <-wait: // return resp.Error // case <-time.After(10*time.Second): // sp.LogEvent("timed out waiting for processing") // return ErrTimedOut // } // } // // This looks reasonable at first, but a request which spends more than ten // seconds in the queue is abandoned by the main goroutine and its trace // finished, leading to use-after-finish when the request is finally // processed. Note also that even joining on to a finished Span via // StartSpanWithOptions constitutes an illegal operation. // // Code bases which do not require (or decide they do not want) Spans to // be passed across goroutine boundaries can run with this flag enabled in // tests to increase their chances of spotting wrong-doers. DebugAssertSingleGoroutine bool // DebugAssertUseAfterFinish is provided strictly for development purposes. // When set, it attempts to exacerbate issues emanating from use of Spans // after calling Finish by running additional assertions. DebugAssertUseAfterFinish bool }
TracerOptions allows creating a customized Tracer via NewWithOptions. The object must not be updated when there is an active tracer using it.