Launcher, a Lightstep Distro for OpenTelemetry 🚀

What is Launcher?

Launcher is a configuration layer that chooses default values for configuration options that many OpenTelemetry users want. It provides a single function in each language to simplify discovery of the options and components available to users. The goal of Launcher is to help users that aren't familiar with OpenTelemetry quickly ramp up on what they need to get going and instrument.

Getting started

go get github.com/lightstep/otel-launcher-go/launcher

Configure

Minimal setup

import "github.com/lightstep/otel-launcher-go/launcher"

func main() {
    otel := launcher.ConfigureOpentelemetry(
        launcher.WithServiceName("service-name"),
        launcher.WithAccessToken("access-token"),
    )
    defer otel.Shutdown()
}

For non-lightstep providers, you can set headers directly instead.

import "github.com/lightstep/otel-launcher-go/launcher"

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

Additional options

Configuration Options

Principles behind Launcher

100% interoperability with OpenTelemetry

One of the key principles behind putting together Launcher is to make lives of OpenTelemetry users easier, this means that there is no special configuration that requires users to install Launcher in order to use OpenTelemetry. It also means that any users of Launcher can leverage the flexibility of configuring OpenTelemetry as they need.

Validation

Another decision we made with launcher is to provide end users with a layer of validation of their configuration. This provides us the ability to give feedback to our users faster, so they can start collecting telemetry sooner.

Start using it today in Go, Java, Javascript and Python and let us know what you think!

OpenTelemetry Metrics support

Lightstep Metrics SDK

NOTE: The Lightstep Metrics SDK is enabled by default.

The Launcher contains an alternative to the OTel-Go community Metrics SDK being maintained by Lightstep as a way to quickly validate newer OpenTelemetry features, such as the OpenTelemetry exponential histogram.

The OTel-Go community SDK is not enabled by default. This option will return when the OTel-Go community SDK reaches a stable release.

To select the OTel-Go community Metrics SDK, use WithLightstepMetricsSDK(false) or set LS_METRICS_SDK=false.

The differences between the OpenTelemetry Metrics SDK specification and the alternative SDK are documented in its README.

Metrics Temporality settings

OpenTelemetry metrics SDKs give the user control over "temporality", which is the selection of "delta" or "cumulative" policies for aggregating Counter and Histogram instruments. These settings determine both memory usage and reliability of metrics reporting.

Delta temporality requires less memory than cumulative temporality for synchronous instruments, while Cumulative requires less memory than delta temporality for asynchronous instruments. When reporting is intermittent, cumulative series will average out the missing reports, whereas delta series will have gaps.

Note that Lightstep considers a change of temporality to be a breaking change. Once a temporality preference has been set, the setting has to be maintained. The temporality preference is configured by calling WithMetricExporterTemporalityPreference() or using the OTEL_EXPORTER_OTLP_METRIC_TEMPORALITY_PREFERENCE environment variable.

The launcher supports a "stateless" temporality preference. This selection configures the ideal behavior for Lightstep by mixing temporality setings.

The 1.x launcher release series configures the "cumulative" temporality preference by default. The next major release of launcher will configure the "stateless" temporality preference.

Lightstep users are recommended to select either the "cumulative" or "stateless" preference. The OpenTelemetry-specified "delta" temporality preference is not recommended for Lightstep users.

Metrics validation errors

Lightstep performs a number of validation steps over metrics data before accepting it. When an OTLP Metrics export request is successful but data is completely or partially rejected for any reason, the outcome is detailed using Lightstep-specific response headers.

These headers predate work in OpenTelemetry on returning partial success. Lightstep expects to use standard OTLP fields to convey these partially-successful outcomes in the future.

Validation errors are generally repetitive. Lightstep limits the size of each partial-success response to lower the overhead associated with these responses using random selection.

The launcher contains special code to interpret these headers and direct them to the standard OpenTelemetry-Go error handler.

Made with @ Lightstep