xray

package
v1.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 6, 2024 License: MIT Imports: 26 Imported by: 3

Documentation

Overview

Package xray provides a simple API for tracing and monitoring AWS X-Ray.

Index

Constants

View Source 
const Name = "X-Ray YA-SDK for Go"

Name records which X-Ray SDK customer uses.

View Source 
const TraceIDHeaderKey string = "x-amzn-trace-id"

TraceIDHeaderKey is the HTTP header name used for tracing.

View Source 
const Version = "1.8.0"

Version records the current X-Ray Go SDK version.

Variables

View Source 
var ServiceData = &schema.Service{
	Runtime:        runtime.Compiler,
	RuntimeVersion: runtime.Version(),
}

ServiceData is the metadata of the user service. It is used by all segments that X-Ray YA-SDK sends.

Functions

func AddAnnotationBool 

func AddAnnotationBool(ctx context.Context, key string, value bool)

AddAnnotationBool adds a boolean type annotation.

func AddAnnotationFloat64 

func AddAnnotationFloat64(ctx context.Context, key string, value float64)

AddAnnotationFloat64 adds a 64 bit integer type annotation.

func AddAnnotationInt64 

func AddAnnotationInt64(ctx context.Context, key string, value int64)

AddAnnotationInt64 adds a 64 bit integer type annotation.

func AddAnnotationString 

func AddAnnotationString(ctx context.Context, key, value string)

AddAnnotationString adds a string type annotation.

func AddAnnotationUint64 

func AddAnnotationUint64(ctx context.Context, key string, value uint64)

AddAnnotationUint64 adds a 64 bit integer type annotation.

func AddError 

func AddError(ctx context.Context, err error) bool

AddError sets the segment of the current context an error.

func AddMetadata 

func AddMetadata(ctx context.Context, key string, value any)

AddMetadata adds metadata.

func AddMetadataToNamespace 

func AddMetadataToNamespace(ctx context.Context, namespace, key string, value any)

AddMetadataToNamespace adds metadata.

func AddPanic added in v0.0.2 

func AddPanic(ctx context.Context, err any) bool

AddPanic is the shorthand of ContextSegment(ctx).AddPanic(err).

func AddPlugin 

func AddPlugin(plugin Plugin)

AddPlugin adds a plugin.

func Capture 

func Capture(ctx context.Context, name string, f func(context.Context) error) error

Capture traces the provided synchronous function by beginning and closing a subsegment around its execution.

func Configure added in v0.0.2 

func Configure(cfg *Config)

Configure replaces the default client with the cfg.

func ContextTraceID added in v1.0.0 

func ContextTraceID(ctx context.Context) string

ContextTraceID returns the trace id associated ctx.

func DetachContextSegment added in v1.2.0 

func DetachContextSegment(ctx context.Context) context.Context

DetachContextSegment returns a new context with the existing segment. All values associated with ctx are also associated with the new context. This is useful for creating background tasks which won't be cancelled when a request completes.

On Go 1.21 or later, this function is just an alias of context.WithoutCancel. Use context.WithoutCancel directly.

func NewSegmentID 

func NewSegmentID() string

NewSegmentID generates a string format of segment ID.

func NewTraceID 

func NewTraceID() string

NewTraceID generates a string format of random trace ID.

func SetAWS 

func SetAWS(ctx context.Context, awsData schema.AWS)

SetAWS sets the information about the AWS resource on which your application served the request.

func SetError 

func SetError(ctx context.Context)

SetError sets error flag.

func SetFault 

func SetFault(ctx context.Context)

SetFault sets fault flag.

func SetHTTPRequest 

func SetHTTPRequest(ctx context.Context, request *schema.HTTPRequest)

SetHTTPRequest sets the information of HTTP requests.

func SetHTTPResponse 

func SetHTTPResponse(ctx context.Context, response *schema.HTTPResponse)

SetHTTPResponse sets the information of HTTP requests.

func SetNamespace 

func SetNamespace(ctx context.Context, namespace string)

SetNamespace sets namespace

func SetSQL 

func SetSQL(ctx context.Context, sql *schema.SQL)

SetSQL sets the information of SQL queries.

func SetThrottle 

func SetThrottle(ctx context.Context)

SetThrottle sets error flag.

func SetUser 

func SetUser(ctx context.Context, user string)

SetUser sets a user id.

func WithClient 

func WithClient(ctx context.Context, client *Client) context.Context

WithClient returns new context with the client.

func WithSegment 

func WithSegment(ctx context.Context, seg *Segment) context.Context

WithSegment returns a new context with the existing segment.

Types

type Client 

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

Client is a client for AWS X-Ray daemon.

func ContextClient 

func ContextClient(ctx context.Context) *Client

ContextClient returns the client of current context.

func New 

func New(config *Config) *Client

New returns a new Client.

func (*Client) Close 

func (c *Client) Close() error

Close closes the client.

func (*Client) Emit 

func (c *Client) Emit(ctx context.Context, seg *Segment)

Emit sends seg to X-Ray daemon.

type Config 

type Config struct {
	// DaemonAddress is the address for connecting AWS X-Ray daemon.
	// It overwrites the address from the AWS_XRAY_DAEMON_ADDRESS environment value.
	// By default, the SDK uses 127.0.0.1:2000 for both trace data (UDP) and sampling (TCP).
	// The format is "address:port" or "tcp:address:port udp:address:port".
	DaemonAddress string

	// Disabled disables X-Ray tracing.
	// It overwrites the setting from the AWS_XRAY_SDK_ENABLED environment value.
	Disabled bool

	StreamingStrategy StreamingStrategy
	SamplingStrategy  sampling.Strategy

	// ContextMissingStrategy specifies the strategy to use when a segment is not associated with a context.
	ContextMissingStrategy ctxmissing.Strategy
}

Config is a configure for connecting AWS X-Ray daemon.

type NullDaemon 

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

NullDaemon receives segment documents, but ignore them.

func NewNullDaemon 

func NewNullDaemon() (context.Context, *NullDaemon)

NewNullDaemon creates new NullDaemon.

func (*NullDaemon) Close 

func (td *NullDaemon) Close()

Close shutdowns the daemon.

type Plugin 

type Plugin interface {
	// HandleSegment is called by AWS X-Ray YA-SDK
	// before submitting the root segment.
	// The document is the raw data of the segment, and plugins can rewrite it.
	HandleSegment(segment *Segment, document *schema.Segment)

	// Origin returns the type of AWS resource that the plugin detected.
	// If the plugin can't detect any type, it returns empty string.
	Origin() string
}

Plugin is the interface of AWS X-Ray plugin.

type SamplingDecision 

type SamplingDecision rune

SamplingDecision is whether or not the current segment has been sampled. 

const (
	// SamplingDecisionSampled indicates the current segment has been
	// sampled and will be sent to the X-Ray daemon.
	SamplingDecisionSampled SamplingDecision = '1'

	// SamplingDecisionNotSampled indicates the current segment has
	// not been sampled.
	SamplingDecisionNotSampled SamplingDecision = '0'

	// SamplingDecisionRequested indicates sampling decision will be
	// made by the downstream service and propagated
	// back upstream in the response.
	SamplingDecisionRequested SamplingDecision = '?'

	// SamplingDecisionUnknown indicates no sampling decision will be made.
	SamplingDecisionUnknown SamplingDecision = 0
)

type Segment 

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

Segment is a segment.

func BeginDummySegment added in v0.0.4 

func BeginDummySegment(ctx context.Context) (context.Context, *Segment)

BeginDummySegment creates a new segment that traces nothing.

func BeginSegment 

func BeginSegment(ctx context.Context, name string) (context.Context, *Segment)

BeginSegment creates a new Segment for a given name and context.

Caller should close the segment when the work is done.

func BeginSegmentAt added in v1.7.4 

func BeginSegmentAt(ctx context.Context, now time.Time, name string) (context.Context, *Segment)

BeginSegmentAt creates a new Segment for a given time, name and context.

Caller should close the segment when the work is done.

func BeginSegmentWithHeader added in v0.0.3 

func BeginSegmentWithHeader(ctx context.Context, name, header string) (context.Context, *Segment)

BeginSegmentWithHeader creates a new Segment for a given name, context, and trace header. It is used for recovering the trace context. e.g. the receiver component of Amazon SQS. https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sqs.html#xray-services-sqs-retrieving

Caller should close the segment when the work is done.

func BeginSegmentWithRequest 

func BeginSegmentWithRequest(ctx context.Context, name string, r *http.Request) (context.Context, *Segment)

BeginSegmentWithRequest creates a new Segment for a given name and context. The trace id is set by the x-amzn-trace-id header of the request.

Caller should close the segment when the work is done.

func BeginSubsegment 

func BeginSubsegment(ctx context.Context, name string) (context.Context, *Segment)

BeginSubsegment creates a new Segment for a given name and context.

Caller should close the segment when the work is done.

func BeginSubsegmentAt added in v1.7.4 

func BeginSubsegmentAt(ctx context.Context, now time.Time, name string) (context.Context, *Segment)

BeginSubsegmentAt creates a new Segment for a given time, name and context.

Caller should close the segment when the work is done.

func ContextSegment 

func ContextSegment(ctx context.Context) *Segment

ContextSegment return the segment of current context.

func (*Segment) AddAnnotationBool 

func (seg *Segment) AddAnnotationBool(key string, value bool)

AddAnnotationBool adds a boolean type annotation.

func (*Segment) AddAnnotationFloat64 

func (seg *Segment) AddAnnotationFloat64(key string, value float64)

AddAnnotationFloat64 adds a 64 bit integer type annotation.

func (*Segment) AddAnnotationInt64 

func (seg *Segment) AddAnnotationInt64(key string, value int64)

AddAnnotationInt64 adds a 64 bit integer type annotation.

func (*Segment) AddAnnotationString 

func (seg *Segment) AddAnnotationString(key, value string)

AddAnnotationString adds a string type annotation.

func (*Segment) AddAnnotationUint64 

func (seg *Segment) AddAnnotationUint64(key string, value uint64)

AddAnnotationUint64 adds a 64 bit integer type annotation.

func (*Segment) AddError 

func (seg *Segment) AddError(err error) bool

AddError sets error.

func (*Segment) AddMetadata 

func (seg *Segment) AddMetadata(key string, value any)

AddMetadata adds metadata.

func (*Segment) AddMetadataToNamespace 

func (seg *Segment) AddMetadataToNamespace(namespace, key string, value any)

AddMetadataToNamespace adds metadata.

func (*Segment) AddPanic added in v0.0.2 

func (seg *Segment) AddPanic(err any) bool

AddPanic adds the information about panic.

func (*Segment) Close 

func (seg *Segment) Close()

Close closes the segment.

func (*Segment) Namespace 

func (seg *Segment) Namespace() string

Namespace returns the namespace.

func (*Segment) Sampled 

func (seg *Segment) Sampled() bool

Sampled returns whether the current segment is sampled.

func (*Segment) SetAWS 

func (seg *Segment) SetAWS(awsData schema.AWS)

SetAWS sets the information about the AWS resource on which your application served the request.

func (*Segment) SetError 

func (seg *Segment) SetError()

SetError sets error flag.

func (*Segment) SetFault 

func (seg *Segment) SetFault()

SetFault sets fault flag.

func (*Segment) SetHTTPRequest 

func (seg *Segment) SetHTTPRequest(request *schema.HTTPRequest)

SetHTTPRequest sets the information of HTTP requests.

func (*Segment) SetHTTPResponse 

func (seg *Segment) SetHTTPResponse(response *schema.HTTPResponse)

SetHTTPResponse sets the information of HTTP requests.

func (*Segment) SetNamespace 

func (seg *Segment) SetNamespace(namespace string)

SetNamespace sets namespace

func (*Segment) SetSQL 

func (seg *Segment) SetSQL(sql *schema.SQL)

SetSQL sets the information of SQL queries.

func (*Segment) SetThrottle 

func (seg *Segment) SetThrottle()

SetThrottle sets throttle flag.

func (*Segment) SetUser 

func (seg *Segment) SetUser(user string)

SetUser sets a user id.

type StreamingStrategy 

type StreamingStrategy interface {
	StreamSegment(seg *Segment) []*schema.Segment
}

StreamingStrategy provides an interface for implementing streaming strategies.

func NewStreamingStrategyBatchAll 

func NewStreamingStrategyBatchAll() StreamingStrategy

NewStreamingStrategyBatchAll returns a streaming strategy.

func NewStreamingStrategyLimitSubsegment 

func NewStreamingStrategyLimitSubsegment(limit int) StreamingStrategy

NewStreamingStrategyLimitSubsegment returns a streaming strategy.

type TestDaemon 

type TestDaemon struct {
	// ContextMissing is callback function for the context missing strategy.
	// If it is nil, ignore context missing errors.
	ContextMissing func(ctx context.Context, v any)
	// contains filtered or unexported fields
}

TestDaemon is the mock server of AWS X-Ray daemon.

func NewTestDaemon 

func NewTestDaemon(handler http.Handler) (context.Context, *TestDaemon)

NewTestDaemon creates new TestDaemon

func (*TestDaemon) Close 

func (td *TestDaemon) Close()

Close shutdowns the daemon.

func (*TestDaemon) Recv 

func (td *TestDaemon) Recv() (*schema.Segment, error)

Recv returns the received segment.

type TraceHeader 

type TraceHeader struct {
	TraceID          string
	ParentID         string
	SamplingDecision SamplingDecision

	AdditionalData map[string]string
}

TraceHeader is the value of X-Amzn-Trace-Id.

func DownstreamHeader 

func DownstreamHeader(ctx context.Context) TraceHeader

DownstreamHeader returns a header for passing to downstream calls.

func ParseTraceHeader 

func ParseTraceHeader(s string) TraceHeader

ParseTraceHeader parses X-Amzn-Trace-Id header.

func (TraceHeader) String 

func (h TraceHeader) String() string

Source Files

View all Source files

Directories

Path Synopsis
Package ctxmissing provides the context missing strategy.
 Package ctxmissing provides the context missing strategy.
Package sampling provides the sampling strategy.
 Package sampling provides the sampling strategy.
Package schema provides types for [AWS X-Ray Segment Documents].
 Package schema provides types for [AWS X-Ray Segment Documents].
Package xraylog implements a logger with a log level, and an interface for a custom logger.
 Package xraylog implements a logger with a log level, and an interface for a custom logger.
Package xrayslog provides utilities for interfacing with the slog package.
 Package xrayslog provides utilities for interfacing with the slog package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.