Update the website getting started docs (#2203)

* Update the website getting started docs

Add a new example, fib, that contains an application for the computation
of Fibonacci numbers. Use this example to update the website getting
started documentation.

* Revise docs english

* Update example/fib/go.mod

Co-authored-by: Anthony Mirabella <[email protected]>

* Add a What's Next section

* Clean up intro

* Apply suggestions from code review

Co-authored-by: Anthony Mirabella <[email protected]>

* Apply feedback

* Return from Poll on error

* Update website_docs/getting-started.md

Co-authored-by: Joshua MacDonald <[email protected]>

* Add root and parent relationship info

Co-authored-by: Anthony Mirabella <[email protected]>
Co-authored-by: Joshua MacDonald <[email protected]>

.github/dependabot.yml

@@ -56,6 +56,16 @@ updates:
     schedule:
       day: sunday
       interval: weekly
+  -
+    package-ecosystem: gomod
+    directory: /example/fib
+    labels:
+      - dependencies
+      - go
+      - "Skip Changelog"
+    schedule:
+      day: sunday
+      interval: weekly
   -
     package-ecosystem: gomod
     directory: /example/prom-collector

.gitignore

@@ -10,6 +10,7 @@ coverage.*
 
 gen/
 
+/example/fib/fib
 /example/jaeger/jaeger
 /example/namedtracer/namedtracer
 /example/opencensus/opencensus

CHANGELOG.md

@@ -14,6 +14,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Added `"go.opentelemetry.io/otel/trace".WithStackTrace` option to add a stack trace when using `span.RecordError` or when panic is handled in `span.End`. (#2163)
 - Added typed slice attribute types and functionality to the `go.opentelemetry.io/otel/attribute` package to replace the existing array type and functions. (#2162)
   - `BoolSlice`, `IntSlice`, `Int64Slice`, `Float64Slice`, and `StringSlice` replace the use of the `Array` function in the package.
+- Added the `go.opentelemetry.io/otel/example/fib` example package.
+  Included is an example application that computes Fibonacci numbers. (#2203)
 
 ### Changed
 

bridge/opencensus/go.mod

@@ -72,3 +72,5 @@ replace go.opentelemetry.io/otel/exporters/stdout/stdouttrace => ../../exporters
 replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../../exporters/otlp/otlpmetric/otlpmetrichttp
 
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ./test
+
+replace go.opentelemetry.io/otel/example/fib => ../../example/fib

bridge/opencensus/test/go.mod

@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/sdk/export/metric => ../../../sdk/export/metric
 replace go.opentelemetry.io/otel/sdk/metric => ../../../sdk/metric
 
 replace go.opentelemetry.io/otel/trace => ../../../trace
+
+replace go.opentelemetry.io/otel/example/fib => ../../../example/fib

bridge/opentracing/go.mod

@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/exporters/stdout/stdouttrace => ../../exporters
 replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../../exporters/otlp/otlpmetric/otlpmetrichttp
 
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../opencensus/test
+
+replace go.opentelemetry.io/otel/example/fib => ../../example/fib

example/fib/app.go

@@ -0,0 +1,104 @@
+// 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 main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"log"
+	"strconv"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// name is the Tracer name used to identify this instrumentation library.
+const name = "fib"
+
+// App is an Fibonacci computation application.
+type App struct {
+	r io.Reader
+	l *log.Logger
+}
+
+// NewApp returns a new App.
+func NewApp(r io.Reader, l *log.Logger) *App {
+	return &App{r: r, l: l}
+}
+
+// Run starts polling users for Fibonacci number requests and writes results.
+func (a *App) Run(ctx context.Context) error {
+	for {
+		var span trace.Span
+		ctx, span = otel.Tracer(name).Start(ctx, "Run")
+
+		n, err := a.Poll(ctx)
+		if err != nil {
+			span.End()
+			return err
+		}
+
+		a.Write(ctx, n)
+		span.End()
+	}
+}
+
+// Poll asks a user for input and returns the request.
+func (a *App) Poll(ctx context.Context) (uint, error) {
+	_, span := otel.Tracer(name).Start(ctx, "Poll")
+	defer span.End()
+
+	a.l.Print("What Fibonacci number would you like to know: ")
+
+	var n uint
+	_, err := fmt.Fscanf(a.r, "%d", &n)
+	if err != nil {
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return 0, err
+	}
+
+	// Store n as a string to not overflow an int64.
+	nStr := strconv.FormatUint(uint64(n), 10)
+	span.SetAttributes(attribute.String("request.n", nStr))
+
+	return n, nil
+}
+
+// Write writes the n-th Fibonacci number back to the user.
+func (a *App) Write(ctx context.Context, n uint) {
+	var span trace.Span
+	ctx, span = otel.Tracer(name).Start(ctx, "Write")
+	defer span.End()
+
+	f, err := func(ctx context.Context) (uint64, error) {
+		_, span := otel.Tracer(name).Start(ctx, "Fibonacci")
+		defer span.End()
+		f, err := Fibonacci(n)
+		if err != nil {
+			span.RecordError(err)
+			span.SetStatus(codes.Error, err.Error())
+		}
+		return f, err
+	}(ctx)
+	if err != nil {
+		a.l.Printf("Fibonacci(%d): %v\n", n, err)
+	} else {
+		a.l.Printf("Fibonacci(%d) = %d\n", n, f)
+	}
+}

example/fib/fib.go

@@ -0,0 +1,35 @@
+// 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 main
+
+import "fmt"
+
+// Fibonacci returns the n-th fibonacci number.
+func Fibonacci(n uint) (uint64, error) {
+	if n <= 1 {
+		return uint64(n), nil
+	}
+
+	if n > 93 {
+		return 0, fmt.Errorf("unsupported fibonacci number %d: too large", n)
+	}
+
+	var n2, n1 uint64 = 0, 1
+	for i := uint(2); i < n; i++ {
+		n2, n1 = n1, n1+n2
+	}
+
+	return n2 + n1, nil
+}

example/fib/go.mod

@@ -0,0 +1,72 @@
+module go.opentelemetry.io/otel/example/fib
+
+go 1.15
+
+require (
+	go.opentelemetry.io/otel v1.0.0-RC2
+	go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.0.0-RC2
+	go.opentelemetry.io/otel/sdk v1.0.0-RC2
+	go.opentelemetry.io/otel/trace v1.0.0-RC2
+)
+
+replace go.opentelemetry.io/otel => ../..
+
+replace go.opentelemetry.io/otel/bridge/opencensus => ../../bridge/opencensus
+
+replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
+
+replace go.opentelemetry.io/otel/bridge/opentracing => ../../bridge/opentracing
+
+replace go.opentelemetry.io/otel/example/jaeger => ../jaeger
+
+replace go.opentelemetry.io/otel/example/namedtracer => ../namedtracer
+
+replace go.opentelemetry.io/otel/example/opencensus => ../opencensus
+
+replace go.opentelemetry.io/otel/example/otel-collector => ../otel-collector
+
+replace go.opentelemetry.io/otel/example/passthrough => ../passthrough
+
+replace go.opentelemetry.io/otel/example/prometheus => ../prometheus
+
+replace go.opentelemetry.io/otel/example/zipkin => ../zipkin
+
+replace go.opentelemetry.io/otel/exporters/jaeger => ../../exporters/jaeger
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric => ../../exporters/otlp/otlpmetric
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc => ../../exporters/otlp/otlpmetric/otlpmetricgrpc
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../../exporters/otlp/otlpmetric/otlpmetrichttp
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlptrace => ../../exporters/otlp/otlptrace
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc => ../../exporters/otlp/otlptrace/otlptracegrpc
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp => ../../exporters/otlp/otlptrace/otlptracehttp
+
+replace go.opentelemetry.io/otel/exporters/prometheus => ../../exporters/prometheus
+
+replace go.opentelemetry.io/otel/exporters/stdout/stdoutmetric => ../../exporters/stdout/stdoutmetric
+
+replace go.opentelemetry.io/otel/exporters/stdout/stdouttrace => ../../exporters/stdout/stdouttrace
+
+replace go.opentelemetry.io/otel/exporters/zipkin => ../../exporters/zipkin
+
+replace go.opentelemetry.io/otel/internal/metric => ../../internal/metric
+
+replace go.opentelemetry.io/otel/internal/tools => ../../internal/tools
+
+replace go.opentelemetry.io/otel/metric => ../../metric
+
+replace go.opentelemetry.io/otel/oteltest => ../../oteltest
+
+replace go.opentelemetry.io/otel/sdk => ../../sdk
+
+replace go.opentelemetry.io/otel/sdk/export/metric => ../../sdk/export/metric
+
+replace go.opentelemetry.io/otel/sdk/metric => ../../sdk/metric
+
+replace go.opentelemetry.io/otel/trace => ../../trace
+
+replace go.opentelemetry.io/otel/example/fib => ./

example/fib/go.sum

@@ -0,0 +1,17 @@
+github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/google/go-cmp v0.5.6 h1:BKbKCqvP6I+rmFHt06ZmyQtvB8xAkWdhFyr0ZUNZcxQ=
+github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+golang.org/x/sys v0.0.0-20210423185535-09eb48e85fd7 h1:iGu644GcxtEcrInvDsQRCwJjtCIOlT2V7IRt6ah2Whw=
+golang.org/x/sys v0.0.0-20210423185535-09eb48e85fd7/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

example/fib/main.go

@@ -0,0 +1,101 @@
+// 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 main
+
+import (
+	"context"
+	"io"
+	"log"
+	"os"
+	"os/signal"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
+	"go.opentelemetry.io/otel/sdk/resource"
+	"go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.4.0"
+)
+
+// newExporter returns a console exporter.
+func newExporter(w io.Writer) (trace.SpanExporter, error) {
+	return stdouttrace.New(
+		stdouttrace.WithWriter(w),
+		// Use human readable output.
+		stdouttrace.WithPrettyPrint(),
+		// Do not print timestamps for the demo.
+		stdouttrace.WithoutTimestamps(),
+	)
+}
+
+// newResource returns a resource describing this application.
+func newResource() *resource.Resource {
+	r, _ := resource.Merge(
+		resource.Default(),
+		resource.NewWithAttributes(
+			semconv.SchemaURL,
+			semconv.ServiceNameKey.String("fib"),
+			semconv.ServiceVersionKey.String("v0.1.0"),
+			attribute.String("environment", "demo"),
+		),
+	)
+	return r
+}
+
+func main() {
+	l := log.New(os.Stdout, "", 0)
+
+	// Write telemetry data to a file.
+	f, err := os.Create("traces.txt")
+	if err != nil {
+		l.Fatal(err)
+	}
+	defer f.Close()
+
+	exp, err := newExporter(f)
+	if err != nil {
+		l.Fatal(err)
+	}
+
+	tp := trace.NewTracerProvider(
+		trace.WithBatcher(exp),
+		trace.WithResource(newResource()),
+	)
+	defer func() {
+		if err := tp.Shutdown(context.Background()); err != nil {
+			l.Fatal(err)
+		}
+	}()
+	otel.SetTracerProvider(tp)
+
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, os.Interrupt)
+
+	errCh := make(chan error)
+	app := NewApp(os.Stdin, l)
+	go func() {
+		errCh <- app.Run(context.Background())
+	}()
+
+	select {
+	case <-sigCh:
+		l.Println("\ngoodbye")
+		return
+	case err := <-errCh:
+		if err != nil {
+			l.Fatal(err)
+		}
+	}
+}

example/jaeger/go.mod

@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/exporters/stdout/stdouttrace => ../../exporters
 replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../../exporters/otlp/otlpmetric/otlpmetrichttp
 
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
+
+replace go.opentelemetry.io/otel/example/fib => ../fib

example/namedtracer/go.mod

@@ -71,3 +71,5 @@ replace go.opentelemetry.io/otel/exporters/stdout/stdouttrace => ../../exporters
 replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../../exporters/otlp/otlpmetric/otlpmetrichttp
 
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
+
+replace go.opentelemetry.io/otel/example/fib => ../fib