From 80d1eb98ed1006f137edd0279480dd77b446871b Mon Sep 17 00:00:00 2001 From: wtong98 Date: Wed, 27 May 2020 10:06:33 -0500 Subject: [PATCH] Finish OTLP example --- example/README.md | 78 ++++++++++++++++++++++++++- example/otlp/example-otlp-config.yaml | 29 ++++++++++ example/otlp/go.mod | 3 +- example/otlp/main.go | 29 ++++++---- example/preview.html | 28 ---------- 5 files changed, 127 insertions(+), 40 deletions(-) create mode 100644 example/otlp/example-otlp-config.yaml delete mode 100644 example/preview.html diff --git a/example/README.md b/example/README.md index b868af3b5..0c722e100 100644 --- a/example/README.md +++ b/example/README.md @@ -3,7 +3,83 @@ Here is a collection of OpenTelemtry-Go examples showcasing basic functionality. ## OTLP This example demonstrates how to export trace and metric data from an -application using OpenTelemetry's own wire protocal OTLP. +application using OpenTelemetry's own wire protocal OTLP. We will also walk +you through configuring a collector to accept OTLP exports. + +### How to run? + +#### Prequisites +- go >=1.14 installed +- `GOPATH` is configured +- (optional) OpenTelemetry collector is available + +#### Start the Application +An example application is included in `example/otlp`. It simulates the process +of scribing a spell scroll (e.g. in [D&D](https://roll20.net/compendium/dnd5e/Spell%20Scroll#content)). +The application has been instrumented and exports both trace and metric data +via OTLP to any listening receiver. To run it: + +```sh +go get -d go.opentelemetry.io/otel +cd $GOPATH/go.opentelemetry.io/otel/example/otlp +go run main.go +``` + +The application is currently configured to transmit exported data to +`localhost:55680`. See [main.go](example/otlp/main.go) for full details. + +Note, if you don't have a receiver configured to take in metric data, the +application will complain about being unable to connect. + +#### (optional) Configure the Collector +Follow the instructions [on the +website](https://opentelemetry.io/docs/collector/about/) to install a working +instance of the collector. This example assumes you have the collector installed +locally. + +To configure the collector to accept OTLP traffic from our application, +ensure that it has the following configs: + +```yaml +receivers: + otlp: + endpoint: 0.0.0.0:55680 # listens to localhost:55680 + + # potentially other receivers + +service: + pipelines: + + traces: + receivers: + - otlp + # potentially other receivers + processors: # whatever processors you need + exporters: # wherever you want your data to go + + metrics: + receivers: + -otlp + # potentially other receivers + processors: etc + exporters: etc + + # other services +``` + +An example config has been provided at +[example-otlp-config.yaml](example/otlp/example-otlp-config.yaml). + +Then to run: +```sh +./[YOUR_COLLECTOR_BINARY] --config [PATH_TO_CONFIG] +``` + +If you use the example config, it's set to export to `stdout`. If you run +the collector on the same machine as the example application, you should +see trace and metric outputs from the collector. + + ## HTTP This is a simple example that demonstrates tracing http request from client to server. The example diff --git a/example/otlp/example-otlp-config.yaml b/example/otlp/example-otlp-config.yaml new file mode 100644 index 000000000..54e0262be --- /dev/null +++ b/example/otlp/example-otlp-config.yaml @@ -0,0 +1,29 @@ + extensions: + health_check: + + receivers: + otlp: + endpoint: 0.0.0.0:55680 + + processors: + batch: + queued_retry: + + exporters: + logging: + loglevel: debug + + service: + + pipelines: + + traces: + receivers: [otlp] + processors: [batch, queued_retry] + exporters: [logging] + + metrics: + receivers: [otlp] + exporters: [logging] + + extensions: [health_check] diff --git a/example/otlp/go.mod b/example/otlp/go.mod index 4d38111d8..c439cbed1 100644 --- a/example/otlp/go.mod +++ b/example/otlp/go.mod @@ -4,5 +4,6 @@ go 1.14 require ( github.com/open-telemetry/opentelemetry-collector v0.3.0 // indirect - go.opentelemetry.io/otel/exporters/otlp v0.6.0 // indirect + go.opentelemetry.io/otel v0.6.0 + go.opentelemetry.io/otel/exporters/otlp v0.6.0 ) diff --git a/example/otlp/main.go b/example/otlp/main.go index 7e36f13fa..804ebd8a5 100644 --- a/example/otlp/main.go +++ b/example/otlp/main.go @@ -1,4 +1,5 @@ -// dummy application for testing opentelemetry Go agent + collector +// Example application showcasing opentelemetry Go using the OTLP wire +// protocal package main @@ -17,8 +18,9 @@ import ( sdktrace "go.opentelemetry.io/otel/sdk/trace" ) -// TODO: basic documentation -func initProvider() { +// Initializes an OTLP exporter, and configures the corresponding trace and +// metric providers. +func initProvider() (*otlp.Exporter, *push.Controller) { exp, err := otlp.NewExporter( otlp.WithInsecure(), otlp.WithAddress("localhost:55680"), @@ -27,7 +29,7 @@ func initProvider() { traceProvider, err := sdktrace.NewProvider( sdktrace.WithConfig(sdktrace.Config{DefaultSampler: sdktrace.AlwaysSample()}), - sdktrace.WithSyncer(exp), + sdktrace.WithSyncer(exp), ) handleErr(err, "Failed to create trace provider: %v") @@ -35,17 +37,20 @@ func initProvider() { simple.NewWithExactDistribution(), exp, push.WithStateful(true), - push.WithPeriod(time.Duration(5) * time.Second), + push.WithPeriod(2*time.Second), ) global.SetTraceProvider(traceProvider) global.SetMeterProvider(pusher.Provider()) pusher.Start() + + return exp, pusher } - func main() { - initProvider() + exp, pusher := initProvider() + defer exp.Stop() + defer pusher.Stop() // pushes any last exports to the receiver tracer := global.Tracer("mage-sense") meter := global.Meter("mage-read") @@ -56,6 +61,7 @@ func main() { kv.String("priority", "Ultra"), } + // Observer metric example oneMetricCB := func(_ context.Context, result metric.Float64ObserverResult) { result.Observe(1, commonLabels...) } @@ -63,16 +69,19 @@ func main() { metric.WithDescription("A ValueObserver set to 1.0"), ) + // Recorder metric example valuerecorder := metric.Must(meter). NewFloat64ValueRecorder("scrying.glass.two"). Bind(commonLabels...) defer valuerecorder.Unbind() - ctx, span := tracer.Start(context.Background(), "Archmage-Overlord") + // work begins + ctx, span := tracer.Start(context.Background(), "Archmage-Overlord-Inspection") for i := 0; i < 10; i++ { _, innerSpan := tracer.Start(ctx, fmt.Sprintf("Minion-%d", i)) log.Println("Minions hard at work, scribing...") - valuerecorder.Record(ctx, float64(i) * 1.5) + valuerecorder.Record(ctx, float64(i)*1.5) + <-time.After(time.Second) innerSpan.End() } @@ -80,7 +89,7 @@ func main() { span.End() <-time.After(time.Second) - log.Println("Spell-scroll scribed!") + log.Println("Spell-scroll scribed!") } func handleErr(err error, message string) { diff --git a/example/preview.html b/example/preview.html deleted file mode 100644 index 211052cd4..000000000 --- a/example/preview.html +++ /dev/null @@ -1,28 +0,0 @@ -

Example

-

HTTP

-

This is a simple example that demonstrates tracing http request from client to server. The example shows key aspects of tracing such as:

- -

Example uses - open-telemetry SDK as trace instrumentation provider, - httptrace plugin to facilitate tracing http request on client and server - http trace_context propagation to propagate SpanContext on the wire. - stdout exporter to print information about spans in the terminal

-

How to run?

-

Prequisites

- -

1 Download git repo

-
GO111MODULE="" go get -d go.opentelemetry.io/otel
-

2 Start Server

-
cd $GOPATH/src/go.opentelemetry.io/otel/example/http/
-go run ./server/server.go
-

3 Start Client

-
cd $GOPATH/src/go.opentelemetry.io/otel/example/http/
-go run ./client/client.go
-

4 Check traces in stdout

-

The spans should be visible in stdout in the order that they were exported.