candlelight

README

candlelight

candlelight provides a simple chainable or uber-fx based wrapper for OpenTelemetry

Summary

candlelight takes the OpenTelemetry API and makes a couple of useful wrappers for web services that enable tracing initially.

Table of Contents

• Code of Conduct
• Details
• Install
• Contributing

Code of Conduct

This project and everyone participating in it are governed by the XMiDT Code Of Conduct. By participating, you agree to this Code.

Details

Add details here.

Install

Add details here.

Contributing

Refer to CONTRIBUTING.md.

Documentation

Overview

*

• Copyright (c) 2021 Comcast Cable Communications Management, LLC *
• Licensed under the Apache License, Version 2.0 (the "License");
• you may not use this file except in compliance with the License.
• You may obtain a copy of the License at *
• http://www.apache.org/licenses/LICENSE-2.0 *
• Unless required by applicable law or agreed to in writing, software
• distributed under the License 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. *

*

• Copyright (c) 2021 Comcast Cable Communications Management, LLC *
• Licensed under the Apache License, Version 2.0 (the "License");
• you may not use this file except in compliance with the License.
• You may obtain a copy of the License at *
• http://www.apache.org/licenses/LICENSE-2.0 *
• Unless required by applicable law or agreed to in writing, software
• distributed under the License 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. *

*

• Copyright (c) 2021 Comcast Cable Communications Management, LLC *
• Licensed under the Apache License, Version 2.0 (the "License");
• you may not use this file except in compliance with the License.
• You may obtain a copy of the License at *
• http://www.apache.org/licenses/LICENSE-2.0 *
• Unless required by applicable law or agreed to in writing, software
• distributed under the License 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. *

*

• Copyright (c) 2021 Comcast Cable Communications Management, LLC *
• Licensed under the Apache License, Version 2.0 (the "License");
• you may not use this file except in compliance with the License.
• You may obtain a copy of the License at *
• http://www.apache.org/licenses/LICENSE-2.0 *
• Unless required by applicable law or agreed to in writing, software
• distributed under the License 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

• Constants
• Variables
• func AppendTraceInfo(ctx context.Context, kvs []interface{}) ([]interface{}, bool)
• func ConfigureTracerProvider(config Config) (trace.TracerProvider, error)
• func EchoFirstTraceNodeInfo(propagator propagation.TextMapPropagator, isDecodable bool) func(http.Handler) http.Handler
• func ExtractTraceInfo(ctx context.Context) (string, string, bool)
• func GenTID() (tid string)
• func InjectTraceInfo(ctx context.Context, carrier propagation.TextMapCarrier)
• func InjectTraceInfoInLogger() func([]interface{}, *http.Request) []interface{}
• type Config
• type LoggerFunc
• type ProviderConstructor
• type TraceConfig
  • func (traceConfig *TraceConfig) TraceMiddleware(delegate http.Handler) http.Handler
• type Tracing
  • func New(config Config) (Tracing, error)
  • func (t Tracing) IsNoop() bool
  • func (t Tracing) Propagator() propagation.TextMapPropagator
  • func (t Tracing) TracerProvider() trace.TracerProvider

Constants

const (
	SpanIDLogKeyName  = "span-id"
	TraceIdLogKeyName = "trace-id"
	// HeaderWPATIDKeyName is the header key for the WebPA transaction UUID
	HeaderWPATIDKeyName = "X-WebPA-Transaction-Id"
)

const DefaultTracerProvider = "noop"

DefaultTracerProvider is used when no provider is given. The Noop tracer provider turns all tracing related operations into noops essentially disabling tracing.

Variables

var (
	ErrTracerProviderNotFound    = errors.New("TracerProvider builder could not be found")
	ErrTracerProviderBuildFailed = errors.New("Failed building TracerProvider")
	ErrInvalidParentBasedValue   = errors.New("Invalid ParentBased value provided in configuration")
	ErrInvalidNoParentValue      = errors.New("Invalid No Parent value provided in configuration")
)

Functions

func AppendTraceInfo

func AppendTraceInfo(ctx context.Context, kvs []interface{}) ([]interface{}, bool)

AppendTraceInfo appends the trace and span ID key value pairs if they are found in the context. The boolean is a quick way to know if the pairs were added. This should be useful for adding tracing information in logging statements.

func ConfigureTracerProvider

func ConfigureTracerProvider(config Config) (trace.TracerProvider, error)

ConfigureTracerProvider creates the TracerProvider based on the configuration provided. It has built-in support for jaeger, zipkin, stdout and noop providers. A different provider can be used if a constructor for it is provided in the config. If a provider name is not provided, a noop tracerProvider will be returned.

func EchoFirstTraceNodeInfo

func EchoFirstTraceNodeInfo(propagator propagation.TextMapPropagator, isDecodable bool) func(http.Handler) http.Handler

EchoFirstNodeTraceInfo captures the trace information from a request, writes it back in the response headers, and adds it to the request's context It can also decode the request and save the resulting WRP object in the context if isDecodable is true

func ExtractTraceInfo

func ExtractTraceInfo(ctx context.Context) (string, string, bool)

ExtractTraceInfo returns the ID of the trace flowing through the context as well as ID the current active span. The third boolean return value represents whether the returned IDs are valid and safe to use. OpenTelemetry's noop tracer provider, for instance, returns zero value trace information that's considered invalid and should be ignored.

func GenTID

func GenTID() (tid string)

GenTID generates a 16-byte long string it returns "N/A" in the extreme case the random string could not be generated

func InjectTraceInfo

func InjectTraceInfo(ctx context.Context, carrier propagation.TextMapCarrier)

InjectTraceInfo will be injecting traceParent and tracestate as headers in carrier from span which is available in context.

func InjectTraceInfoInLogger

func InjectTraceInfoInLogger() func([]interface{}, *http.Request) []interface{}

InjectTraceInfoInLogger adds the traceID and spanID to key value pairs that can be provided to a logger.

Types

type Config

type Config struct {
	// ApplicationName is the name for this application.
	ApplicationName string `json:"applicationName"`

	// Provider is the name of the trace provider to use.
	Provider string `json:"provider"`

	// Endpoint is the endpoint to which spans need to be submitted.
	Endpoint string `json:"endpoint"`

	// SkipTraceExport works only in case of provider stdout. Set
	// SkipTraceExport = true if you don't want to print the span
	// and tracer information in stdout.
	SkipTraceExport bool `json:"skipTraceExport"`

	// Providers are useful when client wants to add their own custom
	// TracerProvider.
	Providers map[string]ProviderConstructor `json:"-"`

	// ParentBased and NoParent dictate if and when new spans should be created.
	// ParentBased = "ignore" (default), tracing is effectively turned off and the "NoParent" value is ignored
	// ParentBased = "honor", the sampling decision is made by the parent of the span
	ParentBased string `json:"parentBased"`

	// NoParent decides if a root span should be initiated in the case where there is no existing parent
	// This value is ignored if ParentBased = "ignore"
	// NoParent = "never" (default), root spans are not initiated
	// NoParent = "always", roots spans are initiated
	NoParent string `json:"noParent"`
}

Config specifies parameters relevant for otel trace provider.

type LoggerFunc

type LoggerFunc func([]interface{}, *http.Request) []interface{}

LoggerFunc is a strategy for adding key/value pairs (possibly) based on an HTTP request. Functions of this type must append key/value pairs to the supplied slice and then return the new slice.

type ProviderConstructor

type ProviderConstructor func(config Config, sampler sdktrace.Sampler) (trace.TracerProvider, error)

ProviderConstructor is useful when client wants to add their own custom TracerProvider.

type TraceConfig

type TraceConfig struct {
	TraceProvider trace.TracerProvider
}

TraceConfig will be used in TraceMiddleware to use config and TraceProvider objects created by ConfigureTracerProvider. (Deprecated). Consider using Tracing instead.

func (*TraceConfig) TraceMiddleware

func (traceConfig *TraceConfig) TraceMiddleware(delegate http.Handler) http.Handler

TraceMiddleware acts as interceptor that is the first point of interaction for all requests. It will be responsible for starting a new span with existing traceId if present in the request header as traceparent. Otherwise it will generate new trace id. Example of traceparent will be version[2]-traceId[32]-spanId[16]-traceFlags[2]. It is mandatory for continuing existing traces while tracestate is optional. Deprecated. Please consider using EchoFirstTraceNodeInfo.

type Tracing

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

Tracing contains the core dependencies to make tracing possible across an application.

func New

func New(config Config) (Tracing, error)

New creates a structure with components that apps can use to initialize OpenTelemetry tracing instrumentation code.

func (Tracing) IsNoop

func (t Tracing) IsNoop() bool

IsNoop returns true if the tracer provider component is a noop. False otherwise.

func (Tracing) Propagator

func (t Tracing) Propagator() propagation.TextMapPropagator

Propagator returns the component that helps propagate trace context across API boundaries. By default, a W3C Trace Context format propagator is returned.

func (Tracing) TracerProvider

func (t Tracing) TracerProvider() trace.TracerProvider

TracerProvider returns the tracer provider component. By default, the noop tracer provider is returned.