xray

Documentation

Index

• func New(service, daemon string) (goa.Middleware, error)
• func NewID() string
• func NewTraceID() string
• func WithSegment(ctx context.Context, s *Segment) context.Context
• type Cause
• type Doer
  • func WrapClient(ctx context.Context, c *http.Client) Doer
• type Exception
• type HTTP
• type Request
• type Response
• type Segment
  • func ContextSegment(ctx context.Context) *Segment
  • func NewSegment(name, traceID, spanID string, conn net.Conn) *Segment
  • func (s *Segment) AddAnnotation(key string, value string)
  • func (s *Segment) AddBoolAnnotation(key string, value bool)
  • func (s *Segment) AddBoolMetadata(key string, value bool)
  • func (s *Segment) AddInt64Annotation(key string, value int64)
  • func (s *Segment) AddInt64Metadata(key string, value int64)
  • func (s *Segment) AddMetadata(key string, value string)
  • func (s *Segment) Capture(name string, fn func())
  • func (s *Segment) Close()
  • func (s *Segment) NewSubsegment(name string) *Segment
  • func (s *Segment) RecordError(e error)
• type StackEntry

Functions

func New

func New(service, daemon string) (goa.Middleware, error)

New returns a middleware that sends AWS X-Ray segments to the daemon running at the given address.

service is the name of the service reported to X-Ray. daemon is the hostname (including port) of the X-Ray daemon collecting the segments.

The middleware works by extracting the trace information from the context using the tracing middleware package. The tracing middleware must be mounted first on the service.

The middleware stores the request segment in the context. Use ContextSegment to retrieve it. User code can further configure the segment for example to set a service version or record an error.

User code may create child segments using the Segment NewSubsegment method for tracing requests to external services. Such segments should be closed via the Close method once the request completes. The middleware takes care of closing the top level segment. Typical usage:

segment := xray.ContextSegment(ctx)
sub := segment.NewSubsegment("external-service")
defer sub.Close()
err := client.MakeRequest()
if err != nil {
    sub.Error = xray.Wrap(err)
}
return

func NewID

func NewID() string

NewID is a span ID creation algorithm which produces values that are compatible with AWS X-Ray.

func NewTraceID

func NewTraceID() string

NewTraceID is a trace ID creation algorithm which produces values that are compatible with AWS X-Ray.

func WithSegment

func WithSegment(ctx context.Context, s *Segment) context.Context

WithSegment creates a context containing the given segment. Use ContextSegment to retrieve it.

Types

type Cause

type Cause struct {
	// ID to segment where error originated, exclusive with other
	// fields.
	ID string `json:"id,omitempty"`
	// WorkingDirectory when error occurred. Exclusive with ID.
	WorkingDirectory string `json:"working_directory,omitempty"`
	// Exceptions contains the details on the error(s) that occurred
	// when the request as processing.
	Exceptions []*Exception `json:"exceptions,omitempty"`
}

Cause list errors that happens during the request.

type Doer

type Doer interface {
	Do(*http.Request) (*http.Response, error)
}

Doer is the http Client interface.

func WrapClient

func WrapClient(ctx context.Context, c *http.Client) Doer

WrapClient wraps a http client and creates subsegments of the segment in the context for each request it makes. The subsegments created this way have their namespace set to "remote".

ctx must contain the current request segment as set by the xray middleware or the client passed as argument is returned.

type Exception

type Exception struct {
	// Message contains the error message.
	Message string `json:"message"`
	// Stack is the error stack trace as initialized via the
	// github.com/pkg/errors package.
	Stack []*StackEntry `json:"stack"`
}

Exception describes an error.

type HTTP

type HTTP struct {
	// Request contains the data reported about the incoming request.
	Request *Request `json:"request,omitempty"`
	// Response contains the data reported about the HTTP response.
	Response *Response `json:"response,omitempty"`
}

HTTP describes a HTTP request.

type Request

type Request struct {
	Method    string `json:"method,omitempty"`
	URL       string `json:"url,omitempty"`
	UserAgent string `json:"user_agent,omitempty"`
	ClientIP  string `json:"client_ip,omitempty"`
}

Request describes a HTTP request.

type Response

type Response struct {
	Status        int `json:"status"`
	ContentLength int `json:"content_length"`
}

Response describes a HTTP response.

type Segment

type Segment struct {
	// Mutex used to synchronize access to segment.
	*sync.Mutex
	// Name is the name of the service reported to X-Ray.
	Name string `json:"name"`
	// Namespace identifies the source that created the segment.
	Namespace string `json:"namespace"`
	// Type is either the empty string or "subsegment".
	Type string `json:"type,omitempty"`
	// ID is a unique ID for the segment.
	ID string `json:"id"`
	// TraceID is the ID of the root trace.
	TraceID string `json:"trace_id,omitempty"`
	// ParentID is the ID of the parent segment when it is from a
	// remote service. It is only initialized for the root segment.
	ParentID string `json:"parent_id,omitempty"`
	// StartTime is the segment start time.
	StartTime float64 `json:"start_time,omitempty"`
	// EndTime is the segment end time.
	EndTime float64 `json:"end_time,omitempty"`
	// InProgress is true if the segment hasn't completed yet.
	InProgress bool `json:"in_progress"`
	// HTTP contains the HTTP request and response information and is
	// only initialized for the root segment.
	HTTP *HTTP `json:"http,omitempty"`
	// Cause contains information about an error that occurred while
	// processing the request.
	Cause *Cause `json:"cause,omitempty"`
	// Error is true when a request causes an internal error. It is
	// automatically set by Close when the response status code is
	// 500 or more.
	Error bool `json:"error"`
	// Fault is true when a request results in an error that is due
	// to the user. Typically it should be set when the response
	// status code is between 400 and 500 (but not 429).
	Fault bool `json:"fault"`
	// Throttle is true when a request is throttled. It is set to
	// true when the segment closes and the response status code is
	// 429. Client code may set it to true manually as well.
	Throttle bool `json:"throttle"`
	// Annotations contains the segment annotations.
	Annotations map[string]interface{} `json:"annotations,omitempty"`
	// Metadata contains the segment metadata.
	Metadata map[string]map[string]interface{} `json:"metadata,omitempty"`
	// Subsegments contains all the subsegments.
	Subsegments []*Segment `json:"subsegments,omitempty"`
	// Parent is the subsegment parent, it's nil for the root
	// segment.
	Parent *Segment `json:"-"`
	// contains filtered or unexported fields
}

Segment represents a AWS X-Ray segment document.

func ContextSegment

func ContextSegment(ctx context.Context) *Segment

ContextSegment extracts the segment set in the context with WithSegment.

func NewSegment

func NewSegment(name, traceID, spanID string, conn net.Conn) *Segment

NewSegment creates a new segment that gets written to the given connection on close.

func (*Segment) AddAnnotation

func (s *Segment) AddAnnotation(key string, value string)

AddAnnotation adds a key-value pair that can be queried by AWS X-Ray.

func (*Segment) AddBoolAnnotation

func (s *Segment) AddBoolAnnotation(key string, value bool)

AddBoolAnnotation adds a key-value pair that can be queried by AWS X-Ray.

func (*Segment) AddBoolMetadata

func (s *Segment) AddBoolMetadata(key string, value bool)

AddBoolMetadata adds a key-value pair that can be queried by AWS X-Ray.

func (*Segment) AddInt64Annotation

func (s *Segment) AddInt64Annotation(key string, value int64)

AddInt64Annotation adds a key-value pair that can be queried by AWS X-Ray.

func (*Segment) AddInt64Metadata

func (s *Segment) AddInt64Metadata(key string, value int64)

AddInt64Metadata adds a key-value pair that can be queried by AWS X-Ray.

func (*Segment) AddMetadata

func (s *Segment) AddMetadata(key string, value string)

AddMetadata adds a key-value pair to the metadata.default attribute. Metadata is not queryable, but is recorded.

func (*Segment) Capture

func (s *Segment) Capture(name string, fn func())

Capture creates a subsegment to record the execution of the given function. Usage:

s := xray.ContextSegment(ctx)
s.Capture("slow-func", func() {
    // ... some long executing code
})

func (*Segment) Close

func (s *Segment) Close()

Close closes the segment by setting its EndTime.

func (*Segment) NewSubsegment

func (s *Segment) NewSubsegment(name string) *Segment

NewSubsegment creates a subsegment of s.

func (*Segment) RecordError

func (s *Segment) RecordError(e error)

RecordError traces an error. The client may also want to initialize the fault field of s.

The trace contains a stack trace and a cause for the error if the argument was created using one of the New, Errorf, Wrap or Wrapf functions of the github.com/pkg/errors package. Otherwise the Stack and Cause fields are empty.

type StackEntry

type StackEntry struct {
	// Path to code file
	Path string `json:"path"`
	// Line number
	Line int `json:"line"`
	// Label is the line label if any
	Label string `json:"label,omitempty"`
}

StackEntry represents an entry in a error stacktrace.