Documentation
¶
Overview ¶
Package vxray integrates amazon's xray distributed tracing system with vanadium's vtrace. When used this implementation of vtrace will publish to xray in addition to the normal vtrace functionality.
Package vxray provides an implementation of vtrace that uses AWS' xray service as its backend store. It is intended to be interoperable with the AWS xray libraries in the sense that calling the xray libraries directly should result in operations that affect the enclosing vtrace spans. Similarly, use of the xray http handlers will result in any spans from local or remote nested operations being associated with that newly created trace.
vxray is installed on a per-context basis, via the InitXRay function:
ctx, _ = vxray.InitXRay(ctx,
v23.GetRuntimeFlags().VtraceFlags,
xray.Config{ServiceVersion: ""},
vxray.EC2Plugin(),
vxray.MergeLogging(true))
Once so initialized any spans created using the returned context will be backed by xray. All of the existing vtrace functionality is supported by the vxray spans.
xray is http centric and makes sampling decisions when a new trace/segment is created. The vtrace.SamplingRequest struct is mapped to the http primites that xray expects. In particular:
SamplingRequest.Local is mapped to http.Request.Host SamplingRequest.Name is mapped to http.Request.URL.Path SamplingRequest.Method is mapped to http.Request.Method
These mappings are used purely for sampling decisions, in addition, the name of the top-level span, is treated as the xray ServiceName can also be used for sampling decisions. Note that SamplingRequest.Name need not be the same as the name of the span. Also note that the Method can be any Vanadium method and not one of the pre-defined HTTP methods. This appears to work fine with xray since its implementation just compares the wildcarded strings. However, the xray console has a limit (10) on the length of the methods that can be specified and hence wild cards must be used instead; e.g. ResolveSt* rather than ResolveStep. This restriction may not apply to sampling rules created programmatically.
The Vanadium RPC runtime creates spans for client and server calls and when doing so associates metadata which them that can is both passed through to xray as well as, optionally, being interpreted by this package. In particular, if the MapToHTTP option is set, (it is the default), then some of these annotations (see the comment for MapToHTTP) will translated into xray.HTTPData fields.
Index ¶
- func GetConfig(ctx *context.T) *xray.Config
- func GetSegment(ctx *context.T) *xray.Segment
- func GetTraceHeader(ctx *context.T) *header.Header
- func InitXRay(ctx *context.T, vflags flags.VtraceFlags, config xray.Config, opts ...Option) (*context.T, error)
- func MergeHTTPRequestContext(ctx *context.T, req *http.Request) *context.T
- func WithConfig(ctx *context.T, config xray.Config) (*context.T, error)
- func WithSegment(ctx *context.T, seg *xray.Segment) *context.T
- func WithTraceHeader(ctx *context.T, hdr *header.Header) *context.T
- type Option
- func BeanstalkPlugin() Option
- func ContainerIDAndHost() Option
- func EC2Plugin() Option
- func ECSPlugin() Option
- func EKSCluster() Option
- func KubernetesCluster(configMap, configMapKey string) Option
- func MapToHTTP(v bool) Option
- func MergeLogging(v bool) Option
- func WithNewStore(vflags flags.VtraceFlags) Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetSegment ¶
GetSegment returns the xray segment stored in the context, or nil. It uses the same context key as the xray package.
func GetTraceHeader ¶
GetTraceHeader returns the xray header.Header stored in the current context, or nil. It looks for both a *header.Header managed by this package as well as the string representation of header.Header managed by the xray package.
func InitXRay ¶
func InitXRay(ctx *context.T, vflags flags.VtraceFlags, config xray.Config, opts ...Option) (*context.T, error)
InitXRay configures the AWS xray service and returns a context containing the xray configuration. This should only be called once. The vflags argument is used solely to check if xray tracing is enabled and not to create a new vtrace.Store, if a new/alternate store is required, the WithNewStore option should be used to specify the store to be used.
func MergeHTTPRequestContext ¶
MergeHTTPRequestContext merges any xray related metadata such as an existing trace header or segment into the returned context. This returned context can then be used with all of the vtrace methods in this package. MergeHTTPRequestContext should be called by any xray managed http.Handler that issues vanadium RPCs or that uses vtrace.
func WithConfig ¶
WithConfig records the xray.Config in the returned context. It uses the same context key as the xray package.
func WithSegment ¶
WithSegment records the xray segment in the returned context. It uses the same context key as the xray package.
Types ¶
type Option ¶
type Option func(o *options)
Option represents an option to InitXRay.
func BeanstalkPlugin ¶
func BeanstalkPlugin() Option
BeanstalkPlugin initializes the BeanstalkPlugin plugin.
func ContainerIDAndHost ¶ added in v0.1.18
func ContainerIDAndHost() Option
ContainerIDAndHost requests that container id and host information be obtained and added to traces. The container id is obtained by parsing the /proc/self/cgroup file, and the host by call the operating system's hostname function. When running under kubernetes for example, a pod's name is configured as its hostname.
When configured, xray segments will contain 'container_id' and 'container_host' annotations.
func EKSCluster ¶ added in v0.1.18
func EKSCluster() Option
EKSCluster calls KubernetesCluster with the values commonly used with EKS clusters.
func KubernetesCluster ¶ added in v0.1.18
KubernetesCluster configures obtaining information about the process' current environment when running under Kubernetes (k8s), whether managed by AWS EKS or any other control plane implementation. It requires that the K8S configuration creates a configmap that contains the cluster name. The configMap argument names that configmap and configMapKey is the key in that configmap for the cluster name. For example, when using the AWS cloudwatch/insights/xray-daemon daemonset the values for those would be:
/api/v1/namespaces/amazon-cloudwatch/configmaps/cluster-info cluster.name
When configured, xray segments will contain a 'cluster_name' annotation.
func MapToHTTP ¶
MapToHTTP maps vtrace fields/concepts to xray's http-centric xray.RequestData fields. This relies on knowledge of how the vanadium runtime encodes metadata in a span. In particular, it assumes that metadata values are set for:
- name string // the vanadium name for the service, maps to a url
- method string // the vanadium method, maps to an http method, this is informational only since xray has limits on the length of a method name.
- clientAddr string // the client invoking the rpc, maps to clientip. The user agent is set to vanadium.
NOTE that this mapping will only occur if there is no existing xray.RequestData encoded in the segment. This allows for xray segments created directly by xray API calls prior to spans being created to be supported without losing any of the original HTTP request data encoded therein.
func MergeLogging ¶
MergeLogging arrays for xray logging messages to be merged with vanadium log messages.
func WithNewStore ¶
func WithNewStore(vflags flags.VtraceFlags) Option
WithNewStore requests that a new vtrace.Store be created and stored in the context returned by InitXRay.
Source Files
Directories