xray

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Aug 3, 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-23 (980dbe22)

Coverage

Metric Value
Operations audited 38 (36 ok, 2 deferred)
Feature families 3 (3 ok)
Known gaps 6
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 (unchanged this pass)
  • Insight.Categories, ClientRequestImpactStatistics, RootCauseServiceId/RequestImpactStatistics, TopAnomalousServices, and GetInsightImpactGraph's Services always empty/unset -- gopherstack's insight detector (detectInsights in insights.go) is a simple fault-rate-threshold heuristic and never populates these AWS anomaly-detection-derived fields. Judged intentional: replicating AWS's actual insight-impact-graph/anomaly-detection algorithm is out of scope for an emulator's insight feature, which itself is best-effort. Unchanged this pass; LastUpdateTime (a plain timestamp, not anomaly-detection-derived) WAS added this pass since it required no such algorithm.
  • SamplingRateBoost (SamplingRule.SamplingRateBoost, SamplingRuleUpdate.SamplingRateBoost, SamplingTargetDocument.SamplingBoost) is a newer AWS X-Ray feature (temporary sampling-rate boosts). This pass added the config fields end-to-end for wire parity (Create/Update/Get all accept, store, and return {MaxRate,CooldownWindowMinutes}), but does NOT implement the runtime boost-trigger algorithm: GetSamplingTargets never populates SamplingTargetDocument.SamplingBoost. Judged the same class of scope limit as the insight-anomaly-detection fields above -- simulating AWS's actual boost-trigger heuristics is out of scope for this pass.
  • Edge objects in GetServiceGraph/GetTraceGraph responses only carry {ReferenceId}; the real Edge type also supports SummaryStatistics/StartTime/EndTime/EdgeType/aliases/histograms. Not wire-breaking (all optional pointer fields -- a real client just sees zero values on these), but a real client's service-map visualization would show unlabeled edges. Not implemented this pass; candidate for a follow-up if edge-level stats matter for a user's workflow.
  • PutResourcePolicy's BypassPolicyLockoutCheck field is parsed but LockoutPreventionException is never raised. Real AWS simulates whether the proposed policy would lock the caller out of managing the policy in the future -- an IAM policy-evaluation problem. Implementing genuine IAM policy simulation is out of scope for this pass; the parameter is accepted (matches wire shape) but has no effect, which is safe (never falsely rejects a real client's request) even if it under-enforces relative to real AWS.
  • ThrottledException is declared in the modeled error set for every X-Ray operation but is never emitted anywhere in gopherstack (no rate limiting is modeled). This is consistent with the rest of gopherstack's emulation approach (no service throttles by default) and is not treated as a gap specific to X-Ray.
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.
	// UpdateIndexingRule's modeled error set uses ResourceNotFoundException here
	// (unlike GetGroup/DeleteGroup/etc., which only ever return InvalidRequestException).
	ErrIndexingRuleNotFound = awserr.New("ResourceNotFoundException", 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)
	// ErrPolicySizeLimitExceeded is returned when a resource policy document exceeds the maximum size.
	ErrPolicySizeLimitExceeded = awserr.New("PolicySizeLimitExceededException", awserr.ErrInvalidParameter)
	// ErrRuleLimitExceeded is returned when the maximum number of sampling rules is exceeded.
	ErrRuleLimitExceeded = awserr.New("RuleLimitExceededException", awserr.ErrInvalidParameter)
	// ErrTooManyTags is returned when a resource would exceed the maximum number of tags.
	ErrTooManyTags = awserr.New("TooManyTagsException", awserr.ErrInvalidParameter)
	// ErrResourceNotFound is returned for operations whose modeled error is
	// ResourceNotFoundException rather than InvalidRequestException (TagResource,
	// UntagResource, ListTagsForResource, UpdateIndexingRule, and the trace-retrieval
	// token operations StartTraceRetrieval/CancelTraceRetrieval/ListRetrievedTraces/
	// GetRetrievedTracesGraph -- confirmed against each operation's declared error set
	// in aws-sdk-go-v2/service/xray's deserializers.go).
	ErrResourceNotFound = awserr.New("ResourceNotFoundException", awserr.ErrNotFound)
	// ErrTraceRetrievalNotFound is returned when a RetrievalToken passed to
	// CancelTraceRetrieval, ListRetrievedTraces, or GetRetrievedTracesGraph does not
	// correspond to a retrieval started by StartTraceRetrieval. All three declare
	// ResourceNotFoundException in their modeled error set.
	ErrTraceRetrievalNotFound = awserr.New("ResourceNotFoundException", awserr.ErrNotFound)
)
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) error

CancelTraceRetrieval marks a trace retrieval as cancelled. Returns ErrTraceRetrievalNotFound if the token was never created by StartTraceRetrieval (real AWS declares ResourceNotFoundException for CancelTraceRetrieval on unknown tokens).

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. Returns ErrRuleLimitExceeded if the account already has maxSamplingRules rules.

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, policyRevisionID string) error

DeleteResourcePolicy removes the resource policy with the given name. If policyRevisionID is non-empty, it must match the stored policy's current revision ID, or ErrInvalidPolicyRevisionID is returned (matches real AWS: providing a PolicyRevisionId makes the delete atomic and guards against a concurrent PutResourcePolicy).

func (*InMemoryBackend) DeleteSamplingRule 

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

DeleteSamplingRule removes the sampling rule identified by ruleName (if non-empty, else ruleARN) and returns it. The built-in "Default" rule cannot be deleted, whether identified by name or ARN; 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, error)

GetRetrievedTracesGraph returns the status and services for a retrieval token. Returns ErrTraceRetrievalNotFound if the token was never created by StartTraceRetrieval.

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, error)

ListRetrievedTraces returns the status and traces associated with a retrieval token. Returns ErrTraceRetrievalNotFound if the token was never created by StartTraceRetrieval.

func (*InMemoryBackend) ListTagsForResource 

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

ListTagsForResource returns all tags for the given resource ARN as a slice of key/value maps. Returns ErrResourceNotFound if resourceARN is not a known group or sampling rule.

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 ErrPolicySizeLimitExceeded if policyDocument exceeds maxResourcePolicySizeBytes. 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) error

TagResource adds or updates tags on a resource identified by ARN. Tags are stored in a per-ARN map on the backend. Returns ErrResourceNotFound if resourceARN is not a known group or sampling rule. Returns ErrTooManyTags if applying tags would exceed maxTagsPerResource.

func (*InMemoryBackend) UntagResource 

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

UntagResource removes the specified tag keys from a resource. Returns ErrResourceNotFound if resourceARN is not a known group or sampling rule.

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 string,
	filterExpr *string,
	insights *InsightsConfiguration,
) (*Group, error)

UpdateGroupByARN updates a group by ARN or name. filterExpr and insights are pointer-semantic: a nil pointer leaves the corresponding field unchanged, matching the real UpdateGroupInput shape where FilterExpression and InsightsConfiguration are both independently optional (unlike CreateGroup, omitting one on update must not reset the other to its zero value).

func (*InMemoryBackend) UpdateIndexingRule 

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

UpdateIndexingRule updates the named indexing rule's probabilistic sampling percentage (the actual point of UpdateIndexingRule per the real API: its request carries a required Rule.Probabilistic.DesiredSamplingPercentage). gopherstack applies the desired percentage immediately as the actual percentage too, since there is no gradual-rollout simulation to model here. 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, ruleARN string,
	updates SamplingRuleUpdate,
) (*SamplingRule, error)

UpdateSamplingRuleWithPointers applies pointer-semantic updates so zero values apply. The rule is identified by ruleName if non-empty, otherwise by ruleARN (matching the real SamplingRuleUpdate shape, which allows specifying either but not both).

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"`
	Rule       *ProbabilisticRuleValue `json:"rule,omitempty"`
	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"`
	LastUpdateTime time.Time `json:"lastUpdateTime"`
	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 ProbabilisticRuleValue added in v1.2.0 

type ProbabilisticRuleValue struct {
	DesiredSamplingPercentage float64 `json:"desiredSamplingPercentage"`
	ActualSamplingPercentage  float64 `json:"actualSamplingPercentage"`
}

ProbabilisticRuleValue holds the probabilistic sampling percentage configuration for an indexing rule.

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 {
	LastUpdatedTime  time.Time `json:"lastUpdatedTime"`
	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 SamplingRateBoost added in v1.2.0 

type SamplingRateBoost struct {
	MaxRate               float64 `json:"maxRate"`
	CooldownWindowMinutes int32   `json:"cooldownWindowMinutes"`
}

SamplingRateBoost holds the configuration for temporary sampling-rate boosts.

type SamplingRule 

type SamplingRule struct {
	CreatedAt         time.Time          `json:"createdAt"`
	ModifiedAt        time.Time          `json:"modifiedAt"`
	SamplingRateBoost *SamplingRateBoost `json:"samplingRateBoost,omitempty"`
	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
	SamplingRateBoost *SamplingRateBoost
}

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 string, filterExpr *string, insights *InsightsConfiguration) (*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, ruleARN string, updates SamplingRuleUpdate) (*SamplingRule, error)
	DeleteSamplingRule(ruleName, ruleARN 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) error
	DeleteResourcePolicy(policyName, policyRevisionID string) error
	ListResourcePolicies() []ResourcePolicy
	PutResourcePolicy(policyName, policyDocument, revisionID string) (*ResourcePolicy, error)
	// Indexing rules
	GetIndexingRules() []*IndexingRule
	// Retrieval
	GetRetrievedTracesGraph(retrievalToken string) (string, []*Trace, error)
	// 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, error)
	// Tags
	ListTagsForResource(resourceARN string) ([]map[string]string, error)
	StartTraceRetrieval(traceIDs []string) string
	TagResource(resourceARN string, tags map[string]string) error
	UntagResource(resourceARN string, tagKeys []string) error
	// Indexing rule update
	UpdateIndexingRule(name string, rule *ProbabilisticRuleValue) (*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
	EntryPoint   *TraceSummaryServiceID
	TraceID      string
	Users        []string
	ServiceIDs   []TraceSummaryServiceID
	Duration     float64
	ResponseTime 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.