From 109fba0f1297c40ecd7c54db22608a0488bd2f1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 2 Aug 2023 15:04:56 +0200 Subject: [PATCH 1/4] Update docs --- exporters/autoexport/README.md | 22 ----------- exporters/autoexport/doc.go | 21 ++--------- exporters/autoexport/exporter.go | 53 +++++++++++++++++++++++++-- exporters/autoexport/exporter_test.go | 8 ++++ 4 files changed, 61 insertions(+), 43 deletions(-) delete mode 100644 exporters/autoexport/README.md diff --git a/exporters/autoexport/README.md b/exporters/autoexport/README.md deleted file mode 100644 index e005950de01..00000000000 --- a/exporters/autoexport/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# Automatic Exporter configuration - -[![Go Reference][goref-image]][goref-url] -[![Apache License][license-image]][license-url] - -This module provides easy access to configuring a trace exporter that can be used when configuring an OpenTelemetry Go SDK trace export pipeline. - -## Useful links - -- For more information on OpenTelemetry, visit: -- For more about OpenTelemetry Go: -- For help or feedback on this project, join us in [GitHub Discussions][discussions-url] - -## License - -Apache 2.0 - See [LICENSE][license-url] for more information. - -[license-url]: https://github.com/open-telemetry/opentelemetry-go-contrib/blob/main/LICENSE -[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat -[goref-image]: https://pkg.go.dev/badge/go.opentelemetry.io/contrib/exporters/autoexport.svg -[goref-url]: https://pkg.go.dev/go.opentelemetry.io/contrib/exporters/autoexport -[discussions-url]: https://github.com/open-telemetry/opentelemetry-go/discussions diff --git a/exporters/autoexport/doc.go b/exporters/autoexport/doc.go index 998108e1b98..4e1d3a77348 100644 --- a/exporters/autoexport/doc.go +++ b/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 variables support as defined by the +// OpenTelemetry specification. package autoexport // import "go.opentelemetry.io/contrib/exporters/autoexport" diff --git a/exporters/autoexport/exporter.go b/exporters/autoexport/exporter.go index cac3f127e66..214a7ba939f 100644 --- a/exporters/autoexport/exporter.go +++ b/exporters/autoexport/exporter.go @@ -66,9 +66,56 @@ 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 +// +// OTEL_EXPORTER_OTLP_PROTOCOL defines OTLP exporter's transport protocol; +// supported values: +// - "grpc" - protobuf-encoded data using gRPC wire format over HTTP/2 connection +// - "http/protobuf" (default) - protobuf-encoded data over HTTP connection +// +// OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT define +// the target URL to which the OTLP exporter is going to send telemetry. +// For OTEL_EXPORTER_OTLP_ENDPOINT and http/protobuf protocol, +// "v1/traces" is appended to the provided value. +// Default value for grpc protocol: "http://localhost:4317" . +// Default value for http/protobuf protocol: "http://localhost:4318[/v1/traces]". +// +// OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE define +// a filepath to a TLS certificate pool to use by OTLP exporter when verifying +// a server's TLS credentials. If it exists, it is parsed as a [crypto/x509.CertPool]. +// Default value: "". +// +// OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS define +// a comma-separated list of additional HTTP headers sent by OTLP exporter, +// for example: Authorization=secret,X-Key=Value. +// Default value: "". +// +// OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_TRACES_COMPRESSION define +// the compression used by OTLP exporter; supported values: +// - "gzip" +// - "" (default). +// +// OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_TRACES_TIMEOUT define +// the maximum time the OTLP exporter will wait for each batch export. +// The value is interpreted as number of milliseconds. +// Default value: "10000" (10 seconds). +// +// OTEL_EXPORTER_OTLP_TRACES_* environment variables have precedence +// over OTEL_EXPORTER_OTLP_* environment variables. +// +// 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 diff --git a/exporters/autoexport/exporter_test.go b/exporters/autoexport/exporter_test.go index 4f80a1ddbd2..a8a2ce66871 100644 --- a/exporters/autoexport/exporter_test.go +++ b/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") From 06f65801f8d320ac843cf3b227446072594879ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 2 Aug 2023 15:06:43 +0200 Subject: [PATCH 2/4] Update changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c2f89a7f71e..8fabad66e71 100644 --- a/CHANGELOG.md +++ b/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 From 274110e2a46b40b06e7020df4177b2ebac67a092 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 2 Aug 2023 15:39:08 +0200 Subject: [PATCH 3/4] Refer to other docs --- exporters/autoexport/exporter.go | 38 +++++--------------------------- 1 file changed, 5 insertions(+), 33 deletions(-) diff --git a/exporters/autoexport/exporter.go b/exporters/autoexport/exporter.go index 214a7ba939f..eba67b1bc36 100644 --- a/exporters/autoexport/exporter.go +++ b/exporters/autoexport/exporter.go @@ -71,42 +71,14 @@ func WithFallbackSpanExporter(exporter trace.SpanExporter) Option { // // OTEL_TRACES_EXPORTER defines the traces exporter; supported values: // - "none" - "no operation" exporter -// - "otlp" (default) - OTLP 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 -// - "http/protobuf" (default) - protobuf-encoded data over HTTP connection -// -// OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT define -// the target URL to which the OTLP exporter is going to send telemetry. -// For OTEL_EXPORTER_OTLP_ENDPOINT and http/protobuf protocol, -// "v1/traces" is appended to the provided value. -// Default value for grpc protocol: "http://localhost:4317" . -// Default value for http/protobuf protocol: "http://localhost:4318[/v1/traces]". -// -// OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE define -// a filepath to a TLS certificate pool to use by OTLP exporter when verifying -// a server's TLS credentials. If it exists, it is parsed as a [crypto/x509.CertPool]. -// Default value: "". -// -// OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS define -// a comma-separated list of additional HTTP headers sent by OTLP exporter, -// for example: Authorization=secret,X-Key=Value. -// Default value: "". -// -// OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_TRACES_COMPRESSION define -// the compression used by OTLP exporter; supported values: -// - "gzip" -// - "" (default). -// -// OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_TRACES_TIMEOUT define -// the maximum time the OTLP exporter will wait for each batch export. -// The value is interpreted as number of milliseconds. -// Default value: "10000" (10 seconds). -// -// OTEL_EXPORTER_OTLP_TRACES_* environment variables have precedence -// over OTEL_EXPORTER_OTLP_* environment variables. +// - "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. // From cbea2f2a992548c013bf098e46e5b55609daea2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 2 Aug 2023 16:39:45 +0200 Subject: [PATCH 4/4] Update exporters/autoexport/doc.go Co-authored-by: Tyler Yahn --- exporters/autoexport/doc.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exporters/autoexport/doc.go b/exporters/autoexport/doc.go index 4e1d3a77348..31ee574e8fc 100644 --- a/exporters/autoexport/doc.go +++ b/exporters/autoexport/doc.go @@ -13,6 +13,6 @@ // limitations under the License. // Package autoexport provides OpenTelemetry exporter factory functions -// with defaults and environment variables support as defined by the +// with defaults and environment variable support as defined by the // OpenTelemetry specification. package autoexport // import "go.opentelemetry.io/contrib/exporters/autoexport"