Documentation

Overview

    Package xray contains the AWS X-Ray segment document type populated by the transport-specific X-Ray middleware.

    Index

    Constants

    View Source
    const (
    	// SegKey is the request context key used to store the segments if any.
    	SegKey contextKey = iota + 1
    )
    View Source
    const (
    	// UDPHeader is the header of each segment sent to the daemon.
    	UDPHeader = "{\"format\": \"json\", \"version\": 1}\n"
    )

    Variables

    This section is empty.

    Functions

    func Connect

    func Connect(ctx context.Context, renewPeriod time.Duration, dial func() (net.Conn, error)) (func() net.Conn, error)

      Connect creates a goroutine to periodically re-dial a connection, so the hostname can be re-resolved if the IP changes. Returns a func that provides the latest Conn value.

      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.

          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"`
                    	// 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 an AWS X-Ray segment document.

                      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 := ctx.Value(SegKey).(*Segment)
                                      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.

                                            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.

                                                Source Files

                                                Directories

                                                Path Synopsis
                                                Package xraytest contains test helpers for package xray that are used by transport-specific X-Ray middleware tests.
                                                Package xraytest contains test helpers for package xray that are used by transport-specific X-Ray middleware tests.