From 0c5ebd58562213df399701409dc5ed2928bba11b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 8 Nov 2023 17:18:12 +0100 Subject: [PATCH] otlp: Refine documentation (#4695) --- CHANGELOG.md | 2 + exporters/README.md | 18 ++-- .../otlp/otlpmetric/otlpmetricgrpc/README.md | 42 ---------- .../otlp/otlpmetric/otlpmetricgrpc/config.go | 8 +- .../otlp/otlpmetric/otlpmetricgrpc/doc.go | 83 ++++++++++++++++++- .../otlp/otlpmetric/otlpmetrichttp/README.md | 43 ---------- .../otlp/otlpmetric/otlpmetrichttp/doc.go | 81 +++++++++++++++++- exporters/otlp/otlptrace/README.md | 51 ------------ exporters/otlp/otlptrace/doc.go | 21 +++++ exporters/otlp/otlptrace/otlptracegrpc/doc.go | 77 +++++++++++++++++ .../otlptrace/otlptracegrpc/example_test.go | 42 ++++++++++ .../otlp/otlptrace/otlptracegrpc/options.go | 8 +- exporters/otlp/otlptrace/otlptracehttp/doc.go | 59 ++++++++++++- .../otlptrace/otlptracehttp/example_test.go | 72 +++------------- 14 files changed, 380 insertions(+), 227 deletions(-) delete mode 100644 exporters/otlp/otlpmetric/otlpmetricgrpc/README.md delete mode 100644 exporters/otlp/otlpmetric/otlpmetrichttp/README.md delete mode 100644 exporters/otlp/otlptrace/README.md create mode 100644 exporters/otlp/otlptrace/doc.go create mode 100644 exporters/otlp/otlptrace/otlptracegrpc/doc.go create mode 100644 exporters/otlp/otlptrace/otlptracegrpc/example_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index cd94fbc8e97..bebd78266fa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -61,6 +61,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm - Fix improper parsing of characters such us `+`, `\` by `Parse` in `go.opentelemetry.io/otel/baggage` as they were rendered as a whitespace. (#4667) - In `go.opentelemetry.op/otel/exporters/prometheus`, the exporter no longer `Collect`s metrics after `Shutdown` is invoked. (#4648) +- Fix documentation for `WithCompressor` in `go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc`. (#4695) +- Fix documentation for `WithCompressor` in `go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc`. (#4695) ## [1.19.0/0.42.0/0.0.7] 2023-09-28 diff --git a/exporters/README.md b/exporters/README.md index 58561902d43..995226c8d55 100644 --- a/exporters/README.md +++ b/exporters/README.md @@ -7,14 +7,16 @@ This package contains exporters for this purpose. The following exporter packages are provided with the following OpenTelemetry signal support. -| Exporter Package | Metrics | Traces | -| :-----------------------------------------------------------------------------: | :-----: | :----: | -| [go.opentelemetry.io/otel/exporters/otlp/otlpmetric](./otlp/otlpmetric) | ✓ | | -| [go.opentelemetry.io/otel/exporters/otlp/otlptrace](./otlp/otlptrace) | | ✓ | -| [go.opentelemetry.io/otel/exporters/prometheus](./prometheus) | ✓ | | -| [go.opentelemetry.io/otel/exporters/stdout/stdoutmetric](./stdout/stdoutmetric) | ✓ | | -| [go.opentelemetry.io/otel/exporters/stdout/stdouttrace](./stdout/stdouttrace) | | ✓ | -| [go.opentelemetry.io/otel/exporters/zipkin](./zipkin) | | ✓ | +| Exporter Package | Metrics | Traces | +|:-----------------------------------------------------------------------------------------------------:|:-------:|:------:| +| [go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc](./otlp/otlpmetric/otlpmetricgrpc) | ✓ | | +| [go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp](./otlp/otlpmetric/otlpmetrichttp) | ✓ | | +| [go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc](./otlp/otlptrace/otlptracegrpc) | | ✓ | +| [go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp](./otlp/otlptrace/otlptracehttp) | | ✓ | +| [go.opentelemetry.io/otel/exporters/prometheus](./prometheus) | ✓ | | +| [go.opentelemetry.io/otel/exporters/stdout/stdoutmetric](./stdout/stdoutmetric) | ✓ | | +| [go.opentelemetry.io/otel/exporters/stdout/stdouttrace](./stdout/stdouttrace) | | ✓ | +| [go.opentelemetry.io/otel/exporters/zipkin](./zipkin) | | ✓ | See the [OpenTelemetry registry] for 3rd-party exporters compatible with this project. diff --git a/exporters/otlp/otlpmetric/otlpmetricgrpc/README.md b/exporters/otlp/otlpmetric/otlpmetricgrpc/README.md deleted file mode 100644 index 0b3a39947cc..00000000000 --- a/exporters/otlp/otlpmetric/otlpmetricgrpc/README.md +++ /dev/null @@ -1,42 +0,0 @@ -# OpenTelemetry-Go OTLP Metric gRPC Exporter - -[![Go Reference](https://pkg.go.dev/badge/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc.svg)](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc) - -[OpenTelemetry Protocol Exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/protocol/exporter.md) implementation using gRPC. - -## Installation - -``` -go get -u go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc -``` - -## Usage - -Exporters should be created using the [New](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc#New) and used with a [PeriodicReader]. - -## Environment Variables - -The following environment variables can be used (instead of options objects) to override the default configuration. - -| Name | Description | Default | Override with | -|------|-------------|---------|---------------| -| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint to which the exporter is going to send traces or metrics. If the scheme is `http` or `unix` this will also set `OTEL_EXPORTER_OTLP_INSECURE` to true | `https://localhost:4317` | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, [WithEndpoint()] | -| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Endpoint to which the exporter is going to send metrics. If the scheme is `http` or `unix` this will also set `OTEL_EXPORTER_OTLP_INSECURE` to true | `https://localhost:4317` | [WithEndpoint()] | -| `OTEL_EXPORTER_OTLP_INSECURE` | If set to true the connection will not attempt to use TLS when connecting | `false` | `OTEL_EXPORTER_OTLP_METRICS_INSECURE`, [WithInsecure()] | -| `OTEL_EXPORTER_OTLP_METRICS_INSECURE` | If set to true the connection will not attempt to use TLS when connecting | `false` | [WithInsecure()] | -| `OTEL_EXPORTER_OTLP_HEADERS` | A list of headers to send with each request | none | `OTEL_EXPORTER_OTLP_METRICS_HEADERS`, [WithHeaders()] | -| `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | A list of headers to send with each request | none | [WithHeaders()] | -| `OTEL_EXPORTER_OTLP_COMPRESSION` | Sets the compressions used in the connection. Supports `none` and `gzip`. Must import the compressor for gzip to work. | none | `OTEL_EXPORTER_OTLP_METRICS_COMPRESSION`, [WithCompressor()] | -| `OTEL_EXPORTER_OTLP_METRICS_COMPRESSION` | Sets the compressions used in the connection. Supports `none` and `gzip`. Must import the compressor for gzip to work. | none | [WithCompressor()] | -| `OTEL_EXPORTER_OTLP_TIMEOUT` | Sets the max amount of time (as milliseconds) an Exporter will attempt an export | `10000` | `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT`, [WithTimeout()] | -| `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT` | Sets the max amount of time (as milliseconds) an Exporter will attempt an export | `10000` | [WithTimeout()] | -| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | The aggregation temporality to use on the basis of instrument kind. Available values are `Cumulative`, `Delta`, and `LowMemory`. See [The OTLP Exporter Specification] for more details | `Cumulative` | [WithTemporalitySelector()] | - -[PeriodicReader]: https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#NewPeriodicReader -[WithEndpoint()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc#WithEndpoint -[WithInsecure()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc#WithInsecure -[WithHeaders()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc#WithHeaders -[WithCompressor()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc#WithCompressor -[WithTimeout()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc#WithTimeout -[The OTLP Exporter Specification]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/otlp.md#additional-configuration -[WithTemporalitySelector()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc#WithTemporalitySelector diff --git a/exporters/otlp/otlpmetric/otlpmetricgrpc/config.go b/exporters/otlp/otlpmetric/otlpmetricgrpc/config.go index 6ba3600b1c1..fbd495e7d7d 100644 --- a/exporters/otlp/otlpmetric/otlpmetricgrpc/config.go +++ b/exporters/otlp/otlpmetric/otlpmetricgrpc/config.go @@ -109,13 +109,7 @@ func compressorToCompression(compressor string) oconf.Compression { } // WithCompressor sets the compressor the gRPC client uses. -// -// It is the responsibility of the caller to ensure that the compressor set -// has been registered with google.golang.org/grpc/encoding (see -// encoding.RegisterCompressor for more information). For example, to register -// the gzip compressor import the package: -// -// import _ "google.golang.org/grpc/encoding/gzip" +// Supported compressor values: "gzip". // // If the OTEL_EXPORTER_OTLP_COMPRESSION or // OTEL_EXPORTER_OTLP_METRICS_COMPRESSION environment variable is set, and diff --git a/exporters/otlp/otlpmetric/otlpmetricgrpc/doc.go b/exporters/otlp/otlpmetric/otlpmetricgrpc/doc.go index 7820619bf60..7be572a79d0 100644 --- a/exporters/otlp/otlpmetric/otlpmetricgrpc/doc.go +++ b/exporters/otlp/otlpmetric/otlpmetricgrpc/doc.go @@ -12,6 +12,85 @@ // See the License for the specific language governing permissions and // limitations under the License. -// Package otlpmetricgrpc provides an otlpmetric.Exporter that communicates -// with an OTLP receiving endpoint using gRPC. +/* +Package otlpmetricgrpc provides an OTLP metrics exporter using gRPC. +By default the telemetry is sent to https://localhost:4317. + +Exporter should be created using [New] and used with a [metric.PeriodicReader]. + +The environment variables described below can be used for configuration. + +OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT (default: "https://localhost:4317") - +target to which the exporter sends telemetry. +The target syntax is defined in https://github.com/grpc/grpc/blob/master/doc/naming.md. +The value must contain a host. +The value may additionally a port, a scheme, and a path. +The value accepts "http" and "https" scheme. +The value should not contain a query string or fragment. +OTEL_EXPORTER_OTLP_METRICS_ENDPOINT takes precedence over OTEL_EXPORTER_OTLP_ENDPOINT. +The configuration can be overridden by [WithEndpoint], [WithInsecure], [WithGRPCConn] options. + +OTEL_EXPORTER_OTLP_INSECURE, OTEL_EXPORTER_OTLP_METRICS_INSECURE (default: "false") - +setting "true" disables client transport security for the exporter's gRPC connection. +You can use this only when an endpoint is provided without the http or https scheme. +OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT setting overrides +the scheme defined via OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT. +OTEL_EXPORTER_OTLP_METRICS_INSECURE takes precedence over OTEL_EXPORTER_OTLP_INSECURE. +The configuration can be overridden by [WithInsecure], [WithGRPCConn] options. + +OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS (default: none) - +key-value pairs used as gRPC metadata associated with gRPC requests. +The value is expected to be represented in a format matching to the [W3C Baggage HTTP Header Content Format], +except that additional semi-colon delimited metadata is not supported. +Example value: "key1=value1,key2=value2". +OTEL_EXPORTER_OTLP_METRICS_HEADERS takes precedence over OTEL_EXPORTER_OTLP_HEADERS. +The configuration can be overridden by [WithHeaders] option. + +OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_METRICS_TIMEOUT (default: "10000") - +maximum time in milliseconds the OTLP exporter waits for each batch export. +OTEL_EXPORTER_OTLP_METRICS_TIMEOUT takes precedence over OTEL_EXPORTER_OTLP_TIMEOUT. +The configuration can be overridden by [WithTimeout] option. + +OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_METRICS_COMPRESSION (default: none) - +the gRPC compressor the exporter uses. +Supported value: "gzip". +OTEL_EXPORTER_OTLP_METRICS_COMPRESSION takes precedence over OTEL_EXPORTER_OTLP_COMPRESSION. +The configuration can be overridden by [WithCompressor], [WithGRPCConn] options. + +OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE (default: none) - +the filepath to the trusted certificate to use when verifying a server's TLS credentials. +OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CERTIFICATE. +The configuration can be overridden by [WithTLSCredentials], [WithGRPCConn] options. + +OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE (default: none) - +the filepath to the client certificate/chain trust for clients private key to use in mTLS communication in PEM format. +OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE. +The configuration can be overridden by [WithTLSCredentials], [WithGRPCConn] options. + +OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY (default: none) - +the filepath to the clients private key to use in mTLS communication in PEM format. +OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY takes precedence over OTEL_EXPORTER_OTLP_CLIENT_KEY. +The configuration can be overridden by [WithTLSCredentials], [WithGRPCConn] option. + +OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE (default: "cumulative") - +aggregation temporality to use on the basis of instrument kind. Supported values: + - "cumulative" - Cumulative aggregation temporality for all instrument kinds, + - "delta" - Delta aggregation temporality for Counter, Asynchronous Counter and Histogram instrument kinds; + Cumulative aggregation for UpDownCounter and Asynchronous UpDownCounter instrument kinds, + - "lowmemory" - Delta aggregation temporality for Synchronous Counter and Histogram instrument kinds; + Cumulative aggregation temporality for Synchronous UpDownCounter, Asynchronous Counter, and Asynchronous UpDownCounter instrument kinds. + +The configuration can be overridden by [WithTemporalitySelector] option. + +OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION (default: "explicit_bucket_histogram") - +default aggregation to use for histogram instruments. Supported values: + - "explicit_bucket_histogram" - [Explicit Bucket Histogram Aggregation], + - "base2_exponential_bucket_histogram" - [Base2 Exponential Bucket Histogram Aggregation]. + +The configuration can be overridden by [WithAggregationSelector] option. + +[W3C Baggage HTTP Header Content Format]: https://www.w3.org/TR/baggage/#header-content +[Explicit Bucket Histogram Aggregation]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/metrics/sdk.md#explicit-bucket-histogram-aggregation +[Base2 Exponential Bucket Histogram Aggregation]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/metrics/sdk.md#base2-exponential-bucket-histogram-aggregation +*/ package otlpmetricgrpc // import "go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc" diff --git a/exporters/otlp/otlpmetric/otlpmetrichttp/README.md b/exporters/otlp/otlpmetric/otlpmetrichttp/README.md deleted file mode 100644 index 114c5d32686..00000000000 --- a/exporters/otlp/otlpmetric/otlpmetrichttp/README.md +++ /dev/null @@ -1,43 +0,0 @@ -# OpenTelemetry-Go OTLP Metric HTTP Exporter - -[![Go Reference](https://pkg.go.dev/badge/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp.svg)](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp) - -[OpenTelemetry Protocol Exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/protocol/exporter.md) implementation using HTTP with protobuf-encoded payloads. - -## Installation - -``` -go get -u go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp -``` - -## Usage - -Exporters should be created using the [New](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp#New) and used with a [PeriodicReader]. - -## Environment Variables - -The following environment variables can be used (instead of options objects) to override the default configuration. - -| Name | Description | Default | Override with | -|------|-------------|---------|---------------| -| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint to which the exporter is going to send traces or metrics. If the scheme is `http` or `unix` this will also set `OTEL_EXPORTER_OTLP_INSECURE` to true | `https://localhost:4317` | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, [WithEndpoint()] | -| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Endpoint to which the exporter is going to send metrics. If the scheme is `http` or `unix` this will also set `OTEL_EXPORTER_OTLP_INSECURE` to true | `https://localhost:4317/v1/metrics` | [WithEndpoint()] and [WithURLPath()] | -| `OTEL_EXPORTER_OTLP_INSECURE` | If set to true the connection will not attempt to use TLS when connecting | `false` | `OTEL_EXPORTER_OTLP_METRICS_INSECURE`, [WithInsecure()] | -| `OTEL_EXPORTER_OTLP_METRICS_INSECURE` | If set to true the connection will not attempt to use TLS when connecting | `false` | [WithInsecure()] | -| `OTEL_EXPORTER_OTLP_HEADERS` | A list of headers to send with each request | none | `OTEL_EXPORTER_OTLP_METRICS_HEADERS`, [WithHeaders()] | -| `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | A list of headers to send with each request | none | [WithHeaders()] | -| `OTEL_EXPORTER_OTLP_COMPRESSION` | Sets the compressions used in the connection. Supports `none` and `gzip`. Must import the compressor for gzip to work. | none | `OTEL_EXPORTER_OTLP_METRICS_COMPRESSION`, [WithCompression()] | -| `OTEL_EXPORTER_OTLP_METRICS_COMPRESSION` | Sets the compressions used in the connection. Supports `none` and `gzip`. Must import the compressor for gzip to work. | none | [WithCompression()] | -| `OTEL_EXPORTER_OTLP_TIMEOUT` | Sets the max amount of time (as milliseconds) an Exporter will attempt an export | `10000` | `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT`, [WithTimeout()] | -| `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT` | Sets the max amount of time (as milliseconds) an Exporter will attempt an export | `10000` | [WithTimeout()] | -| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | The aggregation temporality to use on the basis of instrument kind. Available values are `Cumulative`, `Delta`, and `LowMemory`. See [The OTLP Exporter Specification] for more details | `Cumulative` | [WithTemporalitySelector()] | - -[WithEndpoint()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp#WithEndpoint -[WithURLPath()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp#WithURLPath -[WithInsecure()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp#WithInsecure -[WithHeaders()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp#WithHeaders -[WithCompression()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp#WithCompression -[WithCompressor()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp#WithCompressor -[WithTimeout()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp#WithTimeout -[The OTLP Exporter Specification]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/otlp.md#additional-configuration -[WithTemporalitySelector()]: https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp#WithTemporalitySelector diff --git a/exporters/otlp/otlpmetric/otlpmetrichttp/doc.go b/exporters/otlp/otlpmetric/otlpmetrichttp/doc.go index a49e2465171..94f8b250d3f 100644 --- a/exporters/otlp/otlpmetric/otlpmetrichttp/doc.go +++ b/exporters/otlp/otlpmetric/otlpmetrichttp/doc.go @@ -12,7 +12,82 @@ // See the License for the specific language governing permissions and // limitations under the License. -// Package otlpmetrichttp provides an otlpmetric.Exporter that communicates -// with an OTLP receiving endpoint using protobuf encoded metric data over -// HTTP. +/* +Package otlpmetrichttp provides an OTLP metrics exporter using HTTP with protobuf payloads. +By default the telemetry is sent to https://localhost:4318/v1/metrics. + +Exporter should be created using [New] and used with a [metric.PeriodicReader]. + +The environment variables described below can be used for configuration. + +OTEL_EXPORTER_OTLP_ENDPOINT (default: "https://localhost:4318") - +target base URL ("/v1/metrics" is appended) to which the exporter sends telemetry. +The value must contain a scheme ("http" or "https") and host. +The value may additionally contain a port and a path. +The value should not contain a query string or fragment. +The configuration can be overridden by OTEL_EXPORTER_OTLP_METRICS_ENDPOINT +environment variable and by [WithEndpoint], [WithInsecure] options. + +OTEL_EXPORTER_OTLP_METRICS_ENDPOINT (default: "https://localhost:4318/v1/metrics") - +target URL to which the exporter sends telemetry. +The value must contain a scheme ("http" or "https") and host. +The value may additionally contain a port and a path. +The value should not contain a query string or fragment. +The configuration can be overridden by [WithEndpoint], [WitnInsecure], [WithURLPath] options. + +OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS (default: none) - +key-value pairs used as headers associated with HTTP requests. +The value is expected to be represented in a format matching to the [W3C Baggage HTTP Header Content Format], +except that additional semi-colon delimited metadata is not supported. +Example value: "key1=value1,key2=value2". +OTEL_EXPORTER_OTLP_METRICS_HEADERS takes precedence over OTEL_EXPORTER_OTLP_HEADERS. +The configuration can be overridden by [WithHeaders] option. + +OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_METRICS_TIMEOUT (default: "10000") - +maximum time in milliseconds the OTLP exporter waits for each batch export. +OTEL_EXPORTER_OTLP_METRICS_TIMEOUT takes precedence over OTEL_EXPORTER_OTLP_TIMEOUT. +The configuration can be overridden by [WithTimeout] option. + +OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_METRICS_COMPRESSION (default: none) - +compression strategy the exporter uses to compress the HTTP body. +Supported values: "gzip". +OTEL_EXPORTER_OTLP_METRICS_COMPRESSION takes precedence over OTEL_EXPORTER_OTLP_COMPRESSION. +The configuration can be overridden by [WithCompression] option. + +OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE (default: none) - +filepath to the trusted certificate to use when verifying a server's TLS credentials. +OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CERTIFICATE. +The configuration can be overridden by [WithTLSClientConfig] option. + +OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE (default: none) - +filepath to the client certificate/chain trust for clients private key to use in mTLS communication in PEM format. +OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE. +The configuration can be overridden by [WithTLSClientConfig] option. + +OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY (default: none) - +filepath to the clients private key to use in mTLS communication in PEM format. +OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY takes precedence over OTEL_EXPORTER_OTLP_CLIENT_KEY. +The configuration can be overridden by [WithTLSClientConfig] option. + +OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE (default: "cumulative") - +aggregation temporality to use on the basis of instrument kind. Supported values: + - "cumulative" - Cumulative aggregation temporality for all instrument kinds, + - "delta" - Delta aggregation temporality for Counter, Asynchronous Counter and Histogram instrument kinds; + Cumulative aggregation for UpDownCounter and Asynchronous UpDownCounter instrument kinds, + - "lowmemory" - Delta aggregation temporality for Synchronous Counter and Histogram instrument kinds; + Cumulative aggregation temporality for Synchronous UpDownCounter, Asynchronous Counter, and Asynchronous UpDownCounter instrument kinds. + +The configuration can be overridden by [WithTemporalitySelector] option. + +OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION (default: "explicit_bucket_histogram") - +default aggregation to use for histogram instruments. Supported values: + - "explicit_bucket_histogram" - [Explicit Bucket Histogram Aggregation], + - "base2_exponential_bucket_histogram" - [Base2 Exponential Bucket Histogram Aggregation]. + +The configuration can be overridden by [WithAggregationSelector] option. + +[W3C Baggage HTTP Header Content Format]: https://www.w3.org/TR/baggage/#header-content +[Explicit Bucket Histogram Aggregation]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/metrics/sdk.md#explicit-bucket-histogram-aggregation +[Base2 Exponential Bucket Histogram Aggregation]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/metrics/sdk.md#base2-exponential-bucket-histogram-aggregation +*/ package otlpmetrichttp // import "go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp" diff --git a/exporters/otlp/otlptrace/README.md b/exporters/otlp/otlptrace/README.md deleted file mode 100644 index 50295223182..00000000000 --- a/exporters/otlp/otlptrace/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# OpenTelemetry-Go OTLP Span Exporter - -[![Go Reference](https://pkg.go.dev/badge/go.opentelemetry.io/otel/exporters/otlp/otlptrace.svg)](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace) - -[OpenTelemetry Protocol Exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/protocol/exporter.md) implementation. - -## Installation - -``` -go get -u go.opentelemetry.io/otel/exporters/otlp/otlptrace -``` - -## Examples - -- [HTTP Exporter setup and examples](./otlptracehttp/example_test.go) -- [Full example of gRPC Exporter sending telemetry to a local collector](../../../example/otel-collector) - -## [`otlptrace`](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace) - -The `otlptrace` package provides an exporter implementing the OTel span exporter interface. -This exporter is configured using a client satisfying the `otlptrace.Client` interface. -This client handles the transformation of data into wire format and the transmission of that data to the collector. - -## [`otlptracegrpc`](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc) - -The `otlptracegrpc` package implements a client for the span exporter that sends trace telemetry data to the collector using gRPC with protobuf-encoded payloads. - -## [`otlptracehttp`](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp) - -The `otlptracehttp` package implements a client for the span exporter that sends trace telemetry data to the collector using HTTP with protobuf-encoded payloads. - -## Configuration - -### Environment Variables - -The following environment variables can be used (instead of options objects) to -override the default configuration. For more information about how each of -these environment variables is interpreted, see [the OpenTelemetry -specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/protocol/exporter.md). - -| Environment variable | Option | Default value | -| ------------------------------------------------------------------------ |------------------------------ | -------------------------------------------------------- | -| `OTEL_EXPORTER_OTLP_ENDPOINT` `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | `WithEndpoint` `WithInsecure` | `https://localhost:4317` or `https://localhost:4318`[^1] | -| `OTEL_EXPORTER_OTLP_CERTIFICATE` `OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE` | `WithTLSClientConfig` | | -| `OTEL_EXPORTER_OTLP_HEADERS` `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | `WithHeaders` | | -| `OTEL_EXPORTER_OTLP_COMPRESSION` `OTEL_EXPORTER_OTLP_TRACES_COMPRESSION` | `WithCompression` | | -| `OTEL_EXPORTER_OTLP_TIMEOUT` `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT` | `WithTimeout` | `10s` | - -[^1]: The gRPC client defaults to `https://localhost:4317` and the HTTP client `https://localhost:4318`. - -Configuration using options have precedence over the environment variables. diff --git a/exporters/otlp/otlptrace/doc.go b/exporters/otlp/otlptrace/doc.go new file mode 100644 index 00000000000..9e642235ade --- /dev/null +++ b/exporters/otlp/otlptrace/doc.go @@ -0,0 +1,21 @@ +// Copyright The OpenTelemetry Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/* +Package otlptrace contains abstractions for OTLP span exporters. +See the official OTLP span exporter implementations: + - [go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc], + - [go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp]. +*/ +package otlptrace // import "go.opentelemetry.io/otel/exporters/otlp/otlptrace" diff --git a/exporters/otlp/otlptrace/otlptracegrpc/doc.go b/exporters/otlp/otlptrace/otlptracegrpc/doc.go new file mode 100644 index 00000000000..1f514ef9ea3 --- /dev/null +++ b/exporters/otlp/otlptrace/otlptracegrpc/doc.go @@ -0,0 +1,77 @@ +// Copyright The OpenTelemetry Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/* +Package otlptracegrpc provides an OTLP span exporter using gRPC. +By default the telemetry is sent to https://localhost:4317. + +Exporter should be created using [New]. + +The environment variables described below can be used for configuration. + +OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (default: "https://localhost:4317") - +target to which the exporter sends telemetry. +The target syntax is defined in https://github.com/grpc/grpc/blob/master/doc/naming.md. +The value must contain a host. +The value may additionally a port, a scheme, and a path. +The value accepts "http" and "https" scheme. +The value should not contain a query string or fragment. +OTEL_EXPORTER_OTLP_TRACES_ENDPOINT takes precedence over OTEL_EXPORTER_OTLP_ENDPOINT. +The configuration can be overridden by [WithEndpoint], [WithInsecure], [WithGRPCConn] options. + +OTEL_EXPORTER_OTLP_INSECURE, OTEL_EXPORTER_OTLP_TRACES_INSECURE (default: "false") - +setting "true" disables client transport security for the exporter's gRPC connection. +You can use this only when an endpoint is provided without the http or https scheme. +OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT setting overrides +the scheme defined via OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT. +OTEL_EXPORTER_OTLP_TRACES_INSECURE takes precedence over OTEL_EXPORTER_OTLP_INSECURE. +The configuration can be overridden by [WithInsecure], [WithGRPCConn] options. + +OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS (default: none) - +key-value pairs used as gRPC metadata associated with gRPC requests. +The value is expected to be represented in a format matching to the [W3C Baggage HTTP Header Content Format], +except that additional semi-colon delimited metadata is not supported. +Example value: "key1=value1,key2=value2". +OTEL_EXPORTER_OTLP_TRACES_HEADERS takes precedence over OTEL_EXPORTER_OTLP_HEADERS. +The configuration can be overridden by [WithHeaders] option. + +OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_TRACES_TIMEOUT (default: "10000") - +maximum time in milliseconds the OTLP exporter waits for each batch export. +OTEL_EXPORTER_OTLP_TRACES_TIMEOUT takes precedence over OTEL_EXPORTER_OTLP_TIMEOUT. +The configuration can be overridden by [WithTimeout] option. + +OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_TRACES_COMPRESSION (default: none) - +the gRPC compressor the exporter uses. +Supported value: "gzip". +OTEL_EXPORTER_OTLP_TRACES_COMPRESSION takes precedence over OTEL_EXPORTER_OTLP_COMPRESSION. +The configuration can be overridden by [WithCompressor], [WithGRPCConn] options. + +OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE (default: none) - +the filepath to the trusted certificate to use when verifying a server's TLS credentials. +OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CERTIFICATE. +The configuration can be overridden by [WithTLSCredentials], [WithGRPCConn] options. + +OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE (default: none) - +the filepath to the client certificate/chain trust for clients private key to use in mTLS communication in PEM format. +OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE. +The configuration can be overridden by [WithTLSCredentials], [WithGRPCConn] options. + +OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY (default: none) - +the filepath to the clients private key to use in mTLS communication in PEM format. +OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY takes precedence over OTEL_EXPORTER_OTLP_CLIENT_KEY. +The configuration can be overridden by [WithTLSCredentials], [WithGRPCConn] option. + +[W3C Baggage HTTP Header Content Format]: https://www.w3.org/TR/baggage/#header-content +*/ +package otlptracegrpc // import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc" diff --git a/exporters/otlp/otlptrace/otlptracegrpc/example_test.go b/exporters/otlp/otlptrace/otlptracegrpc/example_test.go new file mode 100644 index 00000000000..ee03d1b505a --- /dev/null +++ b/exporters/otlp/otlptrace/otlptracegrpc/example_test.go @@ -0,0 +1,42 @@ +// Copyright The OpenTelemetry Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package otlptracegrpc_test + +import ( + "context" + + "go.opentelemetry.io/otel" + "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc" + "go.opentelemetry.io/otel/sdk/trace" +) + +func Example() { + ctx := context.Background() + exp, err := otlptracegrpc.New(ctx) + if err != nil { + panic(err) + } + + tracerProvider := trace.NewTracerProvider(trace.WithBatcher(exp)) + defer func() { + if err := tracerProvider.Shutdown(ctx); err != nil { + panic(err) + } + }() + otel.SetTracerProvider(tracerProvider) + + // From here, the tracerProvider can be used by instrumentation to collect + // telemetry. +} diff --git a/exporters/otlp/otlptrace/otlptracegrpc/options.go b/exporters/otlp/otlptrace/otlptracegrpc/options.go index 78ce9ad8f0b..17ffeaf6ef0 100644 --- a/exporters/otlp/otlptrace/otlptracegrpc/options.go +++ b/exporters/otlp/otlptrace/otlptracegrpc/options.go @@ -93,13 +93,7 @@ func compressorToCompression(compressor string) otlpconfig.Compression { } // WithCompressor sets the compressor for the gRPC client to use when sending -// requests. It is the responsibility of the caller to ensure that the -// compressor set has been registered with google.golang.org/grpc/encoding. -// This can be done by encoding.RegisterCompressor. Some compressors -// auto-register on import, such as gzip, which can be registered by calling -// `import _ "google.golang.org/grpc/encoding/gzip"`. -// -// This option has no effect if WithGRPCConn is used. +// requests. Supported compressor values: "gzip". func WithCompressor(compressor string) Option { return wrappedOption{otlpconfig.WithCompression(compressorToCompression(compressor))} } diff --git a/exporters/otlp/otlptrace/otlptracehttp/doc.go b/exporters/otlp/otlptrace/otlptracehttp/doc.go index e7f066b43ce..854cc38c8e4 100644 --- a/exporters/otlp/otlptrace/otlptracehttp/doc.go +++ b/exporters/otlp/otlptrace/otlptracehttp/doc.go @@ -13,7 +13,62 @@ // limitations under the License. /* -Package otlptracehttp a client that sends traces to the collector using HTTP -with binary protobuf payloads. +Package otlptracehttp provides an OTLP span exporter using HTTP with protobuf payloads. +By default the telemetry is sent to https://localhost:4318/v1/traces. + +Exporter should be created using [New]. + +The environment variables described below can be used for configuration. + +OTEL_EXPORTER_OTLP_ENDPOINT (default: "https://localhost:4318") - +target base URL ("/v1/traces" is appended) to which the exporter sends telemetry. +The value must contain a scheme ("http" or "https") and host. +The value may additionally contain a port and a path. +The value should not contain a query string or fragment. +The configuration can be overridden by OTEL_EXPORTER_OTLP_TRACES_ENDPOINT +environment variable and by [WithEndpoint], [WithInsecure] options. + +OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (default: "https://localhost:4318/v1/traces") - +target URL to which the exporter sends telemetry. +The value must contain a scheme ("http" or "https") and host. +The value may additionally contain a port and a path. +The value should not contain a query string or fragment. +The configuration can be overridden by [WithEndpoint], [WitnInsecure], [WithURLPath] options. + +OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS (default: none) - +key-value pairs used as headers associated with HTTP requests. +The value is expected to be represented in a format matching to the [W3C Baggage HTTP Header Content Format], +except that additional semi-colon delimited metadata is not supported. +Example value: "key1=value1,key2=value2". +OTEL_EXPORTER_OTLP_TRACES_HEADERS takes precedence over OTEL_EXPORTER_OTLP_HEADERS. +The configuration can be overridden by [WithHeaders] option. + +OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_TRACES_TIMEOUT (default: "10000") - +maximum time in milliseconds the OTLP exporter waits for each batch export. +OTEL_EXPORTER_OTLP_TRACES_TIMEOUT takes precedence over OTEL_EXPORTER_OTLP_TIMEOUT. +The configuration can be overridden by [WithTimeout] option. + +OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_TRACES_COMPRESSION (default: none) - +the compression strategy the exporter uses to compress the HTTP body. +Supported value: "gzip". +OTEL_EXPORTER_OTLP_TRACES_COMPRESSION takes precedence over OTEL_EXPORTER_OTLP_COMPRESSION. +The configuration can be overridden by [WithCompression] option. + +OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE (default: none) - +the filepath to the trusted certificate to use when verifying a server's TLS credentials. +OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CERTIFICATE. +The configuration can be overridden by [WithTLSClientConfig] option. + +OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE (default: none) - +the filepath to the client certificate/chain trust for clients private key to use in mTLS communication in PEM format. +OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE. +The configuration can be overridden by [WithTLSClientConfig] option. + +OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY (default: none) - +the filepath to the clients private key to use in mTLS communication in PEM format. +OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY takes precedence over OTEL_EXPORTER_OTLP_CLIENT_KEY. +The configuration can be overridden by [WithTLSClientConfig] option. + +[W3C Baggage HTTP Header Content Format]: https://www.w3.org/TR/baggage/#header-content */ package otlptracehttp // import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp" diff --git a/exporters/otlp/otlptrace/otlptracehttp/example_test.go b/exporters/otlp/otlptrace/otlptracehttp/example_test.go index d6bf4b0ab17..d67bdf5afea 100644 --- a/exporters/otlp/otlptrace/otlptracehttp/example_test.go +++ b/exporters/otlp/otlptrace/otlptracehttp/example_test.go @@ -16,79 +16,27 @@ package otlptracehttp_test import ( "context" - "fmt" - "log" "go.opentelemetry.io/otel" "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp" - "go.opentelemetry.io/otel/sdk/resource" - sdktrace "go.opentelemetry.io/otel/sdk/trace" - semconv "go.opentelemetry.io/otel/semconv/v1.21.0" - "go.opentelemetry.io/otel/trace" + "go.opentelemetry.io/otel/sdk/trace" ) -const ( - instrumentationName = "github.com/instrumentron" - instrumentationVersion = "0.1.0" -) - -var tracer = otel.GetTracerProvider().Tracer( - instrumentationName, - trace.WithInstrumentationVersion(instrumentationVersion), - trace.WithSchemaURL(semconv.SchemaURL), -) - -func add(ctx context.Context, x, y int64) int64 { - var span trace.Span - _, span = tracer.Start(ctx, "Addition") - defer span.End() - - return x + y -} - -func multiply(ctx context.Context, x, y int64) int64 { - var span trace.Span - _, span = tracer.Start(ctx, "Multiplication") - defer span.End() - - return x * y -} - -func newResource() *resource.Resource { - return resource.NewWithAttributes( - semconv.SchemaURL, - semconv.ServiceName("otlptrace-example"), - semconv.ServiceVersion("0.0.1"), - ) -} - -func installExportPipeline(ctx context.Context) (func(context.Context) error, error) { - exporter, err := otlptracehttp.New(ctx) - if err != nil { - return nil, fmt.Errorf("creating OTLP trace exporter: %w", err) - } - - tracerProvider := sdktrace.NewTracerProvider( - sdktrace.WithBatcher(exporter), - sdktrace.WithResource(newResource()), - ) - otel.SetTracerProvider(tracerProvider) - - return tracerProvider.Shutdown, nil -} - func Example() { ctx := context.Background() - // Registers a tracer Provider globally. - shutdown, err := installExportPipeline(ctx) + exp, err := otlptracehttp.New(ctx) if err != nil { - log.Fatal(err) + panic(err) } + + tracerProvider := trace.NewTracerProvider(trace.WithBatcher(exp)) defer func() { - if err := shutdown(ctx); err != nil { - log.Fatal(err) + if err := tracerProvider.Shutdown(ctx); err != nil { + panic(err) } }() + otel.SetTracerProvider(tracerProvider) - log.Println("the answer is", add(ctx, multiply(ctx, multiply(ctx, 2, 2), 10), 2)) + // From here, the tracerProvider can be used by instrumentation to collect + // telemetry. }