xray

package
v1.1.4 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 2026 License: MIT Imports: 26 Imported by: 0

README

X-Ray

Parity grade: A · SDK aws-sdk-go-v2/service/xray@v1.36.20 · last audited 2026-07-12 (980dbe22)

Coverage

Metric Value
Operations audited 38 (33 ok, 5 deferred)
Feature families 3 (3 ok)
Known gaps 3
Deferred items 1
Resource leaks clean
Known gaps
  • PutTelemetryRecords ring buffer (100 entries) not persisted across restart; low-risk, AWS telemetry data itself is operational/ephemeral by nature (no bd issue filed, judged not worth tracking)
  • resourceTags (TagResource/UntagResource/ListTagsForResource) not included in backendSnapshot; tags on X-Ray groups/sampling-rules are lost across a gopherstack restart. Pre-existing gap, out of this pass's ~2000 LOC budget after the route-matcher + traceSegmentDest fixes. Worth a follow-up bd issue if tag persistence matters for a user's workflow.
  • Insight.Categories, ClientRequestImpactStatistics, RootCauseServiceId/RequestImpactStatistics, GetInsightImpactGraph's Services always empty/unset -- gopherstack's insight detector (detectInsights in backend.go) is a simple fault-rate-threshold heuristic and never populates these AWS anomaly-detection-derived fields. Real bug or intentional scope limit? Judged intentional: replicating AWS's actual insight-impact-graph algorithm is out of scope for an emulator's insight feature, which itself is best-effort.
Deferred
  • none; all routed ops covered by ops/families above

More

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrGroupNotFound is returned when an X-Ray group is not found.
	ErrGroupNotFound = awserr.New("InvalidRequestException", awserr.ErrNotFound)
	// ErrGroupAlreadyExists is returned when an X-Ray group already exists.
	ErrGroupAlreadyExists = awserr.New("GroupAlreadyExistsException", awserr.ErrConflict)
	// ErrSamplingRuleNotFound is returned when a sampling rule is not found.
	ErrSamplingRuleNotFound = awserr.New("InvalidRequestException", awserr.ErrNotFound)
	// ErrSamplingRuleAlreadyExists is returned when a sampling rule already exists.
	ErrSamplingRuleAlreadyExists = awserr.New("RuleAlreadyExistsException", awserr.ErrConflict)
	// ErrInsightNotFound is returned when an X-Ray insight is not found.
	ErrInsightNotFound = awserr.New("InvalidRequestException", awserr.ErrNotFound)
	// ErrResourcePolicyNotFound is returned when a resource policy is not found.
	ErrResourcePolicyNotFound = awserr.New("InvalidRequestException", awserr.ErrNotFound)
	// ErrIndexingRuleNotFound is returned when an indexing rule is not found.
	ErrIndexingRuleNotFound = awserr.New("InvalidRequestException", awserr.ErrNotFound)
	// ErrValidation is returned when a request fails field-level validation.
	ErrValidation = awserr.New("InvalidRequestException", awserr.ErrInvalidParameter)
	// ErrInvalidSamplingRule is returned when sampling rule fields fail validation.
	ErrInvalidSamplingRule = awserr.New("InvalidSamplingRuleException", awserr.ErrInvalidParameter)
	// ErrInvalidPolicyRevisionID is returned when a policy revision ID does not match.
	ErrInvalidPolicyRevisionID = awserr.New("InvalidPolicyRevisionIdException", awserr.ErrConflict)
	// ErrMalformedPolicyDocument is returned when a policy document is not valid JSON.
	ErrMalformedPolicyDocument = awserr.New("MalformedPolicyDocumentException", awserr.ErrInvalidParameter)
	// ErrTooManyPolicies is returned when the max policy count is exceeded.
	ErrTooManyPolicies = awserr.New("InvalidRequestException", awserr.ErrInvalidParameter)
	// ErrBatchGetTracesLimit is returned when more than 5 trace IDs are requested.
	ErrBatchGetTracesLimit = awserr.New("InvalidRequestException", awserr.ErrInvalidParameter)
	// ErrDefaultRuleUndeletable is returned when the built-in Default sampling rule is deleted.
	ErrDefaultRuleUndeletable = awserr.New("InvalidRequestException", awserr.ErrInvalidParameter)
)
View Source 
var ErrNilAppContext = errors.New("xray: nil app context")

ErrNilAppContext is returned when Init is called with a nil AppContext.

Functions

func EvaluateFilter 

func EvaluateFilter(expr string, summary TraceSummaryData) bool

EvaluateFilter is exported for tests.

func ValidateSamplingRule 

func ValidateSamplingRule(rule SamplingRule) error

ValidateSamplingRule validates sampling rule fields per AWS constraints.

Types

type ConfigProvider 

type ConfigProvider interface {
	GetXRaySettings() Settings
}

ConfigProvider is a private interface to extract X-Ray configuration from the abstract AppContext Config.

type EncryptionConfig 

type EncryptionConfig struct {
	KeyID  string `json:"KeyId,omitempty"`
	Status string `json:"Status"`
	Type   string `json:"Type"`
}

EncryptionConfig represents X-Ray encryption configuration.

type Group 

type Group struct {
	CreatedAt             time.Time             `json:"createdAt"`
	GroupARN              string                `json:"groupARN"`
	GroupName             string                `json:"groupName"`
	FilterExpression      string                `json:"filterExpression"`
	InsightsConfiguration InsightsConfiguration `json:"insightsConfiguration"`
}

Group represents an X-Ray group used to filter trace data.

type Handler 

type Handler struct {
	Backend StorageBackend
	// contains filtered or unexported fields
}

Handler is the Echo HTTP handler for AWS X-Ray operations.

func NewHandler 

func NewHandler(backend StorageBackend) *Handler

NewHandler creates a new X-Ray handler backed by backend.

func (*Handler) ChaosOperations 

func (h *Handler) ChaosOperations() []string

ChaosOperations returns all operations that can be fault-injected.

func (*Handler) ChaosRegions 

func (h *Handler) ChaosRegions() []string

ChaosRegions returns all regions this X-Ray instance handles.

func (*Handler) ChaosServiceName 

func (h *Handler) ChaosServiceName() string

ChaosServiceName returns the lowercase AWS service name for fault rule matching.

func (*Handler) ExtractOperation 

func (h *Handler) ExtractOperation(c *echo.Context) string

ExtractOperation extracts the X-Ray operation name from the request path.

func (*Handler) ExtractResource 

func (h *Handler) ExtractResource(c *echo.Context) string

ExtractResource extracts the primary resource identifier from the request body.

func (*Handler) GetSupportedOperations 

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations returns the list of supported X-Ray operations.

func (*Handler) Handler 

func (h *Handler) Handler() echo.HandlerFunc

Handler returns the Echo handler function for X-Ray requests.

func (*Handler) MatchPriority 

func (h *Handler) MatchPriority() int

MatchPriority returns the routing priority.

func (*Handler) Name 

func (h *Handler) Name() string

Name returns the service name.

func (*Handler) Reset 

func (h *Handler) Reset()

Reset clears all backend state.

func (*Handler) Restore 

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable by delegating to the backend.

func (*Handler) RouteMatcher 

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher returns a function that matches X-Ray REST API requests. X-Ray uses POST with specific well-known paths, except /EncryptionConfig which also accepts GET.

func (*Handler) Snapshot 

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable by delegating to the backend.

func (*Handler) StartWorker 

func (h *Handler) StartWorker(ctx context.Context) error

StartWorker starts the background janitor if configured.

func (*Handler) WithJanitor 

func (h *Handler) WithJanitor(interval, ttl time.Duration, taskTimeout ...time.Duration) *Handler

WithJanitor attaches a background janitor to the handler. The optional taskTimeout variadic parameter sets TaskTimeout on the janitor. If Backend is not an *InMemoryBackend the call is a no-op.

type InMemoryBackend 

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

InMemoryBackend is the in-memory store for X-Ray resources.

func NewInMemoryBackend 

func NewInMemoryBackend(accountID, region string) *InMemoryBackend

NewInMemoryBackend creates a new InMemoryBackend with the given accountID and region.

func (*InMemoryBackend) AddInsightEventInternal 

func (b *InMemoryBackend) AddInsightEventInternal(event InsightEvent)

AddInsightEventInternal seeds an event for an insight directly for testing.

func (*InMemoryBackend) AddInsightInternal 

func (b *InMemoryBackend) AddInsightInternal(insight Insight)

AddInsightInternal seeds an insight directly for testing.

func (*InMemoryBackend) AddResourcePolicyInternal 

func (b *InMemoryBackend) AddResourcePolicyInternal(policy ResourcePolicy)

AddResourcePolicyInternal seeds a resource policy directly for testing.

func (*InMemoryBackend) AddTraceRetrievalInternal 

func (b *InMemoryBackend) AddTraceRetrievalInternal(retrieval TraceRetrieval)

AddTraceRetrievalInternal seeds a trace retrieval token directly for testing.

func (*InMemoryBackend) CancelTraceRetrieval 

func (b *InMemoryBackend) CancelTraceRetrieval(retrievalToken string)

CancelTraceRetrieval marks a trace retrieval as cancelled. If the token is not found the operation is a no-op (idempotent).

func (*InMemoryBackend) CreateGroup 

func (b *InMemoryBackend) CreateGroup(name, filterExpr string) (*Group, error)

CreateGroup creates a new X-Ray group with the given name and filter expression.

func (*InMemoryBackend) CreateGroupWithInsights 

func (b *InMemoryBackend) CreateGroupWithInsights(name, filterExpr string, ic InsightsConfiguration) (*Group, error)

CreateGroupWithInsights creates a new group with full InsightsConfiguration.

func (*InMemoryBackend) CreateSamplingRule 

func (b *InMemoryBackend) CreateSamplingRule(rule SamplingRule) (*SamplingRule, error)

CreateSamplingRule creates a new sampling rule.

func (*InMemoryBackend) DeleteGroup 

func (b *InMemoryBackend) DeleteGroup(name string) error

DeleteGroup removes the group with the given name.

func (*InMemoryBackend) DeleteGroupByARN 

func (b *InMemoryBackend) DeleteGroupByARN(name, arn string) error

DeleteGroupByARN removes the group with the given ARN or name.

func (*InMemoryBackend) DeleteResourcePolicy 

func (b *InMemoryBackend) DeleteResourcePolicy(policyName string) error

DeleteResourcePolicy removes the resource policy with the given name.

func (*InMemoryBackend) DeleteSamplingRule 

func (b *InMemoryBackend) DeleteSamplingRule(ruleName string) (*SamplingRule, error)

DeleteSamplingRule removes the sampling rule with the given name and returns it. The built-in "Default" rule cannot be deleted; attempting to do so returns ErrDefaultRuleUndeletable.

func (*InMemoryBackend) GetAllParsedSegments 

func (b *InMemoryBackend) GetAllParsedSegments() map[string][]*Segment

GetAllParsedSegments returns all parsed segments, keyed by trace ID.

func (*InMemoryBackend) GetEncryptionConfig 

func (b *InMemoryBackend) GetEncryptionConfig() *EncryptionConfig

GetEncryptionConfig returns the current X-Ray encryption configuration. If the current status is UPDATING, this call advances it to ACTIVE.

func (*InMemoryBackend) GetGroup 

func (b *InMemoryBackend) GetGroup(name string) (*Group, error)

GetGroup returns the group with the given name, or by ARN if name is empty.

func (*InMemoryBackend) GetGroupByARN 

func (b *InMemoryBackend) GetGroupByARN(arn string) (*Group, error)

GetGroupByARN returns the group with the given ARN.

func (*InMemoryBackend) GetGroups 

func (b *InMemoryBackend) GetGroups() []Group

GetGroups returns all groups sorted by name.

func (*InMemoryBackend) GetIndexingRules 

func (b *InMemoryBackend) GetIndexingRules() []*IndexingRule

GetIndexingRules returns all indexing rules.

func (*InMemoryBackend) GetInsight 

func (b *InMemoryBackend) GetInsight(insightID string) (*Insight, error)

GetInsight returns the insight with the given ID.

func (*InMemoryBackend) GetInsightEvents 

func (b *InMemoryBackend) GetInsightEvents(insightID string) ([]*InsightEvent, error)

GetInsightEvents returns all events for the given insight ID.

func (*InMemoryBackend) GetInsightSummaries 

func (b *InMemoryBackend) GetInsightSummaries(states []string) ([]Insight, error)

GetInsightSummaries returns all insights as summaries, optionally filtered by state. If states is empty, all insights are returned. "ALL" matches both ACTIVE and CLOSED. Unknown states return ErrValidation.

func (*InMemoryBackend) GetParsedSegments 

func (b *InMemoryBackend) GetParsedSegments(traceID string) []*Segment

GetParsedSegments returns a copy of the parsed segments for a given trace ID.

func (*InMemoryBackend) GetRetrievedTracesGraph 

func (b *InMemoryBackend) GetRetrievedTracesGraph(retrievalToken string) (string, []*Trace)

GetRetrievedTracesGraph returns the status and services for a retrieval token. If the token is not found a COMPLETE status is returned.

func (*InMemoryBackend) GetSamplingRules 

func (b *InMemoryBackend) GetSamplingRules() []SamplingRule

GetSamplingRules returns all sampling rules sorted by priority (ascending), then by name for stability.

func (*InMemoryBackend) GetSamplingStatisticSummaries 

func (b *InMemoryBackend) GetSamplingStatisticSummaries() []SamplingStatisticSummary

GetSamplingStatisticSummaries returns accumulated sampling statistic summaries.

func (*InMemoryBackend) GetSamplingTargets 

func (b *InMemoryBackend) GetSamplingTargets(
	docs []SamplingStatisticsDocument,
) ([]SamplingTargetResult, []UnprocessedStatisticsResult)

GetSamplingTargets returns target documents for the provided stat documents. Rules that do not exist are returned in the unprocessed list. Documents with an empty ClientID are returned in the unprocessed list. Statistics from known rules are accumulated for GetSamplingStatisticSummaries.

func (*InMemoryBackend) GetServiceGraph 

func (b *InMemoryBackend) GetServiceGraph(startTime, endTime time.Time) []map[string]any

GetServiceGraph returns a service graph derived from stored traces in the time window.

func (*InMemoryBackend) GetTimeSeriesServiceStatistics 

func (b *InMemoryBackend) GetTimeSeriesServiceStatistics(startTime, endTime time.Time, period int) []map[string]any

GetTimeSeriesServiceStatistics returns per-period bucketed statistics for segments in the time window.

func (*InMemoryBackend) GetTrace 

func (b *InMemoryBackend) GetTrace(traceID string) *Trace

GetTrace returns the trace with the given ID, or nil if not found.

func (*InMemoryBackend) GetTraceGraph 

func (b *InMemoryBackend) GetTraceGraph(traceIDs []string) []map[string]any

GetTraceGraph returns a service graph scoped to the given trace IDs.

func (*InMemoryBackend) GetTraceSegmentDestination 

func (b *InMemoryBackend) GetTraceSegmentDestination() string

GetTraceSegmentDestination returns the current trace segment destination.

func (*InMemoryBackend) GetTraceSummaries 

func (b *InMemoryBackend) GetTraceSummaries() []Trace

GetTraceSummaries returns all trace summaries sorted by start time (newest first).

func (*InMemoryBackend) LastRuleModification 

func (b *InMemoryBackend) LastRuleModification() time.Time

LastRuleModification returns the timestamp of the last sampling rule modification.

func (*InMemoryBackend) ListResourcePolicies 

func (b *InMemoryBackend) ListResourcePolicies() []ResourcePolicy

ListResourcePolicies returns all resource policies sorted by name.

func (*InMemoryBackend) ListRetrievedTraces 

func (b *InMemoryBackend) ListRetrievedTraces(retrievalToken string) (string, []*Trace)

ListRetrievedTraces returns the status and traces associated with a retrieval token.

func (*InMemoryBackend) ListTagsForResource 

func (b *InMemoryBackend) ListTagsForResource(resourceARN string) []map[string]string

ListTagsForResource returns all tags for the given resource ARN as a slice of key/value maps.

func (*InMemoryBackend) PutEncryptionConfig 

func (b *InMemoryBackend) PutEncryptionConfig(encType, keyID string) (*EncryptionConfig, error)

PutEncryptionConfig updates the X-Ray encryption configuration. encType must be one of "NONE" or "KMS". keyID is only used when encType is "KMS". When encType is KMS the keyID must match alias/..., ARN, or UUID format. The status is initially set to UPDATING; the next GET will advance it to ACTIVE.

func (*InMemoryBackend) PutResourcePolicy 

func (b *InMemoryBackend) PutResourcePolicy(policyName, policyDocument, revisionID string) (*ResourcePolicy, error)

PutResourcePolicy creates or updates a resource policy with the given name and document. Returns ErrTooManyPolicies if the account already has maxResourcePolicies. Returns ErrInvalidPolicyRevisionID if revisionID doesn't match the stored one. Returns ErrMalformedPolicyDocument if policyDocument is not valid JSON.

func (*InMemoryBackend) PutTelemetryRecords 

func (b *InMemoryBackend) PutTelemetryRecords(records []TelemetryRecord)

PutTelemetryRecords stores telemetry records in a ring buffer.

func (*InMemoryBackend) PutTraceSegments 

func (b *InMemoryBackend) PutTraceSegments(segments []string) []string

PutTraceSegments stores raw segment JSON strings, parses them into typed Segment structs, and returns the list of unprocessed segment IDs (empty slice means all segments were accepted).

func (*InMemoryBackend) Reset 

func (b *InMemoryBackend) Reset()

Reset clears all backend state, resetting to an empty store.

func (*InMemoryBackend) Restore 

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore loads backend state from a JSON snapshot.

func (*InMemoryBackend) Snapshot 

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serialises the backend state to JSON.

func (*InMemoryBackend) StartTraceRetrieval 

func (b *InMemoryBackend) StartTraceRetrieval(traceIDs []string) string

StartTraceRetrieval creates a new retrieval job for the given trace IDs and returns a token.

func (*InMemoryBackend) TagResource 

func (b *InMemoryBackend) TagResource(resourceARN string, tags map[string]string)

TagResource adds or updates tags on a resource identified by ARN. Tags are stored in a per-ARN map on the backend.

func (*InMemoryBackend) UntagResource 

func (b *InMemoryBackend) UntagResource(resourceARN string, tagKeys []string)

UntagResource removes the specified tag keys from a resource.

func (*InMemoryBackend) UpdateGroup 

func (b *InMemoryBackend) UpdateGroup(name, filterExpr string) (*Group, error)

UpdateGroup updates the filter expression for the group with the given name.

func (*InMemoryBackend) UpdateGroupByARN 

func (b *InMemoryBackend) UpdateGroupByARN(name, arn, filterExpr string) (*Group, error)

UpdateGroupByARN updates a group by ARN or name.

func (*InMemoryBackend) UpdateIndexingRule 

func (b *InMemoryBackend) UpdateIndexingRule(name string) (*IndexingRule, error)

UpdateIndexingRule updates the named indexing rule's ModifiedAt timestamp. Returns ErrIndexingRuleNotFound if no rule with that name exists.

func (*InMemoryBackend) UpdateSamplingRule 

func (b *InMemoryBackend) UpdateSamplingRule(ruleName string, updates SamplingRule) (*SamplingRule, error)

UpdateSamplingRule updates the mutable fields of an existing sampling rule. It accepts a SamplingRule struct where non-zero values are applied (legacy API).

func (*InMemoryBackend) UpdateSamplingRuleWithPointers 

func (b *InMemoryBackend) UpdateSamplingRuleWithPointers(
	ruleName string,
	updates SamplingRuleUpdate,
) (*SamplingRule, error)

UpdateSamplingRuleWithPointers applies pointer-semantic updates so zero values apply.

func (*InMemoryBackend) UpdateTraceSegmentDestination 

func (b *InMemoryBackend) UpdateTraceSegmentDestination(destination string) string

UpdateTraceSegmentDestination sets the trace segment destination and returns it.

type IndexingRule 

type IndexingRule struct {
	ModifiedAt time.Time `json:"modifiedAt"`
	Name       string    `json:"name"`
}

IndexingRule represents an X-Ray CloudWatch Logs indexing rule.

type Insight 

type Insight struct {
	StartTime time.Time `json:"startTime"`
	EndTime   time.Time `json:"endTime,omitzero"`
	InsightID string    `json:"insightId"`
	GroupARN  string    `json:"groupARN"`
	GroupName string    `json:"groupName"`
	State     string    `json:"state"`
	Summary   string    `json:"summary"`
}

Insight represents an X-Ray insight.

type InsightEvent 

type InsightEvent struct {
	EventTime time.Time `json:"eventTime"`
	InsightID string    `json:"insightId"`
	Summary   string    `json:"summary"`
}

InsightEvent represents an event within an X-Ray insight.

type InsightsConfiguration 

type InsightsConfiguration struct {
	InsightsEnabled      bool `json:"InsightsEnabled"`
	NotificationsEnabled bool `json:"NotificationsEnabled"`
}

InsightsConfiguration holds insight notification/notification settings for a group.

type Janitor 

type Janitor struct {
	Backend  *InMemoryBackend
	Interval time.Duration
	TraceTTL time.Duration
	// TaskTimeout bounds each individual janitor task. When non-zero, each task
	// runs with a child context that expires after this duration, preventing a
	// stalled operation from blocking the janitor loop indefinitely.
	TaskTimeout time.Duration
}

Janitor is the X-Ray background worker that evicts old traces to prevent unbounded growth of in-memory state.

func NewJanitor 

func NewJanitor(backend *InMemoryBackend, interval, traceTTL time.Duration) *Janitor

NewJanitor creates a new X-Ray Janitor for the given backend. Zero values for interval or traceTTL fall back to defaults.

func (*Janitor) Run 

func (j *Janitor) Run(ctx context.Context)

Run runs the janitor loop until ctx is cancelled.

func (*Janitor) SweepOnce 

func (j *Janitor) SweepOnce(ctx context.Context)

SweepOnce runs a single sweep pass. Exposed for testing.

type Provider 

type Provider struct{}

Provider implements service.Provider for the X-Ray service.

func (*Provider) Init 

func (p *Provider) Init(ctx *service.AppContext) (service.Registerable, error)

Init initializes the X-Ray service backend and handler.

func (*Provider) Name 

func (p *Provider) Name() string

Name returns the logical name of the provider.

type ResourcePolicy 

type ResourcePolicy struct {
	PolicyName       string `json:"policyName"`
	PolicyDocument   string `json:"policyDocument"`
	PolicyRevisionID string `json:"policyRevisionId"`
}

ResourcePolicy represents a resource-based policy attached to the X-Ray account.

type SamplingRule 

type SamplingRule struct {
	CreatedAt     time.Time         `json:"createdAt"`
	ModifiedAt    time.Time         `json:"modifiedAt"`
	Attributes    map[string]string `json:"attributes,omitempty"`
	RuleARN       string            `json:"ruleARN"`
	RuleName      string            `json:"ruleName"`
	ResourceARN   string            `json:"resourceARN"`
	ServiceName   string            `json:"serviceName"`
	ServiceType   string            `json:"serviceType"`
	Host          string            `json:"host"`
	HTTPMethod    string            `json:"httpMethod"`
	URLPath       string            `json:"urlPath"`
	FixedRate     float64           `json:"fixedRate"`
	Priority      int32             `json:"priority"`
	ReservoirSize int32             `json:"reservoirSize"`
}

SamplingRule represents an X-Ray sampling rule that controls the rate of data collection.

type SamplingRuleUpdate 

type SamplingRuleUpdate struct {
	ResourceARN   *string
	ServiceName   *string
	ServiceType   *string
	Host          *string
	HTTPMethod    *string
	URLPath       *string
	FixedRate     *float64
	Priority      *int32
	ReservoirSize *int32
}

SamplingRuleUpdate holds pointer-semantic updates for UpdateSamplingRule. A nil pointer means "no change"; a non-nil pointer (even to zero/empty) means "apply".

type SamplingStatisticSummary 

type SamplingStatisticSummary struct {
	Timestamp    time.Time `json:"timestamp"`
	RuleName     string    `json:"ruleName"`
	RequestCount int32     `json:"requestCount"`
	SampledCount int32     `json:"sampledCount"`
	BorrowCount  int32     `json:"borrowCount"`
}

SamplingStatisticSummary holds aggregated request sampling data for a rule.

type SamplingStatisticsDocument 

type SamplingStatisticsDocument struct {
	RuleName     string
	ClientID     string
	RequestCount int32
	SampledCount int32
	BorrowCount  int32
}

SamplingStatisticsDocument is a single document submitted in GetSamplingTargets.

type SamplingTargetResult 

type SamplingTargetResult struct {
	ReservoirQuotaTTL time.Time
	RuleName          string
	FixedRate         float64
	ReservoirSize     int32
}

SamplingTargetResult holds the per-document results of GetSamplingTargets.

type Segment 

type Segment struct {
	AWS         map[string]any `json:"aws,omitempty"`
	Annotations map[string]any `json:"annotations,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	HTTP        *SegmentHTTP   `json:"http,omitempty"`
	Namespace   string         `json:"namespace,omitempty"`
	Document    string         `json:"-"`
	TraceID     string         `json:"trace_id"`
	ID          string         `json:"id"`
	ParentID    string         `json:"parent_id,omitempty"`
	Name        string         `json:"name"`
	Origin      string         `json:"origin,omitempty"`
	Subsegments []Segment      `json:"subsegments,omitempty"`
	StartTime   float64        `json:"start_time"`
	EndTime     float64        `json:"end_time,omitempty"`
	Error       bool           `json:"error"`
	Fault       bool           `json:"fault"`
	Throttle    bool           `json:"throttle"`
}

Segment is a parsed X-Ray segment document.

type SegmentHTTP 

type SegmentHTTP struct {
	Request  *SegmentHTTPRequest  `json:"request,omitempty"`
	Response *SegmentHTTPResponse `json:"response,omitempty"`
}

SegmentHTTP holds HTTP request/response data from a segment.

type SegmentHTTPRequest 

type SegmentHTTPRequest struct {
	URL       string `json:"url,omitempty"`
	Method    string `json:"method,omitempty"`
	UserAgent string `json:"user_agent,omitempty"`
	ClientIP  string `json:"client_ip,omitempty"`
}

SegmentHTTPRequest holds HTTP request fields from a segment.

type SegmentHTTPResponse 

type SegmentHTTPResponse struct {
	Status        int `json:"status,omitempty"`
	ContentLength int `json:"content_length,omitempty"`
}

SegmentHTTPResponse holds HTTP response fields from a segment.

type Settings 

type Settings struct {
	JanitorInterval time.Duration `json:"janitor_interval" env:"XRAY_JANITOR_INTERVAL" default:"1m"  help:"Janitor tick interval."`                         //nolint:lll // Kong struct tag makes this line long
	TraceTTL        time.Duration `json:"trace_ttl"        env:"XRAY_TRACE_TTL"        default:"30m" help:"TTL for stored traces before they are evicted."` //nolint:lll // Kong struct tag makes this line long
}

Settings holds service-level configuration for the X-Ray backend. Fields are picked up by the Kong CLI parser when this struct is embedded in the root CLI command.

type StorageBackend 

type StorageBackend interface {
	CreateGroup(name, filterExpr string) (*Group, error)
	CreateGroupWithInsights(name, filterExpr string, ic InsightsConfiguration) (*Group, error)
	GetGroup(name string) (*Group, error)
	GetGroupByARN(arn string) (*Group, error)
	GetGroups() []Group
	UpdateGroup(name, filterExpr string) (*Group, error)
	UpdateGroupByARN(name, arn, filterExpr string) (*Group, error)
	DeleteGroup(name string) error
	DeleteGroupByARN(name, arn string) error
	CreateSamplingRule(rule SamplingRule) (*SamplingRule, error)
	GetSamplingRules() []SamplingRule
	UpdateSamplingRule(ruleName string, updates SamplingRule) (*SamplingRule, error)
	UpdateSamplingRuleWithPointers(ruleName string, updates SamplingRuleUpdate) (*SamplingRule, error)
	DeleteSamplingRule(ruleName string) (*SamplingRule, error)
	PutTraceSegments(segments []string) []string
	GetTraceSummaries() []Trace
	GetTrace(traceID string) *Trace
	GetParsedSegments(traceID string) []*Segment
	GetAllParsedSegments() map[string][]*Segment
	Reset()
	GetEncryptionConfig() *EncryptionConfig
	PutEncryptionConfig(encType, keyID string) (*EncryptionConfig, error)
	Snapshot(ctx context.Context) []byte
	Restore(ctx context.Context, data []byte) error
	// Insight operations
	GetInsight(insightID string) (*Insight, error)
	GetInsightEvents(insightID string) ([]*InsightEvent, error)
	GetInsightSummaries(states []string) ([]Insight, error)
	// Resource policy operations
	CancelTraceRetrieval(retrievalToken string)
	DeleteResourcePolicy(policyName string) error
	ListResourcePolicies() []ResourcePolicy
	PutResourcePolicy(policyName, policyDocument, revisionID string) (*ResourcePolicy, error)
	// Indexing rules
	GetIndexingRules() []*IndexingRule
	// Retrieval
	GetRetrievedTracesGraph(retrievalToken string) (string, []*Trace)
	// Sampling statistics
	GetSamplingStatisticSummaries() []SamplingStatisticSummary
	GetSamplingTargets(docs []SamplingStatisticsDocument) ([]SamplingTargetResult, []UnprocessedStatisticsResult)
	LastRuleModification() time.Time
	// Service graph operations
	GetServiceGraph(startTime, endTime time.Time) []map[string]any
	GetTraceGraph(traceIDs []string) []map[string]any
	GetTimeSeriesServiceStatistics(startTime, endTime time.Time, period int) []map[string]any
	// Destination
	GetTraceSegmentDestination() string
	UpdateTraceSegmentDestination(destination string) string
	// Retrieval list
	ListRetrievedTraces(retrievalToken string) (string, []*Trace)
	// Tags
	ListTagsForResource(resourceARN string) []map[string]string
	StartTraceRetrieval(traceIDs []string) string
	TagResource(resourceARN string, tags map[string]string)
	UntagResource(resourceARN string, tagKeys []string)
	// Indexing rule update
	UpdateIndexingRule(name string) (*IndexingRule, error)
	// Telemetry
	PutTelemetryRecords(records []TelemetryRecord)
}

StorageBackend defines the interface for X-Ray backend implementations. All mutating methods must be safe for concurrent use.

type TelemetryRecord 

type TelemetryRecord struct {
	Timestamp              time.Time `json:"timestamp"`
	SegmentsReceivedCount  int32     `json:"segmentsReceivedCount"`
	SegmentsSentCount      int32     `json:"segmentsSentCount"`
	SegmentsSpilloverCount int32     `json:"segmentsSpilloverCount"`
	SegmentsRejectedCount  int32     `json:"segmentsRejectedCount"`
}

TelemetryRecord holds a single telemetry data point.

type Trace 

type Trace struct {
	StartTime time.Time `json:"startTime"`
	TraceID   string    `json:"traceID"`
	Segments  []string  `json:"segments"`
}

Trace represents a collected X-Ray trace with its constituent segments.

type TraceRetrieval 

type TraceRetrieval struct {
	StartTime      time.Time `json:"startTime"`
	RetrievalToken string    `json:"retrievalToken"`
	Status         string    `json:"status"`
}

TraceRetrieval represents an ongoing trace retrieval operation.

type TraceSummaryData 

type TraceSummaryData struct {
	Annotations  map[string]any
	HTTP         *TraceSummaryHTTP
	TraceID      string
	EntryPoint   string
	Users        []string
	ServiceIDs   []TraceSummaryServiceID
	Duration     float64
	ResponseTime float64
	ApproxTime   float64
	Revision     int
	HasFault     bool
	HasError     bool
	HasThrottle  bool
	IsPartial    bool
}

TraceSummaryData holds derived data for GetTraceSummaries response.

func BuildTraceSummary 

func BuildTraceSummary(traceID string, segs []*Segment) TraceSummaryData

BuildTraceSummary derives TraceSummaryData from parsed segments.

type TraceSummaryHTTP 

type TraceSummaryHTTP struct {
	HTTPURL    string
	HTTPMethod string
	ClientIP   string
	UserAgent  string
	HTTPStatus int
}

TraceSummaryHTTP holds HTTP fields for a trace summary.

type TraceSummaryServiceID 

type TraceSummaryServiceID struct {
	Name string
	Type string
}

TraceSummaryServiceID is a service identifier in a trace summary.

type UnprocessedStatisticsResult 

type UnprocessedStatisticsResult struct {
	RuleName  string
	ErrorCode string
	Message   string
}

UnprocessedStatisticsResult holds results for unknown rule names.

Source Files

View all Source files

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.