diff --git a/CHANGELOG.md b/CHANGELOG.md index 0709ddca2..8ad2295f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,6 +47,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm ## Fixed - Fixed otlpgrpc reconnection issue. +- The example code in the README.md of `go.opentelemetry.io/otel/exporters/otlp` is moved to a compiled example test and used the new `WithAddress` instead of `WithEndpoint`. (#1513) +- The otel-collector example now uses the default OTLP receiver port of the collector. ## [0.16.0] - 2020-01-13 diff --git a/example/otel-collector/README.md b/example/otel-collector/README.md index b00baf158..ec495b85d 100644 --- a/example/otel-collector/README.md +++ b/example/otel-collector/README.md @@ -105,14 +105,14 @@ to the OpenTelemetry Collector, we need to first configure the `otlp` receiver: otel-collector-config: | receivers: # Make sure to add the otlp receiver. - # This will open up the receiver on port 55680. + # This will open up the receiver on port 4317. otlp: - endpoint: 0.0.0.0:55680 + endpoint: 0.0.0.0:4317 processors: ... ``` -This will create the receiver on the Collector side, and open up port `55680` +This will create the receiver on the Collector side, and open up port `4317` for receiving traces. The rest of the configuration is quite standard, with the only mention that we @@ -141,9 +141,9 @@ metadata: spec: ports: - name: otlp # Default endpoint for otlp receiver. - port: 55680 + port: 4317 protocol: TCP - targetPort: 55680 + targetPort: 4317 nodePort: 30080 - name: metrics # Endpoint for metrics from our app. port: 8889 diff --git a/example/otel-collector/k8s/otel-collector.yaml b/example/otel-collector/k8s/otel-collector.yaml index c2146601c..206b0b1ed 100644 --- a/example/otel-collector/k8s/otel-collector.yaml +++ b/example/otel-collector/k8s/otel-collector.yaml @@ -24,11 +24,11 @@ data: otel-collector-config: | receivers: # Make sure to add the otlp receiver. - # This will open up the receiver on port 55680 + # This will open up the receiver on port 4317 otlp: protocols: grpc: - endpoint: "0.0.0.0:55680" + endpoint: "0.0.0.0:4317" processors: extensions: health_check: {} @@ -122,7 +122,7 @@ spec: cpu: 200m memory: 400Mi ports: - - containerPort: 55680 # Default endpoint for otlp receiver. + - containerPort: 4317 # Default endpoint for otlp receiver. - containerPort: 8889 # Default endpoint for querying metrics. volumeMounts: - name: otel-collector-config-vol diff --git a/exporters/otlp/README.md b/exporters/otlp/README.md index 87b1d9319..0cd71f330 100644 --- a/exporters/otlp/README.md +++ b/exporters/otlp/README.md @@ -15,133 +15,10 @@ $ go get -u go.opentelemetry.io/otel/exporters/otlp A new exporter can be created using the `NewExporter` function. -```golang -package main - -import ( - "context" - "log" - - "go.opentelemetry.io/otel/sdk/metric/controller/push" - "go.opentelemetry.io/otel/exporters/otlp" - processor "go.opentelemetry.io/otel/sdk/metric/processor/basic" - "go.opentelemetry.io/otel/sdk/metric/selector/simple" - metricsdk "go.opentelemetry.io/otel/sdk/export/metric" - sdktrace "go.opentelemetry.io/otel/sdk/trace" -) - -func main() { - ctx := context.Background() - exporter, err := otlp.NewExporter(ctx) // Configure as needed. - if err != nil { - log.Fatalf("failed to create exporter: %v", err) - } - defer func() { - err := exporter.Shutdown(ctx) - if err != nil { - log.Fatalf("failed to stop exporter: %v", err) - } - }() - - // Note: The exporter can also be used as a Batcher. E.g. - // tracerProvider := sdktrace.NewTracerProvider( - // sdktrace.WithBatcher(exporter, - // sdktrace.WithBatchTimeout(time.Second*15), - // sdktrace.WithMaxExportBatchSize(100), - // ), - // ) - tracerProvider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter)) - processor := processor.New(simple.NewWithInexpensiveDistribution(), metricsdk.StatelessExportKindSelector()) - pusher := push.New(processor, exporter) - pusher.Start() - metricProvider := pusher.MeterProvider() - - // Your code here ... -} -``` - -## Configuration - -Configurations options can be specified when creating a new exporter (`NewExporter`). - -### `WorkerCount(n uint)` - -Sets the number of Goroutines to use when processing telemetry. - - -### `WithInsecure()` - -Disables client transport security for the exporter's gRPC connection just like [`grpc.WithInsecure()`](https://pkg.go.dev/google.golang.org/grpc#WithInsecure) does. -By default, client security is required unless `WithInsecure` is used. - -### `WithAddress(addr string)` - -Sets the address that the exporter will connect to the collector on. -The default address the exporter connects to is `localhost:55680`. - -### `WithReconnectionPeriod(rp time.Duration)` - -Set the delay between connection attempts after failing to connect with the collector. - -### `WithCompressor(compressor string)` - -Set the compressor for the gRPC client to use when sending requests. -The compressor used needs to have been registered with `google.golang.org/grpc/encoding` prior to using here. -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"`. - -### `WithHeaders(headers map[string]string)` - -Headers to send with gRPC requests. - -### `WithTLSCredentials(creds "google.golang.org/grpc/credentials".TransportCredentials)` - -TLS credentials to use when talking to the server. - -### `WithGRPCServiceConfig(serviceConfig string)` - -The default gRPC service config used when . - -By default, the exporter is configured to support [retries](#retries). - -```json -{ - "methodConfig":[{ - "name":[ - { "service":"opentelemetry.proto.collector.metrics.v1.MetricsService" }, - { "service":"opentelemetry.proto.collector.trace.v1.TraceService" } - ], - "waitForReady": true, - "retryPolicy":{ - "MaxAttempts":5, - "InitialBackoff":"0.3s", - "MaxBackoff":"5s", - "BackoffMultiplier":2, - "RetryableStatusCodes":[ - "UNAVAILABLE", - "CANCELLED", - "DEADLINE_EXCEEDED", - "RESOURCE_EXHAUSTED", - "ABORTED", - "OUT_OF_RANGE", - "UNAVAILABLE", - "DATA_LOSS" - ] - } - }] -} -``` - -### `WithGRPCDialOption(opts ..."google.golang.org/grpc".DialOption)` - -Additional `grpc.DialOption` to be used. - -These options take precedence over any other set by other parts of the configuration. - ## Retries The exporter will not, by default, retry failed requests to the collector. -However, it is configured in a way that it can easily be enable. +However, it is configured in a way that it can be easily enabled. To enable retries, the `GRPC_GO_RETRY` environment variable needs to be set to `on`. For example, diff --git a/exporters/otlp/example_test.go b/exporters/otlp/example_test.go new file mode 100644 index 000000000..96bc218b3 --- /dev/null +++ b/exporters/otlp/example_test.go @@ -0,0 +1,56 @@ +// 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 otlp_test + +import ( + "context" + "log" + + "go.opentelemetry.io/otel/exporters/otlp" + + "go.opentelemetry.io/otel" + "go.opentelemetry.io/otel/exporters/otlp/otlpgrpc" + sdktrace "go.opentelemetry.io/otel/sdk/trace" +) + +func ExampleNewExporter() { + ctx := context.Background() + + // Set different endpoints for the metrics and traces collectors + metricsDriver := otlpgrpc.NewDriver( + // Configure metrics driver here + ) + tracesDriver := otlpgrpc.NewDriver( + // Configure traces driver here + ) + config := otlp.SplitConfig{ + ForMetrics: metricsDriver, + ForTraces: tracesDriver, + } + driver := otlp.NewSplitDriver(config) + exporter, err := otlp.NewExporter(ctx, driver) // Configure as needed. + if err != nil { + log.Fatalf("failed to create exporter: %v", err) + } + defer func() { + err := exporter.Shutdown(ctx) + if err != nil { + log.Fatalf("failed to stop exporter: %v", err) + } + }() + + tracerProvider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter)) + otel.SetTracerProvider(tracerProvider) +}