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 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.
go get github.com/lightstep/otel-launcher-go/launcher
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
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 |
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.
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!
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
.
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.
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