From 0285570420ee36470422f06a30a2b64854160035 Mon Sep 17 00:00:00 2001 From: JamieDanielson Date: Thu, 21 Jul 2022 13:44:42 -0400 Subject: [PATCH 1/7] create launcher design doc --- design/0000-launcher.md | 122 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 design/0000-launcher.md diff --git a/design/0000-launcher.md b/design/0000-launcher.md new file mode 100644 index 00000000000..80478916e2e --- /dev/null +++ b/design/0000-launcher.md @@ -0,0 +1,122 @@ +# Launcher + +## What is it? + +The Go Launcher (name TBD) is a configuration layer that chooses default values for configuration options that many OpenTelemetry users would ultimately configure manually, allowing for minimal code to quickly instrument with OpenTelemetry. + +## Motivation + +The goal of this Launcher is to help users that aren't familiar with OpenTelemetry quickly ramp up on what they need to get going and instrument their applications. [There is currently a lot of boilerplate code required to use OpenTelemetry](https://opentelemetry.io/docs/instrumentation/go/manual/#initializing-a-new-tracer), and users must make decisions early on before instrumentation works - for example, they must determine and find the appropriate exporters, set resource attributes, etc. This launcher is intended to simplify the setup and minimize decision-making overhead to be able to quickly get started. + +Separately, vendors may choose to provide a vendor-specific package compatible with this launcher for easier exporting to their own backend. Neither the launcher nor the vendor-specific package are required to use OpenTelemetry, and using the launcher does not require the end user to use a vendor-specific package. + +## Explanation + +The Go Launcher provides a single function to reduce the amount of code that needs to be written to get started, and provides additional, straightforward options to add in that still make additional configuration easy. + +The vendor-neutral launcher will live in the opentelemetry-go-contrib repo, and vendors may create separately hosted vendor-specific configuration packages that can be used with the launcher. + +### Getting started + +```shell +go get github.com/opentelemetry-go-contrib/otel-launcher-go/launcher +``` + +### Configure + +Minimal setup - by default will send all telemetry to localhost:4317, with the ability to set environment variables for endpoint, headers, resource attributes, and more as listed in the configuration options noted below: + +```go +import "github.com/opentelemetry-go-contrib/otel-launcher-go/launcher" + +func main() { + lnchr, err := launcher.ConfigureOpentelemetry() + defer lnchr.Shutdown() +} +``` + +Or set headers directly in code instead: + +```go +import "github.com/opentelemetry-go-contrib/otel-launcher-go/launcher" + +func main() { + lnchr, err := launcher.ConfigureOpentelemetry( + launcher.WithServiceName("service-name"), + launcher.WithHeaders(map[string]string{ + "service-auth-key": "value", + "service-useful-field": "testing", + }), + ) + defer lnchr.Shutdown() +} +``` + +### Configuration Options + +| Config Option | Env Variable | Required | Default | +| -------------------------- | ----------------------------------- | -------- | -------------------- | +| WithServiceName | OTEL_SERVICE_NAME | y | - | +| WithServiceVersion | OTEL_SERVICE_VERSION | n | - | +| WithHeaders | OTEL_EXPORTER_OTLP_HEADERS | n | {} | +| WithTracesExporterEndpoint | OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | n | localhost:4317 | +| WithTracesExporterInsecure | OTEL_EXPORTER_OTLP_TRACES_INSECURE | n | false | +| WithMetricsExporterEndpoint | OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | n | localhost:4317 | +| WithMetricsExporterInsecure | OTEL_EXPORTER_OTLP_METRICS_INSECURE | n | false | +| WithLogLevel | OTEL_LOG_LEVEL | n | info | +| WithPropagators | OTEL_PROPAGATORS | n | tracecontext,baggage | +| WithResourceAttributes | OTEL_RESOURCE_ATTRIBUTES | n | - | +| WithMetricsReportingPeriod | OTEL_EXPORTER_OTLP_METRICS_PERIOD | n | 30s | +| WithMetricsEnabled | OTEL_METRICS_ENABLED | n | true | +| WithTracesEnabled | OTEL_TRACES_ENABLED | n | true | +| WithProtocol | OTEL_EXPORTER_OTLP_PROTOCOL | n | grpc | + +### Additional Configuration Options + +Not yet implemented but still desired configuration options would include: + +- `OTEL_EXPORTER_OTLP_PROTOCOL`: `http/protobuf` + - ideally, selecting this would change the default endpoint to localhost:4318 + +### Using a Vendor-Specific Package + +Vendors may create and maintain convenience configuration packages to more easily setup for export to a specific backend. For example, using a Honeycomb package would look like this: + +Minimal setup, which sends to the Honeycomb endpoint and requires `HONEYCOMB_API_KEY` environment variable: + +```go +import ( + "github.com/opentelemetry-go-contrib/otel-launcher-go/launcher" + _ "github.com/honeycombio/otel-launcher-go/launcher/honeycomb" +) + +func main() { + lnchr, err := launcher.ConfigureOpentelemetry() + defer lnchr.Shutdown() +} +``` + +Or, with headers set directly in code: + +```go +import ( + "github.com/opentelemetry-go-contrib/otel-launcher-go/launcher" + "github.com/honeycombio/otel-launcher-go/launcher/honeycomb" +) + +func main() { + lnchr, err := launcher.ConfigureOpentelemetry( + launcher.WithServiceName("service-name"), + honeycomb.WithApiKey("api-key"), + ) + defer lnchr.Shutdown() +} +``` + +## Trade-offs and mitigations + +This launcher is intentionally providing default configuration options, which may not precisely map out to the final configuration an end user desires. As such, there may be dependencies in the package that are not being used. For example, the default configuration will bring in both gRPC and HTTP exporters; using gRPC will result in HTTP being included but not used; similarly, using HTTP/protobuf will result in the gRPC dependency being pulled in but unused. + +There still exists the ability to change the default configuration with environment variables or in-code configuration options, but there is not an easy way to remove unused dependencies without also keeping the minimal configuration option. + +If removing unused dependencies is required, the user can avoid using the launcher and initialize OTel manually, which is the current experience today. From 4fd47fc8b1b9070f45bb4cbbb2806db62b76c5af Mon Sep 17 00:00:00 2001 From: JamieDanielson Date: Thu, 21 Jul 2022 15:40:45 -0400 Subject: [PATCH 2/7] clarify example showing honeycomb api key --- design/0000-launcher.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/design/0000-launcher.md b/design/0000-launcher.md index 80478916e2e..d9e7c5b3fec 100644 --- a/design/0000-launcher.md +++ b/design/0000-launcher.md @@ -96,7 +96,7 @@ func main() { } ``` -Or, with headers set directly in code: +Alternatively, to set the Honeycomb API key directly in code: ```go import ( @@ -106,7 +106,6 @@ import ( func main() { lnchr, err := launcher.ConfigureOpentelemetry( - launcher.WithServiceName("service-name"), honeycomb.WithApiKey("api-key"), ) defer lnchr.Shutdown() From e96e2cc1089c0ba291097271b287ad90fd2d4fda Mon Sep 17 00:00:00 2001 From: JamieDanielson Date: Tue, 26 Jul 2022 13:25:29 -0400 Subject: [PATCH 3/7] replace import with vanity url --- design/0000-launcher.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/design/0000-launcher.md b/design/0000-launcher.md index d9e7c5b3fec..cfc51ce80ea 100644 --- a/design/0000-launcher.md +++ b/design/0000-launcher.md @@ -19,7 +19,7 @@ The vendor-neutral launcher will live in the opentelemetry-go-contrib repo, and ### Getting started ```shell -go get github.com/opentelemetry-go-contrib/otel-launcher-go/launcher +go get go.opentelemetry.io/contrib/launcher ``` ### Configure @@ -27,7 +27,7 @@ go get github.com/opentelemetry-go-contrib/otel-launcher-go/launcher Minimal setup - by default will send all telemetry to localhost:4317, with the ability to set environment variables for endpoint, headers, resource attributes, and more as listed in the configuration options noted below: ```go -import "github.com/opentelemetry-go-contrib/otel-launcher-go/launcher" +import "go.opentelemetry.io/contrib/launcher" func main() { lnchr, err := launcher.ConfigureOpentelemetry() @@ -38,7 +38,7 @@ func main() { Or set headers directly in code instead: ```go -import "github.com/opentelemetry-go-contrib/otel-launcher-go/launcher" +import "go.opentelemetry.io/contrib/launcher" func main() { lnchr, err := launcher.ConfigureOpentelemetry( @@ -86,7 +86,7 @@ Minimal setup, which sends to the Honeycomb endpoint and requires `HONEYCOMB_API ```go import ( - "github.com/opentelemetry-go-contrib/otel-launcher-go/launcher" + "go.opentelemetry.io/contrib/launcher" _ "github.com/honeycombio/otel-launcher-go/launcher/honeycomb" ) @@ -100,7 +100,7 @@ Alternatively, to set the Honeycomb API key directly in code: ```go import ( - "github.com/opentelemetry-go-contrib/otel-launcher-go/launcher" + "go.opentelemetry.io/contrib/launcher" "github.com/honeycombio/otel-launcher-go/launcher/honeycomb" ) From e03964910c117672ef15f1d6a9c289c2068fc205 Mon Sep 17 00:00:00 2001 From: JamieDanielson Date: Fri, 29 Jul 2022 15:21:12 -0400 Subject: [PATCH 4/7] clarify service name defaults --- design/0000-launcher.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/design/0000-launcher.md b/design/0000-launcher.md index cfc51ce80ea..906223c36c6 100644 --- a/design/0000-launcher.md +++ b/design/0000-launcher.md @@ -56,7 +56,7 @@ func main() { | Config Option | Env Variable | Required | Default | | -------------------------- | ----------------------------------- | -------- | -------------------- | -| WithServiceName | OTEL_SERVICE_NAME | y | - | +| WithServiceName | OTEL_SERVICE_NAME | n* | unknown_service:go | | WithServiceVersion | OTEL_SERVICE_VERSION | n | - | | WithHeaders | OTEL_EXPORTER_OTLP_HEADERS | n | {} | | WithTracesExporterEndpoint | OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | n | localhost:4317 | @@ -71,6 +71,8 @@ func main() { | WithTracesEnabled | OTEL_TRACES_ENABLED | n | true | | WithProtocol | OTEL_EXPORTER_OTLP_PROTOCOL | n | grpc | +*Service name should be set using the `WithServiceName` configuration option, the `OTEL_SERVICE_NAME` environment variable, or by setting the `service.name` in `OTEL_RESOURCE_ATTRIBUTES`. The default service name is based on the SDK's behavior as it conforms to the specification: `unknown_service`, suffixed with either the process name (where possible) or `go`. + ### Additional Configuration Options Not yet implemented but still desired configuration options would include: From 6c427879f93047ea0e09feacaac8e8e653eb2a86 Mon Sep 17 00:00:00 2001 From: JamieDanielson Date: Thu, 18 Aug 2022 13:12:42 -0400 Subject: [PATCH 5/7] clarify what it isnt, update config options --- design/0000-launcher.md | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/design/0000-launcher.md b/design/0000-launcher.md index 906223c36c6..d2931058c92 100644 --- a/design/0000-launcher.md +++ b/design/0000-launcher.md @@ -1,8 +1,16 @@ # Launcher -## What is it? +## What it is -The Go Launcher (name TBD) is a configuration layer that chooses default values for configuration options that many OpenTelemetry users would ultimately configure manually, allowing for minimal code to quickly instrument with OpenTelemetry. +The Go Launcher (name TBD) is a configuration layer that chooses default values for configuration options that many OpenTelemetry users would ultimately configure manually, allowing for minimal code to quickly instrument with OpenTelemetry. It is intended as the main “getting started” path for newcomers and people without advanced configuration needs. + +## What it isn’t + +The Go Launcher is not a new Go SDK but rather a complementary wrapper around the existing SDK. Certain functionality like resource detectors, autoprop packages, and autoexporter packages, can and should be used from the core SDK to make the configuration layer more resilient to - and compatible with - potential upstream changes. Other functionality that differs from the Go SDK should not be introduced to the Launcher, either by new environment variables or code configuration, including but not limited to changing out processors, adding specific sampling methods, and enabling or disabling specific instrumentation. New functionality may be provided using a separate package, such as vendor-specific requirements. + +The Go Launcher is also not intended to be a lightweight configuration option for advanced users who specifically require minimal dependencies and smaller package size. To achieve the minimal configuration for developers, some unused dependencies will be included as a necessity; see Tradeoffs below. + +The Go Launcher is ideally used with environment variables; as such, not all configuration options may be available to set directly within code. If there is more desire to use configuration options directly within code, either the regular SDK can be used, or a vendor package can be used that allows for extra configuration options. ## Motivation @@ -59,9 +67,9 @@ func main() { | WithServiceName | OTEL_SERVICE_NAME | n* | unknown_service:go | | WithServiceVersion | OTEL_SERVICE_VERSION | n | - | | WithHeaders | OTEL_EXPORTER_OTLP_HEADERS | n | {} | -| WithTracesExporterEndpoint | OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | n | localhost:4317 | +| WithTracesExporterEndpoint | OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | n | localhost:4317** | | WithTracesExporterInsecure | OTEL_EXPORTER_OTLP_TRACES_INSECURE | n | false | -| WithMetricsExporterEndpoint | OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | n | localhost:4317 | +| WithMetricsExporterEndpoint | OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | n | localhost:4317** | | WithMetricsExporterInsecure | OTEL_EXPORTER_OTLP_METRICS_INSECURE | n | false | | WithLogLevel | OTEL_LOG_LEVEL | n | info | | WithPropagators | OTEL_PROPAGATORS | n | tracecontext,baggage | @@ -73,12 +81,17 @@ func main() { *Service name should be set using the `WithServiceName` configuration option, the `OTEL_SERVICE_NAME` environment variable, or by setting the `service.name` in `OTEL_RESOURCE_ATTRIBUTES`. The default service name is based on the SDK's behavior as it conforms to the specification: `unknown_service`, suffixed with either the process name (where possible) or `go`. +**If `OTEL_EXPORTER_OTLP_PROTOCOL` is set to `http/protobuf`, the default endpoint will be `localhost:4318`. + ### Additional Configuration Options Not yet implemented but still desired configuration options would include: -- `OTEL_EXPORTER_OTLP_PROTOCOL`: `http/protobuf` - - ideally, selecting this would change the default endpoint to localhost:4318 +- `autoexporter` registry +- `WithTracesExporter` = `OTLP` default, with options to select from the autoexporter registry once available +- `WithMetricsExporter` = `OTLP` default, with options to select from the autoexporter registry once available +- `WithOTLPTracesExporterEndpoint` = `localhost:4317` default, or `localhost:4318` if http protocol is set +- `WithOTLPMetricsExporterEndpoint` = `localhost:4317` default, or `localhost:4318` if http protocol is set ### Using a Vendor-Specific Package From 735553361d395adb3a88e6d06d2551ba94b88f3c Mon Sep 17 00:00:00 2001 From: JamieDanielson Date: Mon, 29 Aug 2022 16:50:30 -0400 Subject: [PATCH 6/7] Rename Launcher to Initialization Layer --- design/0000-launcher.md | 56 ++++++++++++++++++++--------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/design/0000-launcher.md b/design/0000-launcher.md index d2931058c92..309a81f7aa0 100644 --- a/design/0000-launcher.md +++ b/design/0000-launcher.md @@ -1,33 +1,33 @@ -# Launcher +# OpenTelemetry Go Initialization Layer ## What it is -The Go Launcher (name TBD) is a configuration layer that chooses default values for configuration options that many OpenTelemetry users would ultimately configure manually, allowing for minimal code to quickly instrument with OpenTelemetry. It is intended as the main “getting started” path for newcomers and people without advanced configuration needs. +The OpenTelemetry Go Initialization Layer is a configuration layer that chooses default values for configuration options that many OpenTelemetry users would ultimately configure manually, allowing for minimal code to quickly instrument with OpenTelemetry. It is intended as the main “getting started” path for newcomers and people without advanced configuration needs. ## What it isn’t -The Go Launcher is not a new Go SDK but rather a complementary wrapper around the existing SDK. Certain functionality like resource detectors, autoprop packages, and autoexporter packages, can and should be used from the core SDK to make the configuration layer more resilient to - and compatible with - potential upstream changes. Other functionality that differs from the Go SDK should not be introduced to the Launcher, either by new environment variables or code configuration, including but not limited to changing out processors, adding specific sampling methods, and enabling or disabling specific instrumentation. New functionality may be provided using a separate package, such as vendor-specific requirements. +The Go Initialization Layer is not a new Go SDK but rather a complementary wrapper around the existing SDK. Certain functionality like resource detectors, autoprop packages, and autoexporter packages, can and should be used from the core SDK to make the configuration layer more resilient to - and compatible with - potential upstream changes. Other functionality that differs from the Go SDK should not be introduced to the Initialization Layer, either by new environment variables or code configuration, including but not limited to changing out processors, adding specific sampling methods, and enabling or disabling specific instrumentation. New functionality may be provided using a separate package, such as vendor-specific requirements. -The Go Launcher is also not intended to be a lightweight configuration option for advanced users who specifically require minimal dependencies and smaller package size. To achieve the minimal configuration for developers, some unused dependencies will be included as a necessity; see Tradeoffs below. +The Go Initialization Layer is also not intended to be a lightweight configuration option for advanced users who specifically require minimal dependencies and smaller package size. To achieve the minimal configuration for developers, some unused dependencies will be included as a necessity; see Tradeoffs below. -The Go Launcher is ideally used with environment variables; as such, not all configuration options may be available to set directly within code. If there is more desire to use configuration options directly within code, either the regular SDK can be used, or a vendor package can be used that allows for extra configuration options. +The Go Initialization Layer is ideally used with environment variables; as such, not all configuration options may be available to set directly within code. If there is more desire to use configuration options directly within code, either the regular SDK can be used, or a vendor package can be used that allows for extra configuration options. ## Motivation -The goal of this Launcher is to help users that aren't familiar with OpenTelemetry quickly ramp up on what they need to get going and instrument their applications. [There is currently a lot of boilerplate code required to use OpenTelemetry](https://opentelemetry.io/docs/instrumentation/go/manual/#initializing-a-new-tracer), and users must make decisions early on before instrumentation works - for example, they must determine and find the appropriate exporters, set resource attributes, etc. This launcher is intended to simplify the setup and minimize decision-making overhead to be able to quickly get started. +The goal of this Initialization Layer is to help users that aren't familiar with OpenTelemetry quickly ramp up on what they need to get going and instrument their applications. [There is currently a lot of boilerplate code required to use OpenTelemetry](https://opentelemetry.io/docs/instrumentation/go/manual/#initializing-a-new-tracer), and users must make decisions early on before instrumentation works - for example, they must determine and find the appropriate exporters, set resource attributes, etc. This Initialization Layer is intended to simplify the setup and minimize decision-making overhead to be able to quickly get started. -Separately, vendors may choose to provide a vendor-specific package compatible with this launcher for easier exporting to their own backend. Neither the launcher nor the vendor-specific package are required to use OpenTelemetry, and using the launcher does not require the end user to use a vendor-specific package. +Separately, vendors may choose to provide a vendor-specific package compatible with this Initialization Layer for easier exporting to their own backend. Neither the Initialization Layer nor the vendor-specific package are required to use OpenTelemetry, and using the Initialization Layer does not require the end user to use a vendor-specific package. ## Explanation -The Go Launcher provides a single function to reduce the amount of code that needs to be written to get started, and provides additional, straightforward options to add in that still make additional configuration easy. +The Go Initialization Layer provides a single function to reduce the amount of code that needs to be written to get started, and provides additional, straightforward options to add in that still make additional configuration easy. -The vendor-neutral launcher will live in the opentelemetry-go-contrib repo, and vendors may create separately hosted vendor-specific configuration packages that can be used with the launcher. +The vendor-neutral Initialization Layer will live in the opentelemetry-go-contrib repo, and vendors may create separately hosted vendor-specific configuration packages that can be used with the Initialization Layer. ### Getting started ```shell -go get go.opentelemetry.io/contrib/launcher +go get go.opentelemetry.io/contrib/otelinit ``` ### Configure @@ -35,28 +35,28 @@ go get go.opentelemetry.io/contrib/launcher Minimal setup - by default will send all telemetry to localhost:4317, with the ability to set environment variables for endpoint, headers, resource attributes, and more as listed in the configuration options noted below: ```go -import "go.opentelemetry.io/contrib/launcher" +import "go.opentelemetry.io/contrib/otelinit" func main() { - lnchr, err := launcher.ConfigureOpentelemetry() - defer lnchr.Shutdown() + init, err := otelinit.ConfigureOpentelemetry() + defer init.Shutdown() } ``` Or set headers directly in code instead: ```go -import "go.opentelemetry.io/contrib/launcher" +import "go.opentelemetry.io/contrib/otelinit" func main() { - lnchr, err := launcher.ConfigureOpentelemetry( - launcher.WithServiceName("service-name"), - launcher.WithHeaders(map[string]string{ + init, err := otelinit.ConfigureOpentelemetry( + otelinit.WithServiceName("service-name"), + otelinit.WithHeaders(map[string]string{ "service-auth-key": "value", "service-useful-field": "testing", }), ) - defer lnchr.Shutdown() + defer init.Shutdown() } ``` @@ -101,13 +101,13 @@ Minimal setup, which sends to the Honeycomb endpoint and requires `HONEYCOMB_API ```go import ( - "go.opentelemetry.io/contrib/launcher" - _ "github.com/honeycombio/otel-launcher-go/launcher/honeycomb" + "go.opentelemetry.io/contrib/otelinit" + _ "github.com/honeycombio/otel-go/otelinit/honeycomb" ) func main() { - lnchr, err := launcher.ConfigureOpentelemetry() - defer lnchr.Shutdown() + init, err := otelinit.ConfigureOpentelemetry() + defer init.Shutdown() } ``` @@ -115,22 +115,22 @@ Alternatively, to set the Honeycomb API key directly in code: ```go import ( - "go.opentelemetry.io/contrib/launcher" - "github.com/honeycombio/otel-launcher-go/launcher/honeycomb" + "go.opentelemetry.io/contrib/otelinit" + "github.com/honeycombio/otel-go/otelinit/honeycomb" ) func main() { - lnchr, err := launcher.ConfigureOpentelemetry( + init, err := otelinit.ConfigureOpentelemetry( honeycomb.WithApiKey("api-key"), ) - defer lnchr.Shutdown() + defer init.Shutdown() } ``` ## Trade-offs and mitigations -This launcher is intentionally providing default configuration options, which may not precisely map out to the final configuration an end user desires. As such, there may be dependencies in the package that are not being used. For example, the default configuration will bring in both gRPC and HTTP exporters; using gRPC will result in HTTP being included but not used; similarly, using HTTP/protobuf will result in the gRPC dependency being pulled in but unused. +This Initialization Layer is intentionally providing default configuration options, which may not precisely map out to the final configuration an end user desires. As such, there may be dependencies in the package that are not being used. For example, the default configuration will bring in both gRPC and HTTP exporters; using gRPC will result in HTTP being included but not used; similarly, using HTTP/protobuf will result in the gRPC dependency being pulled in but unused. There still exists the ability to change the default configuration with environment variables or in-code configuration options, but there is not an easy way to remove unused dependencies without also keeping the minimal configuration option. -If removing unused dependencies is required, the user can avoid using the launcher and initialize OTel manually, which is the current experience today. +If removing unused dependencies is required, the user can avoid using the Initialization Layer and initialize OTel manually, which is the current experience today. From 75017458bc720aadf2ffa64971109a099eb18b4b Mon Sep 17 00:00:00 2001 From: JamieDanielson Date: Fri, 30 Sep 2022 09:41:49 -0400 Subject: [PATCH 7/7] Update to use autoexport package --- design/0000-launcher.md | 32 ++++++++------------------------ 1 file changed, 8 insertions(+), 24 deletions(-) diff --git a/design/0000-launcher.md b/design/0000-launcher.md index 309a81f7aa0..66dbded8adc 100644 --- a/design/0000-launcher.md +++ b/design/0000-launcher.md @@ -32,7 +32,7 @@ go get go.opentelemetry.io/contrib/otelinit ### Configure -Minimal setup - by default will send all telemetry to localhost:4317, with the ability to set environment variables for endpoint, headers, resource attributes, and more as listed in the configuration options noted below: +Minimal setup - by default will send all telemetry to `localhost:4317`, with the ability to set environment variables for endpoint, headers, resource attributes, and more as listed in the configuration options noted below: ```go import "go.opentelemetry.io/contrib/otelinit" @@ -43,18 +43,16 @@ func main() { } ``` -Or set headers directly in code instead: +Alternatively, set environment variables or set variables directly in code to override defaults: ```go import "go.opentelemetry.io/contrib/otelinit" func main() { init, err := otelinit.ConfigureOpentelemetry( + otelinit.WithTracesExporter(new trace.SpanExporter("jaeger")) // if using non-default exporter + otelinit.WithPropagators(b3.New()) // if using non-default propagator otelinit.WithServiceName("service-name"), - otelinit.WithHeaders(map[string]string{ - "service-auth-key": "value", - "service-useful-field": "testing", - }), ) defer init.Shutdown() } @@ -66,36 +64,22 @@ func main() { | -------------------------- | ----------------------------------- | -------- | -------------------- | | WithServiceName | OTEL_SERVICE_NAME | n* | unknown_service:go | | WithServiceVersion | OTEL_SERVICE_VERSION | n | - | -| WithHeaders | OTEL_EXPORTER_OTLP_HEADERS | n | {} | -| WithTracesExporterEndpoint | OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | n | localhost:4317** | -| WithTracesExporterInsecure | OTEL_EXPORTER_OTLP_TRACES_INSECURE | n | false | -| WithMetricsExporterEndpoint | OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | n | localhost:4317** | -| WithMetricsExporterInsecure | OTEL_EXPORTER_OTLP_METRICS_INSECURE | n | false | +| WithTracesExporter | OTEL_TRACES_EXPORTER | n | otlp | | WithLogLevel | OTEL_LOG_LEVEL | n | info | | WithPropagators | OTEL_PROPAGATORS | n | tracecontext,baggage | | WithResourceAttributes | OTEL_RESOURCE_ATTRIBUTES | n | - | -| WithMetricsReportingPeriod | OTEL_EXPORTER_OTLP_METRICS_PERIOD | n | 30s | | WithMetricsEnabled | OTEL_METRICS_ENABLED | n | true | | WithTracesEnabled | OTEL_TRACES_ENABLED | n | true | -| WithProtocol | OTEL_EXPORTER_OTLP_PROTOCOL | n | grpc | *Service name should be set using the `WithServiceName` configuration option, the `OTEL_SERVICE_NAME` environment variable, or by setting the `service.name` in `OTEL_RESOURCE_ATTRIBUTES`. The default service name is based on the SDK's behavior as it conforms to the specification: `unknown_service`, suffixed with either the process name (where possible) or `go`. -**If `OTEL_EXPORTER_OTLP_PROTOCOL` is set to `http/protobuf`, the default endpoint will be `localhost:4318`. +The propagator(s) will be set using the `autoprop` package. `WithPropagators` is an option that sets the default `tracecontext,baggage` propagators if none are set using environment variables. -### Additional Configuration Options - -Not yet implemented but still desired configuration options would include: - -- `autoexporter` registry -- `WithTracesExporter` = `OTLP` default, with options to select from the autoexporter registry once available -- `WithMetricsExporter` = `OTLP` default, with options to select from the autoexporter registry once available -- `WithOTLPTracesExporterEndpoint` = `localhost:4317` default, or `localhost:4318` if http protocol is set -- `WithOTLPMetricsExporterEndpoint` = `localhost:4317` default, or `localhost:4318` if http protocol is set +The exporter(s) will be set using the `autoexport` package. `WithTracesExporter` is an option that sets the default span exporter if none are set using environment variables. ### Using a Vendor-Specific Package -Vendors may create and maintain convenience configuration packages to more easily setup for export to a specific backend. For example, using a Honeycomb package would look like this: +Vendors may create and maintain convenience configuration packages to more easily setup for export to a specific backend. This is commonly done to set a specific endpoint, and set specific metadata or headers needed for telemetry - thus overriding defaults. For example, using a Honeycomb package would look like this: Minimal setup, which sends to the Honeycomb endpoint and requires `HONEYCOMB_API_KEY` environment variable: