OpenTelemetry Go distro for Uptrace

uptrace-go configures opentelemetry-go to export spans and metrics to Uptrace using OTLP/gRPC.

• Installation
• Configuration
• Getting started
• Head-based sampling
• Resource detectors
• What's next?

Installation

To install uptrace-go:

go get github.com/uptrace/uptrace-go

Configuration

You can configure Uptrace client using a DSN (Data Source Name, e.g. https://<key>@uptrace.dev/<project_id>) from the project settings page.

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

uptrace.ConfigureOpentelemetry(
    // copy your project DSN here or use UPTRACE_DSN env var
    //uptrace.WithDSN("https://<key>@uptrace.dev/<project_id>"),

    uptrace.WithServiceName("myservice"),
    uptrace.WithServiceVersion("v1.0.0"),
)

You can find the full list of available options at pkg.go.dev.

Option	Description
WithDSN	A data source that specifies Uptrace project credentials. For example, https://<key>@uptrace.dev/<project_id>.
WithServiceName	service.name resource attribute. For example, myservice.
WithServiceVersion	service.version resource attribute. For example, 1.0.0.
WithResourceAttributes	Any other resource attributes.
WithResourceDetectors	Configures additional resource detectors, for example, EC2 detector or GCE detector.
WithResource	Resource contains attributes representing an entity that produces telemetry. Resource attributes are copied to all spans and events.

You can also use environment variables to configure the client:

Env var	Description
UPTRACE_DSN	A data source that is used to connect to uptrace.dev. For example, https://<key>@uptrace.dev/<project_id>.
OTEL_RESOURCE_ATTRIBUTES	Key-value pairs to be used as resource attributes. For example, service.name=myservice,service.version=1.0.0.
OTEL_PROPAGATORS	Propagators to be used as a comma separated list. The default is tracecontext,baggage.

Getting started

Install OpenTelemetry distro, generate your first trace, and click the link in your terminal to open Uptrace. All it takes is a minute of your time.

• Step 0. Create an Uptrace project to obtain a DSN (connection string), for example, https://<key>@uptrace.dev/<project_id>.

• Step 1. Install uptrace-go:

go get github.com/uptrace/uptrace-go

• Step 2. Copy the code to main.go replacing the <dsn>:

package main

import (
	"context"
	"errors"
	"fmt"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"

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

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

	// Configure OpenTelemetry with sensible defaults.
	uptrace.ConfigureOpentelemetry(
		// copy your project DSN here or use UPTRACE_DSN env var
		//uptrace.WithDSN("https://<key>@uptrace.dev/<project_id>"),

		uptrace.WithServiceName("myservice"),
		uptrace.WithServiceVersion("1.0.0"),
	)
	// Send buffered spans and free resources.
	defer uptrace.Shutdown(ctx)

	// Create a tracer. Usually, tracer is a global variable.
	tracer := otel.Tracer("app_or_package_name")

	// Create a root span (a trace) to measure some operation.
	ctx, main := tracer.Start(ctx, "main-operation")
	// End the span when the operation we are measuring is done.
	defer main.End()

	// We pass the main (parent) span in the ctx so we can reconstruct a trace later.
	_, child1 := tracer.Start(ctx, "child1-of-main")
	child1.SetAttributes(attribute.String("key1", "value1"))
	child1.RecordError(errors.New("error1"))
	child1.End()

	_, child2 := tracer.Start(ctx, "child2-of-main")
	child2.SetAttributes(attribute.Int("key2", 42), attribute.Float64("key3", 123.456))
	child2.End()

	fmt.Printf("trace: %s\n", uptrace.TraceURL(main))
}

• Step 3. Run the example to get a link for the generated trace:

go run main.go
trace: https://uptrace.dev/search/<project_id>?q=<trace_id>

• Step 4. Follow the link to view the trace:

Head-based sampling

You can reduce the number of created (sampled) spans by configuring head-based sampling:

import sdktrace "go.opentelemetry.io/otel/sdk/trace"

sampler := sdktrace.ParentBased(
	sdktrace.TraceIDRatioBased(0.5), // sample 50% of traces
)

uptrace.ConfigureOpentelemetry(
	uptrace.WithTraceSampler(sampler),

	// Other options
)

By default, uptrace-go samples all spans.

Resource detectors

By default, uptrace-go uses host and environment resource detectors, but you can configure it to use additional detectors, for example:

import (
	"github.com/uptrace/uptrace-go/uptrace"
	"go.opentelemetry.io/contrib/detectors/aws/ec2"
)

uptrace.ConfigureOpentelemetry(
	// copy your project DSN here or use UPTRACE_DSN env var
	//uptrace.WithDSN("https://<key>@uptrace.dev/<project_id>"),

	uptrace.WithServiceName("myservice"),
	uptrace.WithServiceVersion("1.0.0"),

	uptrace.WithResourceDetectors(ec2.NewResourceDetector()),
)

AWS

See AWS detectors.

EC2

import "go.opentelemetry.io/contrib/detectors/aws/ec2"

ec2ResourceDetector := ec2.NewResourceDetector()

EC2

import "go.opentelemetry.io/contrib/detectors/aws/ecs"

ecsResourceDetector := ecs.NewResourceDetector()

EKS

import "go.opentelemetry.io/contrib/detectors/aws/eks"

eksResourceDetector := eks.NewResourceDetector()

Google Cloud

See GCP detectors.

Cloud Run

import "go.opentelemetry.io/contrib/detectors/gcp"

cloudRunResourceDetector := gcp.NewCloudRun()

GCE

import "go.opentelemetry.io/contrib/detectors/gcp"

gceResourceDetector := gcp.GCE{}

GKE

import "go.opentelemetry.io/contrib/detectors/gcp"

gkeResourceDetector := gcp.GKE{}

What's next?

• Look for instrumentations, for example, Gin or gRPC.
• Learn about OpenTelemetry Tracing API and Metrics API to create your own instrumentations.

Tutorials:

• OpenTelemetry guide for Gin and GORM
• Monitoring cache stats using OpenTelemetry Metrics
• Instrumenting basic Go app