xray

Documentation

Overview

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

Index

• Constants
• func Connect(ctx context.Context, renewPeriod time.Duration, dial func() (net.Conn, error)) (func() net.Conn, error)
• func NewID() string
• func NewTraceID() string
• type Cause
• type Exception
• type HTTP
• type Request
• type Response
• type 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)
  • func (s *Segment) SubmitInProgress()
• type StackEntry

Constants

const (
	// SegKey is the request context key used to store the segments if any.
	SegKey contextKey = iota + 1
)

const (
	// UDPHeader is the header of each segment sent to the daemon.
	UDPHeader = "{\"format\": \"json\", \"version\": 1}\n"
)

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,omitempty"`
	// 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]any `json:"annotations,omitempty"`
	// Metadata contains the segment metadata.
	Metadata map[string]map[string]any `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.