Docs » Instrument back-end applications to send spans to Splunk APM » Instrument Go applications for Splunk Observability Cloud » Migrate from the SignalFx Tracing Library for Go

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 Go OTel instrumentation, follow these instructions.

Compatibility and requirements πŸ”—

The Splunk Distribution of OpenTelemetry Go requires Go 1.16 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.