goa: goa.design/goa/middleware/xray Index | Files | Directories

package xray

import "goa.design/goa/middleware/xray"

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


Package Files

segment.go xray.go


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"

func Connect Uses

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 Uses

func NewID() string

NewID is a span ID creation algorithm which produces values that are compatible with AWS X-Ray.

func NewTraceID Uses

func NewTraceID() string

NewTraceID is a trace ID creation algorithm which produces values that are compatible with AWS X-Ray.

type Cause Uses

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 Uses

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 Uses

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 Uses

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 Uses

type Response struct {
    Status        int   `json:"status"`
    ContentLength int64 `json:"content_length"`

Response describes a HTTP response.

type Segment Uses

type Segment struct {
    // Mutex used to synchronize access to segment.
    // 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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (s *Segment) Close()

Close closes the segment by setting its EndTime.

func (*Segment) NewSubsegment Uses

func (s *Segment) NewSubsegment(name string) *Segment

NewSubsegment creates a subsegment of s.

func (*Segment) RecordError Uses

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 Uses

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:


type StackEntry Uses

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.


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

Package xray imports 10 packages (graph) and is imported by 9 packages. Updated 2020-11-09. Refresh now. Tools for package owners.