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 (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"
)
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 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 ¶
NewSegment creates a new segment that gets written to the given connection on close.
func (*Segment) AddAnnotation ¶
AddAnnotation adds a key-value pair that can be queried by AWS X-Ray.
func (*Segment) AddBoolAnnotation ¶
AddBoolAnnotation adds a key-value pair that can be queried by AWS X-Ray.
func (*Segment) AddBoolMetadata ¶
AddBoolMetadata adds a key-value pair that can be queried by AWS X-Ray.
func (*Segment) AddInt64Annotation ¶
AddInt64Annotation adds a key-value pair that can be queried by AWS X-Ray.
func (*Segment) AddInt64Metadata ¶
AddInt64Metadata adds a key-value pair that can be queried by AWS X-Ray.
func (*Segment) AddMetadata ¶
AddMetadata adds a key-value pair to the metadata.default attribute. Metadata is not queryable, but is recorded.
func (*Segment) Capture ¶
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) NewSubsegment ¶
NewSubsegment creates a subsegment of s.
func (*Segment) RecordError ¶
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 ¶ added in v1.4.2
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.