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.