# Instrumenting basic Go app

# Introduction

This tutorial demonstrates how to instrument a basic Go app using OpenTelemetry API. We will instrument the code to measure timing of each operation along with some execution context. We will also record errors that may happen during program execution.

# Example application

Let's create a directory and initialize a Go module for our application:

mkdir go-example-app
cd go-example-app
go mod init go-example-app
1
2
3

Our example application makes an HTTP call to download information about user's IP address via ip2c.org API. The main.go file looks like this:

package main

import (
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
    "strings"
)

func main() {
    countryInfo, err := fetchCountryInfo()
    if err != nil {
        log.Print(err)
        return
    }

    countryCode, countryName, err := parseCountryInfo(countryInfo)
    if err != nil {
        log.Print(err)
        return
    }

    fmt.Println(countryCode, countryName)
}

func fetchCountryInfo() (string, error) {
    resp, err := http.Get("https://ip2c.org/self")
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    b, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        return "", err
    }
    return string(b), nil
}

func parseCountryInfo(s string) (code, country string, _ error) {
    parts := strings.Split(s, ";")
    if len(parts) < 4 {
        return "", "", fmt.Errorf("ip2c: can't parse response: %q", s)
    }
    return parts[1], parts[3], nil
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# Adding context.Context

Go uses context.Contextopen in new window to pass the active span from one function to another. Let's create a default context and accept it as a first arg in our functions:

diff --git a/main.go b/main.go
index 8cc2c64..1408398 100644
--- a/main.go
+++ b/main.go
@@ -1,6 +1,7 @@
 package main

 import (
+       "context"
        "fmt"
        "io/ioutil"
        "log"
@@ -9,13 +10,15 @@ import (
 )

 func main() {
-       countryInfo, err := fetchCountryInfo()
+       ctx := context.Background()
+
+       countryInfo, err := fetchCountryInfo(ctx)
        if err != nil {
                log.Print(err)
                return
        }

-       countryCode, countryName, err := parseCountryInfo(countryInfo)
+       countryCode, countryName, err := parseCountryInfo(ctx, countryInfo)
        if err != nil {
                log.Print(err)
                return
@@ -24,7 +27,7 @@ func main() {
        fmt.Println(countryCode, countryName)
 }

-func fetchCountryInfo() (string, error) {
+func fetchCountryInfo(ctx context.Context) (string, error) {
        resp, err := http.Get("https://ip2c.org/self")
        if err != nil {
                return "", err
@@ -38,7 +41,7 @@ func fetchCountryInfo() (string, error) {
        return string(b), nil
 }

-func parseCountryInfo(s string) (code, country string, _ error) {
+func parseCountryInfo(ctx context.Context, s string) (code, country string, _ error) {
        parts := strings.Split(s, ";")
        if len(parts) < 4 {
                return "", "", fmt.Errorf("ip2c: can't parse response: %q", s)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# Creating a tracer

To monitor our program, we need to wrap (instrument) potentially interesting parts of the program with spans. You create spans with a tracer so we will need one. But first let's install Uptrace which comes with OpenTelemetry as a dependency:

go get github.com/uptrace/uptrace-go
1

Now we can create a named tracer go-example-app:

import "go.opentelemetry.io/otel"

var tracer = otel.Tracer("go-example-app")
1
2
3

# Instrumenting code with spans

We instrument code by creating a span at the start of each operation and calling span.End at the end. To set active span, API accepts and returns context.Context that we should use later to start other spans.

ctx, span := tracer.Start(ctx, "operation-name")

// operation body

span.End()
1
2
3
4
5

Let's use that knowledge to instrument fetchCountryInfo function and record execution context using span.SetAttributes API:

diff --git a/main.go b/main.go
index ff4d7c8..930a90f 100644
--- a/main.go
+++ b/main.go
@@ -9,6 +9,7 @@ import (
        "strings"

        "go.opentelemetry.io/otel"
+       "go.opentelemetry.io/otel/label"
 )

 var tracer = otel.Tracer("go-example-app")
@@ -32,6 +33,9 @@ func main() {
 }

 func fetchCountryInfo(ctx context.Context) (string, error) {
+       ctx, span := tracer.Start(ctx, "fetchCountryInfo")
+       defer span.End()
+
        resp, err := http.Get("https://ip2c.org/self")
        if err != nil {
                return "", err
@@ -43,6 +47,11 @@ func fetchCountryInfo(ctx context.Context) (string, error) {
                return "", err
        }

+       span.SetAttributes(
+               label.String("ip", "self"),
+               label.Int("resp_len", len(b)),
+       )
+
        return string(b), nil
 }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# Monitoring errors

To record errors, OpenTelemetry uses span events and provides span.RecordError API:

if err != nil {
    span.RecordError(ctx, err)
    return err
}
1
2
3
4

You can also use some logging library like logrusopen in new window and integrate it with OpenTelemetry:

if err != nil {
    logrus.WithContext(ctx).WithError(err).Error("http.Get failed")
    return err
}
1
2
3
4

# Root span

After successfully instrumenting our 2 functions we need to tie them together into a single trace. We do that by creating a root span fetchCountry for them. While we are at it, let's also record the errors.

diff --git a/main.go b/main.go
index 3973b46..2db8354 100644
--- a/main.go
+++ b/main.go
@@ -24,15 +23,18 @@ func main() {

        ctx := context.Background()

+       ctx, span := tracer.Start(ctx, "fetchCountry")
+       defer span.End()
+
        countryInfo, err := fetchCountryInfo(ctx)
        if err != nil {
-               log.Print(err)
+               span.RecordError(ctx, err)
                return
        }

        countryCode, countryName, err := parseCountryInfo(ctx, countryInfo)
        if err != nil {
-               log.Print(err)
+               span.RecordError(ctx, err)
                return
        }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# Configuring Uptrace

As the last we need to configure OpenTelemetry to export spans to Uptrace. You can do that using a DSN from the project settings page:

import "github.com/uptrace/uptrace-go/uptrace"

uptrace.ConfigureOpentelemetry(&uptrace.Config{
    // copy your project DSN here or use UPTRACE_DSN env var
    DSN: "",
})
1
2
3
4
5
6

# Putting all together

The resulting program is available at GitHubopen in new window.

package main

import (
    "context"
    "fmt"
    "io/ioutil"
    "net/http"
    "strings"

    "github.com/uptrace/uptrace-go/uptrace"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/label"
)

var tracer = otel.Tracer("go-example-app")

func main() {
    ctx := context.Background()

    uptrace.ConfigureOpentelemetry(&uptrace.Config{
        // copy your project DSN here or use UPTRACE_DSN env var
        DSN: "",
    })
    defer uptrace.Shutdown(ctx)

    ctx, span := tracer.Start(ctx, "fetchCountry")
    defer span.End()

    countryInfo, err := fetchCountryInfo(ctx)
    if err != nil {
        span.RecordError(ctx, err)
        return
    }

    countryCode, countryName, err := parseCountryInfo(ctx, countryInfo)
    if err != nil {
        span.RecordError(ctx, err)
        return
    }

    span.SetAttributes(
        label.String("country.code", countryCode),
        label.String("country.name", countryName),
    )

    fmt.Println("trace", uptrace.TraceURL(span))
}

func fetchCountryInfo(ctx context.Context) (string, error) {
    ctx, span := tracer.Start(ctx, "fetchCountryInfo")
    defer span.End()

    resp, err := http.Get("https://ip2c.org/self")
    if err != nil {
        span.RecordError(ctx, err)
        return "", err
    }
    defer resp.Body.Close()

    b, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        span.RecordError(ctx, err)
        return "", err
    }

    span.SetAttributes(
        label.String("ip", "self"),
        label.Int("resp_len", len(b)),
    )

    return string(b), nil
}

func parseCountryInfo(ctx context.Context, s string) (code, country string, _ error) {
    ctx, span := tracer.Start(ctx, "parseCountryInfo")
    defer span.End()

    parts := strings.Split(s, ";")
    if len(parts) < 4 {
        err := fmt.Errorf("ip2c: can't parse response: %q", s)
        span.RecordError(ctx, err)
        return "", "", err
    }
    return parts[1], parts[3], nil
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

You can run it passing the DSN as an environment variable:

UPTRACE_DSN=https://<token>@api.uptrace.dev/<project_id> go run main.go
trace: https://uptrace.dev/search/<project_id>?q=<trace_id>
1
2

By following the link you should be able to see the trace which demonstrates that app spends the majority of time in fetchCountryInfo function

Trace with two child spans

# Conclusion

By using context.Context and OpenTelemetry API we were able to instrument our simple program. Curious to try it yourself? Check out Getting started guide for Go.