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
    

    An X-Ray trace is limited to 500 KB of segment data (JSON) being submitted for it. See: https://aws.amazon.com/xray/pricing/

    Traces running for multiple minutes may encounter additional dynamic limits, resulting in the trace being limited to less than 500 KB. The workaround is to send less data -- fewer segments, subsegments, annotations, or metadata. And perhaps split up a single large trace into several different traces.

    Here are some observations of the relationship between trace duration and the number of bytes that could be sent successfully:

    - 49 seconds: 543 KB
    - 2.4 minutes: 51 KB
    - 6.8 minutes: 14 KB
    - 1.4 hours:   14 KB
    

    Besides those varying size limitations, a trace may be open for up to 7 days.

    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 WrapDoer

          func WrapDoer(wrapped client.Doer) client.Doer

            WrapDoer wraps a goa client Doer, and creates xray subsegments for traced requests.

            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 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"`
                        	// 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,omitempty""`
                        	// 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,omitempty""`
                        	// 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,omitempty""`
                        	// 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,omitempty""`
                        	// 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"`
                        	// 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

                                                        func (*Segment) SubmitInProgress

                                                        func (s *Segment) SubmitInProgress()

                                                          SubmitInProgress sends this in-progress segment to the AWS X-Ray daemon. This way, the segment will be immediately visible in the UI, with status "Pending". When this segment is closed, the final version will overwrite any in-progress version. This method should be called no more than once for this segment. Subsequent calls will have no effect.

                                                          See the `in_progress` docs:

                                                          https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-fields
                                                          

                                                          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.

                                                            type TestClientExpectation

                                                            type TestClientExpectation struct {
                                                            	// contains filtered or unexported fields
                                                            }

                                                              TestClientExpectation is a generic mock.

                                                              func NewTestClientExpectation

                                                              func NewTestClientExpectation() *TestClientExpectation

                                                                NewTestClientExpectation creates a new *TestClientExpectation

                                                                func (*TestClientExpectation) Expect

                                                                func (c *TestClientExpectation) Expect(fn string, e interface{})

                                                                  Expect records the request handler in the list of expected request calls.

                                                                  func (*TestClientExpectation) ExpectNTimes

                                                                  func (c *TestClientExpectation) ExpectNTimes(n int, fn string, e interface{})

                                                                    ExpectNTimes records the request handler n times in the list of expected request calls.

                                                                    func (*TestClientExpectation) Expectation

                                                                    func (c *TestClientExpectation) Expectation(fn string) interface{}

                                                                      Expectation removes the expectation for the function with the given name from the expected calls if there is one and returns it. If there is no (more) expectations for the function, it prints a warning to stderr and returns nil.

                                                                      func (*TestClientExpectation) MetExpectations

                                                                      func (c *TestClientExpectation) MetExpectations() error

                                                                        MetExpectations returns nil if there no expectation left to be called and if there is no call that was made that did not match an expectation. It returns an error describing what is left to be called or what was called with no expectation otherwise.

                                                                        type TestNetConn

                                                                        type TestNetConn struct {
                                                                        	*TestClientExpectation
                                                                        }

                                                                          TestNetConn is a mock net.Conn

                                                                          func NewTestNetConn

                                                                          func NewTestNetConn() *TestNetConn

                                                                            NewTestNetConn creates a mock net.Conn which uses expectations set by the tests to implement the behavior.

                                                                            func (*TestNetConn) Close

                                                                            func (c *TestNetConn) Close() error

                                                                              Close runs any preset expectation.

                                                                              func (*TestNetConn) LocalAddr

                                                                              func (c *TestNetConn) LocalAddr() net.Addr

                                                                                LocalAddr runs any preset expectation.

                                                                                func (*TestNetConn) Read

                                                                                func (c *TestNetConn) Read(b []byte) (n int, err error)

                                                                                  Read runs any preset expectation.

                                                                                  func (*TestNetConn) RemoteAddr

                                                                                  func (c *TestNetConn) RemoteAddr() net.Addr

                                                                                    RemoteAddr runs any preset expectation.

                                                                                    func (*TestNetConn) SetDeadline

                                                                                    func (c *TestNetConn) SetDeadline(t time.Time) error

                                                                                      SetDeadline runs any preset expectation.

                                                                                      func (*TestNetConn) SetReadDeadline

                                                                                      func (c *TestNetConn) SetReadDeadline(t time.Time) error

                                                                                        SetReadDeadline runs any preset expectation.

                                                                                        func (*TestNetConn) SetWriteDeadline

                                                                                        func (c *TestNetConn) SetWriteDeadline(t time.Time) error

                                                                                          SetWriteDeadline runs any preset expectation.

                                                                                          func (*TestNetConn) Write

                                                                                          func (c *TestNetConn) Write(b []byte) (n int, err error)

                                                                                            Write runs any preset expectation.