Change defaults: stateless temporality preference, lightstep metrics SDK

CHANGELOG.md

@@ -21,6 +21,16 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   SDKs.  Users who encounter errors related to histogram instruments
   (e.g,. `process.runtime.go.gc.pause_ns`) please contact a Lightstep
   representative. [#249](https://github.com/lightstep/otel-launcher-go/pull/249)
+- Exponential histogram changes boundary inclusivity from lower-inclusive to
+  upper-inclusive. This is defined as a non-breaking change because implementations
+  have not required exactness.  With this change, exact powers-of-two are
+  treated as exact special cases.  [#254](https://github.com/lightstep/otel-launcher-go/pull/254)
+- Lightstep metrics SDK is enabled by default.  We are now confident in this
+  SDK even as we have discovered new issues with the old one. [#258](https://github.com/lightstep/otel-launcher-go/pull/258)
+- Stateless temporality preference is used by default; we are intentionally
+  combining a number of potentially breaking changes into this release, to avoid
+  repeated breakage.  This is especially important for exponential histogram
+  data quality. [#258](https://github.com/lightstep/otel-launcher-go/pull/258)
 
 ## [1.9.0](https://github.com/lightstep/otel-launcher-go/releases/tag/v1.9.0) - 2022-08-04
 

README.md

@@ -86,19 +86,19 @@ Start using it today in [Go](https://github.com/lightstep/otel-launcher-go), [Ja
 
 ### Lightstep Metrics SDK
 
-**WARNING**: This SDK is new and is still undergoing early production
-testing at Lightstep.  Please use this SDK with caution until further
-notice.
+**NOTE**: The Lightstep Metrics SDK is enabled by default.
 
 The Launcher contains an alternative to the [OTel-Go community Metrics
 SDK](https://github.com/open-telemetry/opentelemetry-go) being
 maintained by Lightstep as a way to quickly validate newer
 OpenTelemetry features, such as the OpenTelemetry exponential
 histogram.
 
-The community SDK is used by default.  To select the alternative
-Metrics SDK, use `WithLightstepMetricsSDK(true)` or set
-`LS_METRICS_SDK=true`.
+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
@@ -124,11 +124,6 @@ to be maintained.  The temporality preference is configured by calling
 `OTEL_EXPORTER_OTLP_METRIC_TEMPORALITY_PREFERENCE` environment
 variable.
 
-The exporter temporality preference is set to "cumulative" by default,
-as per the OpenTelemetry SDK specification.  The OpenTelemetry
-specified "delta" temporality preference is not recommended for
-Lightstep users.
-
 The launcher supports an experimental "stateless" temporality
 preference.  This selection configures the ideal behavior for
 Lightstep by mixing temporality setings.  This setting uses delta
@@ -138,6 +133,11 @@ synchronous and asynchronous UpDownCounter instruments are specified
 to use cumulative temporality in OpenTelemetry metrics SDKs
 independent of the temporality preference.
 
+The exporter temporality preference is set to "stateless" by default,
+which is not specified presently in OpenTelemetry.  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

go.mod

@@ -39,7 +39,7 @@ require (
 	go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v0.31.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.9.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.9.0 // indirect
-	go.opentelemetry.io/otel/sdk/metric v0.31.0 // indirect
+	go.opentelemetry.io/otel/sdk/metric v0.31.1-0.20220826135333-55b49c407e07 // indirect
 	go.opentelemetry.io/proto/otlp v0.18.0 // indirect
 	go.uber.org/atomic v1.7.0 // indirect
 	go.uber.org/multierr v1.8.0 // indirect

go.sum

@@ -211,8 +211,8 @@ go.opentelemetry.io/otel/metric v0.31.0 h1:6SiklT+gfWAwWUR0meEMxQBtihpiEs4c+vL9s
 go.opentelemetry.io/otel/metric v0.31.0/go.mod h1:ohmwj9KTSIeBnDBm/ZwH2PSZxZzoOaG2xZeekTRzL5A=
 go.opentelemetry.io/otel/sdk v1.9.0 h1:LNXp1vrr83fNXTHgU8eO89mhzxb/bbWAsHG6fNf3qWo=
 go.opentelemetry.io/otel/sdk v1.9.0/go.mod h1:AEZc8nt5bd2F7BC24J5R0mrjYnpEgYHyTcM/vrSple4=
-go.opentelemetry.io/otel/sdk/metric v0.31.0 h1:2sZx4R43ZMhJdteKAlKoHvRgrMp53V1aRxvEf5lCq8Q=
-go.opentelemetry.io/otel/sdk/metric v0.31.0/go.mod h1:fl0SmNnX9mN9xgU6OLYLMBMrNAsaZQi7qBwprwO3abk=
+go.opentelemetry.io/otel/sdk/metric v0.31.1-0.20220826135333-55b49c407e07 h1:nOHjEUsL5x134vpNDPwCZdp+EmvVE6qcPp9g7gWbf2E=
+go.opentelemetry.io/otel/sdk/metric v0.31.1-0.20220826135333-55b49c407e07/go.mod h1:Wx4hLV+yy0fBWE4doK+3sK8O6gcaVHRf0BRvwOzl+jI=
 go.opentelemetry.io/otel/trace v1.9.0 h1:oZaCNJUjWcg60VXWee8lJKlqhPbXAPB51URuR47pQYc=
 go.opentelemetry.io/otel/trace v1.9.0/go.mod h1:2737Q0MuG8q1uILYm2YYVkAyLtOofiTNGg6VODnOiPo=
 go.opentelemetry.io/proto/otlp v0.7.0/go.mod h1:PqfVotwruBrMGOCsRd/89rSnXhoiJIqeYNgFYFoEGnI=

launcher/config.go

@@ -212,12 +212,12 @@ type Config struct {
 	Headers                             map[string]string `env:"OTEL_EXPORTER_OTLP_HEADERS"`
 	MetricExporterEndpoint              string            `env:"OTEL_EXPORTER_OTLP_METRIC_ENDPOINT,default=ingest.lightstep.com:443"`
 	MetricExporterEndpointInsecure      bool              `env:"OTEL_EXPORTER_OTLP_METRIC_INSECURE,default=false"`
-	MetricExporterTemporalityPreference string            `env:"OTEL_EXPORTER_OTLP_METRIC_TEMPORALITY_PREFERENCE,default=cumulative"`
+	MetricExporterTemporalityPreference string            `env:"OTEL_EXPORTER_OTLP_METRIC_TEMPORALITY_PREFERENCE,default=stateless"`
 	MetricsEnabled                      bool              `env:"LS_METRICS_ENABLED,default=true"`
 	LogLevel                            string            `env:"OTEL_LOG_LEVEL,default=info"`
 	Propagators                         []string          `env:"OTEL_PROPAGATORS,default=b3"`
 	MetricReportingPeriod               string            `env:"OTEL_EXPORTER_OTLP_METRIC_PERIOD,default=30s"`
-	UseLightstepMetricsSDK              bool              `env:"LS_METRICS_SDK,default=false"`
+	UseLightstepMetricsSDK              bool              `env:"LS_METRICS_SDK,default=true"`
 	ResourceAttributes                  map[string]string
 	Resource                            *resource.Resource
 	logger                              Logger

launcher/config_test.go

@@ -375,11 +375,11 @@ func (suite *testSuite) TestDefaultConfig() {
 		MetricExporterEndpointInsecure:      false,
 		MetricReportingPeriod:               "30s",
 		MetricsEnabled:                      true,
-		MetricExporterTemporalityPreference: "cumulative",
+		MetricExporterTemporalityPreference: "stateless",
 		LogLevel:                            "info",
 		Propagators:                         []string{"b3"},
 		Resource:                            resource.NewWithAttributes(semconv.SchemaURL, attributes...),
-		UseLightstepMetricsSDK:              false,
+		UseLightstepMetricsSDK:              true,
 		logger:                              &suite.testLogger,
 		errorHandler:                        &suite.testErrorHandler,
 	}

lightstep/sdk/metric/exporters/otlp/internal/metrictransform/metric_test.go

@@ -214,7 +214,19 @@ func TestMetricTransform(t *testing.T) {
 						testUnit,
 						expectCumulative,
 						otlptest.HistogramDataPoint(
-							expectAttrs1, startTime, endTime, 7, 3, 0, 1, 4, 0, 0, []uint64{1, 1, 1}, 0, nil,
+							expectAttrs1,
+							startTime,
+							endTime,
+							7,  // sum
+							3,  // count
+							0,  // zero count
+							1,  // min
+							4,  // max
+							0,  // scale
+							-1, // positive offset
+							[]uint64{1, 1, 1},
+							0, // negative offset
+							nil,
 						),
 					),
 				),
@@ -253,17 +265,15 @@ func TestMetricTransform(t *testing.T) {
 							expectAttrs0,
 							middleTime,
 							endTime,
-							10.5,
-							8,
-							2,
-							-2, // min
-							8,  // max
-							0,
-							// positive offset by 1
-							1,
+							10.5, // sum
+							8,    // count
+							2,    // zero count
+							-2,   // min
+							8,    // max
+							0,    // scale
+							0,    // positive offset
 							[]uint64{1, 1, 1},
-							// negative offset by -1
-							-1,
+							-2, // negative offset
 							[]uint64{1, 1, 1},
 						),
 					),

pipelines/metrics.go

@@ -239,6 +239,12 @@ func tempoOptions(c PipelineConfig) (view.Option, oldaggregation.TemporalitySele
 		syncPref = aggregation.DeltaTemporality
 		asyncPref = aggregation.DeltaTemporality
 
+		// Note: the following is incorrect for UpDownCounter
+		// and async UpDownCounter, which the OTel
+		// specification stipulates are not affected by the
+		// preference setting.  We WILL NOT FIX this defect.
+		// Instead, as otel-launcher-go v1.10.x will use the
+		// Lightstep metrics SDK by default.
 		oldSelector = oldaggregation.DeltaTemporalitySelector()
 	case "stateless":
 		// asyncPref set above.