SignalFx Tracing Library for 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 |
|---|---|
|
環境変数 |
|
|
|
リソースの定義 を参照してください。 |
|
スパンリミットの設定 を参照してください。 |
|
リソースの定義 を参照してください。 |
|
トレース・ライブラリに関するメタデータは、 |
アプリケーションが停止したら、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 には、コードが計算リソースを過剰に使用するのを防ぐためのガードが含まれています。以下の環境変数を設定することで、スパン制限を設定することができます：
環境変数 |
説明 |
|---|---|
|
スパンごとの属性の最大数。デフォルト値は無制限です。 |
|
イベントごとの属性の最大数。デフォルト値は無制限です。 |
|
リンクあたりの最大属性数。デフォルト値は無制限です。 |
|
1スパンあたりの最大イベント数。デフォルト値は無制限です。 |
|
スパンあたりの最大リンク数。デフォルト値は |
|
span属性値の文字列の最大長。制限値より大きな値は切り捨てられます。デフォルト値は |
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 |
|---|---|
|
スパン間の関係は、 |
|
リソースの定義 を参照してください。 |
|
リソースの定義 を参照してください。 |
|
|
|
|
|
|
|
スパンリミットの設定 を参照してください。 |
|
スパンIDは自動的に設定されます。カスタム・スパンIDが必要な場合は、カスタム |
すべてのスパンを終了する 🔗
次の例のように、OpenTelemetry End メソッドを使用してスパンを終了します：
defer span.End()
すべてのインストルメンテーション・ライブラリを交換する 🔗
もしあれば、以下のインストルメンテーション・ライブラリを OpenTelemetry と同等のものに置き換えてください：
SignalFx ライブラリ |
OpenTelemetry ライブラリ |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
本パッケージは OpenTelemetry のネイティブサポートを提供します。 |
|
|
|
|
|
otelgrpc または otelhttp のいずれかを、gRPC または HTTP クライアントとともに使用して、 |
|
otelgrpc と共に最新バージョンのパッケージを使用してください。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
splunkhttp および otelhttp |
|
|
|
|
|
|
|
SignalFxトレーシング・ライブラリの削除 🔗
移行が完了したら、github.com/signalfx/signalfx-go-tracing パッケージの依存関係をすべて削除してください。go.mod ファイルをクリーンアップした後、これを確認してください。