diff --git a/CHANGELOG.md b/CHANGELOG.md index c8a140969..df156e908 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index abd15f5b0..5c06abb07 100644 --- a/CONTRIBUTING.md +++ b/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 } diff --git a/api/trace/tracetest/config.go b/api/trace/tracetest/config.go index 8cd93d779..bb97266c7 100644 --- a/api/trace/tracetest/config.go +++ b/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) diff --git a/api/trace/tracetest/provider.go b/api/trace/tracetest/provider.go index ca6161b05..84b5c97ba 100644 --- a/api/trace/tracetest/provider.go +++ b/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), } } diff --git a/exporters/otlp/options.go b/exporters/otlp/options.go index 7d9b6f991..d544176b6 100644 --- a/exporters/otlp/options.go +++ b/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 } } diff --git a/exporters/otlp/otlp.go b/exporters/otlp/otlp.go index af0a01ed1..d4d2a89e5 100644 --- a/exporters/otlp/otlp.go +++ b/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) } diff --git a/exporters/stdout/config.go b/exporters/stdout/config.go index 39549ea11..00facf19c 100644 --- a/exporters/stdout/config.go +++ b/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, diff --git a/exporters/stdout/exporter.go b/exporters/stdout/exporter.go index b7323b699..37832b679 100644 --- a/exporters/stdout/exporter.go +++ b/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 }