In August 2023, Lightstep became ServiceNow Cloud Observability To ease the transition, all code artifacts will continue to use the Lightstep name. You don't need to do anything to keep using this repository.

Launcher, a Lightstep Distro for OpenTelemetry 🚀 [Deprecated]

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

Config Option	Env Variable	Required	Default
WithServiceName	LS_SERVICE_NAME	y	-
WithServiceVersion	LS_SERVICE_VERSION	n	unknown
WithHeaders	OTEL_EXPORTER_OTLP_HEADERS	n	{}
WithSpanExporterEndpoint	OTEL_EXPORTER_OTLP_SPAN_ENDPOINT	n	ingest.lightstep.com:443
WithSpanExporterInsecure	OTEL_EXPORTER_OTLP_SPAN_INSECURE	n	false
WithMetricExporterEndpoint	OTEL_EXPORTER_OTLP_METRIC_ENDPOINT	n	ingest.lightstep.com:443
WithMetricExporterInsecure	OTEL_EXPORTER_OTLP_METRIC_INSECURE	n	false
WithMetricExporterTemporalityPreference	OTEL_EXPORTER_OTLP_METRIC_TEMPORALITY_PREFERENCE	n	cumulative
WithAccessToken	LS_ACCESS_TOKEN	n	-
WithLogLevel	OTEL_LOG_LEVEL	n	info
WithPropagators	OTEL_PROPAGATORS	n	b3
WithResourceAttributes	OTEL_RESOURCE_ATTRIBUTES	n	-
WithMetricReportingPeriod	OTEL_EXPORTER_OTLP_METRIC_PERIOD	n	30s
WithMetricsEnabled	LS_METRICS_ENABLED	n	true
WithMetricsBuiltinsEnabled	LS_METRICS_BUILTINS_ENABLED	n	true
WithMetricsBuiltinLibraries	LS_METRICS_BUILTIN_LIBRARIES	n	all:stable
WithLightstepMetricsSDK	LS_METRICS_SDK	n	true

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

Builtin metrics libraries

The Launcher optionally starts selected libraries of builtin instrumentation unless explicitly disabled. Use WithMetricsBuiltinsEnabled(false) or set LS_METRICS_BUILTINS_ENABLED=false to disable all builtin metrics instrumentation.

The set of builtin metrics libraries can be configured explicitly. Due to the evolving nature of OpenTelemetry, the metrics produced in these libraries may vary. Use WithMetricsBuiltinLibraries(...) or set LS_METRICS_BUILTIN_LIBRARIES=... to configure which builtin libraries are used. The argument is a comma-separated list of short library names, optionally short_name:version to select a specific version. When no version is specified, the "stable" instrumentation version is selected.

In Launcher version 1.11.0, the default builtin libraries changed to more closely-track the OpenTelemetry metrics specification. The default setting ("all:stable") selects three libraries, described below:

Short name	Metrics produced
host	system.cpu.time, system.memory.usage, system.memory.utilization, system.network.io
cputime	process.cpu.time, process.uptime
runtime	process.runtime.go.* generated from runtime/metrics, e.g., process.runtime.go.cpu.time

The available instrumentation library and versions are listed below:

Short name	Version	Instrumentation
all	stable	same as cputime:stable,host:stable,runtime:stable
cputime	stable	`./lightstep/instrumentation/cputime`
cputime	prestable	none
runtime	stable	`./lightstep/instrumentation/runtime`
runtime	prestable	opentelemetry-go-contrib/instrumentation/runtime
host	stable	`./lightstep/instrumentation/host`
host	prestable	opentelemetry-go-contrib/instrumentation/host

When running inside a container where host metrics are already being collected (e.g., using the OpenTelemetry Collector hostmetrics receiver), users may wish to configure only "cputime" and "runtime" instrumentation.

Note that the "cputime" library is a placeholder for metrics that overlap with or that we expect to be produced in future versions of the "runtime" instrumentation. For example, we expect the Go-1.20 runtime/metrics package to include GC and user CPU time metrics. See the documentation in each of the instrumentation packages for more details.

To configure the behavior in Launcher versions 1.10.x and prior, use WithMetricsBuiltinLibraries("all:prestable") or set LS_METRICS_BUILTIN_LIBRARIES=all:prestable.

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 the standard "lowmemory" temporality preference, also known as "stateless" in this library. 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 "lowmemory" temporality preference.

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

Made with @ Lightstep