autoexport: Update docs (#4132)

CHANGELOG.md

@@ -12,7 +12,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - Add `NewMiddleware` function in `go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp`. (#2964)
 - Add the new `go.opentelemetry.io/contrib/instrgen` package to provide auto-generated source code instrumentation. (#3068, #3108)
-- The `go.opentelemetry.io/contrib/exporters/autoexport` package to provide configuration of trace exporters with useful defaults and envar support. (#2753, #4100, #4129)
+- The `go.opentelemetry.io/contrib/exporters/autoexport` package to provide configuration of trace exporters with useful defaults and envar support. (#2753, #4100, #4129, #4132)
 - `WithRouteTag` in `go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp` adds HTTP route attribute to metrics. (#615)
 
 ### Fixed

exporters/autoexport/doc.go

@@ -12,22 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// This module provides easy access to configuring a trace exporter
-// that can be used when configuring an OpenTelemetry Go SDK trace export
-// pipeline.
-//
-// [NewSpanExporter] looks for the `OTEL_TRACES_EXPORTER` environment
-// variable and if set, attempts to load the exporter from it's registry of
-// exporters. The registry is always loaded with an OTLP exporter with the key
-// `otlp` and additional exporters can be registered using
-// [RegisterSpanExporter].
-// Exporter registration uses a factory method pattern to not unneccarily build
-// exporters and use resources until they are requested.
-//
-// If the environment variable is not set, the fallback exporter is returned.
-// The fallback exporter defaults to an
-// [OTLP exporter](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace)
-// and can be overridden using the [RegisterSpanExporter](https://pkg.go.dev/go.opentelemetry.io/contrib/exporters/autoexport#WithFallbackSpanExporter)
-// option.
-
+// Package autoexport provides OpenTelemetry exporter factory functions
+// with defaults and environment variable support as defined by the
+// OpenTelemetry specification.
 package autoexport // import "go.opentelemetry.io/contrib/exporters/autoexport"

exporters/autoexport/exporter.go

@@ -66,9 +66,28 @@ func WithFallbackSpanExporter(exporter trace.SpanExporter) Option {
 	})
 }
 
-// NewSpanExporter returns a configured SpanExporter defined using the environment
-// variable OTEL_TRACES_EXPORTER, the configured fallback exporter via options or
-// a default OTLP exporter (in this order).
+// NewSpanExporter returns a configured [go.opentelemetry.io/otel/sdk/trace.SpanExporter]
+// defined using the environment variables described below.
+//
+// OTEL_TRACES_EXPORTER defines the traces exporter; supported values:
+//   - "none" - "no operation" exporter
+//   - "otlp" (default) - OTLP exporter; see [go.opentelemetry.io/otel/exporters/otlp/otlptrace]
+//
+// OTEL_EXPORTER_OTLP_PROTOCOL defines OTLP exporter's transport protocol;
+// supported values:
+//   - "grpc" - protobuf-encoded data using gRPC wire format over HTTP/2 connection;
+//     see: [go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc]
+//   - "http/protobuf" (default) -  protobuf-encoded data over HTTP connection;
+//     see: [go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp]
+//
+// An error is returned if an environment value is set to an unhandled value.
+//
+// Use [RegisterSpanExporter] to handle more values of OTEL_TRACES_EXPORTER.
+//
+// Use [WithFallbackSpanExporter] option to change the returned exporter
+// when OTEL_TRACES_EXPORTER is unset or empty.
+//
+// Use [IsNone] to check if the retured exporter is a "no operation" exporter.
 func NewSpanExporter(ctx context.Context, opts ...Option) (trace.SpanExporter, error) {
 	// prefer exporter configured via environment variables over exporter
 	// passed in via exporter parameter

exporters/autoexport/exporter_test.go

@@ -72,6 +72,14 @@ func TestEnvExporterOTLPOverGRPC(t *testing.T) {
 	assertOTLPGRPCExporter(t, exporter)
 }
 
+func TestEnvExporterOTLPOverGRPCOnlyProtocol(t *testing.T) {
+	t.Setenv("OTEL_EXPORTER_OTLP_PROTOCOL", "grpc")
+
+	exporter, err := NewSpanExporter(context.Background())
+	assert.NoError(t, err)
+	assertOTLPGRPCExporter(t, exporter)
+}
+
 func TestEnvExporterOTLPInvalidProtocol(t *testing.T) {
 	t.Setenv("OTEL_TRACES_EXPORTER", "otlp")
 	t.Setenv("OTEL_EXPORTER_OTLP_PROTOCOL", "invalid")