launcher

README

OpenTelemetry Go Launcher

The Go Launcher is a configuration layer that chooses default values for configuration options that many OpenTelemetry users would ultimately configure manually, allowing for minimal code to quickly instrument with OpenTelemetry.

Getting started

go get github.com/opentelemetry-go-contrib/otel-launcher-go/launcher

Configure

Minimal setup - by default will send all telemetry via GRPC to localhost:4317

import "github.com/opentelemetry-go-contrib/otel-launcher-go/launcher"

func main() {
    lnchr, err := launcher.ConfigureOpentelemetry()
    defer lnchr.Shutdown()
}

You can set headers directly instead.

import "github.com/opentelemetry-go-contrib/otel-launcher-go/launcher"

func main() {
    lnchr, err := launcher.ConfigureOpentelemetry(
        launcher.WithServiceName("service-name"),
        launcher.WithHeaders(map[string]string{
            "service-auth-key": "value",
            "service-useful-field": "testing",
        }),
    )
    defer lnchr.Shutdown()
}

Configuration Options

Config Option	Env Variable	Required	Default
WithServiceName	OTEL_SERVICE_NAME	y	-
WithServiceVersion	OTEL_SERVICE_VERSION	n	-
WithHeaders	OTEL_EXPORTER_OTLP_HEADERS	n	{}
WithProtocol	OTEL_EXPORTER_OTLP_PROTOCOL	n	grpc
WithTracesExporterEndpoint	OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	n	localhost:4317
WithTracesExporterInsecure	OTEL_EXPORTER_OTLP_TRACES_INSECURE	n	false
WithMetricsExporterEndpoint	OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	n	localhost:4317
WithMetricsExporterInsecure	OTEL_EXPORTER_OTLP_METRICS_INSECURE	n	false
WithLogLevel	OTEL_LOG_LEVEL	n	info
WithPropagators	OTEL_PROPAGATORS	n	tracecontext,baggage
WithResourceAttributes	OTEL_RESOURCE_ATTRIBUTES	n	-
WithMetricsReportingPeriod	OTEL_EXPORTER_OTLP_METRICS_PERIOD	n	30s
WithMetricsEnabled	OTEL_METRICS_ENABLED	n	true
WithTracesEnabled	OTEL_TRACES_ENABLED	n	true

Documentation

Index

• Constants
• Variables
• func ConfigureOpenTelemetry(opts ...Option) (func(), error)
• type Config
• type Launcher
  • func (ls Launcher) Shutdown()
• type Logger
• type Option
  • func WithErrorHandler(handler otel.ErrorHandler) Option
  • func WithExporterEndpoint(url string) Option
  • func WithExporterInsecure(insecure bool) Option
  • func WithExporterProtocol(protocol Protocol) Option
  • func WithHeaders(headers map[string]string) Option
  • func WithLogLevel(loglevel string) Option
  • func WithLogger(logger Logger) Option
  • func WithMetricsEnabled(enabled bool) Option
  • func WithMetricsExporterEndpoint(url string) Option
  • func WithMetricsExporterInsecure(insecure bool) Option
  • func WithMetricsExporterProtocol(protocol Protocol) Option
  • func WithMetricsHeaders(headers map[string]string) Option
  • func WithMetricsReportingPeriod(p time.Duration) Option
  • func WithPropagators(propagators []string) Option
  • func WithResourceAttributes(attributes map[string]string) Option
  • func WithSampler(sampler trace.Sampler) Option
  • func WithServiceName(name string) Option
  • func WithServiceVersion(version string) Option
  • func WithShutdown(f func(c *Config) error) Option
  • func WithSpanProcessor(sp ...trace.SpanProcessor) Option
  • func WithTracesEnabled(enabled bool) Option
  • func WithTracesExporterEndpoint(url string) Option
  • func WithTracesExporterInsecure(insecure bool) Option
  • func WithTracesExporterProtocol(protocol Protocol) Option
  • func WithTracesHeaders(headers map[string]string) Option
• type Protocol

Constants

const (
	// GRPC default port.
	GRPCDefaultPort = "4317"
	// HTTP default port.
	HTTPDefaultPort = "4318"
)

These are strings because they get appended to the host.

Variables

var (
	// SetVendorOptions provides a way for a vendor to add a set of Options that are automatically applied.
	SetVendorOptions func() []Option
	// ValidateConfig is a function that a vendor can implement to provide additional validation after
	// a configuration is built.
	ValidateConfig func(*Config) error
)

Functions

func ConfigureOpenTelemetry

func ConfigureOpenTelemetry(opts ...Option) (func(), error)

ConfigureOpenTelemetry is a function that be called with zero or more options. Options can be the basic ones above, or provided by individual vendors.

Types

type Config

type Config struct {
	ExporterEndpoint                string   `env:"OTEL_EXPORTER_OTLP_ENDPOINT,default=localhost"`
	ExporterEndpointInsecure        bool     `env:"OTEL_EXPORTER_OTLP_INSECURE,default=false"`
	TracesExporterEndpoint          string   `env:"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"`
	TracesExporterEndpointInsecure  bool     `env:"OTEL_EXPORTER_OTLP_TRACES_INSECURE"`
	TracesEnabled                   bool     `env:"OTEL_TRACES_ENABLED,default=true"`
	ServiceName                     string   `env:"OTEL_SERVICE_NAME"`
	ServiceVersion                  string   `env:"OTEL_SERVICE_VERSION,default=unknown"`
	MetricsExporterEndpoint         string   `env:"OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"`
	MetricsExporterEndpointInsecure bool     `env:"OTEL_EXPORTER_OTLP_METRICS_INSECURE"`
	MetricsEnabled                  bool     `env:"OTEL_METRICS_ENABLED,default=true"`
	MetricsReportingPeriod          string   `env:"OTEL_EXPORTER_OTLP_METRICS_PERIOD,default=30s"`
	LogLevel                        string   `env:"OTEL_LOG_LEVEL,default=info"`
	Propagators                     []string `env:"OTEL_PROPAGATORS,default=tracecontext,baggage"`
	ResourceAttributesFromEnv       string   `env:"OTEL_RESOURCE_ATTRIBUTES"`
	ExporterProtocol                Protocol `env:"OTEL_EXPORTER_OTLP_PROTOCOL,default=grpc"`
	TracesExporterProtocol          Protocol `env:"OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"`
	MetricsExporterProtocol         Protocol `env:"OTEL_EXPORTER_OTLP_METRICS_PROTOCOL"`
	Headers                         map[string]string
	TracesHeaders                   map[string]string
	MetricsHeaders                  map[string]string
	ResourceAttributes              map[string]string
	SpanProcessors                  []trace.SpanProcessor
	Sampler                         trace.Sampler
	Resource                        *resource.Resource
	Logger                          Logger
	ShutdownFunctions               []func(c *Config) error
	// contains filtered or unexported fields
}

Config is a configuration object; it is public so that it can be manipulated by vendors. Note that ExporterEndpoint specifies "DEFAULTPORT"; this is because the default port should vary depending on the protocol chosen. If not overridden by explicit configuration, it will be overridden with an appropriate default upon initialization.

type Launcher

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

Launcher is the object we're here for; it implements the initialization of Open Telemetry.

func (Launcher) Shutdown

func (ls Launcher) Shutdown()

Shutdown is the function called to shut down OpenTelemetry. It invokes any registered shutdown functions.

type Logger

type Logger interface {
	Fatalf(format string, v ...interface{})
	Debugf(format string, v ...interface{})
}

Logger is an interface for a logger that can be passed to WithLogger.

type Option

type Option func(*Config)

Option is the type of an Option to the ConfigureOpenTelemetry function; it's a function that accepts a config and modifies it.

func WithErrorHandler

func WithErrorHandler(handler otel.ErrorHandler) Option

Configures a global error handler to be used throughout an OpenTelemetry instrumented project. See "go.opentelemetry.io/otel".

func WithExporterEndpoint

func WithExporterEndpoint(url string) Option

WithExporterEndpoint configures the generic endpoint used for sending all telemtry signals via OTLP.

func WithExporterInsecure

func WithExporterInsecure(insecure bool) Option

WithExporterInsecure permits connecting to the generic exporter endpoint without a certificate.

func WithExporterProtocol

func WithExporterProtocol(protocol Protocol) Option

WithExporterProtocol defines the default protocol.

func WithHeaders

func WithHeaders(headers map[string]string) Option

WithHeaders configures OTLP exporter headers.

func WithLogLevel

func WithLogLevel(loglevel string) Option

WithLogLevel configures the logging level for OpenTelemetry.

func WithLogger

func WithLogger(logger Logger) Option

WithLogger sets up the logger to be used by the launcher.

func WithMetricsEnabled

func WithMetricsEnabled(enabled bool) Option

WithMetricsEnabled configures whether metrics should be enabled.

func WithMetricsExporterEndpoint

func WithMetricsExporterEndpoint(url string) Option

WithMetricsExporterEndpoint configures the endpoint for sending metrics via OTLP.

func WithMetricsExporterInsecure

func WithMetricsExporterInsecure(insecure bool) Option

WithMetricsExporterInsecure permits connecting to the metric endpoint without a certificate.

func WithMetricsExporterProtocol

func WithMetricsExporterProtocol(protocol Protocol) Option

WithMetricsExporterProtocol defines the protocol for Metrics.

func WithMetricsHeaders

func WithMetricsHeaders(headers map[string]string) Option

WithMetricsHeaders configures OTLP metrics exporter headers.

func WithMetricsReportingPeriod

func WithMetricsReportingPeriod(p time.Duration) Option

WithMetricsReportingPeriod configures the metric reporting period, how often the controller collects and exports metric data.

func WithPropagators

func WithPropagators(propagators []string) Option

WithPropagators configures propagators.

func WithResourceAttributes

func WithResourceAttributes(attributes map[string]string) Option

WithResourceAttributes configures attributes on the resource; if the resource already exists, it sets additional attributes or overwrites those already there.

func WithSampler

func WithSampler(sampler trace.Sampler) Option

WithSampler configures the Sampler to use when processing trace spans.

func WithServiceName

func WithServiceName(name string) Option

WithServiceName configures a "service.name" resource label.

func WithServiceVersion

func WithServiceVersion(version string) Option

WithServiceVersion configures a "service.version" resource label.

func WithShutdown

func WithShutdown(f func(c *Config) error) Option

WithShutdown adds functions that will be called first when the shutdown function is called. They are given a copy of the Config object (which has access to the Logger), and should return an error only in extreme circumstances, as an error return here is immediately fatal.

func WithSpanProcessor

func WithSpanProcessor(sp ...trace.SpanProcessor) Option

WithSpanProcessor adds one or more SpanProcessors.

func WithTracesEnabled

func WithTracesEnabled(enabled bool) Option

WithTracesEnabled configures whether traces should be enabled.

func WithTracesExporterEndpoint

func WithTracesExporterEndpoint(url string) Option

WithTracesExporterEndpoint configures the endpoint for sending traces via OTLP.

func WithTracesExporterInsecure

func WithTracesExporterInsecure(insecure bool) Option

WithTracesExporterInsecure permits connecting to the trace endpoint without a certificate.

func WithTracesExporterProtocol

func WithTracesExporterProtocol(protocol Protocol) Option

WithTracesExporterProtocol defines the protocol for Traces.

func WithTracesHeaders

func WithTracesHeaders(headers map[string]string) Option

WithTracesHeaders configures OTLP traces exporter headers.

type Protocol

type Protocol pipelines.Protocol

Protocol defines the possible values of the protocol field.

const (
	ProtocolGRPC      Protocol = Protocol(pipelines.ProtocolGRPC)
	ProtocolHTTPProto Protocol = Protocol(pipelines.ProtocolHTTPProtobuf)
	ProtocolHTTPJSON  Protocol = Protocol(pipelines.ProtocolHTTPJSON)
)

Import the values for Protocol from pipelines but make them available without importing pipelines.