Migrate from the SignalFx Tracing Library for Go

The Splunk Distribution of OpenTelemetry Go replaces the deprecated SignalFx Go Tracing Library. To migrate to the Splunk Distribution of OpenTelemetry Go, follow these instructions.

The Splunk Distribution of OpenTelemetry Go replaces the deprecated SignalFx Go Tracing Library. To migrate to the Splunk Go OTel instrumentation, follow these instructions.

Compatibility and requirements

The Splunk Distribution of OpenTelemetry Go requires Go 1.18 and higher. See Go instrumentation compatibility and requirements.

Reconfigure the tracing settings

The distro package from the Splunk Distribution of OpenTelemetry Go replaces the tracing package from the SignalFx Tracing Library for Go. Replace the tracing.Start function with distro.Run.

Use the following replacements in tracing.StartOption instances:


SignalFx Tracing Library	Splunk OTel Go
`tracing.WithAccessToken`	Use the `SPLUNK_ACCESS_TOKEN` environment variable. See General settings for more information.
`tracing.WithEndpointURL`	Use the `SPLUNK_REALM` or other environment variables to configure the exporter. See Exporters configuration for more information.
`tracing.WithGlobalTag`	See Defining resources.
`tracing.WithRecordedValueMaxLength`	See Setting span limits.
`tracing.WithServiceName`	See Defining resources.
`tracing.WithoutLibraryTags`	Metadata about the tracing library is available in the `Resource` associated with the `distro.SDK`. See Defining resources for more information.

The distro.SDK must shut down when your application stops. Defer a cleanup function in your application main function as in the following example:

sdk, err := distro.Run()
if err != nil {
   panic(err)
}
defer func() {
   // A context with a deadline can be passed here instead if needed
   if err := sdk.Shutdown(context.Background()); err != nil {
      panic(err)
   }
}()
/* ... */

Defining resources

OpenTelemetry uses resources to describe the metadata applied to all spans. The distro.Run function creates a default Resource entity containing all the required Splunk and OpenTelemetry metadata for traces. To provide metadata about your service, include it in Resource.

To include additional attributes in the metadata for all traces produced by the distro.SDK, use the OTEL_RESOURCE_ATTRIBUTES environment variable. For example:

export OTEL_RESOURCE_ATTRIBUTES="ab-test-value=red,owner=Lisa"

CAUTION: Setting the name of the service is required. If you don’t set a service name using the OTEL_SERVICE_NAME environment variable, trace data might be unidentifiable.

Setting span limits

OpenTelemetry includes guards to prevent code from producing excessive usage of computational resources. You can configure span limits by setting the following environment variables:


Environment variable	Description
`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`	Maximum number of attributes per span. The default value is unlimited.
`OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT`	Maximum number of attributes per event. The default value is unlimited.
`OTEL_LINK_ATTRIBUTE_COUNT_LIMIT`	Maximum number of attributes per link. The default value is unlimited.
`OTEL_SPAN_EVENT_COUNT_LIMIT`	Maximum number of events per span. The default value is unlimited.
`OTEL_SPAN_LINK_COUNT_LIMIT`	Maximum number of links per span. The default value is `1000`.
`OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`	Maximum length of strings for span attribute values. Values larger than the limit are truncated. The default value is `12000`.

Replace instances of tracing.WithRecordedValueMaxLength by setting the OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT environment variable to the same value.

Rewrite all manual instrumentation

Edit all spans created using the tracer package so that they use OpenTelemetry.

Consider the following function instrumented using the tracer package:

func BusinessOperation(ctx context.Context, client string) {
   opts := []tracer.StartSpanOption{
      tracer.Tag("client", client),
      tracer.SpanType("internal"),
   }
   if parent, ok := tracer.SpanFromContext(ctx); ok {
      opts = append(opts, tracer.ChildOf(parent.Context()))
   }
   span := tracer.StartSpan("BusinessOperation", opts...)
   defer span.Finish()
   /* ... */
}

After editing all the spans to use OpenTelemetry, the code looks like the following example:

func BusinessOperation(ctx context.Context, client string) {
   tracer := otel.Tracer("app-name")
   opts := []trace.SpanStartOption{
      trace.WithAttributes(attribute.String("client", client)),
      trace.WithSpanKind(trace.SpanKindInternal),
   }
   ctx, span := tracer.Start(ctx, "BusinessOperation", opts...)
   defer span.End()
   /* ... */
}

Create OpenTelemetry Tracers

OpenTelemetry uses traces to encapsulate the tracing function of a single instrumentation library. Create a Tracer from the global TracerProvider registered when you start distro.SDK, as in the following example:

tracer := otel.Tracer("app-name")

Use the new tracer and its Start function to replace all tracer.StartSpan invocations:

ctx, span := tracer.Start(ctx, "BusinessOperation", /* options ... */)

Use the operationName parameter from tracer.StartSpan as the name parameter for Start.

Replace StartSpanOption instances

Use the following replacements for tracer.StartSpanOption instances:


SignalFx Tracing Library	Splunk OTel Go
`tracer.ChildOf`	The relationship between spans is defined using a `context.Context`. The `context.Context` passed to `Start` needs to contain your parent span. This is done automatically if the context is returned from a previous call to `Start`. To define a parent span explicitly in a context, use `trace.ContextWithSpan`.
`tracer.ResourceName`	See Defining resources.
`tracer.ServiceName`	See Defining resources.
`tracer.SpanType`	`trace.WithSpanKind`
`tracer.StartTime`	`trace.WithTimestamp`
`tracer.Tag`	`trace.WithAttributes`
`tracer.WithRecordedValueMaxLength`	See Setting span limits.
`tracer.WithSpanID`	Span IDs are automatically set. If you require custom span IDs, create a custom `IDGenerator`.

End all spans

Use the OpenTelemetry End method to end spans, as in the following example:

defer span.End()

Replace all instrumentation libraries

Replace the following instrumentation libraries with the OpenTelemetry equivalent, if available:


SignalFx library	OpenTelemetry library
`aws/aws-sdk-go/aws`	otelaws
`bradfitz/gomemcache/memcache`	otelmemcache
`confluentinc/confluent-kafka-go/kafka`	splunkkafka
`database/sql`	splunksql (splunkmysql , splunkpgx , splunkpq )
`emicklei/go-restful`	otelrestful
`garyburd/redigo`	`gomodule/redigo` and splunkredigo
`gin-gonic/gin`	otelgin
`globalsign/mgo`	`mongodb/mongo-go-driver` and `otelmongo`
`go-chi/chi`	splunkchi
`go-redis/redis`	This package provides native support for OpenTelemetry.
`gocql/gocql`	otelgocql
`gomodule/redigo`	splunkredigo
`google.golang.org/api`	Use either otelgrpc or otelhttp with a gRPC or HTTP client when calling `cloudresourcemanager.NewService`.
`google.golang.org/grpc.v12`	Use the latest version of the package alongside otelgrpc .
`google.golang.org/grpc`	otelgrpc
`gorilla/mux`	otelmux
`graph-gophers/graphql-go`	splunkgraphql
`jinzhu/gorm`	splunkgorm
`jmoiron/sqlx`	splunksqlx
`julienschmidt/httprouter`	splunkhttprouter
`k8s.io/client-go/kubernetes`	splunkclient-go
`labstack/echo.v4`	otelecho
`labstack/echo`	Upgrade to `echo@v4` and use `otelecho`.
`miekg/dns`	splunkdns
`mongodb/mongo-go-driver/mongo`	otelmongo
`net/http`	splunkhttp and otelhttp
`olivere/elastic`	splunkelastic
`Shopify/sarama`	otelsarama
`syndtr/goleveldb/leveldb`	splunkleveldb
`tidwall/buntdb`	splunkbuntdb

Remove the SignalFx Tracing Library

After you’ve completed the migration, remove all dependencies on github.com/signalfx/signalfx-go-tracing packages. Make sure to verify this by checking your go.mod files after cleaning them up.