Updating documentation with an working example for creating NewExport…

…er (#1513) * Updating documentation with an working example for creating NewExporter * Updated Changelog * Moved examples in README to testing example * ExampleTest shouldn't log anything if working as expected * Fixing the lint * Fixing the lint * Review comments * Changes done moved to Fixed section of Changelog
open-telemetry · Feb 24, 2021 · 85e696d · 85e696d
1 parent 562eb28
commit 85e696d
Show file tree

Hide file tree

Showing 5 changed files with 67 additions and 132 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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)
+}