sampling

Documentation

Overview

Reservoirs allow a specified (`perSecond`) amount of `Take()`s per second.

Copyright 2017-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at

http://aws.amazon.com/apache2.0/

or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• func NewProxy(d *daemoncfg.DaemonEndpoints) (svcProxy, error)
• type CentralizedManifest
• type CentralizedReservoir
  • func (r *CentralizedReservoir) Take(now int64) bool
• type CentralizedRule
  • func (r *CentralizedRule) AppliesTo(request *Request) bool
  • func (r *CentralizedRule) Sample() *Decision
• type CentralizedStrategy
  • func NewCentralizedStrategy() (*CentralizedStrategy, error)
  • func NewCentralizedStrategyWithFilePath(fp string) (*CentralizedStrategy, error)
  • func NewCentralizedStrategyWithJSONBytes(b []byte) (*CentralizedStrategy, error)
  • func (ss *CentralizedStrategy) LoadDaemonEndpoints(endpoints *daemoncfg.DaemonEndpoints)
  • func (ss *CentralizedStrategy) ShouldTrace(request *Request) *Decision
• type Decision
• type LocalizedStrategy
  • func NewLocalizedStrategy() (*LocalizedStrategy, error)
  • func NewLocalizedStrategyFromFilePath(fp string) (*LocalizedStrategy, error)
  • func NewLocalizedStrategyFromJSONBytes(b []byte) (*LocalizedStrategy, error)
  • func (lss *LocalizedStrategy) ShouldTrace(rq *Request) *Decision
• type Properties
  • func (p *Properties) AppliesTo(host, path, method string) bool
• type Request
• type Reservoir
  • func (r *Reservoir) Take() bool
• type Rule
  • func (r *Rule) Sample() *Decision
• type RuleManifest
  • func ManifestFromFilePath(fp string) (*RuleManifest, error)
  • func ManifestFromJSONBytes(b []byte) (*RuleManifest, error)
• type Strategy

Functions

func NewProxy

func NewProxy(d *daemoncfg.DaemonEndpoints) (svcProxy, error)

NewProxy returns a Proxy

Types

type CentralizedManifest

type CentralizedManifest struct {
	Default *CentralizedRule
	Rules   []*CentralizedRule
	Index   map[string]*CentralizedRule

	sync.RWMutex
	// contains filtered or unexported fields
}

CentralizedManifest represents a full sampling ruleset, with a list of custom rules and default values for incoming requests that do not match any of the provided rules.

type CentralizedReservoir

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

CentralizedReservoir is a reservoir distributed among all running instances of the SDK

func (*CentralizedReservoir) Take

func (r *CentralizedReservoir) Take(now int64) bool

Take consumes quota from reservoir, if any remains, and returns true. False otherwise.

type CentralizedRule

type CentralizedRule struct {

	// Common sampling rule properties
	*Properties

	sync.RWMutex
	// contains filtered or unexported fields
}

CentralizedRule represents a centralized sampling rule

func (*CentralizedRule) AppliesTo

func (r *CentralizedRule) AppliesTo(request *Request) bool

AppliesTo returns true if the sampling rule matches against given sampling request. False Otherwise. Assumes lock is already held, if required.

func (*CentralizedRule) Sample

func (r *CentralizedRule) Sample() *Decision

Sample returns true if the request should be sampled. False otherwise.

type CentralizedStrategy

type CentralizedStrategy struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

CentralizedStrategy is an implementation of SamplingStrategy. It performs quota-based sampling with X-Ray acting as arbitrator for clients. It will fall back to LocalizedStrategy if sampling rules are not available from X-Ray APIS.

func NewCentralizedStrategy

func NewCentralizedStrategy() (*CentralizedStrategy, error)

NewCentralizedStrategy creates a centralized sampling strategy with a fallback on local default rule.

func NewCentralizedStrategyWithFilePath

func NewCentralizedStrategyWithFilePath(fp string) (*CentralizedStrategy, error)

NewCentralizedStrategyWithFilePath creates a centralized sampling strategy with a fallback on local rules located at the given file path.

func NewCentralizedStrategyWithJSONBytes

func NewCentralizedStrategyWithJSONBytes(b []byte) (*CentralizedStrategy, error)

NewCentralizedStrategyWithJSONBytes creates a centralized sampling strategy with a fallback on local rules specified in the given byte slice.

func (*CentralizedStrategy) LoadDaemonEndpoints

func (ss *CentralizedStrategy) LoadDaemonEndpoints(endpoints *daemoncfg.DaemonEndpoints)

LoadDaemonEndpoints configures proxy with the provided endpoint.

func (*CentralizedStrategy) ShouldTrace

func (ss *CentralizedStrategy) ShouldTrace(request *Request) *Decision

ShouldTrace determines whether a request should be sampled. It matches the given parameters against a list of known rules and uses the matched rule's values to make a decision.

type Decision

type Decision struct {
	Sample bool
	Rule   *string
}

Decision contains sampling decision and the rule matched for an incoming request

type LocalizedStrategy

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

LocalizedStrategy makes trace sampling decisions based on a set of rules provided in a local JSON file. Trace sampling decisions are made by the root node in the trace. If a sampling decision is made by the root service, it will be passed to downstream services through the trace header.

func NewLocalizedStrategy

func NewLocalizedStrategy() (*LocalizedStrategy, error)

NewLocalizedStrategy initializes an instance of LocalizedStrategy with the default trace sampling rules. The default rules sample the first request per second, and 5% of requests thereafter.

func NewLocalizedStrategyFromFilePath

func NewLocalizedStrategyFromFilePath(fp string) (*LocalizedStrategy, error)

NewLocalizedStrategyFromFilePath initializes an instance of LocalizedStrategy using a custom ruleset found at the filepath fp.

func NewLocalizedStrategyFromJSONBytes

func NewLocalizedStrategyFromJSONBytes(b []byte) (*LocalizedStrategy, error)

NewLocalizedStrategyFromJSONBytes initializes an instance of LocalizedStrategy using a custom ruleset provided in the json bytes b.

func (*LocalizedStrategy) ShouldTrace

func (lss *LocalizedStrategy) ShouldTrace(rq *Request) *Decision

ShouldTrace consults the LocalizedStrategy's rule set to determine if the given request should be traced or not.

type Properties

type Properties struct {
	ServiceName string  `json:"service_name"`
	Host        string  `json:"host"`
	HTTPMethod  string  `json:"http_method"`
	URLPath     string  `json:"url_path"`
	FixedTarget int64   `json:"fixed_target"`
	Rate        float64 `json:"rate"`
}

Properties is the base set of properties that define a sampling rule.

func (*Properties) AppliesTo

func (p *Properties) AppliesTo(host, path, method string) bool

AppliesTo returns true if the sampling rule matches against given parameters. False Otherwise. Assumes lock is already held, if required.

type Request

type Request struct {
	Host        string
	Method      string
	Url         string
	ServiceName string
	ServiceType string
}

Request represents parameters used to make a sampling decision.

type Reservoir

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

Reservoir is a reservoir local to the running instance of the SDK

func (*Reservoir) Take

func (r *Reservoir) Take() bool

Take attempts to consume a unit from the local reservoir. Returns true if unit taken, false otherwise.

type Rule

type Rule struct {

	// Common sampling rule properties
	*Properties
	// contains filtered or unexported fields
}

Local Sampling Rule

func (*Rule) Sample

func (r *Rule) Sample() *Decision

type RuleManifest

type RuleManifest struct {
	Version int     `json:"version"`
	Default *Rule   `json:"default"`
	Rules   []*Rule `json:"rules"`
}

RuleManifest represents a full sampling ruleset, with a list of custom rules and default values for incoming requests that do not match any of the provided rules.

func ManifestFromFilePath

func ManifestFromFilePath(fp string) (*RuleManifest, error)

ManifestFromFilePath creates a sampling ruleset from a given filepath fp.

func ManifestFromJSONBytes

func ManifestFromJSONBytes(b []byte) (*RuleManifest, error)

ManifestFromJSONBytes creates a sampling ruleset from given JSON bytes b.

type Strategy

type Strategy interface {
	ShouldTrace(request *Request) *Decision
}

Strategy provides an interface for implementing trace sampling strategies.