autoprop

Documentation

Overview

Package autoprop provides an OpenTelemetry TextMapPropagator creation function. The OpenTelemetry specification states that the default TextMapPropagator needs to be a no-operation implementation. The opentelemetry-go project adheres to this requirement. However, for systems that perform propagation this default is not ideal. This package provides a TextMapPropagator with useful defaults (a combined TraceContext and Baggage TextMapPropagator), and supports environment overrides using the OTEL_PROPAGATORS environment variable.

Index

• Constants
• func NewTextMapPropagator(props ...propagation.TextMapPropagator) propagation.TextMapPropagator
• func RegisterTextMapPropagator(name string, p propagation.TextMapPropagator)
• func TextMapPropagator(names ...string) (propagation.TextMapPropagator, error)

Examples

• NewTextMapPropagator
• NewTextMapPropagator (Arguments)
• NewTextMapPropagator (Environment)
• RegisterTextMapPropagator

Constants

const Version = "0.68.0"

Version is the current release version of the autoprop module.

Functions

func NewTextMapPropagator

func NewTextMapPropagator(props ...propagation.TextMapPropagator) propagation.TextMapPropagator

NewTextMapPropagator returns a new TextMapPropagator composited by props or one defined by the OTEL_PROPAGATORS environment variable. The TextMapPropagator defined by OTEL_PROPAGATORS, if set, will take precedence to the once composited by props.

The propagators supported with the OTEL_PROPAGATORS environment variable by default are: tracecontext, baggage, b3, b3multi, jaeger, xray, ottrace, and none. Each of these values, and their combination, are supported in conformance with the OpenTelemetry specification. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md#general-sdk-configuration for more information.

The supported environment variable propagators can be extended to include custom 3rd-party TextMapPropagator. See the RegisterTextMapPropagator function for more information.

If OTEL_PROPAGATORS is not defined and props is no provided, the returned TextMapPropagator will be a composite of the TraceContext and Baggage propagators.

Example

package main

import (
	"fmt"
	"sort"

	"go.opentelemetry.io/otel"

	"go.opentelemetry.io/contrib/propagators/autoprop"
)

func main() {
	// NewTextMapPropagator returns a TraceContext and Baggage propagator by
	// default. The response of this function can be directly registered with
	// the go.opentelemetry.io/otel package.
	otel.SetTextMapPropagator(autoprop.NewTextMapPropagator())

	fields := otel.GetTextMapPropagator().Fields()
	sort.Strings(fields)
	fmt.Println(fields)
}

Output:
[baggage traceparent tracestate]

Example (Arguments)

package main

import (
	"fmt"
	"sort"

	"go.opentelemetry.io/otel/propagation"

	"go.opentelemetry.io/contrib/propagators/autoprop"
	"go.opentelemetry.io/contrib/propagators/b3"
)

func main() {
	// NewTextMapPropagator behaves the same as the
	// NewCompositeTextMapPropagator function in the
	// go.opentelemetry.io/otel/propagation package when TextMapPropagator are
	// passed as arguments.
	fields := autoprop.NewTextMapPropagator(
		propagation.TraceContext{},
		propagation.Baggage{},
		b3.New(),
	).Fields()
	sort.Strings(fields)
	fmt.Println(fields)
}

Output:
[baggage traceparent tracestate x-b3-flags x-b3-sampled x-b3-spanid x-b3-traceid]

Example (Environment)

package main

import (
	"fmt"
	"os"
	"sort"

	"go.opentelemetry.io/otel/propagation"

	"go.opentelemetry.io/contrib/propagators/autoprop"
)

func main() {
	// Propagators set for the OTEL_PROPAGATORS environment variable take
	// precedence and will override any arguments passed to
	// NewTextMapPropagator.
	_ = os.Setenv("OTEL_PROPAGATORS", "b3,baggage")

	// Returns only a B3 and Baggage TextMapPropagator (i.e. does not include
	// TraceContext).
	fields := autoprop.NewTextMapPropagator(propagation.TraceContext{}).Fields()
	sort.Strings(fields)
	fmt.Println(fields)
}

Output:
[baggage x-b3-flags x-b3-sampled x-b3-spanid x-b3-traceid]

func RegisterTextMapPropagator

func RegisterTextMapPropagator(name string, p propagation.TextMapPropagator)

RegisterTextMapPropagator sets the TextMapPropagator p to be used when the OTEL_PROPAGATORS environment variable contains the propagator name. This will panic if name has already been registered or is a default (tracecontext, baggage, b3, b3multi, jaeger, xray, or ottrace).

Example

package main

import (
	"fmt"
	"os"

	"go.opentelemetry.io/otel/propagation"

	"go.opentelemetry.io/contrib/propagators/autoprop"
)

type myTextMapPropagator struct{ propagation.TextMapPropagator }

func (myTextMapPropagator) Fields() []string {
	return []string{"my-header-val"}
}

func main() {
	// To use your own or a 3rd-party exporter via the OTEL_PROPAGATORS
	// environment variable, it needs to be registered prior to calling
	// NewTextMapPropagator.
	autoprop.RegisterTextMapPropagator("custom-prop", myTextMapPropagator{})

	_ = os.Setenv("OTEL_PROPAGATORS", "custom-prop")
	fmt.Println(autoprop.NewTextMapPropagator().Fields())
}

Output:
[my-header-val]

func TextMapPropagator

func TextMapPropagator(names ...string) (propagation.TextMapPropagator, error)

TextMapPropagator returns a TextMapPropagator composed from the passed names of registered TextMapPropagators. Each name must match an already registered TextMapPropagator (see the RegisterTextMapPropagator function for more information) or a default (tracecontext, baggage, b3, b3multi, jaeger, xray, or ottrace).

If "none" is included in the arguments, or no names are provided, the returned TextMapPropagator will be a no-operation implementation.

An error is returned for any un-registered names. The remaining, known, names will be used to compose a TextMapPropagator that is returned with the error.