Verify and update OTLP trace exporter documentation (#2053)

* Inventory the documentation for and examples of the OTLP exporter. * modify the documentation for otlptrace exporter. * Update exporters/otlp/otlptrace/README.md Co-authored-by: Robert Pająk <[email protected]> * Update exporters/otlp/otlptrace/README.md Co-authored-by: Robert Pająk <[email protected]> * Update exporters/otlp/otlptrace/README.md Co-authored-by: Tyler Yahn <[email protected]> * Update exporters/otlp/otlptrace/README.md Co-authored-by: Tyler Yahn <[email protected]> * Update exporters/otlp/otlptrace/README.md Co-authored-by: Tyler Yahn <[email protected]> * add otlptrace example_test.go * modify the documentation for otlptrace exporter. * modify the documentation for otlptrace exporter. * Update exporters/otlp/otlptrace/example_test.go Co-authored-by: Tyler Yahn <[email protected]> * Update exporters/otlp/otlptrace/example_test.go Co-authored-by: Tyler Yahn <[email protected]> * Update exporters/otlp/otlptrace/example_test.go Co-authored-by: Tyler Yahn <[email protected]> * Update exporters/otlp/otlptrace/README.md Co-authored-by: Tyler Yahn <[email protected]> * Update exporters/otlp/otlptrace/README.md Co-authored-by: Robert Pająk <[email protected]> * modify the documentation for otlptrace exporter. * Update exporters/otlp/otlptrace/README.md Co-authored-by: Robert Pająk <[email protected]> * Update exporters/otlp/otlptrace/README.md Co-authored-by: Robert Pająk <[email protected]> * Update exporters/otlp/otlptrace/README.md Co-authored-by: Robert Pająk <[email protected]> * Update exporters/otlp/otlptrace/README.md Co-authored-by: Tyler Yahn <[email protected]> * Update exporters/otlp/otlptrace/README.md Co-authored-by: Tyler Yahn <[email protected]> * Update exporters/otlp/otlptrace/README.md Co-authored-by: Tyler Yahn <[email protected]> * Move example to otlptracehttp package * Unexport example functions * Fix markdownlint errors * Specify payload types in README Co-authored-by: Robert Pająk <[email protected]> Co-authored-by: Tyler Yahn <[email protected]> Co-authored-by: Tyler Yahn <[email protected]>
ljmsc · Sep 2, 2021 · db317fc · db317fc
1 parent 04de34a
commit db317fc
Show file tree

Hide file tree

Showing 3 changed files with 127 additions and 0 deletions.
diff --git a/exporters/otlp/otlptrace/README.md b/exporters/otlp/otlptrace/README.md
@@ -0,0 +1,30 @@
+# 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.5.0/specification/protocol/exporter.md) implementation.
+
+## Installation
+
+```
+go get -u go.opentelemetry.io/otel/exporters/otlp/otlptrace
+```
+
+## Examples
+
+- [Exporter setup and examples](./otlptracehttp/example_test.go)
+- [Full example 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.
diff --git a/exporters/otlp/otlptrace/otlptracehttp/example_test.go b/exporters/otlp/otlptrace/otlptracehttp/example_test.go
@@ -0,0 +1,94 @@
+// 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
+//
+// https://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 otlptracehttp_test
+
+import (
+ "context"
+ "log"
+
+ "go.opentelemetry.io/otel"
+ "go.opentelemetry.io/otel/exporters/otlp/otlptrace"
+ "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.4.0"
+ "go.opentelemetry.io/otel/trace"
+)
+
+const (
+ instrumentationName = "github.com/instrumentron"
+ instrumentationVersion = "v0.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.ServiceNameKey.String("otlptrace-example"),
+ semconv.ServiceVersionKey.String("0.0.1"),
+ )
+}
+
+func installExportPipeline(ctx context.Context) func() {
+ client := otlptracehttp.NewClient()
+ exporter, err := otlptrace.New(ctx, client)
+ if err != nil {
+ log.Fatalf("creating OTLP trace exporter: %v", err)
+ }
+
+ tracerProvider := sdktrace.NewTracerProvider(
+ sdktrace.WithBatcher(exporter),
+ sdktrace.WithResource(newResource()),
+ )
+ otel.SetTracerProvider(tracerProvider)
+
+ return func() {
+ if err := tracerProvider.Shutdown(ctx); err != nil {
+ log.Fatalf("stopping tracer provider: %v", err)
+ }
+ }
+}
+
+func Example() {
+ ctx := context.Background()
+ // Registers a tracer Provider globally.
+ cleanup := installExportPipeline(ctx)
+ defer cleanup()
+
+ log.Println("the answer is", add(ctx, multiply(ctx, multiply(ctx, 2, 2), 10), 2))
+}
diff --git a/exporters/otlp/otlptrace/otlptracehttp/go.mod b/exporters/otlp/otlptrace/otlptracehttp/go.mod
@@ -4,7 +4,10 @@ go 1.15
 
 require (
  github.com/stretchr/testify v1.7.0
+ go.opentelemetry.io/otel v1.0.0-RC2
  go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.0.0-RC2
+ go.opentelemetry.io/otel/sdk v1.0.0-RC2
+ go.opentelemetry.io/otel/trace v1.0.0-RC2
  go.opentelemetry.io/proto/otlp v0.9.0
  google.golang.org/protobuf v1.27.1
 )