Skip to content

Commit 04de34a

Browse files
MrAliasAneurysm9jmacd
authored
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]>
1 parent a7b9d02 commit 04de34a

File tree

39 files changed

+842
-125
lines changed

39 files changed

+842
-125
lines changed

.github/dependabot.yml

+10
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,16 @@ updates:
5656
schedule:
5757
day: sunday
5858
interval: weekly
59+
-
60+
package-ecosystem: gomod
61+
directory: /example/fib
62+
labels:
63+
- dependencies
64+
- go
65+
- "Skip Changelog"
66+
schedule:
67+
day: sunday
68+
interval: weekly
5969
-
6070
package-ecosystem: gomod
6171
directory: /example/prom-collector

.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ coverage.*
1010

1111
gen/
1212

13+
/example/fib/fib
1314
/example/jaeger/jaeger
1415
/example/namedtracer/namedtracer
1516
/example/opencensus/opencensus

CHANGELOG.md

+2
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
1414
- 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)
1515
- Added typed slice attribute types and functionality to the `go.opentelemetry.io/otel/attribute` package to replace the existing array type and functions. (#2162)
1616
- `BoolSlice`, `IntSlice`, `Int64Slice`, `Float64Slice`, and `StringSlice` replace the use of the `Array` function in the package.
17+
- Added the `go.opentelemetry.io/otel/example/fib` example package.
18+
Included is an example application that computes Fibonacci numbers. (#2203)
1719

1820
### Changed
1921

bridge/opencensus/go.mod

+2
Original file line numberDiff line numberDiff line change
@@ -72,3 +72,5 @@ replace go.opentelemetry.io/otel/exporters/stdout/stdouttrace => ../../exporters
7272
replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../../exporters/otlp/otlpmetric/otlpmetrichttp
7373

7474
replace go.opentelemetry.io/otel/bridge/opencensus/test => ./test
75+
76+
replace go.opentelemetry.io/otel/example/fib => ../../example/fib

bridge/opencensus/test/go.mod

+2
Original file line numberDiff line numberDiff line change
@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/sdk/export/metric => ../../../sdk/export/metric
6969
replace go.opentelemetry.io/otel/sdk/metric => ../../../sdk/metric
7070

7171
replace go.opentelemetry.io/otel/trace => ../../../trace
72+
73+
replace go.opentelemetry.io/otel/example/fib => ../../../example/fib

bridge/opentracing/go.mod

+2
Original file line numberDiff line numberDiff line change
@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/exporters/stdout/stdouttrace => ../../exporters
6969
replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../../exporters/otlp/otlpmetric/otlpmetrichttp
7070

7171
replace go.opentelemetry.io/otel/bridge/opencensus/test => ../opencensus/test
72+
73+
replace go.opentelemetry.io/otel/example/fib => ../../example/fib

example/fib/app.go

+104
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
// Copyright The OpenTelemetry Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package main
16+
17+
import (
18+
"context"
19+
"fmt"
20+
"io"
21+
"log"
22+
"strconv"
23+
24+
"go.opentelemetry.io/otel"
25+
"go.opentelemetry.io/otel/attribute"
26+
"go.opentelemetry.io/otel/codes"
27+
"go.opentelemetry.io/otel/trace"
28+
)
29+
30+
// name is the Tracer name used to identify this instrumentation library.
31+
const name = "fib"
32+
33+
// App is an Fibonacci computation application.
34+
type App struct {
35+
r io.Reader
36+
l *log.Logger
37+
}
38+
39+
// NewApp returns a new App.
40+
func NewApp(r io.Reader, l *log.Logger) *App {
41+
return &App{r: r, l: l}
42+
}
43+
44+
// Run starts polling users for Fibonacci number requests and writes results.
45+
func (a *App) Run(ctx context.Context) error {
46+
for {
47+
var span trace.Span
48+
ctx, span = otel.Tracer(name).Start(ctx, "Run")
49+
50+
n, err := a.Poll(ctx)
51+
if err != nil {
52+
span.End()
53+
return err
54+
}
55+
56+
a.Write(ctx, n)
57+
span.End()
58+
}
59+
}
60+
61+
// Poll asks a user for input and returns the request.
62+
func (a *App) Poll(ctx context.Context) (uint, error) {
63+
_, span := otel.Tracer(name).Start(ctx, "Poll")
64+
defer span.End()
65+
66+
a.l.Print("What Fibonacci number would you like to know: ")
67+
68+
var n uint
69+
_, err := fmt.Fscanf(a.r, "%d", &n)
70+
if err != nil {
71+
span.RecordError(err)
72+
span.SetStatus(codes.Error, err.Error())
73+
return 0, err
74+
}
75+
76+
// Store n as a string to not overflow an int64.
77+
nStr := strconv.FormatUint(uint64(n), 10)
78+
span.SetAttributes(attribute.String("request.n", nStr))
79+
80+
return n, nil
81+
}
82+
83+
// Write writes the n-th Fibonacci number back to the user.
84+
func (a *App) Write(ctx context.Context, n uint) {
85+
var span trace.Span
86+
ctx, span = otel.Tracer(name).Start(ctx, "Write")
87+
defer span.End()
88+
89+
f, err := func(ctx context.Context) (uint64, error) {
90+
_, span := otel.Tracer(name).Start(ctx, "Fibonacci")
91+
defer span.End()
92+
f, err := Fibonacci(n)
93+
if err != nil {
94+
span.RecordError(err)
95+
span.SetStatus(codes.Error, err.Error())
96+
}
97+
return f, err
98+
}(ctx)
99+
if err != nil {
100+
a.l.Printf("Fibonacci(%d): %v\n", n, err)
101+
} else {
102+
a.l.Printf("Fibonacci(%d) = %d\n", n, f)
103+
}
104+
}

example/fib/fib.go

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// Copyright The OpenTelemetry Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package main
16+
17+
import "fmt"
18+
19+
// Fibonacci returns the n-th fibonacci number.
20+
func Fibonacci(n uint) (uint64, error) {
21+
if n <= 1 {
22+
return uint64(n), nil
23+
}
24+
25+
if n > 93 {
26+
return 0, fmt.Errorf("unsupported fibonacci number %d: too large", n)
27+
}
28+
29+
var n2, n1 uint64 = 0, 1
30+
for i := uint(2); i < n; i++ {
31+
n2, n1 = n1, n1+n2
32+
}
33+
34+
return n2 + n1, nil
35+
}

example/fib/go.mod

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
module go.opentelemetry.io/otel/example/fib
2+
3+
go 1.15
4+
5+
require (
6+
go.opentelemetry.io/otel v1.0.0-RC2
7+
go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.0.0-RC2
8+
go.opentelemetry.io/otel/sdk v1.0.0-RC2
9+
go.opentelemetry.io/otel/trace v1.0.0-RC2
10+
)
11+
12+
replace go.opentelemetry.io/otel => ../..
13+
14+
replace go.opentelemetry.io/otel/bridge/opencensus => ../../bridge/opencensus
15+
16+
replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
17+
18+
replace go.opentelemetry.io/otel/bridge/opentracing => ../../bridge/opentracing
19+
20+
replace go.opentelemetry.io/otel/example/jaeger => ../jaeger
21+
22+
replace go.opentelemetry.io/otel/example/namedtracer => ../namedtracer
23+
24+
replace go.opentelemetry.io/otel/example/opencensus => ../opencensus
25+
26+
replace go.opentelemetry.io/otel/example/otel-collector => ../otel-collector
27+
28+
replace go.opentelemetry.io/otel/example/passthrough => ../passthrough
29+
30+
replace go.opentelemetry.io/otel/example/prometheus => ../prometheus
31+
32+
replace go.opentelemetry.io/otel/example/zipkin => ../zipkin
33+
34+
replace go.opentelemetry.io/otel/exporters/jaeger => ../../exporters/jaeger
35+
36+
replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric => ../../exporters/otlp/otlpmetric
37+
38+
replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc => ../../exporters/otlp/otlpmetric/otlpmetricgrpc
39+
40+
replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../../exporters/otlp/otlpmetric/otlpmetrichttp
41+
42+
replace go.opentelemetry.io/otel/exporters/otlp/otlptrace => ../../exporters/otlp/otlptrace
43+
44+
replace go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc => ../../exporters/otlp/otlptrace/otlptracegrpc
45+
46+
replace go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp => ../../exporters/otlp/otlptrace/otlptracehttp
47+
48+
replace go.opentelemetry.io/otel/exporters/prometheus => ../../exporters/prometheus
49+
50+
replace go.opentelemetry.io/otel/exporters/stdout/stdoutmetric => ../../exporters/stdout/stdoutmetric
51+
52+
replace go.opentelemetry.io/otel/exporters/stdout/stdouttrace => ../../exporters/stdout/stdouttrace
53+
54+
replace go.opentelemetry.io/otel/exporters/zipkin => ../../exporters/zipkin
55+
56+
replace go.opentelemetry.io/otel/internal/metric => ../../internal/metric
57+
58+
replace go.opentelemetry.io/otel/internal/tools => ../../internal/tools
59+
60+
replace go.opentelemetry.io/otel/metric => ../../metric
61+
62+
replace go.opentelemetry.io/otel/oteltest => ../../oteltest
63+
64+
replace go.opentelemetry.io/otel/sdk => ../../sdk
65+
66+
replace go.opentelemetry.io/otel/sdk/export/metric => ../../sdk/export/metric
67+
68+
replace go.opentelemetry.io/otel/sdk/metric => ../../sdk/metric
69+
70+
replace go.opentelemetry.io/otel/trace => ../../trace
71+
72+
replace go.opentelemetry.io/otel/example/fib => ./

example/fib/go.sum

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

example/fib/main.go

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
// Copyright The OpenTelemetry Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package main
16+
17+
import (
18+
"context"
19+
"io"
20+
"log"
21+
"os"
22+
"os/signal"
23+
24+
"go.opentelemetry.io/otel"
25+
"go.opentelemetry.io/otel/attribute"
26+
"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
27+
"go.opentelemetry.io/otel/sdk/resource"
28+
"go.opentelemetry.io/otel/sdk/trace"
29+
semconv "go.opentelemetry.io/otel/semconv/v1.4.0"
30+
)
31+
32+
// newExporter returns a console exporter.
33+
func newExporter(w io.Writer) (trace.SpanExporter, error) {
34+
return stdouttrace.New(
35+
stdouttrace.WithWriter(w),
36+
// Use human readable output.
37+
stdouttrace.WithPrettyPrint(),
38+
// Do not print timestamps for the demo.
39+
stdouttrace.WithoutTimestamps(),
40+
)
41+
}
42+
43+
// newResource returns a resource describing this application.
44+
func newResource() *resource.Resource {
45+
r, _ := resource.Merge(
46+
resource.Default(),
47+
resource.NewWithAttributes(
48+
semconv.SchemaURL,
49+
semconv.ServiceNameKey.String("fib"),
50+
semconv.ServiceVersionKey.String("v0.1.0"),
51+
attribute.String("environment", "demo"),
52+
),
53+
)
54+
return r
55+
}
56+
57+
func main() {
58+
l := log.New(os.Stdout, "", 0)
59+
60+
// Write telemetry data to a file.
61+
f, err := os.Create("traces.txt")
62+
if err != nil {
63+
l.Fatal(err)
64+
}
65+
defer f.Close()
66+
67+
exp, err := newExporter(f)
68+
if err != nil {
69+
l.Fatal(err)
70+
}
71+
72+
tp := trace.NewTracerProvider(
73+
trace.WithBatcher(exp),
74+
trace.WithResource(newResource()),
75+
)
76+
defer func() {
77+
if err := tp.Shutdown(context.Background()); err != nil {
78+
l.Fatal(err)
79+
}
80+
}()
81+
otel.SetTracerProvider(tp)
82+
83+
sigCh := make(chan os.Signal, 1)
84+
signal.Notify(sigCh, os.Interrupt)
85+
86+
errCh := make(chan error)
87+
app := NewApp(os.Stdin, l)
88+
go func() {
89+
errCh <- app.Run(context.Background())
90+
}()
91+
92+
select {
93+
case <-sigCh:
94+
l.Println("\ngoodbye")
95+
return
96+
case err := <-errCh:
97+
if err != nil {
98+
l.Fatal(err)
99+
}
100+
}
101+
}

example/jaeger/go.mod

+2
Original file line numberDiff line numberDiff line change
@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/exporters/stdout/stdouttrace => ../../exporters
6969
replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../../exporters/otlp/otlpmetric/otlpmetrichttp
7070

7171
replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
72+
73+
replace go.opentelemetry.io/otel/example/fib => ../fib

example/namedtracer/go.mod

+2
Original file line numberDiff line numberDiff line change
@@ -71,3 +71,5 @@ replace go.opentelemetry.io/otel/exporters/stdout/stdouttrace => ../../exporters
7171
replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../../exporters/otlp/otlpmetric/otlpmetrichttp
7272

7373
replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
74+
75+
replace go.opentelemetry.io/otel/example/fib => ../fib

0 commit comments

Comments
 (0)