Recommend use of initializers for config structs (#1163)

* Recommend use of initializers for config structs

Updates style guide and changes existing configure() implementations to
newConfig() as appropriate.

* Add CHANGELOG.md entry

* Update stdout exporter config initializer

* Add documentation to exported functions

* Convert otlp.Config to unexported otlp.config

CHANGELOG.md

@@ -35,6 +35,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Rename `ParentOrElse` sampler to `ParentBased` and allow setting samplers depending on parent span. (#1153)
 - In the `go.opentelemetry.io/otel/api/trace` package, `SpanConfigure` was renamed to `NewSpanConfig`. (#1155)
 - Change `dependabot.yml` to add a `Skip Changelog` label to dependabot-sourced PRs. (#1161)
+- The [configuration style guide](https://github.com/open-telemetry/opentelemetry-go/blob/master/CONTRIBUTING.md#config) has been updated to
+   recommend the use of `newConfig()` instead of `configure()`. (#1163)
+- The `otlp.Config` type has been unexported and changed to `otlp.config`, along with its initializer. (#1163)
 
 ## [0.11.0] - 2020-08-24
 

CONTRIBUTING.md

@@ -187,13 +187,13 @@ how the user can extend the configuration.
 It is important that `config` are not shared across package boundaries.
 Meaning a `config` from one package should not be directly used by another.
 
-Optionally, it is common to include a `configure` function (with the same
+Optionally, it is common to include a `newConfig` function (with the same
 naming scheme). This function wraps any defaults setting and looping over
 all options to create a configured `config`.
 
 ```go
-// configure returns an appropriately configured config.
-func configure([]Option) config {
+// newConfig returns an appropriately configured config.
+func newConfig([]Option) config {
     // Set default values for config.
     config := config{/* […] */}
     for _, option := range options {
@@ -209,7 +209,7 @@ error as well that is expected to be handled by the instantiation function
 or propagated to the user.
 
 Given the design goal of not having the user need to work with the `config`,
-the `configure` function should also be unexported.
+the `newConfig` function should also be unexported.
 
 #### `Option`
 
@@ -218,7 +218,7 @@ To set the value of the options a `config` contains, a corresponding
 
 ```go
 type Option interface {
-  Apply(*Config)
+  Apply(*config)
 }
 ```
 
@@ -244,7 +244,7 @@ func With*(…) Option { … }
 ```go
 type defaultFalseOption bool
 
-func (o defaultFalseOption) Apply(c *Config) {
+func (o defaultFalseOption) Apply(c *config) {
     c.Bool = bool(o)
 }
 
@@ -257,7 +257,7 @@ func WithOption() Option {
 ```go
 type defaultTrueOption bool
 
-func (o defaultTrueOption) Apply(c *Config) {
+func (o defaultTrueOption) Apply(c *config) {
     c.Bool = bool(o)
 }
 
@@ -274,7 +274,7 @@ type myTypeOption struct {
     MyType MyType
 }
 
-func (o myTypeOption) Apply(c *Config) {
+func (o myTypeOption) Apply(c *config) {
     c.MyType = o.MyType
 }
 

api/trace/tracetest/config.go

@@ -49,7 +49,7 @@ type config struct {
 	SpanRecorder SpanRecorder
 }
 
-func configure(opts ...Option) config {
+func newConfig(opts ...Option) config {
 	conf := config{}
 	for _, opt := range opts {
 		opt.Apply(&conf)

api/trace/tracetest/provider.go

@@ -31,7 +31,7 @@ var _ trace.Provider = (*Provider)(nil)
 
 func NewProvider(opts ...Option) *Provider {
 	return &Provider{
-		config:  configure(opts...),
+		config:  newConfig(opts...),
 		tracers: make(map[instrumentation]*Tracer),
 	}
 }

exporters/otlp/options.go

@@ -61,9 +61,9 @@ const (
 }`
 )
 
-type ExporterOption func(*Config)
+type ExporterOption func(*config)
 
-type Config struct {
+type config struct {
 	canDialInsecure    bool
 	collectorAddr      string
 	compressor         string
@@ -80,7 +80,7 @@ func WorkerCount(n uint) ExporterOption {
 	if n == 0 {
 		n = DefaultNumWorkers
 	}
-	return func(cfg *Config) {
+	return func(cfg *config) {
 		cfg.numWorkers = n
 	}
 }
@@ -89,7 +89,7 @@ func WorkerCount(n uint) ExporterOption {
 // just like grpc.WithInsecure() https://pkg.go.dev/google.golang.org/grpc#WithInsecure
 // does. Note, by default, client security is required unless WithInsecure is used.
 func WithInsecure() ExporterOption {
-	return func(cfg *Config) {
+	return func(cfg *config) {
 		cfg.canDialInsecure = true
 	}
 }
@@ -98,7 +98,7 @@ func WithInsecure() ExporterOption {
 // connect to the collector on. If unset, it will instead try to use
 // connect to DefaultCollectorHost:DefaultCollectorPort.
 func WithAddress(addr string) ExporterOption {
-	return func(cfg *Config) {
+	return func(cfg *config) {
 		cfg.collectorAddr = addr
 	}
 }
@@ -106,7 +106,7 @@ func WithAddress(addr string) ExporterOption {
 // WithReconnectionPeriod allows one to set the delay between next connection attempt
 // after failing to connect with the collector.
 func WithReconnectionPeriod(rp time.Duration) ExporterOption {
-	return func(cfg *Config) {
+	return func(cfg *config) {
 		cfg.reconnectionPeriod = rp
 	}
 }
@@ -117,14 +117,14 @@ func WithReconnectionPeriod(rp time.Duration) ExporterOption {
 // compressors auto-register on import, such as gzip, which can be registered by calling
 // `import _ "google.golang.org/grpc/encoding/gzip"`
 func WithCompressor(compressor string) ExporterOption {
-	return func(cfg *Config) {
+	return func(cfg *config) {
 		cfg.compressor = compressor
 	}
 }
 
 // WithHeaders will send the provided headers with gRPC requests
 func WithHeaders(headers map[string]string) ExporterOption {
-	return func(cfg *Config) {
+	return func(cfg *config) {
 		cfg.headers = headers
 	}
 }
@@ -135,14 +135,14 @@ func WithHeaders(headers map[string]string) ExporterOption {
 // these credentials can be done in many ways e.g. plain file, in code tls.Config
 // or by certificate rotation, so it is up to the caller to decide what to use.
 func WithTLSCredentials(creds credentials.TransportCredentials) ExporterOption {
-	return func(cfg *Config) {
+	return func(cfg *config) {
 		cfg.clientCredentials = creds
 	}
 }
 
 // WithGRPCServiceConfig defines the default gRPC service config used.
 func WithGRPCServiceConfig(serviceConfig string) ExporterOption {
-	return func(cfg *Config) {
+	return func(cfg *config) {
 		cfg.grpcServiceConfig = serviceConfig
 	}
 }
@@ -151,7 +151,7 @@ func WithGRPCServiceConfig(serviceConfig string) ExporterOption {
 // with some other configuration the GRPC specified via the collector the ones here will
 // take preference since they are set last.
 func WithGRPCDialOption(opts ...grpc.DialOption) ExporterOption {
-	return func(cfg *Config) {
+	return func(cfg *config) {
 		cfg.grpcDialOptions = opts
 	}
 }

exporters/otlp/otlp.go

@@ -52,19 +52,27 @@ type Exporter struct {
 
 	backgroundConnectionDoneCh chan bool
 
-	c        Config
+	c        config
 	metadata metadata.MD
 }
 
 var _ tracesdk.SpanExporter = (*Exporter)(nil)
 var _ metricsdk.Exporter = (*Exporter)(nil)
 
-func configureOptions(cfg *Config, opts ...ExporterOption) {
-	for _, opt := range opts {
-		opt(cfg)
+// newConfig initializes a config struct with default values and applies
+// any ExporterOptions provided.
+func newConfig(opts ...ExporterOption) config {
+	cfg := config{
+		numWorkers:        DefaultNumWorkers,
+		grpcServiceConfig: DefaultGRPCServiceConfig,
 	}
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+	return cfg
 }
 
+// NewExporter constructs a new Exporter and starts it.
 func NewExporter(opts ...ExporterOption) (*Exporter, error) {
 	exp := NewUnstartedExporter(opts...)
 	if err := exp.Start(); err != nil {
@@ -73,13 +81,10 @@ func NewExporter(opts ...ExporterOption) (*Exporter, error) {
 	return exp, nil
 }
 
+// NewUnstartedExporter constructs a new Exporter and does not start it.
 func NewUnstartedExporter(opts ...ExporterOption) *Exporter {
 	e := new(Exporter)
-	e.c = Config{
-		numWorkers:        DefaultNumWorkers,
-		grpcServiceConfig: DefaultGRPCServiceConfig,
-	}
-	configureOptions(&e.c, opts...)
+	e.c = newConfig(opts...)
 	if len(e.c.headers) > 0 {
 		e.metadata = metadata.New(e.c.headers)
 	}

exporters/stdout/config.go

@@ -64,8 +64,8 @@ type Config struct {
 	DisableMetricExport bool
 }
 
-// Configure creates a validated Config configured with options.
-func Configure(options ...Option) (Config, error) {
+// NewConfig creates a validated Config configured with options.
+func NewConfig(options ...Option) (Config, error) {
 	config := Config{
 		Writer:              defaultWriter,
 		PrettyPrint:         defaultPrettyPrint,

exporters/stdout/exporter.go

@@ -37,7 +37,7 @@ var (
 
 // NewExporter creates an Exporter with the passed options.
 func NewExporter(options ...Option) (*Exporter, error) {
-	config, err := Configure(options...)
+	config, err := NewConfig(options...)
 	if err != nil {
 		return nil, err
 	}