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.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 |
|---|---|
|
Use the |
|
Use the |
|
See Defining resources. |
|
See Setting span limits. |
|
See Defining resources. |
|
Metadata about the tracing library is available in the |
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 |
|---|---|
|
Maximum number of attributes per span. The default value is unlimited. |
|
Maximum number of attributes per event. The default value is unlimited. |
|
Maximum number of attributes per link. The default value is unlimited. |
|
Maximum number of events per span. The default value is unlimited. |
|
Maximum number of links per span. The default value is |
|
Maximum length of strings for span attribute values. Values larger than the limit are truncated. The default value is |
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 |
|---|---|
|
The relationship between spans is defined using a |
|
See Defining resources. |
|
See Defining resources. |
|
|
|
|
|
|
|
See Setting span limits. |
|
Span IDs are automatically set. If you require custom span IDs, create a custom |
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 |
|---|---|
|
|
|
|
|
|
|
splunksql (splunkmysql , splunkpgx , splunkpq ) |
|
|
|
|
|
|
|
|
|
|
|
This package provides native support for OpenTelemetry. |
|
|
|
|
|
Use either otelgrpc or otelhttp with a gRPC or HTTP client when calling |
|
Use the latest version of the package alongside otelgrpc . |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Upgrade to |
|
|
|
|
|
splunkhttp and otelhttp |
|
|
|
|
|
|
|
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.