env

README

This is a utility to work with OpenTelemetry to propagate tracing context through environment variables. Read more about propagation here. This is meant to be used by command line tools which enable tracing.

Documentation

Index

• func ContextWithRemoteSpanContext(ctx context.Context, environ []string) context.Context
• func Inject(ctx context.Context, environ []string) []string
• type Carrier
  • func (c *Carrier) Get(key string) string
  • func (c *Carrier) Keys() []string
  • func (c *Carrier) Set(key, value string)

Examples

• ContextWithRemoteSpanContext
• ContextWithRemoteSpanContext (B3)
• Inject
• Inject (B3)

Functions

func ContextWithRemoteSpanContext

func ContextWithRemoteSpanContext(ctx context.Context, environ []string) context.Context

ContextWithRemoteSpanContext extracts a remote SpanContext from the environment and will set the new SpanContext on the returned Context

Example

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/coryb/otelbundle/propagation/env"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/propagation"
	"go.opentelemetry.io/otel/trace"
)

func main() {
	otel.SetTextMapPropagator(propagation.TraceContext{})

	// these would normally be imported from environment
	os.Setenv("TRACESTATE", "")
	os.Setenv("TRACEPARENT", "00-60d19e9e9abf2197c1d6d8f93e28ee2a-a028bd951229a46f-01")

	// extract span context from environ
	ctx := env.ContextWithRemoteSpanContext(context.Background(), os.Environ())
	span := trace.SpanFromContext(ctx)

	fmt.Printf("TraceID: %s\n", span.SpanContext().TraceID().String())
	fmt.Printf("SpanID: %s\n", span.SpanContext().SpanID().String())
	fmt.Printf("Is Sampled: %t\n", span.SpanContext().IsSampled())
}

Output:

TraceID: 60d19e9e9abf2197c1d6d8f93e28ee2a
SpanID: a028bd951229a46f
Is Sampled: true

Example (B3)

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/coryb/otelbundle/propagation/env"
	"go.opentelemetry.io/contrib/propagators/b3"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/trace"
)

func main() {
	otel.SetTextMapPropagator(b3.B3{InjectEncoding: b3.B3MultipleHeader})

	// these would normally be imported from environment
	os.Setenv("X_B3_TRACEID", "60d19e9e9abf2197c1d6d8f93e28ee2a")
	os.Setenv("X_B3_SPANID", "a028bd951229a46f")
	os.Setenv("X_B3_SAMPLED", "1")

	// extract span context from environ
	ctx := env.ContextWithRemoteSpanContext(context.Background(), os.Environ())
	span := trace.SpanFromContext(ctx)

	fmt.Printf("TraceID: %s\n", span.SpanContext().TraceID().String())
	fmt.Printf("SpanID: %s\n", span.SpanContext().SpanID().String())
	fmt.Printf("Is Sampled: %t\n", span.SpanContext().IsSampled())
}

Output:

TraceID: 60d19e9e9abf2197c1d6d8f93e28ee2a
SpanID: a028bd951229a46f
Is Sampled: true

func Inject

func Inject(ctx context.Context, environ []string) []string

Inject will add add any necessary environment variables for the span found in the Context. If environment variables are already present in `environ` then they will be updated. If no variables are found the new ones will be appended. The new environment will be returned, `environ` will never be modified.

Example

package main

import (
	"context"
	"os"
	"os/exec"

	"github.com/coryb/otelbundle/propagation/env"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/propagation"
)

func main() {
	otel.SetTextMapPropagator(propagation.TraceContext{})
	tracer := otel.Tracer("example")
	ctx, span := tracer.Start(context.Background(), "testing")
	defer span.End()

	cmd := exec.Command("env")
	cmd.Stdout = os.Stdout
	cmd.Env = env.Inject(ctx, []string{"PATH=/usr/bin:/bin"})
	cmd.Run()
}

Output:

PATH=/usr/bin:/bin
TRACESTATE=
TRACEPARENT=00-60d19e9e9abf2197c1d6d8f93e28ee2a-a028bd951229a46f-01

Example (B3)

package main

import (
	"context"
	"os"
	"os/exec"

	"github.com/coryb/otelbundle/propagation/env"
	"go.opentelemetry.io/contrib/propagators/b3"
	"go.opentelemetry.io/otel"
)

func main() {
	otel.SetTextMapPropagator(b3.B3{InjectEncoding: b3.B3MultipleHeader})
	tracer := otel.Tracer("example")
	ctx, span := tracer.Start(context.Background(), "testing")
	defer span.End()

	cmd := exec.Command("env")
	cmd.Stdout = os.Stdout
	cmd.Env = env.Inject(ctx, []string{"PATH=/usr/bin:/bin"})
	cmd.Run()
}

Output:

PATH=/usr/bin:/bin
X_B3_TRACEID=60d19e9e9abf2197c1d6d8f93e28ee2a
X_B3_SPANID=a028bd951229a46f
X_B3_SAMPLED=1

Types

type Carrier

type Carrier struct {
	Env []string
}

Carrier is a propagation.TextMapCarrier that is used to extract or inject tracing environment variables. This is used with a propagation.TextMapPropagator

func (*Carrier) Get

func (c *Carrier) Get(key string) string

func (*Carrier) Keys

func (c *Carrier) Keys() []string

func (*Carrier) Set

func (c *Carrier) Set(key, value string)