コンテンツにスキップ

Trace 設定

Trace 初期化設定

FTSdk.initTraceWithConfig(new FTTraceConfig()
    .setTraceSamplingRate(80f)
    .setEnableAutoTrace(true)
    .setEnableLinkRUMData(true));
FTSdk.initTraceWithConfig(
    FTTraceConfig()
        .setTraceSamplingRate(80f)
        .setEnableAutoTrace(true)
        .setEnableLinkRUMData(true)
)
メソッド名 型 必須 説明
setTraceSamplingRate Float いいえ サンプリング比率。範囲は [0,100]、デフォルトは 100。小数にも対応しており、例えば 0.1 は 0.1% を表します。0 は収集しないこと、100 は全量収集することを示します。新しいフィールドを明示的に設定した場合は、設定順序に関係なく旧フィールドより優先されます。ft-sdk >= 1.7.6 で対応しています。
setSamplingRate Float いいえ ft-sdk 1.7.6 以降は非推奨ですが、互換性のため残されています。 サンプリングレートを設定します。範囲は [0,1] で、0 は収集しないこと、1 は全量収集することを示します。デフォルト値は 1 です。
setTraceType TraceType いいえ 分散型トレーシングのタイプを設定します。デフォルトは DDTrace で、現在は Zipkin、Jaeger、DDTrace、Skywalking (8.0+)、TraceParent (W3C) に対応しています。OpenTelemetry を接続し、対応するトレースタイプを選択する場合は、サポートされているタイプと agent の関連設定を必ず確認してください。
setEnableLinkRUMData Boolean いいえ RUM データと関連付けるかどうか。デフォルトは false です。
setEnableAutoTrace Boolean いいえ 自動 HTTP Trace を有効にするかどうかを設定します。デフォルトは false です。自動計装は ft-plugin に依存し、OkHttp に対応しています。ft-sdk >= 1.7.6-alpha03 と ft-plugin >= 1.3.9-alpha01 を組み合わせ、URLConnection Resource の収集を有効にしている場合は、HttpURLConnection / HttpsURLConnection にも対応します。詳しくは URLConnection Trace を参照してください。
setOkHttpTraceHeaderHandler Callback いいえ ASM でグローバルな FTTraceInterceptor.HeaderHandler を設定します。デフォルトでは設定されず、ft-sdk 1.6.8 以上で対応しています。ft-sdk 1.6.17 以降は、getTraceContext(Request) のオーバーライドを優先してサポートしており、Header、traceId、spanId を一度に返すことができます。例は カスタム Trace を参照してください。

HttpURLConnection / HttpsURLConnection Trace

ft-sdk >= 1.7.6-alpha03 と ft-plugin >= 1.3.9-alpha01 を組み合わせる場合、先に URLConnection 自動収集 に従って setEnableTraceUserResource(true) と setEnableHttpURLConnectionResource(true) を有効にし、その後 FTTraceConfig.setEnableAutoTrace(true) で Trace Header の注入を有効にします。Trace スイッチだけを有効にしても URLConnection のラップは有効になりません。また、Resource URL フィルタリングによって、そのパスでの Trace 注入も除外されます。

伝搬形式とサンプリング決定は、FTTraceConfig の Trace タイプとサンプリングレート設定に従います。setEnableLinkRUMData(true) を有効にすると、正常に注入された trace_id / span_id が対応する Resource に関連付けられます。上記の Trace 初期化例は、RUM 設定と組み合わせて使用できます。

URLConnection は、選択した伝搬形式の既存 Trace Header を置き換えます。リクエストが他の SDK や JS レイヤーで既にトレース情報を注入されている場合は、重複して有効にしないでください。Resource の Trace 情報がサーバー側で受信した Header と一致しなくなるおそれがあります。setOkHttpTraceHeaderHandler は OkHttp に対してのみ機能し、URLConnection の Trace Header のカスタマイズには使用されません。

Tracer ネットワーク分散型トレーシング

FTTraceConfig で enableAutoTrace を有効にするとトレースデータが自動的に追加されます。また、FTTraceManager を手動で使用して HTTP リクエストに Propagation Header を追加することもできます。以下に例を示します。

String url = "https://request.url";
String uuid = "uuid";
// トレースヘッダー情報を取得
Map<String, String> headers = FTTraceManager.get().getTraceHeader(uuid, url);

OkHttpClient client = new OkHttpClient.Builder().addInterceptor(chain -> {
    Request original = chain.request();
    Request.Builder requestBuilder = original.newBuilder();
    // リクエストにトレースヘッダー情報を追加
    for (String key : headers.keySet()) {
        requestBuilder.header(key, headers.get(key));
    }
    Request request = requestBuilder.build();

    Response response = chain.proceed(request);

    if (response != null) {
        Map<String, String> requestHeaderMap = new HashMap<>();
        Map<String, String> responseHeaderMap = new HashMap<>();
        for (Pair<String, String> header : response.request().headers()) {
            requestHeaderMap.put(header.first, header.second);
        }
        for (Pair<String, String> header : response.headers()) {
            responseHeaderMap.put(header.first, header.second);
        }
    }

    return response;
}).build();

Request.Builder builder = new Request.Builder().url(url).method(RequestMethod.GET.name(), null);
client.newCall(builder.build()).execute();
val url = "https://request.url"
val uuid = "uuid"
// トレースヘッダー情報を取得
val headers = FTTraceManager.get().getTraceHeader(uuid, url)

val client: OkHttpClient = OkHttpClient.Builder().addInterceptor { chain ->
    val original = chain.request()
    val requestBuilder = original.newBuilder()
    // リクエストにトレースヘッダー情報を追加
    for (key in headers.keys) {
        requestBuilder.header(key!!, headers[key]!!)
    }
    val request = requestBuilder.build()

    val response = chain.proceed(request)

    if (response != null) {
        val requestHeaderMap = HashMap<String, String>()
        val responseHeaderMap = HashMap<String, String>()
        request.headers.forEach {
            requestHeaderMap[it.first] = it.second
        }
        response.headers.forEach {
            responseHeaderMap[it.first] = it.second
        }
    }

    response
}.build()

val builder: Request.Builder = Request.Builder().url(url).method(RequestMethod.GET.name, null)
client.newCall(builder.build()).execute()

OkHttp Interceptor による Resource と TraceHeader のカスタマイズ

Resource

FTRUMConfig.setEnableTraceUserResource(true) または FTRUMConfig.setOkHttpResourceContentHandler(...) を有効にすると、OkHttp のカスタム Interceptor が優先的に読み込まれます。

new OkHttpClient.Builder()
    .addInterceptor(new FTTraceInterceptor())
    .addInterceptor(new FTResourceInterceptor(new FTResourceInterceptor.ContentHandlerHelper() {
        @Override
        public void onRequest(Request request, HashMap<String, Object> extraData) {
            String contentType = request.header("Content-Type");
            extraData.put("df_request_header", request.headers().toString());
            if ("application/json".equals(contentType) ||
                    "application/x-www-form-urlencoded".equals(contentType) ||
                    "application/xml".equals(contentType)) {
                extraData.put("df_request_body", request.body());
            }
        }

        @Override
        public void onResponse(Response response, HashMap<String, Object> extraData) throws IOException {
            String contentType = response.header("Content-Type");
            extraData.put("df_response_header", response.headers().toString());
            if ("application/json".equals(contentType) ||
                    "application/xml".equals(contentType)) {
                // body の一部をコピーして読み取り、大規模データ処理の消費を回避
                ResponseBody body = response.peekBody(33554432);
                extraData.put("df_response_body", body.string());
            }
        }

        @Override
        public void onException(Exception e, HashMap<String, Object> extraData) {
        }
    }))
    .eventListenerFactory(new FTResourceEventListener.FTFactory())
    .build();
OkHttpClient.Builder()
    .addInterceptor(FTTraceInterceptor())
    .addInterceptor(FTResourceInterceptor(object : FTResourceInterceptor.ContentHandlerHelper {
        override fun onRequest(request: Request, extraData: HashMap<String, Any>) {
            val contentType = request.header("Content-Type")
            extraData["df_request_header"] = request.headers().toString()
            if ("application/json" == contentType ||
                "application/x-www-form-urlencoded" == contentType ||
                "application/xml" == contentType) {
                extraData["df_request_body"] = request.body()
            }
        }

        override fun onResponse(response: Response, extraData: HashMap<String, Any>) {
            val contentType = response.header("Content-Type")
            extraData["df_response_header"] = response.headers().toString()
            if ("application/json" == contentType ||
                "application/xml" == contentType) {
                // レスポンスボディの一部をコピーして大規模データの消費を回避
                val body = response.peekBody(33554432)
                extraData["df_response_body"] = body.string()
            }
        }

        override fun onException(e: Exception, extraData: HashMap<String, Any>) {
            // 例外を処理
        }
    }))
    .eventListenerFactory(FTResourceEventListener.FTFactory())
    .build()

TraceHeader

FTTraceConfig.setEnableAutoTrace(true) または FTTraceConfig.setOkHttpTraceHeaderHandler(...) を有効にすると、OkHttp のカスタム Interceptor が優先的に読み込まれます。以下では W3C Trace Context を例に説明します。

ft-sdk < 1.4.1 の場合は、FTTraceConfig.setEnableAutoTrace(false) を設定してオフにする必要があります。 ft-sdk > 1.6.7 では、カスタム Trace Header と RUM データの関連付けに対応しています。 ft-sdk >= 1.6.17 で getTraceContext(Request) が追加され、リクエスト Header、traceId、spanId を一度に返せます。この方式を優先して使用することを推奨します。

推奨する方式:getTraceContext(Request) を使用

new OkHttpClient.Builder()
    .addInterceptor(new FTTraceInterceptor(new FTTraceInterceptor.HeaderHandler() {
        @Override
        public TraceContext getTraceContext(Request request) {
            HashMap<String, String> headers = FTTraceManager.get()
                    .getTraceHeader(request.url().toString());
            return TraceContext.Simple.fromTraceType(headers);
        }
    }))
    .addInterceptor(new FTResourceInterceptor())
    .eventListenerFactory(new FTResourceEventListener.FTFactory())
    .build();
OkHttpClient.Builder()
    .addInterceptor(
        FTTraceInterceptor(object : FTTraceInterceptor.HeaderHandler() {
            override fun getTraceContext(request: Request): TraceContext? {
                val headers = FTTraceManager.get().getTraceHeader(request.url.toString())
                return TraceContext.Simple.fromTraceType(headers)
            }
        })
    )
    .addInterceptor(FTResourceInterceptor())
    .eventListenerFactory(FTResourceEventListener.FTFactory())
    .build()

旧方式との互換:getTraceHeader / getTraceID / getSpanID を個別に実装

new OkHttpClient.Builder()
    .addInterceptor(new FTTraceInterceptor(new FTTraceInterceptor.HeaderHandler() {
        private String[] splits;

        @Override
        public HashMap<String, String> getTraceHeader(Request request) {
            HashMap<String, String> map = new HashMap<>();

            String headerString = FTTraceManager.get()
                    .getTraceHeader(request.url().toString())
                    // ヘッダーから propagation header を取得
                    .get(FTTraceHandler.W3C_TRACEPARENT_KEY);

            splits = headerString.split("-");
            map.put(W3C_TRACEPARENT_KEY, headerString);
            return map;
        }

        @Override
        public String getSpanID() {
            if (splits != null) {
                return splits[2];
            }
            return null;
        }

        @Override
        public String getTraceID() {
            if (splits != null) {
                return splits[1];
            }
            return null;
        }
    }))
    .addInterceptor(new FTResourceInterceptor())
    .eventListenerFactory(new FTResourceEventListener.FTFactory())
    .build();
OkHttpClient.Builder()
    .addInterceptor(
        FTTraceInterceptor(object : FTTraceInterceptor.HeaderHandler {
            private var splits: Array<String>? = null

            override fun getTraceHeader(request: Request): HashMap<String, String> {
                val map = HashMap<String, String>()

                val headerString = FTTraceManager.get()
                    .getTraceHeader(request.url.toString())
                    // ヘッダーから propagation header を取得
                    .get(FTTraceHandler.W3C_TRACEPARENT_KEY)

                splits = headerString?.split("-")?.toTypedArray()

                headerString?.let {
                    map[W3C_TRACEPARENT_KEY] = it
                }

                return map
            }

            override fun getSpanID(): String? {
                return splits?.getOrNull(2)
            }

            override fun getTraceID(): String? {
                return splits?.getOrNull(1)
            }
        })
    )
    .addInterceptor(FTResourceInterceptor())
    .eventListenerFactory(FTResourceEventListener.FTFactory())
    .build()

OkHttp で ResourceID を追加

OkHttp の Request に uuid を追加します。同じリクエストが高頻度で並行実行されるシナリオでは、有効にすることを推奨します。ft-plugin 1.3.5 以上、ft-sdk 1.6.10 以上で FTSDKConfig.setEnableOkhttpRequestTag(true) を有効にすると、Request に ResourceID を自動的に追加できます。

new Request.Builder()
    .tag(ResourceID.class, new ResourceID());
Request.Builder()
    .tag(ResourceID::class.java, ResourceID())

フィードバック

このページは役に立ちましたか?