xray

package
v1.2.1 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2017 License: MIT Imports: 14 Imported by: 117

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

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.

func WrapTransport 

func WrapTransport(rt http.RoundTripper) http.RoundTripper

WrapTransport wraps a http RoundTripper with a RoundTripper which creates subsegments of the segment in each request's context. The subsegments created this way have their namespace set to "remote". The request's ctx must be set and contain the current request segment as set by the xray middleware.

Example of how to wrap http.Client's transport: 

httpClient := &http.Client{
  Transport: WrapTransport(http.DefaultTransport),
}

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"`
	ContentLength int64  `json:"content_length"`
}

Request describes a HTTP request.

type Response 

type Response struct {
	Status        int   `json:"status"`
	ContentLength int64 `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) RecordContextResponse 

func (s *Segment) RecordContextResponse(ctx context.Context)

RecordContextResponse traces a context response if present in the context

It sets Throttle, Fault, Error and HTTP.Response

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.

func (*Segment) RecordRequest 

func (s *Segment) RecordRequest(req *http.Request, namespace string)

RecordRequest traces a request.

It sets Http.Request & Namespace (ex: "remote")

func (*Segment) RecordResponse 

func (s *Segment) RecordResponse(resp *http.Response)

RecordResponse traces a response.

It sets Throttle, Fault, Error and HTTP.Response

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.