tracetools

Documentation

Index

• Constants
• func DecodeTraceContext(env map[string]string) (opentracing.SpanContext, error)
• func EncodeTraceContext(span opentracing.Span, env map[string]string) error
• func FinishWithError(span opentracing.Span, err error, fields ...log.Field)
• func StartSpanFromContext(ctx context.Context, operation string) (opentracing.Span, context.Context)

Examples

• EncodeTraceContext

Constants

const EnvVarTraceContextKey = "BUILDKITE_TRACE_CONTEXT"

EnvVarTraceContextKey is the env var key that will be used to store/retrieve the encoded trace context information into env var maps.

Functions

func DecodeTraceContext

func DecodeTraceContext(env map[string]string) (opentracing.SpanContext, error)

DecodeTraceContext will decode, deserialize, and extract the tracing data from the given env var map.

func EncodeTraceContext

func EncodeTraceContext(span opentracing.Span, env map[string]string) error

EncodeTraceContext will serialize and encode tracing data into a string and place it into the given env vars map.

Example

// Start and configure the tracer to use the propagator.
t := opentracer.New(
	// These args are just to ensure nothing actually gets sent if the test
	// platform actually has a DD agent running locally.
	// This is an unlikely, local, non-default agent address.
	tracer.WithAgentAddr("10.0.0.1:65534"),
	tracer.WithLogger(&nullLogger{}),
)
opentracing.SetGlobalTracer(t)
defer tracer.Stop()

childEnv := map[string]string{}

// Pretend this is the parent process' code
func() {
	span := opentracing.StartSpan("parent process")
	defer span.Finish()

	span.SetBaggageItem("asd", "zxc")

	// Do stuff..
	time.Sleep(time.Millisecond * 20)

	// Now say we want to launch a child process.
	// Prepare it's env vars. This will be the carrier for the tracing data.
	if err := EncodeTraceContext(span, childEnv); err != nil {
		fmt.Println("oops an error for parent process trace injection")
	}
	// Now childEnv will contain the encoded data set with the env var key.
	// Print stuff out for the purpose of the example test.
	if childEnv["BUILDKITE_TRACE_CONTEXT"] == "" {
		fmt.Println("oops empty tracing data in env vars")
	} else {
		fmt.Println("prepared child env carrier data")
	}

	// Normally, you'd now launch a child process with code like:
	// cmd := exec.Command("echo", "hello", "i", "am", "a", "child")
	// cmd.Env = ... // Propagate the env vars here
	// cmd.Run()
	// The important thing is the Env propagation
}()

// Pretend this is the child process' code
func() {
	// Make sure tracing is setup the same way (same env var key)
	// Normally you'd use os.Environ or similar here (the list of strings is
	// supported). We're just reusing childEnv for test simplicity.
	sctx, err := DecodeTraceContext(childEnv)
	if err != nil {
		fmt.Println("oops an error for child process trace extraction")
	} else {
		fmt.Println("extracted tracing data for child process")
	}

	sctx.ForeachBaggageItem(func(k, v string) bool {
		fmt.Printf("bag: %s=%s\n", k, v)
		return true
	})

	// Now you can start a 'root' span for the child that will also be linked to
	// the parent process.
	span := opentracing.StartSpan("child process", opentracing.ChildOf(sctx))
	defer span.Finish()

	// Do stuff...
	time.Sleep(time.Millisecond * 30)
}()

Output:

prepared child env carrier data
extracted tracing data for child process
bag: asd=zxc

func FinishWithError

func FinishWithError(span opentracing.Span, err error, fields ...log.Field)

FinishWithError is syntactic sugar for opentracing APIs to add errors to a span and then finishing it. If the error is nil, the span will only be finished.

func StartSpanFromContext

func StartSpanFromContext(ctx context.Context, operation string) (opentracing.Span, context.Context)

StartSpanFromContext will start a span from the given context with the given operation name. It will also do some common/repeated setup on the span to keep code a little more DRY.