StreamElements / connect-opentelemetry-go

OpenTelemetry tracing and metrics for Connect

connect-opentelemetry-go

connect-opentelemetry-go adds support for OpenTelemetry tracing and metrics collection to connect-go servers and clients.

For more on Connect, OpenTelemetry, and otelconnect, see the Connect announcement blog post and the observability documentation on connect.build.

An example

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"

	"github.com/bufbuild/connect-go"
	otelconnect "github.com/bufbuild/connect-opentelemetry-go"
	// Generated from your protobuf schema by protoc-gen-go and
	// protoc-gen-connect-go.
	pingv1 "github.com/bufbuild/connect-opentelemetry-go/internal/gen/observability/ping/v1"
	"github.com/bufbuild/connect-opentelemetry-go/internal/gen/observability/ping/v1/pingv1connect"
)

func main() {
	mux := http.NewServeMux()

	// otelconnect.NewInterceptor provides an interceptor that adds tracing and
	// metrics to both clients and handlers. By default, it uses OpenTelemetry's
	// global TracerProvider and MeterProvider, which you can configure by
	// following the OpenTelemetry documentation. If you'd prefer to avoid
	// globals, use otelconnect.WithTracerProvider and
	// otelconnect.WithMeterProvider.
	mux.Handle(pingv1connect.NewPingServiceHandler(
		&pingv1connect.UnimplementedPingServiceHandler{},
		connect.WithInterceptors(otelconnect.NewInterceptor()),
	))

	http.ListenAndServe("localhost:8080", mux)
}

func makeRequest() {
	client := pingv1connect.NewPingServiceClient(
		http.DefaultClient,
		"http://localhost:8080",
		connect.WithInterceptors(otelconnect.NewInterceptor()),
	)
	resp, err := client.Ping(
		context.Background(),
		connect.NewRequest(&pingv1.PingRequest{}),
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp)
}

Configuration for internal services

By default, instrumented servers are conservative and behave as though they're internet-facing. They don't trust any tracing information sent by the client, and will create new trace spans for each request. The new spans are linked to the remote span for reference (using OpenTelemetry's trace.Link), but tracing UIs will display the request as a new top-level transaction.

If your server is deployed as an internal service, configure otelconnect to trust the client's tracing information using otelconnect.WithTrustRemote. With this option, servers will create child spans for each request.

Reducing metrics and tracing cardinality

By default, the OpenTelemetry RPC conventions produce high-cardinality server-side metric and tracing output. In particular, servers tag all metrics and trace data with the server's IP address and the remote port number. To drop these attributes, use otelconnect.WithoutServerPeerAttributes. For more customizable attribute filtering, use otelconnect.WithFilter.

Status

connect-opentelemetry-go is available as a beta release.

	Unary	Streaming Client	Streaming Handler
Metrics	✅	✅	✅
Tracing	✅	✅	✅

Users of this package should expect breaking changes as the underlying OpenTelemetry APIs change. Once the Go OpenTelemetry metrics SDK stabilizes, we'll release a stable v1 of this package.

Ecosystem

• connect-go: Service handlers and clients for GoLang
• connect-swift: Swift clients for idiomatic gRPC & Connect RPC
• connect-kotlin: Kotlin clients for idiomatic gRPC & Connect RPC
• connect-web: TypeScript clients for web browsers
• Buf Studio: web UI for ad-hoc RPCs
• connect-crosstest: gRPC and gRPC-Web interoperability tests

Support and Versioning

connect-opentelemetry-go supports:

• The two most recent major releases of Go.
• v1 of the go.opentelemetry.io/otel tracing SDK.
• The current alpha release of the go.opentelemetry.io/otel metrics SDK.

It's not yet stable. We take every effort to maintain backward compatibility, but can't commit to a stable v1 until the OpenTelemetry APIs are stable.

Legal

Offered under the Apache 2 license.