SignalFx Tracing Library for Go からの移行

Splunk Distribution of OpenTelemetry Go は、廃止された SignalFx Go Tracing Library を置き換えるものです。Splunk Distribution of OpenTelemetry Go に移行するには、以下の手順に従ってください。

Splunk Distribution of OpenTelemetry Go は、廃止された SignalFx Go Tracing Library を置き換えるものです。Splunk Go OTel インストルメンテーションに移行するには、以下の手順に従ってください。

互換性と要件

Splunk Distribution of OpenTelemetry Go には Go 1.18 以降が必要です。「Go インストルメンテーションの互換性と要件」を参照してください。

トレース設定の再設定

Splunk Distribution of OpenTelemetry Go の distro パッケージは、SignalFx Tracing Library for Go の tracing パッケージを置き換えるものですtracing.Start 関数を distro.Run に置き換えます。

tracing.StartOption インスタンスでは、以下の置換を使用します：


SignalFx トレーシング・ライブラリ	Splunk OTel Go
`tracing.WithAccessToken`	環境変数 `SPLUNK_ACCESS_TOKEN` を使用します。詳細については、「一般設定」を参照してください。
`tracing.WithEndpointURL`	`SPLUNK_REALM` またはその他の環境変数を使用して、エクスポータを構成します。詳細については、「エクスポータの設定」を参照してください。
`tracing.WithGlobalTag`	「リソースの定義」を参照してください。
`tracing.WithRecordedValueMaxLength`	「スパンリミットの設定」を参照してください。
`tracing.WithServiceName`	「リソースの定義」を参照してください。
`tracing.WithoutLibraryTags`	トレーシングライブラリに関するメタデータは、`distro.SDK` に関連する `Resource` で入手できます。詳細については、「リソースの定義」を参照してください。

アプリケーションが停止した場合は、distro.SDK もシャットダウンする必要があります。次の例のように、アプリケーションの main 関数のクリーンアップ関数を遅延させてください。

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)
   }
}()
/* ... */

リソースの定義

OpenTelemetry は、リソースを使用して、すべてのスパンに適用されるメタデータを記述します。distro.Run 関数は、トレースに必要なすべての Splunk および OpenTelemetry メタデータを含むデフォルトの Resource エンティティを作成します。サービスに関するメタデータを提供するには、Resource に含めます。

distro.SDK によって生成されたすべてのトレースのメタデータに追加属性を含めるには、OTEL_RESOURCE_ATTRIBUTES 環境変数を使用します。例：

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

注意: サービスの名前の設定が必要です。OTEL_SERVICE_NAME 環境変数を使ってサービス名を設定しないと、トレースデータが識別できなくなる可能性があります。

スパンリミットの設定

OpenTelemetry には、コードが計算リソースを過剰に使用するのを防ぐためのガードが含まれています。次の環境変数を設定することにより、スパン制限を設定できます。


環境変数	説明
`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`	スパンごとの属性の最大数。デフォルト値は [無制限] です。
`OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT`	イベントあたりの属性の最大数。デフォルト値は [無制限] です。
`OTEL_LINK_ATTRIBUTE_COUNT_LIMIT`	リンクごとの属性の最大数。デフォルト値は [無制限] です。
`OTEL_SPAN_EVENT_COUNT_LIMIT`	スパンあたりの最大イベント数。デフォルト値は [無制限] です。
`OTEL_SPAN_LINK_COUNT_LIMIT`	スパンあたりの最大リンク数。デフォルト値は `1000` です。
`OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`	スパン属性値の文字列の最大長。上限より大きい値は切り捨てられます。デフォルト値は `12000` です。

OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT 環境変数を同じ値に設定することで、tracing.WithRecordedValueMaxLength のインスタンスを置き換えます。

マニュアルのインストルメンテーションをすべて書き換える

tracer パッケージを使用して作成されたすべてのスパンを、OpenTelemetry を使用するように編集します。

tracer パッケージを使ってインストルメンテーションされた次の関数を考えてみます：

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()
   /* ... */
}

OpenTelemetryを使うようにすべてのスパンを編集すると、コードは次の例のようになります：

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()
   /* ... */
}

OpenTelemetryトレーサーを作成する

OpenTelemetry は、単一のインストルメンテーションライブラリのトレーシング関数をカプセル化するためにトレースを使用します。次の例のように、distro.SDK を開始したときに登録されたグローバル TracerProvider から Tracer を作成します。

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

新しいトレーサーとその Start 関数を使用して、すべての tracer.StartSpan 呼び出しを置き換えます：

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

tracer.StartSpan の operationNameパラメータを Start の name パラメータとして使用します。

StartSpanOptionインスタンスを置き換える

tracer.StartSpanOption インスタンスには以下の置換を使用します：


SignalFx トレーシング・ライブラリ	Splunk OTel Go
`tracer.ChildOf`	スパン間の関係は `context.Context`を使用して定義されます。`Start` に渡される `context.Context` には、親スパンが含まれている必要があります。これは、以前のコールから `Start` にコンテキストが返された場合に自動的に行われます。コンテキストで親スパンを明示的に定義するには、`trace.ContextWithSpan` を使用します。
`tracer.ResourceName`	「リソースの定義」を参照してください。
`tracer.ServiceName`	「リソースの定義」を参照してください。
`tracer.SpanType`	`trace.WithSpanKind`
`tracer.StartTime`	`trace.WithTimestamp`
`tracer.Tag`	`trace.WithAttributes`
`tracer.WithRecordedValueMaxLength`	「スパンリミットの設定」を参照してください。
`tracer.WithSpanID`	スパン ID は自動的に設定されます。カスタムスパン ID が必要な場合は、カスタム `IDGenerator` を作成してください。

すべてのスパンを終了する

次の例のように、OpenTelemetry End メソッドを使用してスパンを終了します：

defer span.End()

すべてのインストルメンテーション・ライブラリを交換する

もしあれば、以下のインストルメンテーション・ライブラリを OpenTelemetry と同等のものに置き換えてください：


SignalFx ライブラリ	OpenTelemetry ライブラリ
`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` および splunkredigo
`gin-gonic/gin`	otelgin
`globalsign/mgo`	`mongodb/mongo-go-driver` および `otelmongo`
`go-chi/chi`	splunkchi
`go-redis/redis`	本パッケージは OpenTelemetry のネイティブサポートを提供します。
`gocql/gocql`	otelgocql
`gomodule/redigo`	splunkredigo
`google.golang.org/api`	`cloudresourcemanager.NewService` を呼び出す場合、otelgrpc または otelhttp のいずれかを、gRPC または HTTP クライアントとともに使用します。
`google.golang.org/grpc.v12`	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`	`echo@v4` にアップグレードし、`otelecho` を使用します。
`miekg/dns`	splunkdns
`mongodb/mongo-go-driver/mongo`	otelmongo
`net/http`	splunkhttp および otelhttp
`olivere/elastic`	splunkelastic
`Shopify/sarama`	otelsarama
`syndtr/goleveldb/leveldb`	splunkleveldb
`tidwall/buntdb`	splunkbuntdb

SignalFxトレーシング・ライブラリの削除

移行が完了したら、github.com/signalfx/signalfx-go-tracing パッケージのすべての依存関係を削除します。これを確認するには、go.mod ファイルをクリーンアップした後にチェックしてください。